AI coding agent spec files, five layers a shipping repo uses

Why the single-file frame is incomplete

The current crop of writeups treats CLAUDE.md, AGENTS.md, and Copilot Instructions as three competing formats. Pick one, write a good one, ship. The framing comes from the early Claude Code days when a single project file was genuinely the whole spec surface. That frame is still useful for a tiny repo. It breaks the moment you have more than one named procedure to teach the agent, more than one ephemeral state that affects the next decision, or more than one machine the same project runs on.

The break happens for a reason. CLAUDE.md is always loaded into context. Every token in it pays rent on every conversation, every subagent, every cron. If you inline a 400-line release procedure into CLAUDE.md, every chat about an unrelated bugfix carries those 400 lines for no reason. The frontmatter-described procedure file fixes that by deferring the load. If you inline runtime state into CLAUDE.md ("the app is currently running at pid 49281"), the file is wrong five seconds later. The status file fixes that by being read fresh.

The frame that actually fits production is: one always-loaded brief, a library of on-demand procedures, a small number of runtime state files, a memory dir the agent writes to itself, and a settings file the harness reads. Same building blocks every major coding agent gives you, used together rather than interchangeably.

The five layers

Each layer answers a different question. Together they describe everything a coding agent needs to know about a repo and the machine running it.

What the numbers actually look like in a shipping repo

The Fazm desktop app is an open-source Mac agent. The repo is at github.com/mediar-ai/fazm, MIT licensed, so you can clone it and re-run the counts. As of 2026-05-11 the spec-layer counts are:

Generated with wc -l on the working tree. The 311-line CLAUDE.md covers project shape and the hard rules an agent needs across every task. The 47 procedure files cover concrete workflows (release, codesign, sentry triage, db migration, build-fix, test-local, user-issue-triage, etc.) that load only when the description matches. Both numbers grow slowly; neither is a stop-the-world rewrite at any single moment.

Layer 1, root context

The always-loaded file. Claude Code reads it from ~/.claude/CLAUDE.md (your global rules), ./CLAUDE.md (the repo root), and any nested CLAUDE.md under a subdirectory. AGENTS.md is the vendor-neutral equivalent that Cursor, Codex, Gemini CLI, Aider, Windsurf, Warp, and others all read. Same idea. The right contents are project shape, conventions, hard rules, common commands, and pointers to deeper files. The wrong contents are long procedures, large reference tables, and anything that changes between sessions.

A good test for what belongs in this file: would a new contributor (human or agent) need this on day one of every task. If yes, it goes in. If it is only relevant to one workflow, it belongs in a procedure file. The Fazm CLAUDE.md picks this trade-off by mostly enumerating sections (Inbox Pipelines, Routines, Logs & Debugging, Release Pipeline) with the high-level shape, then pointing at deeper skill files for the long stuff.

Layer 2, named procedures

The on-demand library. Each file is a small markdown doc with a frontmatter header that includes a name and a description. The agent loads the file when the user's request matches the description. The trick that makes this work is the description itself: it lists the actual phrases or intents that should trigger the procedure, so the agent picks it without having to guess. Here is the frontmatter of the test-local skill from the Fazm repo, so you can see what a real one looks like:

The body of a procedure file is whatever the agent needs to execute the named workflow correctly: command catalog, common pitfalls, expected outputs, decision tree. Procedures stay long because they only load when matched. The Fazm .claude/skills/test-local/SKILL.md is 210 lines; the .claude/skills/user-logs/SKILL.md is 210; the .claude/skills/sentry-release/SKILL.md is in the same range. None of them ride on every conversation.

Layer 3, runtime status files

The newest layer, and the one missing from almost every writeup on this topic. A runtime status file records something the agent needs to know that did not exist when CLAUDE.md was written: is the app currently building, is the dev process up, what pid is the floating bar, did the last build fail and why. The agent reads the file fresh before acting, which means the context never carries stale facts about the live process.

