The entry file for AI agents in the repository I work on says the approved architecture has eleven services. The conventions file it links to says thirteen. Nobody was wrong on the day either sentence was written. The number was true when someone copied it into the entry file. Later the conventions file was updated, and the copy wasn't.
That is the whole problem of instructing coding agents, in one line: a copy is a fork with no merge step. Every time you paste a rule into a second file, you create a second version that will quietly diverge the first time someone edits only one of them. With agents, the stale copy doesn't sit unread in a wiki. It gets loaded into the model's context and acted on.
This is the setup I use so that several agents (Claude Code, Codex, OpenCode, now and then Gemini CLI) work from one rulebook: thin entry files, one owned rules directory with an authority order, skills for procedures, evidence labels, a small consistency check, and hooks for the rules that must actually hold. It is the second habit in this series. The first was keeping Git in human hands.
Why do instructions for AI agents drift?
Start with what each tool actually reads. Every coding agent looks for a file with a particular name when a session starts, and the names differ:
| Tool | Reads by default | Detail that matters |
|---|---|---|
| Claude Code | CLAUDE.md |
Reads AGENTS.md only when no CLAUDE.md exists |
| Codex | AGENTS.md |
Root down to the working dir, 32 KiB cap by default |
| OpenCode | AGENTS.md |
Falls back to CLAUDE.md |
| Gemini CLI | GEMINI.md |
The file name is configurable |
I checked these against each tool's documentation in October 2026. They change from release to release, so check again before you rely on them.
A repository that more than one tool works in therefore ends up with at least two entry files. The obvious move is to make each one complete: paste the coding standards into CLAUDE.md, paste them again into AGENTS.md, maybe a third time for Gemini. Every agent sees everything. On day one it works.
On day thirty someone tightens a rule, say where API documentation must live, and edits the file for the tool they happen to use. The other copies still say the old thing. The agent that reads a stale copy isn't disobeying. It follows its instructions perfectly. There's no error, no warning and no merge conflict, because the fork happened and nothing exists to merge it back.
Picture the directory board in an office lobby. A good board says Accounting, 4th floor. It doesn't list Accounting's phone extensions, opening hours and holiday schedule, because the day Accounting changes its hours the board is wrong, and nobody on the fourth floor remembers the board exists. The board's only job is to point. Entry files for agents should be lobby boards.
What should CLAUDE.md and AGENTS.md contain?
In the repository, CLAUDE.md is 22 lines. It opens by naming the two files that own the rules, and then says outright that it stays short so it can't drift from them. The rest is a few working-agreement lines about how Claude Code should behave, each traceable to an owner. Here's its shape, renamed and trimmed:
# CLAUDE.md
Project rules live in [docs/rules/README.md](docs/rules/README.md) and
[docs/rules/code-standards.md](docs/rules/code-standards.md). This file
stays short so it cannot drift from them.
## Working agreement
- Do not stage, commit, push, rebase or switch branches; a human owns Git.
- Work only in the requested scope and preserve unrelated changes.
- Public client contracts are REST/JSON; gRPC and Kafka stay internal.
- Canonical docs live in `docs/`, never inside the submodules.
## Before you report completion
Verify against the evidence level the rules define and state gaps explicitly.AGENTS.md, which Codex and OpenCode read, is 120 lines. It has the same pointers plus a repository map, submodule commands, a table of where each kind of commit goes, common commands and a list of hard rules. Some of that belongs there: a map of the repository is navigation, and navigation is the board's job. But two things in it show exactly how drift gets in:
- It repeats the detached-HEAD warning and the submodule commands that the Git workflow file already owns.
- It holds a fact, the service count, instead of a link to where that fact lives. That's the sentence that went stale.
The lesson I took from it: an entry file may hold navigation and tool-specific behaviour. It must not hold facts or rules that another file owns. A link can break, and a script can find a broken link. A stale fact looks exactly like a fresh one.
Should you link the rules or import them?
Pointers come with a catch. A Markdown link is a suggestion, and the agent has to decide to open it. Claude Code also supports @path/to/file imports inside CLAUDE.md, which expand the file into context at launch. An import guarantees the content is seen, but you pay for it in every session, whether the task needs it or not.
My rule of thumb is to import the few lines every task needs (the working agreement, the authority order) and link everything else. If you catch yourself importing a 650-line Git workflow into every session, it probably wants to be a skill, not a rule. More on that below.
One more detail: when a repository has both files, Claude Code reads CLAUDE.md and, by default, skips AGENTS.md. If your CLAUDE.md neither imports nor links to the shared owner, Claude is working from a different rulebook from every other agent. Two boards at two entrances are fine. Two boards that send people to different floors are not.
Which rule wins when two files disagree?
Pointing to one place only helps if that place can settle a conflict. The repository's rules index does two things at the top.
First, it names one owner per category:
| Category | Owner file |
|---|---|
| Scope, evidence, language, doc quality | rules/README.md |
| Code structure, naming, framework conventions | code-standards.md |
| Branches, commits, merge requests, submodules | git-workflow.md |
| AI tools, evidence workflow, completion checks | ai-tooling.md |
| Diagrams | diagram-policy.md |
| Transport, identity, data and security invariants | system-conventions.md |
The sentence under the table is the important part: don't create a second policy page for any of these categories. Add the detail to the owner, or link to it.
Second, it states an authority order for conflicts:
- The newest explicit human decision.
- The business requirements.
- The approved target architecture and technology decisions.
- Current source, tests, manifests and lockfiles, as implementation evidence.
- Historical documents, only where nothing newer disagrees.
Source code sits below the architecture decision, which surprised me at first. The reason is that this list answers "what should the system do?" When the code disagrees with an approved decision, the agent may not quietly rewrite either one to match the other. It records an alignment gap and says so. That leads to the second question every agent has to answer. Not "which document wins?" but "how sure am I?"
How do agents say how sure they are?
The same index defines exactly one evidence label per claim: Released, Verified implementation, Prototype observation, Architecture decision, Planned, Alignment gap or Unknown. An agent that writes "the service validates the token" must also say which of those it is. Did it read the controller, run a scoped test, or read an ADR?
Labels belong in a rules article because they turn vague rules into checkable ones. "Don't claim what you haven't verified" is advice. "Every claim carries one of seven labels, and Released requires controller, runtime contract, verification and release evidence" is something a reviewer, or another agent, can check line by line. I cover the labels and the evidence ladder properly in how to verify code an AI agent wrote.
Should it be a rule or a skill?
Rules load on every task, so every line in a rule costs context and attention. Some guidance is needed every time, some once a month. Mixing the two makes the rules file long, and long instruction files are followed less reliably. Claude Code's own documentation suggests keeping each CLAUDE.md under about 200 lines for that reason.
A skill is the other container: a folder with a SKILL.md whose frontmatter carries a name and a description, plus optional reference files and scripts. The agent sees the description up front and loads the body only when the task matches it.
The test I use:
| Question | Rule | Skill |
|---|---|---|
| When does it apply? | Every task | Some tasks |
| What shape is it? | A constraint: never, always | A procedure: steps |
| What if the agent misses it? | Damage | Slower or inconsistent work |
Take one real line from the repository's working agreement: a released API change updates the source, the generated OpenAPI, the public API docs, the Postman collection and the matching sequence diagram together. That constraint is a rule. It applies to every task that touches a public endpoint, and forgetting it ships wrong docs. But how to regenerate OpenAPI, where the Postman builder lives and how to validate its JSON is a procedure, and a procedure belongs in a skill:
---
name: release-api-change
description: Use when a public REST endpoint is added, changed or removed.
Updates generated OpenAPI, the public API page, the Postman collection
and the sequence diagram together, then validates the Postman JSON.
---
# Release an API change
1. Confirm the controller route and DTOs in source.
2. Regenerate the runtime OpenAPI document.
3. Update the public API page for the endpoint.
4. Rebuild the Postman collection and parse it as JSON.
5. Update the matching sequence diagram.
Policy and evidence rules: [AI tooling](../../../docs/rules/ai-tooling.md)The rule says what must be true. The skill says how to make it true, and it links back to the owner instead of restating it.
How do you write a skill description that triggers?
The description is the only part of a skill the agent sees before deciding to use it. It isn't a summary for humans; it's the trigger. Start with "Use when…", describe the situation in the words someone would actually use when asking ("public REST endpoint", "Postman"), and say what the skill produces. A description like "API helper" will either never fire or fire for everything.
How do skills keep the context window small?
This is progressive disclosure, and the repository's numbers make it concrete. It has 46 skills installed under .agents/skills, all from one open-source workflow framework. Their files add up to about 1.6 MB across 234 files, and the SKILL.md bodies alone run to almost 6,900 lines. The descriptions, the only part that's always visible, total under 8 KB.
So the agent pays under 8 KB per session to know that 46 procedures exist, and pays for a body only when it uses one. Inside a large skill the trick repeats: the body points to one step file at a time, and the agent loads step two when it gets to step two.
Rules get the same three layers. The entry file is always in context, the rules index is read when relevant, and an owner file such as the Git workflow is opened only when the task touches Git. Claude Code adds one more middle layer: path-scoped rules in .claude/rules/, which load only when the agent works on matching files. Small things are paid for on every task; big things only when used.
Can a skill just point somewhere?
Yes, and it's often the best kind. The repository's Gemini CLI skill is one paragraph that exists only to send the agent to the canonical Git workflow. A skill that says "for Git, read this file" is a lobby board that appears exactly when someone asks about Git. It costs one description line and duplicates nothing.
Are skill folders per tool too?
They are, and the drift problem comes straight back. Codex scans .agents/skills. OpenCode searches .opencode/skills, .claude/skills and .agents/skills. Claude Code's documentation lists .claude/skills. Put the skills in one folder and a tool that looks elsewhere won't see them, with no error. If two tools need the same skill, keep one source, link or generate the second location, and then check each tool's skill list to confirm it actually loaded.
How do you check the rulebook hasn't rotted?
Rules about rules ("keep entry files thin", "don't duplicate") decay like any other prose. In the repository they live in a completion checklist that agents are asked to read and nothing executes. A check that runs is better. Here's a small one in Node, with no dependencies, run from the repository root:
// scripts/check-agent-docs.mjs
// Fails when an entry file outgrows its budget, links to a missing file,
// or a skill's frontmatter does not match its folder.
import { existsSync, readFileSync, readdirSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
const ENTRY_FILES = ["AGENTS.md", "CLAUDE.md"];
const MAX_ENTRY_LINES = 60;
const SKILL_ROOTS = [".agents/skills", ".claude/skills"];
const MARKDOWN_LINK = /\[[^\]]*\]\(([^)#\s]+)[^)]*\)/g;
const EXTERNAL_URL = /^[a-z][a-z0-9+.-]*:/i;
const problems = [];
for (const file of ENTRY_FILES.filter((path) => existsSync(path))) {
const text = readFileSync(file, "utf8");
const lineCount = text.trimEnd().split("\n").length;
if (lineCount > MAX_ENTRY_LINES) {
problems.push(`${file}: ${lineCount} lines, budget is ${MAX_ENTRY_LINES}`);
}
for (const [, target] of text.matchAll(MARKDOWN_LINK)) {
if (EXTERNAL_URL.test(target)) continue;
if (!existsSync(resolve(dirname(file), target))) {
problems.push(`${file}: broken link -> ${target}`);
}
}
}
for (const root of SKILL_ROOTS.filter((path) => existsSync(path))) {
for (const folder of readdirSync(root)) {
const skillFile = join(root, folder, "SKILL.md");
if (!existsSync(skillFile)) continue;
const frontmatter = readFileSync(skillFile, "utf8").split("---")[1] ?? "";
const name = frontmatter.match(/^name:\s*['"]?([^'"\n]+)/m)?.[1]?.trim();
if (name !== folder) problems.push(`${skillFile}: name "${name}" != folder`);
if (!/^description:\s*\S/m.test(frontmatter)) {
problems.push(`${skillFile}: missing description`);
}
}
}
if (problems.length > 0) {
console.error(problems.join("\n"));
process.exit(1);
}
console.log("agent docs: ok");Run against the repository, it reports exactly one problem and exits with code 1:
$ node scripts/check-agent-docs.mjs
AGENTS.md: 120 lines, budget is 60Every link in the entry files resolves, and all 46 skill names match their folders. The 60-line budget is my number, not a standard. Pick your own and make it fail loudly.
What the script can't catch is the stale "eleven services" sentence. A wrong fact that's well formed passes every syntax check. Only the rule "entry files hold no facts" prevents it, and only a reviewer enforces that rule. Know which of your rules a script can check and which ones only a person can.
Can a rules file stop an agent from doing something?
No. Everything so far is text the model reads, and text is advice. Claude Code's documentation says so directly: instruction files are treated as context, not as enforced configuration, and to block an action regardless of what the model decides you use a PreToolUse hook.
Back in the lobby: the board can say "no deliveries through the main entrance", but it's the guard at the turnstile who actually stops the courier.
The previous article used permission deny rules for "agents never write Git history". A hook is the more general guard: a script sees the whole command and can apply any logic you can write. Register it in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-git-writes.sh"
}
]
}
]
}
}The script reads the pending tool call as JSON on stdin. Exiting with code 2 blocks the call, and whatever it writes to stderr goes back to the agent as the reason:
#!/usr/bin/env bash
# PreToolUse hook: refuse Git commands that write history or move branches.
command=$(jq -r '.tool_input.command // empty')
pattern='(^|[;&|(][[:space:]]*)git([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+(add|commit|push|tag|merge|rebase|reset|switch|checkout)([[:space:]]|$)'
if [[ "$command" =~ $pattern ]]; then
echo "Blocked: Git is human-owned here. Leave changes unstaged and report them." >&2
exit 2
fi
exit 0I fed it a handful of commands. git status, git diff --stat and git log --oneline pass. git commit -m x, cd backend && git push, git -C backend checkout main and pnpm test; git add . are blocked. echo git commit passes, as it should.
Be honest about what this is: a guard rail against mistakes, not a security boundary. A regex over a command string can be sidestepped with sh -c, an alias or a script that calls Git internally. Pair it with things the model can't talk its way around: no push credentials in the agent's environment, and protected branches on the remote. Other tools have their own levers, such as sandbox modes, approval policies and permission rules. The principle is the same everywhere: a rule that must hold needs a mechanism, not a sentence.
What does this setup cost?
- Indirection. A linked rule is only followed if the agent opens the link. For rules every task needs, you either import them and pay for the context in every session, or accept that some sessions won't read them.
- One owner means one blast radius. Editing
system-conventions.mdchanges the behaviour of every tool at once. That's the point, and it's also why owner files deserve the same review as code. - Descriptions are always on. Forty-six descriptions at about 170 characters each is cheap. Hundreds of them, or several that look alike, make the agent worse at picking one. Bulk-installed skill packs also widen what you have to review: a skill can ship scripts, so read what you install.
- Per-tool plumbing. Different file names, skill folders and fallback rules, all moving from release to release. Someone has to re-check them, and the table at the top of this article will age.
What would I do differently?
- Keep facts out of entry files from day one. The one real drift I found came from a single fact copied into
AGENTS.md. A link would still be correct today. - Ship the hook together with the rule. In the repository, "agents never commit" is still prose. No hook is configured there, so nothing in the repository itself would stop an agent that ignored the sentence.
- Run the consistency check in CI, rather than leaving it in a checklist an agent is asked to remember.
- Budget
AGENTS.mdlike code. Much of its 120 lines is useful navigation, but the duplicated submodule section should become a link to the Git workflow, or a router skill. - Install skills on purpose. I'd rather have ten skills written for this repository than a pack of 46 where I can't say which ones ever fire.
Key takeaways
- A copied rule is a fork with no merge step, and agents act on the stale copy without any error.
- Entry files such as
CLAUDE.mdandAGENTS.mdare lobby boards: navigation and tool-specific behaviour only, no facts, no rules owned elsewhere. - Give every rule category one owner, write down an authority order for conflicts, and attach one evidence label to every claim.
- Rules are constraints needed on every task. Skills are procedures that load when their description matches.
- Progressive disclosure keeps 46 skills down to under 8 KB of always-on context in the repository.
- Script what can be checked. Enforce what must hold with hooks, permissions and credentials, because prose only advises.
Once every agent reads the same rulebook, you can start handing work between them with briefs that stand on their own.