| name | writing-code |
| description | Baseline conventions for writing or editing code in any repo. Load before writing/editing source. Yields to repository-specific guidelines (CLAUDE.md, style configs, existing patterns) on any conflict. |
Writing Code
Baseline conventions. Repository-specific guidelines always win on
conflict — a repo's CLAUDE.md, style config (prettier, eslint,
editorconfig, rustfmt, …), or the patterns already in the file override
anything here. When unsure, match what the surrounding code does.
Comments
- No explanatory comments. Correct code speaks for itself.
- Rationale — pitfalls avoided, non-obvious reasoning — goes in the
commit message, not the source.
- Why: returning to a file, you follow the patterns already in it; the
pattern is the guide, so a comment adds nothing.
- Exception: match a file's existing comment density. If a file
deliberately documents (public API docblocks, license headers),
follow suit.
Documentation
- A script/tool's usage contract goes in a doc header at the top of that
file — what it does and how to invoke it. Not in CLAUDE.md, which
should at most point to it.
- Document the contract, not implementation details obvious from the
code.
Follow established patterns
- Read the surrounding code first. Match its naming, structure, error
handling, and idioms so new code is indistinguishable from what's
there.
- Reuse existing utilities/helpers instead of writing new ones. Search
before adding.
Line length
- Wrap at 80 chars unless the repo's own style config says otherwise
(then defer to it).
