If you use Codex, Claude Code, or another coding agent long enough, AGENTS.md and CLAUDE.md tend to grow for a very understandable reason: every failure leaves behind one more rule.

The agent changed files outside the requested scope, so you add “do not touch unrelated files.” It claimed a task was done without running the test, so you add “show real verification output before completion.” A migration failed and cleanup removed the evidence you needed to debug it, so you add another safety rule. None of those rules is unreasonable on its own. The problem shows up six months later, when the root instruction file has quietly turned into a mixture of engineering handbook, incident history, workflow checklist, and project memory.

What eventually bothered me was not the raw line count. It was the fact that everything had become always-on. A documentation edit could still drag in frontend boundaries, release procedure, protocol constraints, and database warnings. The same rule might appear once in the root file, again inside a Skill, again in docs, and once more in CI. At that point the harder question is no longer “is this documented?” It is “who actually owns this rule?”

That is why Nession’s issue #1437 caught my attention. The repository had a root CLAUDE.md of roughly 760 lines, and instead of shaving paragraphs off the same file, the project reorganized instructions into root guidance, scoped owners, Skills, and executable gates. The implementation landed in PR #1442.

I did not want to turn that issue into a translated case study. The interesting questions were more practical: how much did the always-on surface actually shrink, could the new boundaries be enforced by CI, and do the current Codex and Claude Code loading rules still match the assumptions people repeat from older posts?

So I took the pinned commits before and after the migration, measured them through the GitHub API without executing third-party code, and then built a small instruction-contract validator in my own Content Lab. The conclusion I kept coming back to was simpler than “keep CLAUDE.md under N lines”:

Every durable agent rule needs an owner, a loading boundary, and—when possible—a machine-checkable contract.

The real problem is not that one file has 760 lines

If line count were the only issue, splitting the document would be easy. Moving 700 lines from CLAUDE.md into another file that is still loaded on every task makes the repository look cleaner without changing much.

I now think of the root instruction file as the smallest layer that almost every task genuinely needs. Global safety boundaries belong there. The project’s top-level goal belongs there. The rule for how deeper instructions are discovered belongs there. But if a constraint only matters under web/, it is more natural to let that directory own it. If something describes a repeatable process such as staging a release or doing code review, that is closer to a Skill. And if a rule can be checked deterministically—root file budget, duplicate Skill names, broken compatibility links—I would rather have CI reject the regression than keep asking the agent to “remember carefully.”

That changes the question from “how should AGENTS.md and CLAUDE.md be divided?” to “what does each instruction surface own?”

The root is one owner. A scoped instruction file is another. Skills connect repeatable workflows. Docs keep detailed rationale that does not need to stay in the prompt all the time. Code and CI own the constraints that are cheap and reliable to verify automatically.

This is also why I do not think the answer is “put everything into Skills.” A Skill can become another encyclopedia just as easily as a root prompt can. When I look at a rule now, I ask very plain questions: would this still matter if I were only editing README? Does it only apply after entering one part of the repository? Is it a workflow that repeats? Can software decide whether it is valid without asking a model?

Nession’s migration is useful because the knowledge did not disappear. It gained locality. The root got smaller while the number of scoped owners increased. That is very different from simply deleting documentation.

I re-measured the migration from the pinned commits

To avoid relying only on the PR’s reported numbers, I did not run Nession’s own scripts. My analyzer read the tree and blob objects for two immutable GitHub SHAs. The pre-migration snapshot is 2d57f38ca917a327e5e4bdd7545d1e5dc90bc0bb, and the post-migration snapshot is 7d89c460ea302ea3eeb4380341055b6f2a1da39c. It never checked out the repository and never executed third-party hooks, packages, or workflows.

The root instruction surface dropped from 760 lines to 116, or about 84.74%. Character count dropped from 55,160 to 5,734. Across eight main Skill entrypoints, the total went from 4,079 lines to 1,327, about a 67.47% reduction.

Metric	Before	After	Reduction
root instruction lines	760	116	84.74%
root decoded characters	55,160	5,734	89.60%
8 Skill entrypoint lines	4,079	1,327	67.47%
8 Skill entrypoint characters	161,324	42,710	73.53%

