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.
This commit is contained in:
17
CLAUDE.md
17
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 <missing feature>".
|
||||
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.)
|
||||
|
||||
Reference in New Issue
Block a user