Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/1-comments.md
Open on GitHub

What 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/**/*.ts and 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set80

The whole set →
0-folder-size The 0-folder-size rule keeps directories from growing past ten direct .ts files. It also records why an oversized directory exists instead of encouraging file shuffling. CX Codex +1 ★ 571repo stars rule.generated The rule.generated rule requires adding the comment // Team reviewed domain change above every newly declared exported function in src/domain/. It tracks which domain changes have passed team review. CX Codex +1 ★ 571repo stars 1-type-honesty 1-type-honesty prevents dangerous TypeScript casts like any and eliminates compiler error suppressions in source code. CX Codex +1 ★ 571repo stars 0-orchestration The 0-orchestration rule sets boundaries for TypeScript orchestrators: one dependency per area crossed and a cap of four other use cases. CX Codex +1 ★ 571repo stars 01-ticket-info 01-ticket-info is a Claude Code skill that fetches ticket details from a configured issue tracker and displays its fields in the agent chat. It reads the ticket identified in the prompt or conversation context. CX Codex +1 ★ 571repo stars 0-shared-modules The 0-shared-modules rule sets a bar for moving code into shared/: callers must come from two application areas. Use it when reviewing modules under src/contexts/. CX Codex +1 ★ 571repo stars 01-hello 01-hello is a Claude Code skill that runs the greet action to confirm the aidd-ui plugin is loaded. It checks plugin availability. CX Codex +1 ★ 571repo stars 7-auth 7-auth governs how assistant code reads and saves auth credentials: lazy GitHub token lookup, tight file permissions, and delayed error handling. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open