diff --git a/AGENTS.md b/AGENTS.md index e15a09f..c8c7853 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,20 +37,6 @@ what tooling can't check. it starts a name. File names are unaffected: kebab-case lowercases everything (`parse-cli-args.ts` exports `parseCLIArgs`). -### Comments - -- Comments that document a declaration are JSDoc blocks, always multi-line (`/**` alone, one - `*`-prefixed line per point, `*/` alone — never single-line `/** … */`), attached directly to the - declaration they describe; `//` is for statement-level commentary inside bodies. -- Comment a declaration only for what the file doesn't already show — an invariant, cross-file or - runtime behavior, or why the choice is necessary. A comment that restates the name or signature is - a defect — delete it. -- Comments describe the code as it is now — no history ("previously", "now uses"), no project state - (issue numbers, phase labels, "not wired yet"); those live in the commit message. -- Comments don't name other declarations — renames strand the reference. State the contract instead: - "callers must pass edits sorted last-to-first", not "(buildEditsFromAST's contract)". A - declaration's own parameters and signature types are fine to name. - ### Function naming Every function name starts with a prefix from the closed list below: pick from it, or extend this diff --git a/agents/shared.md b/agents/shared.md index 909b715..6ac0cd4 100644 --- a/agents/shared.md +++ b/agents/shared.md @@ -35,20 +35,6 @@ what tooling can't check. it starts a name. File names are unaffected: kebab-case lowercases everything (`parse-cli-args.ts` exports `parseCLIArgs`). -### Comments - -- Comments that document a declaration are JSDoc blocks, always multi-line (`/**` alone, one - `*`-prefixed line per point, `*/` alone — never single-line `/** … */`), attached directly to the - declaration they describe; `//` is for statement-level commentary inside bodies. -- Comment a declaration only for what the file doesn't already show — an invariant, cross-file or - runtime behavior, or why the choice is necessary. A comment that restates the name or signature is - a defect — delete it. -- Comments describe the code as it is now — no history ("previously", "now uses"), no project state - (issue numbers, phase labels, "not wired yet"); those live in the commit message. -- Comments don't name other declarations — renames strand the reference. State the contract instead: - "callers must pass edits sorted last-to-first", not "(buildEditsFromAST's contract)". A - declaration's own parameters and signature types are fine to name. - ### Function naming Every function name starts with a prefix from the closed list below: pick from it, or extend this