claude-code-config
AGENTS.md2 starsChanged 28 days agoMITView on GitHub
Instructions for AI coding agents, whatever the tool. Tool-specific layers build on this file: Claude Code adds CLAUDE.md and .claude/, Cursor adds .cursor/. Core rule: Before creating or modifying code, read 2-3 similar files in the same directory and match their patterns exactly. docs/conventions/ is the single source of truth. The conventions for every area covering a file must be in context before you touch it: Claude Code injects them through .claude/rules/; other tools read them from this table. docs/README.md…
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- AlexisBalayre/claude-code-power-configword for word, first seen Oct 17, 2026
Other versions1 project uses a version of this.
Word for word · 1
- AlexisBalayre/claude-code-power-config★ 2100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository36 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- adapt-to-projectSkill
- address-review-commentsSkill
- backfill-issuesSkill
- cavemanSkill
- codebase-designSkill
- daily-noteSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- find-dead-codeSkill
- fix-sonarSkill
- fix-wizSkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- implement-specSkill
- improve-codebase-architectureSkill
- obsidian-vaultSkill
- pr-ci-reviewSkill
- pr-descriptionSkill
- prototypeSkill
- researchSkill
- retroSkill
- review-retroSkill
- tddSkill
- to-questionnaireSkill
- to-specSkill
- to-ticketsSkill
- wait-whatSkill
- wayfinderSkill
- wizardSkill
- wizSkill
- writing-for-agentsSkill
- zoom-outSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
Core rule: Before creating or modifying code, read 2-3 similar files in the same directory and match their patterns exactly.
- Very specific: line 45
NEVER work on or push to the trunk (GIT_TRUNK in .claude/project.env, default main).
- Very specific: line 46
ALWAYS use scripts/worktree-create.sh <name> (creates .worktrees/<name> on feature/<name>).
- Very specific: line 55
Formatting/typechecking: run the lint and typecheck commands before handing work back.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Project
<!-- TODO(adapt): replace the heading with the project name and write 1-2 sentences on what it is, its stack, and its shape (single package, monorepo, services). Run /adapt-to-project to fill every TODO(adapt) in this repo. -->Instructions for AI coding agents, whatever the tool. Tool-specific layers build on this file: Claude Code adds CLAUDE.md and .claude/, Cursor adds .cursor/.
Role
<!-- TODO(adapt): the expertise to bring, e.g. "Expert Python / FastAPI engineer working in a strict-convention service". -->Core rule: Before creating or modifying code, read 2-3 similar files in the same directory and match their patterns exactly.
Conventions
docs/conventions/ is the single source of truth. The conventions for every area covering a file must be in context before you touch it: Claude Code injects them through .claude/rules/; other tools read them from this table.
| Area | Paths | Conventions |
| Core | any source file | docs/conventions/core.md |
| Testing | test files and test directories | docs/conventions/testing.md |
<!-- TODO(adapt): add one row per area with its own rules (e.g. API, database, frontend), each with a matching docs/conventions/<area>.md and .claude/rules/<area>-conventions.md. -->docs/README.md (Diátaxis-structured) covers anything outside these areas; shared vocabulary lives in docs/glossary.md.
Layout
Topology, components and data flow: docs/reference/architecture.md.
Comments
Default to no inline comment. Add one only for a non-obvious WHY (invariant, unit, ordering, gotcha), never to narrate WHAT the code does. If removing a comment wouldn't confuse a competent reader, delete it. A WHY comment that restates the callee's doc comment is a duplicate: read the callee's docs before keeping it; if the seam already says it, delete the call-site copy.
retries += 1 # increment the retry counter (BAD: restates the code)
retries += 1 # 429s are transient, so retry first (GOOD: explains the why)Altitude
Build the smallest thing that works; the obligation lives in docs/conventions/core.md §Altitude / YAGNI. Before finishing a change that introduced any discretionary construct (new file, helper, wrapper, option, param, interface, generic, or defensive branch), list each one with a keep-or-inline verdict; keep means you can name a second caller or a real WHY. Default to inline/delete. Don't list constructs a convention prescribes, and skip the audit silently when a change added none. Unjustifiable bloat is a /simplify candidate.
Git workflow (CRITICAL)
- NEVER work on or push to the trunk (
GIT_TRUNKin.claude/project.env, defaultmain). PRs only. - ALWAYS use
scripts/worktree-create.sh <name>(creates.worktrees/<name>onfeature/<name>). NEVERgit checkout -bin the main worktree. git branch --show-currentMUST NOT be the trunk before committing.
Key commands
Lint, typecheck, test and install commands live in .claude/project.env (LINT_CMD, TYPECHECK_CMD, TEST_CMD, INSTALL_CMD).
<!-- TODO(adapt): list the commands an agent needs beyond those (dev server, integration tests, codegen, migrations) and any gotcha (services that must be up, env files). -->Formatting/typechecking: run the lint and typecheck commands before handing work back. (Claude Code only: don't run them manually; its Stop hook runs them automatically.)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.