The table is easy to over-read. It does not mean the repository suddenly had only 116 lines of useful instruction, and it definitely does not mean token cost fell by 84%. After the migration, root, Web, protocol, agent runtime, design, scripts, GitHub workflows, and docs each had their own canonical AGENTS.md owner. The knowledge was still present; less of it was forced into every task by default.

That is the part of progressive loading I find genuinely valuable. The goal is not to win a contest for the shortest CLAUDE.md. It is to keep the always-on layer small enough that task-specific knowledge can be loaded closer to where it matters.

I also used the migration as an excuse to test whether this kind of structure could be protected without another giant policy document. The validator I wrote is intentionally generic. It looks at an abstract instruction graph and checks things like root budget overflow, editable compatibility copies, broken local links, duplicate Skill names, missing frontmatter, scoped compatibility files without a canonical owner, and symlinks that no longer point anywhere.

I built positive and negative fixtures for those cases, and all eight behaved as expected. That is not sophisticated software, but it changed how I think about the problem. A surprising amount of instruction hygiene can be guarded by a few hundred lines of ordinary deterministic code instead of more prose telling the agent to be careful.

Codex and Claude Code make the compatibility layer less obvious than it looks

At this point it is tempting to settle on one neat directory shape:

AGENTS.md
CLAUDE.md -> AGENTS.md
.agents/skills -> .claude/skills

Nession uses a compatibility layout in that general direction, but I would not publish it as the universal answer.

OpenAI’s current Codex prompting guide documents AGENTS.md discovery from higher-level locations down toward the working directory, with deeper instructions later in context. That gives the “small root + scoped AGENTS.md” approach a solid basis.

Skill paths are less safe to hard-code as one eternal standard. Current OpenAI material shows more than one repo-scoped pattern depending on the product or migration path. The Skill evaluation article and the Claude Agent SDK migration guide are enough to make one thing clear: the stable design principle should be ownership and compatibility mapping, not worship of one directory name.

Claude Code has also moved. Its current memory and instruction documentation supports AGENTS.md directly while still recommending that CLAUDE.md stay concise—roughly under 200 lines as a target. Path-scoped rules can carry local constraints, and multi-step workflows fit better in Skills. The Skills documentation also follows the same progressive-loading idea rather than keeping every Skill body permanently in context.

That means “every cross-agent project must keep CLAUDE.md -> AGENTS.md” is too strong. If both files exist, behavior can depend on version and project instruction settings. Symlinks are convenient on macOS and Linux, but Windows adds Git checkout and editing caveats.

I would rather maintain a small compatibility matrix: what is canonical, what is an adapter, which Skill paths the exact client version discovers, and what the Windows fallback is. Paths are implementation details. Ownership is the architecture.

If I reorganized a repository today, I would start with ownership, not syntax

For a small project that is just starting to use coding agents, I would not create ten instruction directories on day one. If a few dozen lines of AGENTS.md are enough, keep it that simple.

The point where I would actually refactor is when the warning signs repeat: the root file starts looking like an internal manual, the same rule shows up in root/Skills/docs, directory-specific constraints interfere with unrelated work, or the only response to every new agent failure is “add another sentence to the prompt.”

At that point I would ask who owns each rule. Global constraints stay near the root. Directory-specific invariants move closer to the code they govern. Repeatable procedures become Skills. Long explanations go back to docs. Deterministic constraints become validators or CI gates.

And I would be especially careful with high-consequence rules. If a failed migration must preserve evidence, a release must run a specific gate, or one directory must never contain mock implementations, natural-language reminders should not be the only line of defense. Prompt text can explain why. A Skill can guide the workflow. The final guardrail should be executable when it can be.

That is as far as this experiment goes. I can verify the structural reduction in Nession’s root and Skill entrypoints, and I can verify that a small instruction-graph validator catches a useful set of regressions. I did not run a full authenticated Codex/Claude Code client benchmark here, so I am not claiming a measured improvement in task success or token usage.

But it changed one habit for me. When AGENTS.md or CLAUDE.md starts growing again, I no longer ask first, “how do I write these 500 lines more cleverly?” I ask how many of them should not be always-on in the first place.

If you are also pushing Codex deeper into your daily workflow, What Changed in the New Codex: Why It Feels More Like a Dev Environment is a useful companion. If you care more about the engineering layer around permissions, context, memory, and guardrails, What the Claude Code Source Leak Teaches Us About Harness Engineering sits even closer to this problem.