Ban code comments and Markdown the agent was not asked for
One hard rule in AGENTS.md stops narrating comments and summary files that go stale the day they are written.
Reported by @juliandierker · Verified 2026-11-18
- Agent
- Claude Code
- Model
- claude-opus-5-5
- Stack
- TypeScript
Problem
Agents explain their own code in comments ("// loop over users") and drop
SUMMARY.md or NOTES.md files after a task. Nobody maintains either, so
they turn into wrong documentation.
Setup
One line under "Hard rules" in AGENTS.md:
- No code comments. No new or edited Markdown unless asked.What happened
Diffs contain only code. Names and small functions carry the meaning a comment would have carried. When a document is really needed, I ask for it by name.
Reproduce
Add the rule to
AGENTS.md(orCLAUDE.md).Ask for a refactor and check the diff for comments and new
.mdfiles.