In the Fazm repo the file lives at /tmp/fazm-dev-status. It holds one line of the form state pid unix_timestamp where state is building, running, exited, or failed. The CLAUDE.md tells the agent: always read this file first before running ./run.sh or killing a process; never use pgrep, ps aux, or log tails to guess. The decision tree is short enough to fit in the brief, but the live value is small enough to belong on disk.

The pattern generalizes beyond Mac apps. A web project might write /tmp/project-build-status with the last vercel deploy id. A monorepo might write a per-package lock so multiple agents can coordinate. Anything ephemeral the agent needs to read goes here. The contract is just "a small file the agent can stat and parse in one shell command," and the value is that CLAUDE.md stops accumulating stale text about live state.

Layer 4, the memory directory

CLAUDE.md is the policy you wrote for the agent. The memory directory is the notebook the agent keeps about you. Claude Code uses ~/.claude/projects/<project-path>/memory/ with a MEMORY.md index file and one markdown file per memory. Each memory file has a small frontmatter (name, description, type) and a body. The types are user (who is working with me), feedback (corrections to apply going forward), project (initiatives, why things are happening), and reference (where to look in external systems).

The reason this is separate from CLAUDE.md is authorship and decay. CLAUDE.md is hand-authored and stable; you change it deliberately. Memories are agent-authored and decay fast. A memory written six months ago about "the auth flow lives in AuthService.swift line 735" should be re-verified before acting on it, because the file may have changed. The split lets the always-loaded brief stay durable while the volatile notes live somewhere the agent can audit and rewrite without touching policy.

Layer 5, settings.json

The harness configuration. Not context the agent reads, but configuration that the runtime running the agent enforces. .claude/settings.json is committed and shared with the team; .claude/settings.local.json is gitignored for personal overrides. The file holds tool permissions (which commands run without prompting), hooks (shell scripts that fire on events like PreToolUse, PostToolUse, Stop), env vars, the default model, and a handful of behavioral knobs.

A common confusion to flag: instructions like "always run tests after editing X" do not belong in CLAUDE.md as a plain-text rule. The agent will mostly comply, but not deterministically. They belong in settings.json as a PostToolUse hook that fires on every Edit and runs the test command. CLAUDE.md tells the agent what to do when it has a choice; settings.json tells the harness what to do regardless of the agent. The split is policy versus enforcement.

A five-minute audit of any repo

The fastest way to know whether a codebase is set up for AI coding agents at production scale is to walk the five layers. Each one is a single shell command. If a layer is missing, that is fine; what matters is which layers are there and which are carrying weight they shouldn't.

How to actually start writing them

If you are starting from zero, write CLAUDE.md (or AGENTS.md, if your team uses more than one agent) first. Keep it under 200 lines. Cover project shape, conventions, hard rules, common commands, and pointers to deeper files. Resist the urge to inline procedures. The goal is the brief a new contributor reads on day one.

Add SKILL.md (or commands/) files the second time you find yourself explaining the same workflow to the agent. Each file gets a frontmatter description that lists the phrases that should trigger it. The procedure body can be long because it only loads when matched. Anti-pattern: a CLAUDE.md that grows past 400 lines because every procedure was inlined.

Add runtime status files when you notice the agent guessing about live state from logs or ps output. Pick the smallest file that answers the question (one line with state, pid, timestamp is usually enough). Tell CLAUDE.md to read it before acting.

Let memory accrue on its own; do not pre-write entries. Periodically (every few weeks) read MEMORY.md and prune anything that turned out wrong or stale. The signal that the system is working is that the agent stops needing to re-learn things across sessions.

Touch settings.json last. Start with permissions (the commands you trust the agent to run without prompting). Add hooks when you notice a rule the agent keeps forgetting; the hook makes compliance deterministic rather than aspirational. A clean settings.json with five entries is better than a messy one with fifty.