From aca09d87a180992e618d7f8e83c65b0cbabcd81e Mon Sep 17 00:00:00 2001 From: alexion Date: Wed, 22 Jul 2026 15:33:07 -0400 Subject: [PATCH] docs: move the comment conventions to the global agent instructions The comment 'why not what', self-contained, sentence-per-line rules are project-agnostic, so they belong in the global agent instructions rather than this repo's conventions. Genericise the four Nix- and domain-specific examples to their underlying principles on the way across. --- CLAUDE.md | 17 ----------------- modules/claude-code/CLAUDE.md | 20 ++++++++++++++++++++ 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6250656..06c70a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,23 +5,6 @@ The domain model (Host, Module, Skeleton, Auto-loader, Enable convention, overla ## Conventions -- Write comments only where they earn their place, and keep them concise. - Assume the reader can read code: comment the "why", not the "what", and explain "what" only when it is genuinely non-obvious. - A comment must be self-contained to its file — accurate to a reader looking at that file alone. - Do not write about history ("used to be X", "now moved here") or future state, about how a value is consumed elsewhere, or to justify the choice against alternatives; state the positive reason a thing exists, keeping any real stakes as a present-tense consequence. - The only permitted cross-file mention is a bare pointer explaining why something is *absent* here (e.g. "disko derives `fileSystems`; none declared here"), never narrating what the other file or tool does. - Do not use the domain model's capitalized terms (Host, Module, Skeleton, Auto-loader, Enable convention) as glossary references; describe things in plain language, using "host"/"module" only as ordinary lowercase nouns. - Never reference agent-facing state (anything under `.claude/` or `CLAUDE.md`). - A file-top header is one concise purpose line, added only where the filename or path does not already say it — never a feature inventory of the code below. - For a placeholder, say so plainly plus any actionable present-tense directive ("Placeholder: regenerate with nixos-generate-config on the target machine"), never "placeholder for ". - Option `description`/`mkEnableOption` strings are user-facing documentation rather than comments, so they may describe behaviour more fully — but the self-contained rule and the bans on glossary terms and agent-state references still apply. -- Start each sentence of a comment on its own line, as with Markdown prose. - A sentence needing more than one line is first a prompt to ask whether it should be two sentences. - Only when it genuinely cannot be split does it wrap, and then it wraps normally at the right margin. - Never break a line early at a comma or clause boundary to make it read as a unit. - Never use a semicolon, in a comment or in authored prose. - Recast as two sentences instead. - Only reformat comments you are actually writing or changing. - Comments posted to Gitea (pull requests, issues, reviews) go out under the operator's account, so sign every one to make clear the author is the agent, not the operator. End the comment with a `— Claude` sign-off. (A dedicated bot account may replace this later; until then, the sign-off is the only marker.) diff --git a/modules/claude-code/CLAUDE.md b/modules/claude-code/CLAUDE.md index 8fbd285..d40a011 100644 --- a/modules/claude-code/CLAUDE.md +++ b/modules/claude-code/CLAUDE.md @@ -38,3 +38,23 @@ These are common instructions for Alexion's agents across all scenarios. Briefly mention the edit in your response rather than making it silently. If an existing entry is later found to be wrong or stale, correct or remove it the same way. +## Comments + +- Write comments only where they earn their place, and keep them concise. + Assume the reader can read code: comment the "why", not the "what", and explain "what" only when it is genuinely non-obvious. + A comment must be self-contained to its file — accurate to a reader looking at that file alone. + Do not write about history ("used to be X", "now moved here") or future state, about how a value is consumed elsewhere, or to justify the choice against alternatives; state the positive reason a thing exists, keeping any real stakes as a present-tense consequence. + The only permitted cross-file mention is a bare pointer explaining why something is *absent* here (e.g. a value another tool derives, which this file therefore does not declare), never narrating what the other file or tool does. + Do not use a project's domain-model or ubiquitous-language capitalized terms as glossary references; describe things in plain language, using ordinary lowercase nouns. + Never reference agent-facing state (anything under `.claude/` or `CLAUDE.md`). + A file-top header is one concise purpose line, added only where the filename or path does not already say it — never a feature inventory of the code below. + For a placeholder, say so plainly plus any actionable present-tense directive ("Placeholder: regenerate with on the target machine"), never "placeholder for ". + User-facing documentation strings (an option's `description`, a generated help string) are documentation rather than comments, so they may describe behaviour more fully — but the self-contained rule and the bans on glossary terms and agent-state references still apply. +- Start each sentence of a comment on its own line, as with Markdown prose. + A sentence needing more than one line is first a prompt to ask whether it should be two sentences. + Only when it genuinely cannot be split does it wrap, and then it wraps normally at the right margin. + Never break a line early at a comma or clause boundary to make it read as a unit. + Never use a semicolon, in a comment or in authored prose. + Recast as two sentences instead. + Only reformat comments you are actually writing or changing. +