Persistent Brief
Context belongs in the repo, not the chat.
The agent is only as good as the brief it walks into. The third repetition of the same instruction in chat is the signal: the brief belongs in the repo, in AGENTS.md or whichever tool-specific equivalent the stack uses.
Opinion
I've watched too many teams treat the agent like a goldfish. Every session starts with the same paragraph in the chat: “we use Tailwind, no inline styles, single quotes, named exports, please don't add comments.” By the third session everyone is copy-pasting that paragraph from a Notion page. By the tenth, half the team has a slightly different version. By the thirtieth, two engineers are arguing about which version is right and the agent is following whichever paragraph the latest contributor pasted last. The fix is the one Anthropic's own engineering posts have been pushing since 2024: commit the brief.1Best Practices for Claude Code on CLAUDE.md. Recommended target under 200 lines; prefer pointers to copies; snippets become out-of-date quickly. The 200-line cap is the load-bearing constraint that turns the brief from a wall of text into something the model actually reads.
As of 2026 the industry has converged on the file Linus Torvalds and the Linux Foundation blessed: AGENTS.md, supported by 60,000+ projects and 23+ named coding tools including Cursor, Codex, Claude Code, GitHub Copilot, Aider, Cline, Gemini CLI, Windsurf, Devin, JetBrains Junie, Zed, and Warp.2AGENTS.md — open standard for agent rules files. 60,000+ projects; 23+ tools support it including OpenAI Codex, Cursor, Aider, Claude Code, GitHub Copilot Coding Agent, Gemini CLI, Cline, Goose, Devin, Windsurf, Zed, JetBrains Junie, Warp, VS Code, Augment, RooCode. Each tool layers its own format on top (Anthropic's CLAUDE.md, Cursor's .cursor/rules/ directory, Cline's .clinerules, GitHub's .github/copilot-instructions.md, Aider's CONVENTIONS.md) but the principle survives the surface. Pick the file the tool loads; commit it; review changes to it like changes to tsconfig.json.
This Prickles repo is the canonical microcosm. The shared brief lives in AGENTS.md; CLAUDE.md is a one-line @AGENTS.md import. The agent reads the same file every session no matter which tool I run; the file is version-controlled, lint-checked, and reviewed on PRs that touch it. There is no oral tradition; there is no Notion page; there is no “ask Adam”. The brief is in the repo because the repo is the source of truth for everything else, the same reason the schema lives in the repo and not in somebody's head.
Copy a note and link
Grab this short comment and drop it into a PR comment or an LLM chat to prompt the right change.
Don't repeat instructions across prompts; commit them. AGENTS.md is the standard; CLAUDE.md, `.cursor/rules`, `.clinerules`, `.github/copilot-instructions.md` are the surface-specific equivalents. The brief lives in the repo, not the chat — version it, review it, treat it like code. /tenet/persistent-brief/AI2
AI eyes only
Rule: context belongs in the repo, not the chat. Read the committed brief on session start.
Reject: chat-only instructions that the next session cannot recover. Reject: contradicting the committed brief without flagging it. Reject: making changes whose rationale lives only in the conversation.
Generate: read CLAUDE.md, .cursor/rules/ (MDC alwaysApply: true), or .github/copilot-instructions.md on every session start. Treat the committed brief as the contract; treat chat as conversation that either confirms it or amends it via a commit.
Diagnostic: when chat instructions disagree with the committed brief, halt and surface the contradiction. Either commit the new rule or comply with the existing one. Never silently pick.
Why?
- Stops the paragraph-in-the-chat ritual. Project conventions stop being something every contributor pastes from a Notion page on session start; they become something the model loads automatically.
- Brief becomes version-controlled. PR-reviewable, blame-able, revertable — the same review surface as the rest of the code, with the same audit trail.
- Tool-portable via AGENTS.md. The brief survives the team switching from Cursor to Claude Code to Aider; only the wrapper file changes, and most tools support AGENTS.md as a fallback.
- Compounds with AI1 The Intern Pattern. The agent walks into every session with the brief loaded and the loop understood — the closest coding agents get to a colleague who already knows the team.
- Ramps new contributors faster. The committed brief is the onboarding doc; new humans and new agents start from the same baseline.
- Fixes propagate. When the agent does the wrong thing twice, the fix lands in the brief and every future session inherits it — instead of every contributor re-discovering the same correction.
- Names the source of truth. The brief is the contract between humans and agents; chat messages, Slack threads, and tribal knowledge stop competing for authority.
Origins
The pattern began as a tool-specific kludge. Anthropic shipped CLAUDE.md as the Claude Code convention in early 2024; Cursor shipped .cursorrules, then .cursor/rules/; Cline shipped .clinerules; Aider shipped CONVENTIONS.md; GitHub Copilot shipped .github/copilot-instructions.md. Each format was the same idea in a different filename: a file the model loads automatically so you never have to repeat yourself.
The convergence happened in 2025. AGENTS.md emerged as a tool-agnostic open standard, stewarded by the Linux Foundation's Agentic AI Foundation, with explicit sign-on from OpenAI Codex, Cursor, Aider, Claude Code, GitHub Copilot Coding Agent, Gemini CLI, Cline, Goose, Devin, Windsurf, Zed, JetBrains Junie, Warp, VS Code, Augment, RooCode, and roughly two dozen others.2AGENTS.md — open standard for agent rules files. 60,000+ projects; 23+ tools support it including OpenAI Codex, Cursor, Aider, Claude Code, GitHub Copilot Coding Agent, Gemini CLI, Cline, Goose, Devin, Windsurf, Zed, JetBrains Junie, Warp, VS Code, Augment, RooCode. 60,000+ open-source repositories adopted the file in under twelve months. The industry has rarely converged on a convention so fast; the speed says the principle was load-bearing and the only friction was the filename.
Anthropic's Best Practices for Claude Code codified the rules of the brief: target under 200 lines; keep instructions as universally applicable as possible; prefer pointers to code snippets because snippets become out-of-date quickly.1Best Practices for Claude Code on CLAUDE.md. Recommended target under 200 lines; prefer pointers to copies; snippets become out-of-date quickly. The 200-line cap is the load-bearing constraint that turns the brief from a wall of text into something the model actually reads. The same advice generalises across surfaces — a 2,000-line CLAUDE.md or Cursor rules dump is a brief that the model skims, not a brief that the model reads.
Anthropic's Effective Context Engineering paper (October 2025) reframes the brief as one half of a hybrid context model: “CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time.”3Effective Context Engineering for AI Agents (October 2025). The hybrid context model: CLAUDE.md is naively dropped in up front; glob and grep retrieve files just-in-time. The committed brief is one half of the agent's working context. The committed brief carries the rules; the live filesystem carries the facts. The two together are the working context for every session.
Quotes
A simple, open format for guiding coding agents, used by 60,000+ open-source projects. Think of it as a README for agents.
Recommended target under 200 lines, as universally applicable as possible. Prefer pointers to copies — don't include code snippets in these files if possible, as they will become out-of-date quickly.
Claude Code employs a hybrid model where CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time.
Plain Markdown with no special syntax. A single .clinerules text file in your project root or as multiple markdown files within a .clinerules/ directory.
Evidence
Twenty external sources, ranked by author authority. The first five are the canon; expand to see the rest, including the qualifiers and the named opposers. Each links out to its primary source.
- 01AGENTS.md — open standardSupports60,000+ projects; 23+ tools support it natively. The cross-tool consolidation point that makes the brief portable across Claude Code, Cursor, Codex, Aider, Cline, Copilot, Gemini CLI, and the rest.
- 02Industry-press confirmation of the convergence point. The signal that AGENTS.md is no longer one-of-many but the convention the agent ecosystem agreed on.
- 03Anthropic's own rules of the brief: target under 200 lines, prefer pointers to copies, snippets drift. The most-quoted single source for the discipline.
- 04Hybrid context model: CLAUDE.md is loaded up front; glob and grep retrieve facts just-in-time. The committed brief is one half of the agent's context.
- 05Cursor — .cursor/rules directorySupportsMDC format, glob scoping, manual invocation, subdirectory rules, ~500-line target. Cursor's surface for the same principle, with explicit per-file scoping.
Eighteen sources. The supporters cluster on the cross-tool consolidation point: the AGENTS.md open standard (Linux Foundation), the InfoQ standardisation write-up, Anthropic's CLAUDE.md best practices, and Cursor's .cursor/rules/ convention. The qualifiers further down carry the “not all briefs are alike” nuance. The opposing camp argues for prompt-level instructions or memory-tool replacements; both are addressed in the reply.
Enforcement
Apply these rules in eslint.config.mjs. The full enforcement across every tenet lives on the implementation page.
| Rule | Tool | Catches |
|---|---|---|
| markdownlint-cli2 | markdownlint-cli2 | shape regressions in AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc — heading order, line length, missing top-level heading. |
| eslint-plugin-markdownlint | eslint-plugin-markdownlint | the same shape rules but inside the ESLint pipeline — one binary, one config tree. |
| GitHub Actions — brief validator | GitHub Actions | PRs that delete AGENTS.md, push CLAUDE.md over the 200-line cap, or break the markdown shape. |
eslint.config.mjsconfiguration snippet
import jsonc from 'eslint-plugin-jsonc';
import markdown from 'eslint-plugin-markdownlint';
export default [
{
files: ['AGENTS.md', 'CLAUDE.md', '.cursor/rules/**/*.mdc', '.clinerules', '.clinerules/**/*.md'],
plugins: { markdown },
rules: {
'markdownlint/md001': 'error',
'markdownlint/md013': ['warn', { line_length: 200 }],
'markdownlint/md041': 'error',
},
},
{
files: ['.github/copilot-instructions.md', '.github/instructions/**/*.md'],
plugins: { markdown },
rules: {
'markdownlint/md013': ['warn', { line_length: 200 }],
},
},
];AI rules
.cursor/rules/ai2-persistent-brief.mdc--- description: Prickles AI2 — Persistent Brief globs: "**/*" alwaysApply: true --- ## Prickles AI2 — Persistent Brief The agent's brief lives in the repo, not the prompt. Anything you would say twice belongs in a file the model loads on every session. AGENTS.md is the cross-tool standard (Linux Foundation, 60k+ projects). CLAUDE.md, `.cursor/rules/`, `.clinerules`, `.github/copilot-instructions.md`, and `CONVENTIONS.md` are the surface-specific equivalents — pick the right file for your tool. The brief contains pointers, not snippets. Anthropic's own guidance: target under 200 lines, prefer references to copies, anything that drifts is debt. Treat the brief as code. Version it, lint it, review it on PRs that touch it. The brief is the contract between humans and agents; if it is wrong on main, every session is wrong.
Repo layout, CI, and ESLint wiring for these paths live on /implementation — not repeated on every tenet.
Counter-argument
The honest steelman is that committed briefs go stale. A file that says “we use React 18” in a repo that has shipped React 19 is worse than no file: the agent will follow the brief and write code for an API that no longer exists. Anthropic's own October 2025 memory-tool release suggests the future may be agent-managed memory rather than human-managed briefs: a system that “stores and consults information outside the context window through a file-based system” the agent edits itself.4Memory tool (public beta, October 2025). Stores and consults information outside the context window through a file-based system the agent edits itself. The agent-managed memory case for relaxing the static-brief discipline. If the agent can keep its own brief current, the case for committing a static file weakens.
Counter-argument retort
The staleness objection is real and the fix is the same fix that stops every other repo artefact from going stale: review it. The brief is code. PRs that touch it get reviewed; CI lints it; team practice on the day a major dependency moves includes “update the brief” the same way it includes “update the lockfile”. A brief that is on main and wrong is the same problem as a comment on main that is wrong — covered by F5 Self-Documenting Code. The fix is process, not the absence of a brief.
The agent-managed memory case is more interesting. Anthropic's memory tool (public beta, October 2025) does let the agent edit its own brief, and Cline ships AI-editable rules with the same shape.5.clinerules — version-controlled, shareable, AI-editable instructions. Plain Markdown, no special syntax; single file in the project root or multiple files in .clinerules/. Supports AGENTS.md as a fallback. The risk is that an agent-edited brief is an unaudited brief: the next session reads facts the previous session invented, and the model's confidence travels through the file system into the next workflow. The fix is not to ban agent-edited briefs — it is to treat them like agent-edited code: open a PR, get a human review, then merge. The Reflexion / Self-Refine literature is explicit that pure introspection without external grounding can degrade accuracy; the same caveat applies to letting the agent rewrite its own rules of the road.6Large Language Models Cannot Self-Correct Reasoning Yet (ICLR 2024). Pure self-introspection without external grounding can degrade accuracy. The caveat to letting agents edit their own brief without human review.
The deeper point is that the brief is the only place where the team decides once and lets the decision compound. Without it, every new contributor — human or agent — relitigates the same arguments in the chat, and the rate of bad output rises with the rate of new conversation. Pair AI2 with AI1 The Intern Pattern and the agent walks into every session with the brief loaded, the loop understood, and a written plan to be approved — the closest a coding agent gets to a colleague who already knows how the team works.
Notes
- [1]Anthropic — Best Practices for Claude Code on CLAUDE.md. Recommended target under 200 lines; prefer pointers to copies; snippets become out-of-date quickly. The 200-line cap is the load-bearing constraint that turns the brief from a wall of text into something the model actually reads.
- [2]Linux Foundation Agentic AI Foundation — AGENTS.md — open standard for agent rules files. 60,000+ projects; 23+ tools support it including OpenAI Codex, Cursor, Aider, Claude Code, GitHub Copilot Coding Agent, Gemini CLI, Cline, Goose, Devin, Windsurf, Zed, JetBrains Junie, Warp, VS Code, Augment, RooCode.
- [3]Anthropic — Effective Context Engineering for AI Agents (October 2025). The hybrid context model: CLAUDE.md is naively dropped in up front; glob and grep retrieve files just-in-time. The committed brief is one half of the agent's working context.