Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

agentsop-conventions-pinning

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.

agentsope · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add agentsope/SkillAlchemy --skill agentsop-conventions-pinning

About this skill


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

Read the complete source ↗