Conventions Pinning — Writing a Style Guide Your Coder-Agent Will Actually Read

One line: a conventions file is the system prompt of your codebase. Treat it like a system prompt, not like a README. Anti-patterns: writing prose, narrating history, marketing the project. Patterns: command-first, verifiable, "prefer X over Y", < 200 lines.

1. 何时激活 (When to Activate)

1.1 Direct triggers

• The user (human or upstream agent) asks "how do I make Claude/Cursor/Cline/Aider respect our style?".
• The same correction has been typed in chat ≥ 2 times this week ("use httpx not requests", "add type hints", "no comments on every line"). Claude Code's docs codify this rule: "Add to it when Claude makes the same mistake a second time." [code.claude.com/docs/en/memory]
• A new project is past the "first 2 modules" phase — there are now style choices implicit in the code that an outsider (or fresh-context agent) can't see.
• The team is switching coder-tools (Aider → Claude Code, or adding Cursor) and conventions are scattered in chat history.
• An AI code review caught the same anti-pattern twice.