/agentsop-conventions-pinning

name: agentsop-conventions-pinning
version: 0.1.0
description: SOP for writing, loading, and evolving a project-level convention file (CONVENTIONS.md / CLAUDE.md / .cursor/rules / .clinerules / AGENTS.md) so that a coder-agent reliably respects your codebase's style choices every session. Tool-agnostic; covers the four load mechanics (read-only attachment, ancestor-walk auto-load, glob-scoped rules, agent backstory) and the conflict resolution between pinned conventions and the existing code.
domain: coder-agent infrastructure / context engineering
audience: coder-agents and engineers configuring them, on any project lived in for > 1 day
trigger_keywords:
  - "conventions file"
  - "CONVENTIONS.md"
  - "CLAUDE.md"
  - ".cursorrules"
  - ".clinerules"
  - "AGENTS.md"
  - "coding standards for AI"
  - "style guide for agent"
  - "agent ignored my rule"
  - "pin my coding style"
when_to_use:
  - "any project you (or your agent) will return to more than once"
  - "the same correction has been typed into chat more than twice"
  - "code review (human or LLM) keeps catching style violations the agent should know"
  - "onboarding a new agent / new teammate; they need the project's tacit rules in writing"
  - "you switch coder-tools and want one canonical style source across Aider, Claude Code, Cursor, Cline"
when_not_to_use:
  - "one-off / throwaway scripts where the cost of writing rules > the cost of the work"
  - "true greenfield where conventions ARE being invented as code; pin AFTER the first 2-3 modules stabilise"
  - "you need hard enforcement (lint/format/CI) — conventions are guidance, hooks/precommit are enforcement"
  - "the project already has a lint config that fully encodes the rule — point at the lint config instead"

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.

1.2 Reverse triggers (skip)

• **One-off / throwaway scripts**. The write-cost of a conventions file is fixed; the savings are proportional to session count. < 3 sessions → don't bother.
• **True greenfield**. The first 2-3 files of a project ARE the convention. Pinning style before the style exists locks in arbitrary choices.
• **Hard enforcement needed**. A conventions file is *context*, not a *hook*. Claude Code's docs are explicit: *"CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer."* [code.claude.com/docs/en/memory] If the rule must run every time (e.g. "must `make lint` before commit"), write a hook / precommit / CI check.
• **The rule is already in a config that the agent can read** — `.eslintrc`, `pyproject.toml`, `.editorconfig`, `tsconfig.json`. Point the agent at the config; don't duplicate.

1.3 Mental check

> A conventions file earns its tokens only if it contains **information that is not already in the repository**. The research is unambiguous on this: *"Developer-written context files performed better for exactly the reason you'd guess: they contained information that wasn't already in the repository — tooling preferences, workflow requirements, conventions that existed in developers' heads but not in any documentation."* [developer.upsun.com/posts/ai/agents-md-less-is-more]

If everything you would write into CONVENTIONS.md is already discoverable from `package.json`, `pyproject.toml`, `.eslintrc`, the test directory, and obvious code patterns — don't write the file. The agent will pre-cache it itself.

---

2. 核心心智模型 (Mental Model)

2.1 Convention as compile-time, code-review as runtime

+-------------------------------------+   +-------------------------------------+
|  COMPILE-TIME (conventions file)    |   |  RUNTIME (code review / lint / CI)  |
|                                     |   |                                     |
|  - Loaded once per session          |   |  - Runs on every change             |
|  - Shapes generation                |   |  - Catches violations after-the-fact|
|  - Cheap to update, free to ignore  |   |  - Costly to set up, hard to ignore |
|  - "Prefer X over Y" lives here     |   |  - "X must always hold" lives here  |
|  - Style + intent + preferences     |   |  - Invariants + safety + correctness|
+-------------------------------------+   +-------------------------------------+
        ^                                            ^
        |        Conventions guide;                  |
        |        review enforces.                    |
        |        Both are needed; they fail          |
        |        in different ways.                  |

Conventions fail by **silent drift**: agent ignores the rule once, no one notices, code is merged. Review fails by **late catch**: violation is found post-PR, expensive to fix. The two complement, not substitute.

2.2 The four load mechanics across the ecosystem

Every coder-tool has settled on one of four mechanics for getting persistent context into the agent. Knowing which mechanic your tool uses is