claude-code-blueprint
AGENTS.md73 starsChanged 4 months agoMITView on GitHub
You are an AI assistant (Claude, Cursor, Codex, Gemini, or other) helping a user who has this repo open. This file gives you a fast, accurate read on what this repo IS, what it ISN'T, and how to help the user. A library of ready-to-copy files (CLAUDE.md, hooks, agents, skills, rules) that a developer mixes into their own project to make Claude Code more reliable and consistent. It is not software to install: there is no package, no binary, no…
- Installs packages
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,774 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 repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- memory/CLAUDE.mdCLAUDE.md
- changelogSkill
- db-checkSkill
- deploy-checkSkill
- e2e-checkSkill
- elicit-requirementsSkill
- load-sessionSkill
- pr-reviewSkill
- register-projectSkill
- review-diffSkill
- review-fullSkill
- save-diarySkill
- save-sessionSkill
- scaffold-projectSkill
- self-auditSkill
- session-endSkill
- sprint-planSkill
- statusSkill
- tech-radarSkill
- test-checkSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 46
If the user asks "how do I set this up?": ask their skill level first (beginner / experienced).
- Very specific: line 58
Don't run claude CLI inside this repo's directory.
- Very specific: line 59
Don't suggest the user npm install or pip install anything.
- Distinctive: line 60
Don't recommend the user fork the entire repo if they only need 1-2 files.
- Distinctive: line 61
Don't claim this is "official Anthropic".
- Very specific: line 62
Don't suggest committing memory/ contents to a public repo.
- Distinctive: line 63
Don't treat these files as the user's own config.
≈ “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
AGENTS.md: Repository Orientation for AI Assistants
You are an AI assistant (Claude, Cursor, Codex, Gemini, or other) helping a user who has this repo open. This file gives you a fast, accurate read on what this repo IS, what it ISN'T, and how to help the user.
What this repo is
A library of ready-to-copy files (CLAUDE.md, hooks, agents, skills, rules) that a developer mixes into their own project to make Claude Code more reliable and consistent. It is not software to install: there is no package, no binary, no npm install.
The user typically does one of three things:
- Copy
CLAUDE.mdonly (60-second adoption): gets 4 behavioral rules - Run
./setup.sh --preset=standard: copies hooks + settings + rules + opt-in memory - Fork and adapt: clone, edit, commit shared config to their team
What this repo is NOT
- A Claude Code plugin (Claude Code has no plugin system in that sense)
- A framework or library to import
- A working application
- Software the user runs in this directory (running Claude Code inside this repo causes it to read this blueprint's CLAUDE.md instead of the user's project rules; a common newcomer mistake)
Repository layout
| Path | Purpose |
README.md | Entry point for humans |
AGENTS.md | This file: entry point for AI assistants |
CLAUDE.md | The "hero file": the user copies this to ~/.claude/CLAUDE.md (global, applies to every project) |
GETTING-STARTED.md | Beginner walkthrough |
SETUP.md | Install paths (curl, setup.sh, manual) |
FAQ.md | Common questions |
TROUBLESHOOTING.md | Common errors and fixes |
setup.sh | Interactive installer |
agents/ | 12 reusable agent templates the user can drop into ~/.claude/agents/ |
skills/ | 19 reusable skill templates for ~/.claude/skills/ |
hooks/ | 15 hook scripts for ~/.claude/hooks/ (plus test-hooks.sh, the local test harness; not deployed) |
rules/ | 6 example rule files for ~/.claude/rules/ |
examples/ | Reference settings.json template (framework-agnostic) |
memory/ | Built-in memory system: enabled via setup.sh (Y/n), git-ignored by default for privacy |
docs/ | Deep reference docs (architecture, benchmarks, settings, etc.) |
i18n/ | Translated READMEs (ja, ko, zh) |
How to help the user
If the user asks "what is this?": explain it's a library of copy-paste files, not software to install. Point them to README.md.
If the user asks "how do I set this up?": ask their skill level first (beginner / experienced). Beginners -> GETTING-STARTED.md. Experienced -> SETUP.md or ./setup.sh --preset=standard.
If the user has cloned this repo and wants to start working in it: warn them. The repo is a reference, not a workspace. They should copy files into their own project, not work in this directory.
If the user asks about persistent memory: explain that ./memory/ is a built-in opt-in feature. Running ./setup.sh asks "Enable persistent memory? [Y/n]" with Y default. When enabled, Claude remembers preferences and session context across sessions on this machine. Personal memory content is .gitignored by default; it stays local even if the user pushes their fork publicly. Point to memory/README.md for details. The memory pattern was inspired by Kiyoraka/Project-AI-MemoryCore; see the acknowledgement in README.md.
If the user asks about a specific component (agents/skills/hooks/rules): point them to agents/README.md, skills/README.md, etc.; each folder has its own README.
If the user asks "is this for me?": framework-agnostic, works on any project, any skill level. The README's "Who Is This For?" persona table is the quickest match.
What NOT to do
- Don't run
claudeCLI inside this repo's directory; it loads this CLAUDE.md instead of the user's - Don't suggest the user
npm installorpip installanything; there's nothing to install - Don't recommend the user fork the entire repo if they only need 1-2 files; copy is fine
- Don't claim this is "official Anthropic"; it's a community project by faizkhairi
- Don't suggest committing
memory/contents to a public repo; the.gitignoreexists for a reason - Don't treat these files as the user's own config; they're templates the user adapts
Version
Last verified with Claude Code CLI v2.1.150 (May 2026).
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.