1-comments — Claude Code and Cursor rule: comments that carry facts
1-comments — a rule that keeps AI-written comments to facts the code cannot express and bans pointers to tickets, PRs and dates.
MIT ★ 571 updated 2026-10-29
.claude/rules/1-comments.mdWhat 1-comments does
The agent consults this file whenever it writes a comment or keeps an existing one. A line that repeats the statement below it goes. So does a note about who changed what. What stays is something the code cannot state: a constraint the types miss, a quirk of the host you measured, a simpler shape that was tried and refused.
A paths list narrows the rule to src/**/*.ts, tests/**/*.ts and scripts/**. Elsewhere it stays quiet. Comments run one or two lines; anything longer belongs in aidd_docs/memory/. The framework repo also ships tests/architecture/comments.arch.test.ts, which rejects outside references and lowers the allowed volume over time.
Pointer comments are the first casualty. A reference to a ticket or PR has to be rewritten or dropped. Without the architecture test in your own project, the length limit rests on whoever reads the diff.
What it helps with
- strip comments that repeat the line below them
- replace a ticket reference with the constraint it was meant to explain
- cut an explanation to two lines and move the rest into
aidd_docs/memory/ - record a measured host quirk that types cannot show
- stop comment volume from creeping up across a codebase
Example prompts for the agent
- Go through
src/**/*.tsand drop any comment that restates the code. - Keep only comments that give a fact and its consequence, then rewrite the rest without links.
- Check this diff for ticket, PR or URL references in comments and remove them.
How to install 1-comments
Manually: put the files in place
.claude/rules/1-comments.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/1-comments.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/1-comments.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/1-comments.mdManually: put the files in place
.clinerules/1-comments.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about 1-comments
How do I install 1-comments in Claude Code?
Put .claude/rules/1-comments.md into your project with the rule text inside.
What does 1-comments do?
It tells the agent what a comment may contain: a fact plus what follows from it, with no restating of code and no references to tickets, PRs, commits, dates, reviews or URLs.
Which files does the rule apply to?
Its paths list covers src/**/*.ts, tests/**/*.ts and scripts/**. Outside those files the agent does not follow it.
Source text
1-comments.md · MIT
--- description: Apply when writing or keeping a comment; a comment says what the code cannot, and names no external reference. paths: - "src/**/*.ts" - "tests/**/*.ts" - "scripts/**" --- # Comments - Comment only what code and names cannot say. - Worth one: a constraint types miss, a measured host quirk, a refused simpler shape. - Delete a comment that restates code or narrates history. - Name no ticket, PR, commit, date, review or URL. - Keep the fact and its consequence. - One or two lines; a paragraph belongs in `aidd_docs/memory/`. - `tests/architecture/comments.arch.test.ts` refuses external references and ratchets volume down.
© ai-driven-dev · MIT · ai-driven-dev/framework