DEV Community: Gábor Mészáros

State of AI Instruction Quality: Repos Split on Co-Authored-By

Gábor Mészáros — Tue, 20 Oct 2026 12:40:48 +0000

The 10,000 most-starred repos split on whether their coding agent should sign its commits.

About 400 tell it to leave its name off. One of the most-starred web frameworks puts it in its CLAUDE.md:

Do NOT add "Generated with Claude Code" or co-author footers to commits or PRs

About 330 ask for the opposite: an Assisted-by: line or an AI co-author trailer, often inside a commit template the agent is told to follow. And about 30 of the repos that rule out the co-author line ask for Assisted-by: in its place.

What the rules go after

Mostly the trailer. More than half of the matches in the 465 repos with a rule against it name Co-Authored-By itself. In 295 of them the rule mentions commits, and in 112 it mentions pull requests. Two-thirds of the matches sit in main files like CLAUDE.md and AGENTS.md, which load in every session.

Most of these rules name no agent at all: 283 of the 465 repos write "no co-author trailer" or "no AI attribution" in general. 146 name only Claude. 36 name another agent, most often Codex, then Copilot and Cursor:

No Co-authored-by: Copilot or any other co-author line. Ever.

The vendor-neutral file carries Claude-specific rules too. 77 of the 273 matches in AGENTS.md name Claude.

Who writes them

A rule about commit trailers matters once the agent makes commits, and the repos that write one run bigger, more built-out setups. Their median repo has 4 instruction files, against 2 across the report. 60% write for more than one agent, against 43%, and 17% ship an agent hook, against 7.6%.

They write firmer instructions too: 4.2 hedged instructions per 100 ("should", "try to") against 5.1, lower at every repo size.

Some want a different disclosure

137 repos ask for an Assisted-by: trailer, and about 30 of the repos that rule out the co-author line say to use Assisted-by: instead. The Rust compiler repo, rust-lang/rust, has both in one passage of its AGENTS.md:

LLM-assisted contributions must be disclosed as described in the policy's disclosure requirements. Lying about or concealing LLM use is a Code of Conduct violation. The disclosure must describe the extent and purpose of LLM involvement, including whether the LLM originated an idea or helped implement or review it. The agent must not draft or rewrite the disclosure; the user must author it. Do NOT add Co-Authored-By trailers to commits.

Its last sentence reads like the framework's rule. The sentences above it give the reason: the project wants a person to write the disclosure.

The trailer is a default

Claude Code adds it unless told otherwise. Its settings docs: "Commits get a git trailer such as Co-Authored-By by default; pull request descriptions get plain text." Cursor's agents add a "Made with Cursor" trailer to commits and pull requests, on by default, with a switch in its settings and one for team admins. Cursor's staff add on its forum that a rule won't remove it, because the trailer "is added by Cursor at the tooling level, not by the model".

Cloud agents reverse the roles. GitHub's docs: Copilot cloud agent's commits "are authored by Copilot, with the developer who assigned the issue or requested the change to the pull request marked as the co-author". Cursor's cloud agents commit as Cursor Agent and add the person who started the session the same way, and per Cursor's staff that can't be turned off yet.

In Claude Code, a setting turns it off. In the project's .claude/settings.json:

{
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

That's the form repos use: 49 set commit to an empty string and 44 set pr. Claude Code v2.1.281 and later also take "attribution": false, but earlier versions reject that value and skip the whole settings file that holds it. The strings can also carry your own text, such as an Assisted-by: line.

64 repos turn attribution off in a committed setting, and 54 of them write no rule about it at all. Of the 465 with a rule, 10 also use the setting.

The rule works too. The docs say "Claude Code tells Claude that your own instructions about attribution, such as a CLAUDE.md or memory rule, take precedence over these commit and PR lines". The setting changes what Claude Code adds in the first place, so it holds whether or not the agent follows the rule. Settings can also live in each developer's own ~/.claude/settings.json, which a repo snapshot can't see.

A hook catches the rest

A git commit-msg hook runs after the agent, or the tool behind it, has written the message, so it holds for every agent that commits on your machine. Some repos already run one ("the commit-msg hook will reject it", one CLAUDE.md warns), and Cursor's staff point to it as the workaround for the trailer its tooling adds. This one deletes AI attribution lines and keeps human co-authors:

#!/bin/sh
# .githooks/commit-msg
pattern='^(co-authored-by|made-with):.*(claude|copilot|cursor|codex|gemini|anthropic\.com)|generated with \[?claude code'
{ grep -viE "$pattern" "$1" || true; } > "$1.tmp" && mv "$1.tmp" "$1"

Commit it, make it executable, and run git config core.hooksPath .githooks once per clone. It covers commits only, so pull request text still needs the settings, and it can't reach cloud agents, which commit on the vendor's machines. In Claude Code, a PreToolUse hook can also refuse a commit command that carries the trailer before it runs; Prompts steer, hooks enforce covers how.

A rule every agent reads

The setting is Claude Code's. A rule in AGENTS.md reaches every agent that loads the file, which is the reason to keep one when the repo serves more than one agent. Where the tool adds the trailer itself, as in Cursor, the rule states the policy and the setting or the hook carries it out. Written with the directives first, then context, and the constraint last, it could read:

- Write commit messages in the format described in `CONTRIBUTING.md`.
- Add an `Assisted-by:` trailer only with text the user gives you.
- The project records AI assistance through the person committing the change.
- *Never add your own name to a commit or pull request.*

The constraint is in italics and rules out the trailer without naming it. In a CLAUDE.md of their own, these lines score 9.4 on ails check.

Check yours

The checker scores an attribution rule like any other instruction. The framework's rule quoted at the top draws a finding for a constraint written outside italics. Each run checks one agent's files; the second command switches to Copilot, and cursor, codex and antigravity (for GEMINI.md) work the same way.

npx @reporails/cli check
npx @reporails/cli check --agent codex|cursor|claude #whichever you are using

To find every attribution line, including rules that ask for a trailer and the attribution setting itself:

grep -niE "co-?authored|assisted-by|attribution|generated (by|with)" CLAUDE.md AGENTS.md .claude/settings.json 2>/dev/null

Read what comes back as one policy: what the agent may sign, where, and whether it lives in a sentence the agent reads or a setting it can't skip.

From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot. The data behind the series is in the 2026-Q3 folder of reporails/reports.

A rule against the trailer counts when a line in an instruction file, outside code blocks, has "never", "do not", "don't", "avoid" or "no" followed within 50 characters by "co-authored", "attribution", "mention of Claude/AI/Anthropic" or "generated by/with Claude/AI": 465 of the 9,784 repos with a setup. In a hand-read sample of 40 distinct matching lines, 35 were AI-attribution rules; the rest used "attribution" in another sense, such as data or citations, so "about 400" stands for the 465. An ask counts when an instruction or a commit template in an instruction file asks for an Assisted-by: or AI co-author trailer: 327 repos, with 28 of 30 hand-checked asks real, so "about 330". Settings counts read the .claude/settings.json and .claude/settings.local.json files committed to the repo, 978 files in 959 repos.

I work on Reporails, deterministic diagnostics and governance for the instruction files, rules, and prompts that steer coding agents. It reads the instruction files your coding agent loads, from CLAUDE.md to Copilot and Cursor rules, measures which instructions couple to behavior, and points to the lines worth tightening.

State of AI Instruction Quality: Files With Persona Lines Score Lower

Gábor Mészáros — Mon, 19 Oct 2026 12:53:27 +0000

Main instruction files that tell the agent who it is score lower than the rest, at every file size.

One of them opens like this, on line 3 of its CLAUDE.md:

You are a senior [project] engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.

It's a familiar move from prompt writing. In the 10,000 most-starred repos of the Q3 report, 285 main instruction files have a line that starts "You are a", "You are an" or "You are the", across CLAUDE.md, AGENTS.md, GEMINI.md, Copilot's copilot-instructions.md and Cursor's .cursorrules. On ails check's 0 to 10 scale, their median is 6.6, against 7.7 for the other 20,551 main files. Fewer than one in five score 8 or above. Of the rest, more than four in ten do.

Persona files tend to be longer, so we split all main files into four equal groups by size. The gap holds in every group, from 0.9 to 1.25 points.

A file that reads like a prompt

The "You are" sentence itself reads as description to the checker. The difference is in the rest of the file. Nearly half of what a persona file says is instruction (46.6%), against 30.3% in other main files, which spend more of their lines on the repo. After the "You are" comes a list of what the agent does and doesn't do.

Compared with main files of the same size, that list picks up more of most kinds of finding. In the third size group (68 to 127 items), 80% of persona files have a "never" written more strongly than the permission that goes with it, against 49% of the others. 78% have a hedged instruction ("should", "try to"), against 60%. 59% put their instructions in the weaker order, against 40%, 45% have a heading written as an instruction, against 28%, and 25% put the forbidden thing in bold inside a prohibition, against 10%.

The "never" gap holds in all four size groups. In the largest, it reaches 98% of persona files against 75% of the rest. Persona files also carry more prohibitions in the first place: 88% have at least one, against 78%.

The smallest persona files go wrong in a different way. 71% have an instruction too short to register, such as "Be concise", against 48% of small files without the line.

One finding runs the other way. Persona files have less prose crowding an instruction, 4.2 per 100 instructions against 9.9, which fits files that carry less description.

Where the line sits

In 204 of the 285 files, the "You are" line is in the first five lines, so it's how the file opens. Of setups with a main file, 6.0% of Cursor's have the line there, against 3.5% of Copilot's and 1.0% of Claude Code's.

Claude Code's docs say where a CLAUDE.md ends up: "CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself." By the time the file arrives, the agent already has its system prompt.

Sub-agents are different. A Claude Code sub-agent file is YAML frontmatter "followed by the system prompt in Markdown", and the docs' own examples open with a persona line, such as "You are a senior code reviewer…". 57.4% of sub-agent files in the report have one. There it's the convention, and this post leaves it alone.

What to write instead

Ask what the persona line was meant to buy, and write that down. "Senior engineer who prioritizes type safety" can mean running the type checker and keeping the types strict. Each of those can name its tool, one instruction per sentence: the directives first, a line of context, and the constraint last. For the Yarn/Turbo monorepo above, that could read:

- Run `yarn type-check` before you mark a task as done.
- Use `unknown` and narrow it when a value's type is genuinely unknown.
- Strict types are how this repo catches bugs before review.
- *Never loosen a type just to get the build passing.*

The constraint is in italics and comes after the line that says what to do instead. It describes the move it rules out without naming any or @ts-ignore, so neither shows up in the agent's instructions (why that matters). In a CLAUDE.md of their own, these lines score 9.4 on ails check.

Check yours

The checker flags what the persona files carry: a heading written as an instruction, a hedged "should" or "try to", bold on the thing a prohibition forbids and a one-line trait like "Be concise". Each run checks one agent's files; the second command switches to Copilot, and cursor, codex and antigravity (for GEMINI.md) work the same way.

npx @reporails/cli check
npx @reporails/cli check --agent copilot

To find the line itself:

grep -niE "^\s*You are (a|an|the) " CLAUDE.md AGENTS.md GEMINI.md .github/copilot-instructions.md .cursorrules 2>/dev/null

From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot.

"Main files" are CLAUDE.md, AGENTS.md, copilot-instructions.md, GEMINI.md and .cursorrules, each file counted once even when more than one agent's setup loads it: 20,836 files, with the 285 persona files in 189 repos. A file counts when a line outside code blocks starts with "You are a", "You are an" or "You are the". Size groups are quarters of main files by item count, cut at 32, 67 and 127 items; finding shares compare files in the same group. The hedged, ordering and bold-prohibition gaps hold in three of the four groups, and the smallest group ties or reverses.

Claude Code mods: Brickfall, a brick breaker that's loud without getting in the way

Gábor Mészáros — Fri, 16 Oct 2026 13:51:23 +0000

After the Minesweeper and Doom, the third game in the arcade is a brick breaker after Arkanoid. The brief was one word: louder. Sparkle, big numbers, things raining down, a backdrop that shimmers. Brickfall plays in a pane beside the transcript while Claude works.

/bricks opens the pane. In kitty or Ghostty the field is a real picture; anywhere else it is drawn in quadrant block characters, four pixels a cell. You steer with the mouse, and there are thirteen kinds of capsule (laser, split, lightning, a giant ball, a shield of light...), gems that build toward a FEVER of double points, volt bricks that blow up their neighbours in chains, and ten rounds that come round again faster.

Loud, but never in the way

Every hit lands: light bursts where the brick was, the brick swells and burns out, the walls flash its colour, and a big number flies off it. My first loud version also shook the screen. It looked great in a screenshot and was miserable to play, because you can't catch a ball that jumps around with the field. The shake went, and two rules stayed:

nothing moves the field or stops the play, however much is going off
the ball, the paddle and anything falling are drawn on top of every effect, so what you need to catch stays in sight

Every pixel goes through Claude Code

Doom's frames never touch Claude Code: the engine writes a file and Claude Code hands kitty the path. Brickfall has no engine. The game runs inside the mod, so each frame is RGBA bytes handed to an Image:

state.rgba = toRgba(canvas, state.rgba ?? undefined)
state.source = { rgba: base64(state.rgba), width: canvas.w, height: canvas.h }

That makes sharpness a budget. kitty stretches the picture to fill the pane and smooths it as it goes, so the picture is only as sharp as the pixels you send, and every pixel crosses into the terminal on every frame. Brickfall sends about 58,000 a frame:

export const IMAGE_PIXELS = 36000
export const QUALITY = [1.6, 1.25, 1, 0.8] as const

On a busy machine it gives up a little sharpness, never below half (about 29,000), and only when frames stay slow, so a burst of fireworks never costs it. It wins the sharpness back as soon as the sharper step would still draw in time:

const fits = sharper !== null && (cost * sharper) / here < FRAME_BUDGET_MS * 0.75
const slow = cost > FRAME_BUDGET_MS ? pace.slow + 1 : 0
const quick = fits ? pace.quick + 1 : 0
if (slow >= PACE_FRAMES.down && pace.quality < QUALITY.length - 1) return { quality: pace.quality + 1, slow: 0, quick: 0 }
if (quick >= PACE_FRAMES.up) return { quality: pace.quality - 1, slow: 0, quick: 0 }

45 slow frames to step down, 30 quick ones to step back up. An earlier version kept its sharpness fix to the first round, and later rounds went soft; stepping both ways fixed it.

The paddle follows the pointer

In Claude Code's fullscreen layout (CLAUDE_CODE_NO_FLICKER=1) the terminal reports every pointer move, not just clicks and drags. An invisible Client lies over the picture and posts where the pointer is, and the paddle goes there:

if (pad.x !== null && pad.isInside !== false) aim(g, pad.x * W)
if (pad.isInside === false) state.awaySince ??= Date.now()

Move the pointer off the field to read Claude's answer and the game pauses after a moment, so the ball isn't lost while you look away. Bring it back and play goes on. The keys work too (a and d), but a terminal never says when a key comes up, so a held key moves in steps. The mouse is how it's meant to be played.

What recording the clip taught me

The clip above shows Claude reading three files, writing a DOCS.md and running the tests while the game plays. The first takes stuttered: the field froze for over half a second whenever Claude wrote its file.

It wasn't the game. I recorded control takes and logged Claude Code's main-thread CPU four times a second:

take	effects	Claude working	longest freeze
1	on	yes	567 ms
2	off	yes	733 ms
3	on	no	233 ms (the serve pause)

Both freezes landed on the second Claude Code drew its 16-line file write, with the main thread at 92–100% for about three quarters of a second. While it is drawing a big tool result, a mod can't paint. So if you build a mod with animation, expect the hitch when Claude writes a long file. And if you record one, start the game after the big writes.

What it touches

It reads and changes nothing the model sees. claude plugin validate lists every hook and call before any of its code runs:

❯ ./register.ts hooks: session.start, command.run{command=bricks}, ui.render{component=Pane}, ui.message, ui.close, session.end

No prompt, tool or attachment hook, no network call, no child process. The best score is kept in the plugin's own store.

Play it

In a Claude Code session:

/plugin marketplace add reporails/arcade
/plugin install brickfall@reporails-arcade

Then start Claude Code in the fullscreen layout, which the mouse needs, and run /bricks:

CLAUDE_CODE_NO_FLICKER=1 claude

Mods load by default from Claude Code 2.1.287. Use kitty for the real picture; Ghostty speaks the same protocol but I haven't tried it, and every other terminal gets the blocks. It has been played in kitty on Linux, and its 36 tests pass in CI on 2.1.285 and 2.1.288. If you play it on a Mac, Windows or Ghostty, tell me how it went.

The code is MIT, in reporails/arcade on GitHub.

State of AI Instruction Quality: A Third of Repos Shout

Gábor Mészáros — Thu, 15 Oct 2026 10:37:49 +0000

IMPORTANT. CRITICAL. You MUST. NEVER.

A third of the repos in the Q3 report, 3,319 of the 9,784 with an agent setup, write at least one word like these in capitals in their instruction files, 36,482 times between them. It's the most common habit we counted, and the rest of the list reads like a prompt-writing history: emoji, "please", "think step by step", a warning about hallucinating.

Each habit travels with a particular kind of setup, and some with particular findings.

Who has them

The habits live in the big setups. The median repo in the report has 2 instruction files. For repos with one of these habits, the median runs from 5 files to 14.

Repos with…	Median instruction files	With an agent hook
All repos	2	7.6%
ALL-CAPS	5	13.3%
"Please"	7	13.1%
Emoji	8	15.6%
A destructive-command rule	10	20.0%
"Hallucinate"	11	21.1%
TODO, TBD, FIXME	12	15.6%
"Step by step"	14	17.9%

Part of that is arithmetic. More files mean more text, and more chances to contain any given word. They have more of everything else too. Repos with these habits are two to four times as likely to have sub-agents, and more of them write for more than one agent.

ALL-CAPS: a third of repos

MUST is the most common capitalized word, then CRITICAL, NEVER and ALWAYS. It's least common in CLAUDE.md and AGENTS.md main files, where about 22% of setups have it, and most common in Gemini, Cursor and Copilot ones, at 31% to 35%.

Some of it is RFC-style MUST in a spec, a convention with a defined meaning. Much of it reads like this line from a popular project's Copilot review instructions:

If test coverage is sufficient, DO NOT COMMENT.

Repos that write in capitals are firmer in general. They carry fewer hedged instructions ("should", "try to"), 4.7 per 100 against 5.8, and fewer or the same at every repo size. More of their headings double as instructions, like ## Always Run Tests Before Pushing, at 5.4 per 100 against 3.4. And despite NEVER and DO NOT, they write slightly fewer prohibitions, 16.4% of their instructions against 18.4%. The most common of those capitals, MUST, asks for something.

Anthropic's and OpenAI's prompting guides both say newer models don't need the capitals. Anthropic's says its newer models are "more responsive to the system prompt" and may overtrigger on prompts written to push older ones: "The fix is to dial back any aggressive language. Where you might have said 'CRITICAL: You MUST use this tool when...', you can use more normal prompting like 'Use this tool when...'." OpenAI's GPT-5 guide has the same example from the other side. A line from Cursor's prompt, "Be THOROUGH when gathering information. Make sure you have the FULL picture before replying.", worked with older models and turned out "counterproductive with GPT-5, which is already naturally introspective and proactive at gathering context."

Emoji, "please", and thinking out loud

1,541 repos (15.8%) use emoji in their instruction files, 29,311 times in total. Like the ALL-CAPS repos, more of their headings double as instructions.

839 repos (8.6%) say "please" to their agent, 2,051 times. In small setups, politeness travels with softer instructions. In the smallest quarter of repos, "please" repos carry twice as many hedged instructions as the others, 8.7 per 100 against 4.3. In the largest setups the difference mostly disappears.

798 repos (8.2%) write "step by step", "think hard" or ultrathink. Almost all of it is "step by step", which covers both asking the agent to reason and describing a procedure in steps. Where it asks the agent to reason, reasoning models no longer need it. OpenAI's guide for them: "Since these models perform reasoning internally, prompting them to 'think step by step' or 'explain your reasoning' is unnecessary." ultrathink and "think hard" turn up in a few dozen repos. In Claude Code, ultrathink in a prompt requests deeper reasoning for that turn, while "think" and "think hard" pass "through as ordinary prompt text".

TODOs and hallucinations

787 repos (8.0%) have TODO, TBD or FIXME in their instruction files. Some of those are rules about TODO comments in code. Others are the file's own unfinished business, shipped to the agent as-is.

246 repos (2.5%) mention hallucinating in their instruction files, some as a rule ("don't hallucinate") and some because the project itself works with model output. A bare "don't hallucinate" names nothing to check an answer against. Naming the source does: the schema file, the API docs page, the command that lists what exists.

Never force-push

360 repos (3.7%) write a rule against a destructive command, such as force-pushing, rm -rf, git reset --hard or dropping a table. The line from one machine-learning project is typical:

NEVER push to main. NEVER force push.

That's a rule the agent can follow or miss, and a force-push is the kind of miss you'd rather not find out about after the fact. A hook, a script the agent's harness runs at a set moment such as before a tool call, can stop the command before it runs. Claude Code can also refuse it with a deny rule in the project's .claude/settings.json. 72 of the 360 repos (20%) ship an agent hook of some kind, against 7.6% of all repos, and 6 deny a destructive command in a committed settings file. (Prompts steer, hooks enforce covers the difference.)

The repos that write these rules are firmer elsewhere too, with 3.9 hedged instructions per 100 against 5.2, fewer at every repo size. They also carry more of one finding at every size: a "never" written more strongly than the permission that goes with it, most clearly in small and mid-size setups. The agent may then apply the prohibition more widely than intended, unless the case where the thing is allowed is written as clearly.

The settings files have habits of their own. Of 1,466 committed Claude Code settings files, 19 allow any shell command, and 3 turn permission prompts off entirely.

The 129,121-word `CLAUDE.md`

The median repo's largest main instruction file is 697 words. 57 repos have one over 10,000.

The largest runs to 129,121 words. It opens with the /init line, and its Architecture section alone is 107,019 words across 374 lines, close to 300 words a line. The repo is an autonomous coding-agent project, and its CLAUDE.md has grown with it, one architecture note at a time.

Claude Code reads CLAUDE.md "at the start of every session", and its docs set a target of "under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." At 129,121 words, the file is well over 100,000 tokens before the agent has read a line of code.

Check yours

When a rule isn't being followed, look first at the places this post found: a capitalized line that fires everywhere, a heading doing an instruction's job, a "please" in front of a "maybe", a TODO that never got finished, a file long enough that the rule you care about is a few thousand words in.

The checker flags a TODO left in the file, a "never" with no matching permission and a hedged "try to" on the line where they sit, and it runs the checks behind this post's finding rates. Each run checks one agent's files; the second command switches to Copilot, and cursor, codex and antigravity (for GEMINI.md) work the same way.

npx @reporails/cli check -v
npx @reporails/cli check -v --agent copilot

The capitals, the "please" and the file length are quick to count yourself. Swap in the files your agents read, such as GEMINI.md, .github/copilot-instructions.md or the files under .cursor/rules/:

grep -cwE "IMPORTANT|CRITICAL|MUST|NEVER|ALWAYS|DO NOT" CLAUDE.md AGENTS.md
grep -niE "please|step[- ]by[- ]step|ultrathink|TODO|FIXME|hallucinat" CLAUDE.md AGENTS.md
wc -w CLAUDE.md AGENTS.md

From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot.

Habits are counted in each repo's instruction files with code blocks removed; shares are of the 9,784 repos with a setup. ALL-CAPS counts the words IMPORTANT, CRITICAL, MUST, NEVER, ALWAYS, DO NOT, DON'T, YOU MUST, MANDATORY and REQUIRED in capitals. Finding rates count findings per 100 directives and constraints, in repos with at least 5; "every repo size" means each of four equal groups of repos by setup size.

None of the habits moves the overall score in a consistent direction: compared at similar repo size, the differences shift from one size group to the next.

State of AI Instruction Quality: /init Files Score Higher

Gábor Mészáros — Wed, 14 Oct 2026 15:07:14 +0000

The CLAUDE.md files that started from Claude Code's /init score higher than the rest, at every file size.

You can tell them by the line /init puts at the top:

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

We scored 8,220 CLAUDE.md files from the 10,000 most-starred repos on GitHub for the Q3 report. One in five has that line. On ails check's 0 to 10 scale, their median is 8.4, against 7.7 for the rest. Six in ten of them score 8 or above. Of the rest, fewer than half do.

A short file has fewer chances to pick up findings, so we split all 8,220 into four equal groups by size. The /init files lead in every group, by 0.6 to 0.9 points.

A map, then a few rules

Claude Code's docs describe what /init produces: "Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers."

That's what the files look like. About a fifth of what an /init file says tells the agent what to do. The rest describes the repo: where things live, what each command runs, how the parts fit together. In other CLAUDE.md files, the share of instructions is close to three in ten.

The layout repeats from repo to repo. 87% of /init files have an Architecture section and 84% a Commands section. Among the other files, about one in five has each. Nearly nine in ten /init files carry at least one code block, against 44% of the others, and that gap holds at every file size.

Where its rules go wrong

Fewer rules leave fewer places for a rule to go wrong, and the findings show it. At every file size, fewer /init files carry a hedged instruction ("should", "try to"), and fewer carry a "never" written more strongly than the permission that goes with it, like "NEVER push to remote" next to "you can push if asked". Prohibitions are also a smaller share of their instructions: 16.8%, against 21.2%.

About one instruction in four still names no file, command or tool, against nearly one in three in other CLAUDE.md files.

One finding runs the other way. A file that's mostly description puts prose on the same topic right next to its instructions, and the checker flags an instruction buried in it: 17.7 times per 100 instructions in /init files, against 10.5 elsewhere. At no file size do /init files come out ahead on this one.

What to do with yours

You can delete the line. The checker reads it as description. It marks how the file started, and removing it costs nothing we can measure.

Keep the shape. It does some of the work: 646 CLAUDE.md files without the line have both an Architecture and a Commands section, and their median is 7.9. That's above the 7.7 of all files without the line, and under the 8.4 of files with it.

The same shape works in an AGENTS.md or a GEMINI.md: a map of the repo, its commands in code blocks and a short list of rules. We measured it on CLAUDE.md because that's the file /init leaves a marker in.

Six in ten /init files are the only instruction file in their setup, against three in ten other CLAUDE.md files, so for many repos the map, the commands and a handful of rules are everything the agent gets. Right after describing /init, the docs add: "Refine from there with instructions Claude wouldn't discover on its own." That's the part you write by hand. When you add a rule:

Give it what /init would have: the command, in a code block.
If it's a "never", write the case where the agent may as clearly as the one where it may not.
Keep the explanation around it short. The file already has plenty.

To see where your own file stands:

head -5 CLAUDE.md
npx @reporails/cli check -v

The first command shows whether your file started from /init. The second scores it and lists each finding with its line number. Run git blame CLAUDE.md on those lines to see whether they came with the first version of the file or were added later.

One more thing about the line. The longest main instruction file in all 10,000 repos, 129,121 words, opens with it too. That one is in the habits post.

From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot. Scores are from that run; the checker has been updated since, so your own file may score a little differently.

/init files are CLAUDE.md files with the /init line in their first 4,000 characters: 1,641 files in 1,539 repos. Counting every instruction file, 1,604 repos carry the line. File-size groups cut at 37, 75 and 137 items. Finding rates count findings per 100 directives and constraints, the same denominator as the report.

Counted per repo instead of per file, the gap narrows as setups grow, from 1.3 points in the smallest quarter of setups to 0.2 in the largest. The Architecture-and-Commands shape accounts for part of the gap; the files alone don't show what accounts for the rest.

I work on Reporails, deterministic diagnostics and governance for the instruction files, rules, and prompts that steer coding agents. If your CLAUDE.md started from /init, it starts from the shape that scored higher here. Reporails reads the rest of what you wrote, measures which instructions couple to behavior, and points to the lines worth tightening.

The State of AI Instruction Quality: Q3 2026

Gábor Mészáros — Tue, 13 Oct 2026 16:21:27 +0000

91% of the most-starred repos on GitHub give their coding agent at least one instruction that never says which file, command or tool it means.

In April we measured 28,721 repos, and our own limitations section admitted that a 10-star side project counted the same as a 50,000-star production repo. This time we started from the other end: the 10,000 most-starred English-language repos that ship instructions for a coding agent. If you've ever opened a well-known repo to see how they wrote their AGENTS.md, these are the files you were looking at.

10,000 repos. 15,237 agent setups. Read in September 2026 and scored with the same ails check you can run on your own repo.

The short version

91.1% of repos have at least one vague instruction. Among the lines that tell the agent what to do, about 1 in 3 is vague.

Vague is the most common finding of several: 96.6% of repos have at least one finding, 38 in the median repo.

Star count doesn't predict the score (Spearman's rho -0.028 across 9,674 repos).

Sub-agent files score lowest: 19.6% of them score below 5, against 6.8% of main files.

Only 7.6% of repos back their instructions with an agent hook.

91% of repos carry at least one vague instruction

One AGENTS.md from a popular Python project runs to 386 lines, and most of it is careful work. It names requirements.txt, torch.inference_mode and dozens of the project's own modules the agent can look up. It also has two rules about dependencies:

Both are sensible. The second one gives the agent a file to open and a condition to test. The first leaves "absolutely necessary" for the agent to decide on its own, mid-task, with nothing in the file to check its call against.

ails check flags the first one as CORE:C:0042, a vague instruction: a directive or constraint that names no file, command or tool, in a section where other lines do. The second one passes.

Another popular repo's Copilot instructions ask for the same kind of judgment call:

When there is an option, opt for more performant solutions and trade RAM usage for less CPU cycles

Which option? Measured how? The agent decides, and you find out what it decided when you read the diff.

Across the 9,776 repos with a setup we could check, 8,910 carry at least one CORE:C:0042 (91.1%).

The checker raised that finding 655,791 times. Two-thirds of what sits in these files describes, explains or shows; a third tells the agent what to do. Count only those directives and constraints and about one in three is vague.

Vague instructions are the most common finding, and far from the only one. 96.6% of repos have at least one finding of some kind, 38 in the median repo, and four other checks fire in more than 60% of repos.

Stars don't predict the score

Every file and every setup ails check reads gets a score from 0 to 10, built from all of its findings (how the score works). If popularity bought better instructions, scores would climb with stars. From 493 stars to 454,882, the line stays flat.

Spearman's rho between stars and score is -0.028 across 9,674 repos: stars account for less than 0.1% of the variation. Split the repos into ten equal groups by stars and every group lands in the same place, with 63% to 66% of repos scoring 7 or above. The most-starred tenth, 12,849 stars and up, averages a touch lower than the least-starred tenth.

A famous repo's AGENTS.md scores like anyone else's. If you copy one, read it line by line first.

Next: does the agent you write for change the picture?

Who writes for which agent

Two setups dominate: AGENTS.md in 62.6% of repos and Claude Code in 61.6%. Copilot follows at 17.9%, then Cursor, Gemini and Codex. 4,213 repos (43.1%) write for more than one agent, most often the pair of Claude Code and AGENTS.md (2,399 repos).

The formats differ in what they're made of. Skills are the largest share of files for every agent except Gemini, and Cursor is the only one where rule files outnumber main files.

The quality of what's in them barely moves between agents. The vague rate sits between 32 and 36 of every 100 instructions, whichever agent the file was written for.

Agent	Setups	With a vague instruction	Vague per 100	Below 5
Claude Code	6,030	87.4%	33.7	5.3%
`AGENTS.md` (shared)	6,125	91.0%	32.5	5.0%
GitHub Copilot	1,756	94.4%	34.6	4.8%
Cursor	734	93.2%	33.4	9.6%
Gemini (Antigravity)	430	91.4%	34.2	8.8%
Codex	162	96.3%	36.0	3.1%

Codex counts repos with a .codex/ folder; a plain AGENTS.md setup sits in the shared row.

The one column that does move is the last: Cursor and Gemini setups land below 5 about twice as often as the rest.

Where the numbers do move is between the files inside a setup.

Sub-agent files score lowest

A sub-agent file defines a specialist the main agent hands work to: a reviewer, a debugger, a test writer. Those files are where the low scores pile up. 19.6% of sub-agent files score below 5, against 6.8% of main files like CLAUDE.md and AGENTS.md, nearly three times the rate. Commands and prompts (13.9%), rules (13.6%) and skills (12.1%) sit in between.

The three biggest sub-agent folders all sit above the main-file rate, and Claude Code's is the worst: nearly one in four of its sub-agent files scores below 5.

Sub-agent files are also the busiest. The median one carries 19 directives, against 12 in a main file.

One Copilot bug-fixing sub-agent, in a large TypeScript monorepo, scores 3.9. Its quality gates:

Four gates, and nowhere in the file's 212 lines is the command for any of them. The agent has to work out how this monorepo tests, lints, type-checks and builds before it can obey a single one.

A Claude Code debugging sub-agent in another well-known repo scores 3.6. It opens:

You are an expert software debugger who treats debugging as a scientific process, not guesswork.

In 41 lines, the only file it names is CODE_DEBUGGING_SESSION.md, the report it's told to write. Nothing in it is about the project it lives in; it would read the same in any repo. It also carries the line most sub-agents do: 57.4% of sub-agent files have a line that starts with "You are a", "You are an" or "You are the".

To check yours, run npx @reporails/cli check and read the per-file scores for your .claude/agents/, .github/agents/ or .codex/agents/ folder.

7.6% of repos back their instructions with a hook

Everything above is about instructions, which the agent can follow or not. A hook is different: a script the agent's harness runs at a set moment, such as before a tool call, that can block what an instruction only asks for. (Prompts steer, hooks enforce is the long version.)

746 of the 9,784 repos (7.6%) ship an agent hook of any kind. Claude Code is where they live: 591 of its 6,030 setups (9.8%) have one. Cursor follows at 4.9%, Copilot at 1.3% and Gemini at 0.9%.

For the other 92%, nothing at the agent's own level checks whether the instructions were followed.

What held from April

April's 28,721 repos came from GitHub search. This quarter's 10,000 are the most-starred, read with a newer version of the checker, so the comparison is about direction, not size.

April (28,721 repos)	Q3 2026 (10,000 most-starred)
37% of projects configure more than one agent	Held. 43.1% of repos
The median instruction file: 50 items, 12 of them directives	Held. The median main file: 55 items, 12 directives
`AGENTS.md` is the most common instruction file	Held. `AGENTS.md` (11,248) still leads `CLAUDE.md` (8,838); `SKILL.md` (13,361) now outnumbers both
Cursor setups are rules-heavy	Held. Cursor rule files (1,820) outnumber Cursor main files (1,260)
Sub-agents carry the most directives	Held. Median 19 per sub-agent file, against 12 in main files
Sub-agents are almost entirely persona prompts	Mostly. 57.4% have a line starting "You are a/an/the"
`code-reviewer.md` is the most common sub-agent	Held. Still the most common, in 41 repos
89.9% of configurations carry a vague instruction	Held. 91.1% of repos
The most-copied skills are the vaguest	Didn't hold. No link between how widely a skill is copied and how vague it is (188 skills copied into 5 or more repos)

How we measured

The sample. 10,000 English-language GitHub repos, taken top-down by stars from repos that ship an instruction file for Claude Code, Codex, Copilot, Cursor or Gemini. Stars run from 493 to 454,882, with a median of 1,551. Files are the September 2026 snapshot.
What we read. We read every repository the way its coding agent does: the instruction files each agent loads by default, at the exact names and paths its documentation specifies. That is CLAUDE.md, AGENTS.md, rules, skills, sub-agents and commands, across 15,237 agent setups in 9,784 repos.
Imports. The text of a Claude Code @path import whose target is in the snapshot is read as part of the importing file. Imports written with a leading dot directory (@.github/…) are not recognized and stay literal.
Out of scope. Repo code, and docs an agent opens only when something links to them.
The scorer. Every score comes from the same ails check pipeline you can run on your own repo.
Denominators. Shares of repos, like the 91%, count the 9,776 repos with a checked setup. The vague rate, about 1 in 3, counts against the directives and constraints in those setups: 655,791 findings over 1,894,268 instructions. Score figures count the 9,674 repos with a score.
Not in the figures.
- 158 of the largest agent setups (more than 90 instruction files each, about 1% of setups) are not in these figures. 77 are larger than the 10,000 instruction units ails check currently scores, and 2 exceed its time limit; they are skill and rule libraries, with a median of 15,027 units across 192 files. The other 79 were scored after these figures were frozen and will be added in a dataset update.
- 258 setups contain no directive or constraint (every line is descriptive, or the file is empty), so the scorer returns no score for them.
- 18 setups couldn't be checked: 8 are larger than the same 10,000-unit limit and 10 hit an error during scoring.
- For 76 repos we couldn't pin the files in sub-folders (sub-agents, commands, hooks) to the September snapshot, so they're measured on the files we already had.
What it measures. How the instructions are written, not what any agent did with them.

Check your own files

If you came here to find out whose AGENTS.md to copy: the star count won't tell you, so read the lines instead, or let the checker read them. To run the same check we ran on all 10,000:

npx @reporails/cli check

It lists the findings file by file, with line numbers, and a 0 to 10 score for each file. Start with the three findings most repos carry: instructions that name no file, command or tool (CORE:C:0042), instructions too short to register (CORE:E:0004), and hedged ones, the "should" and "try to" kind (CORE:C:0043).

The data behind these figures is published in the 2026-Q3 folder of reporails/reports. If you disagree with a finding, count the rows.

Next in this series

Four shorter posts follow over the next days, each on one habit from the same 10,000 repos:

The /init header. 1,604 repos (16.4%) still open with the line Claude Code's /init writes, and they score higher than the repos without it.
"You are…" 285 main files tell the agent who it is with a "You are a…" line. They score lower at every file size.
The habits. ALL-CAPS in a third of repos, emoji, "please", TODOs, and a 129,121-word main file.
Hidden attribution. About 400 repos tell the agent not to take credit for its work.

Progressive Disclosure: Why Isn't Claude Code Following My Instructions?

Gábor Mészáros — Wed, 07 Oct 2026 17:17:36 +0000

The last piece (Progressive Disclosure: Claude Code Hooks, Events and Telemetry) sent every hook event through one bus and wrote it all down. It ended on what that log can't tell you: whether a rule that loaded "was worded well enough to steer anything".

So I loaded one spec, worded two ways, into the same 16-turn Claude Code session, three times each, and read what came out at the end. Here's the last migration doc from each, written with roughly 120K to 140K tokens of work piled on top of the spec:

Release: 4.2.0

# 0005: Index cards.created_at

# 0005: Index cards by creation time

Adds `cards_created_at_idx` on `cards (created_at)` so the nightly report can find one day's cards without scanning the whole table.

**Release:** TBD

Both specs asked for the release. The bus log shows each one delivered once, on the first prompt, and nothing took it out of the context after that. The named spec put Release: 4.2.0 on every migration doc. The vague one put TBD there every time.

Same spec, two wordings

The demo is a small Node payments service with two legacy knex migrations. Neither has a down step, and neither doc says which release it went out in, so whatever the agent does about either comes from the spec.

The spec lives in specs/migrations.md, and the bus from last time delivers it. One step is new: a prompt that starts with #migration gets the spec printed into its context, and the log records the delivery. Whatever a UserPromptSubmit hook prints goes in front of the model before it starts (hooks).

#!/usr/bin/env bash
# Every hook event comes through here. Step one: write down what happened.
in=$(cat)
log="$(dirname "$0")/log.jsonl"
jq -c '{ts: (now | todate), event: .hook_event_name, tool: .tool_name,
        file: (.tool_input.file_path // .file_path), reason: .load_reason}
       | with_entries(select(.value != null))' <<<"$in" >> "$log"
# Step two: a prompt tagged #migration gets the migration spec.
if jq -e '.hook_event_name == "UserPromptSubmit" and (.prompt | startswith("#migration"))' <<<"$in" >/dev/null; then
  cat "$CLAUDE_PROJECT_DIR/specs/migrations.md"
  jq -nc '{ts: (now | todate), event: "delivered", file: "specs/migrations.md"}' >> "$log"
fi

The two versions ask for the same two things: a way back from every migration, and the release named in its doc.

# Migration spec

- Every file in `db/migrations/` exports `up` and `down`. `down` undoes exactly what `up` did.
- Every migration gets a doc in `docs/migrations/` with the same number. The doc's first line is `Release:` followed by the `version` from `package.json`.

# Migration notes

Migrations should be reversible where possible, so it's worth thinking about a way to roll each one back. It would also be good to keep the docs for migrations reasonably complete, ideally mentioning which release a change goes out in.

Each session is 16 prompts, run headless with claude -p on Claude Code 2.1.285 and claude-opus-5-5 at its default medium effort. The first prompt starts the migration work and asks for one migration, turn 8 asks for a second and turn 16 for a third. In between, the agent does the rest of a working day: it groups the failures in an import log, finds and fixes bugs in a legacy importer, renames a column across the repository, the API serializer and five billing modules, writes tests, and runs the suite after each change. I ran three sessions per version.

What came back

	Turn 1	Turn 8	Turn 16
Named spec	`Release: 4.2.0` in 3 of 3	`Release: 4.2.0` in 3 of 3	`Release: 4.2.0` in 3 of 3
Vague spec	`TBD` in 3 of 3	`TBD` in 3 of 3	`TBD` in 3 of 3

The vague runs wrote **Release:** TBD, or Release: TBD (next release after 4.2.0). That's a fair reading of "mention which release a change goes out in": the change hasn't shipped yet, so its release is the next one, whatever that turns out to be. What I wanted on that line was the version in package.json, and only the named spec said so.

Every migration in both sets got a down step. Claude writes one for a knex migration whether you ask or not, so that half of the spec costs nothing to follow in either wording. The release line asks for something Claude wouldn't do on its own, and that's where the wording decided the result.

Then I ran the same six sessions at --effort low. The named spec still put Release: 4.2.0 on the first line of all nine migration docs. The vague one dropped the release altogether: none of its nine docs has a release line, not even TBD.

Three sessions per version is a demonstration, and four shorter 8-turn sessions per version came out the same way. The measured effect comes from earlier controlled experiments, where specificity produced a 10.9x odds ratio in compliance (The State of AI Instruction Quality).

It did what the spec said

Claude Code's docs put it plainly: Claude treats CLAUDE.md "as context, not enforced configuration, so how you write instructions affects how reliably Claude follows them", and there's "no guarantee of strict compliance, especially for vague or conflicting instructions" (How Claude remembers your project). A spec your bus delivers is context too.

The vague spec asks for the release "ideally" and never says where the release comes from. So the model read it as the release still to come. One of the shorter runs wrote **Release:** TBD (current package version is 4.2.0): it had the version in front of it and still wrote TBD. From the chair that looks exactly like Claude ignoring the spec. It was doing what the spec said, and the part I meant was never in the words.

It's also the common case. In our analysis of 28,721 repositories, 89.9% of agent configurations contain at least one instruction that doesn't name what it means (same article).

Where the fade comes in

I went in expecting the other failure as well: a spec that holds early and fades as the turns pile up. By turn 16 the context held the import log, the importer, the billing modules and a dozen test runs, and neither spec had moved. Whatever a version did on turn 1, it still did on turn 16.

Long enough sessions do get there. In the decay piece (See how AI instructions decay, then write ones that hold), Never write directly to the database was still sitting in the prompt when the agent, a long session later, wrote directly to the database. The model leans on what it read most recently. It's the same recency tendency that, inside one file, swings how often a rule is obeyed by about 90 points when you move it from the top to the bottom (Opus 5: Cost of Instruction Conflicts).

Here's the picture I use for it. Each hill is an instruction and its height is how well it's written. The water is everything the session piles on. Drag the load up and watch which hills go under first.

In my runs the vague spec never stood above the water, not even on turn 1. The named one still wrote the exact line on turn 16 of every run. Both outcomes were decided by what I wrote in the spec.

Checking what you load

The bus decides when a spec loads and never reads what's in it. You can check one spec by eye. It stops working at the size real setups reach: in the same 30k analysis, sub-agent definitions have a median of 17 directives per file, and 17% of their instructions name a specific construct. Add the rules, the skills, the specs your bus delivers, re-read all of it after every change, and the re-reading is the part that doesn't happen.

Claude Code ships one check for this. /doctor prompt-audit (Claude Code 2.1.283 and later) has Claude read your CLAUDE.md, rules, skills, commands, subagents and output styles and propose edits (Audit your instruction files). On an earlier version of this demo it flagged the same kind of vague lines, and a dead path glob like the one further down. It runs inside a Claude session, on your tokens.

Reporails, the tool I work on, reads instruction files with a fixed rule set. ails check classifies each instruction on your machine and analyzes it on the Reporails API, and neither step is a Claude session, so it spends none of your Claude tokens and gives the same files the same findings on every run. A spec outside the usual agent files gets checked when you name it (excerpt):

$ ails check -v specs/migrations.md
  ┌─ Files (1)  1 directive · 67% prose
  │ specs/migrations.md  1 dir · 67% prose
  │   migrations.md
  │     L3    Hedged language ('should', 'consider', 'migh…  CORE:C:0043
  │     L3    No instruction on this topic is strong enoug…  CORE:C:0052
  │
  └─ 2 findings

  Quality   4.3 / 10  ▓▓▓▓▓▓▓▓▓░░░░░░░░░░░  (1.8s)

ails reads one directive in the vague spec and files the rest as prose. CORE:C:0043 says of the hedge that "the model may treat this as optional", which is what all three sessions did with "ideally". On Pro, the remedy for CORE:C:0052 reads "state it as a direct instruction and name the tool, file or command it already refers to". That's the named version, and it comes back clean:

$ ails check specs/migrations.md
  ✓  No findings.

On Pro, /reporails:ails heal in Claude Code rewrites the file and checks the rewrite. Because the result is the same on every run and costs no Claude tokens, it can also run on every push, with a score the build has to meet:

- uses: reporails/cli/action@0.6.1
  with:
    api-key: ${{ secrets.REPORAILS_API_KEY }}
    min-score: 7

And the organizing part

The last piece also handed over a question: how you keep a rule set organized once the harness stops doing it for you. One part of that is the rename it described. The demo has a path-scoped rule in .claude/rules/docs.md for everything under docs/. Rename docs/ to doc/ and the rule never loads again, and nothing in the log tells you, because a rule that doesn't load doesn't log. The same check reads paths: against the files that exist (excerpt):

$ git mv docs doc && ails check
  ┌─ Rules (1)  2 directive · 0% prose
  │ docs  2 dir · 0% prose
  │   ℹ Path glob `docs/**` matches no file in the p…  CLAUDE:S:0012

Where each rule should live, and what happens when you move a rule set into skills, is the next piece.

So when Claude Code isn't following an instruction, read the instruction before you blame the session. Mine said "ideally" and never said where the release comes from, and every session read it as a release still to come. ails check points at that sentence from the spec file alone, without watching the agent run.

Run npx @reporails/cli check in your project, and name the spec files your bus delivers. It's free and needs no account. Pro adds the remedies and the workflow your coding agent runs to fix the files. Subscribe in October and enter the code HACKTOBER at checkout.

I work on Reporails, deterministic diagnostics and governance for the instruction files, rules, and prompts that steer coding agents. It reads the steering surface you wrote down and tells you, with measured evidence, which instructions couple to behavior and which are text the model can ignore. It does not run your model; it measures the files.

Claude Code mods: but does it run Doom?

Gábor Mészáros — Mon, 05 Oct 2026 15:43:43 +0000

Yes ... Yes it does.

The Minesweeper was the warm-up. A pane that can draw pixels and take the keyboard raises the only question the internet ever asks of a new screen, so the second game in the arcade is Doom: Freedoom on the doomgeneric engine, in a pane beside the transcript, while Claude works.

/doom opens the pane and starts the game. In kitty the screen is a real picture at Doom's own 320×200 (Ghostty speaks the same protocol, but I haven't tried it); in any other terminal it is drawn in quadrant block characters, four pixels a cell. Walk with w and s, turn with a and d or by dragging sideways on the game, fire with space or the right mouse button.

Getting a picture on screen took an afternoon. The controls took the rest of the week, because a terminal never tells you that a key was let go.

Doom runs in a process of its own

A mod's hooks run in a sandbox: no Node, no DOM, no require, and deliberately no WebAssembly. The typings say what to do instead: run the heavy thing as a program of its own. So the game is doomgeneric compiled to a native binary, and the mod starts it with $.process.spawn:

const child = $.process.spawn({ argv: engineArgs(binary, root, placement), env: token !== null ? { DOOM_CLAUDE_TOKEN: token } : {} })

A spawned child lives as long as the mod reads its output and ends when the mod unloads, so there is no daemon to clean up. The engine prints doom-claude listening once it is ready, and from then on the mod talks to it with $.http.fetch: over a Unix socket on Linux and macOS (socketPath), and over 127.0.0.1 with a random 64-digit token on Windows, where every request without the token gets a 403.

There is no compiler on the player's machine to count on, so the arcade ships six prebuilt engines, cross-compiled with zig cc from one Linux box: Linux, macOS and Windows, each on x86_64 and arm64. Honest status: only the Linux x86_64 one has run. The macOS and Windows builds are compiled and checked (file says Mach-O and PE32+, the arm64 Mach-O carries its ad-hoc signature), and nobody has started one yet.

Pixels that never pass through Claude Code

In kitty and Ghostty, Claude Code's Image element can take a file instead of bytes. The engine writes each frame as raw RGB to a file beside its socket (written aside, then renamed over the old one, so it is never read half-written), and the mod points the Image at it:

export function imageSource(path: string, generation: number): ImageSource {
  return { file: path, format: 'rgb', width: IMAGE.width, height: IMAGE.height, generation }
}

Claude Code hands kitty the path (a=T,…,t=f in the graphics protocol), kitty reads the pixels itself, and a new generation makes it read the file again. Not one pixel goes through Claude Code.

Every other terminal gets a Raster, and a Raster has opinions. It rounds every colour to 4 bits a channel. It paints at most 1024 colour pairs and snaps the rest, which speckles a photo-like picture. And it leaves blank cells at the end of a row undrawn, so a dark corridor came out with black holes in it. The engine pre-encodes each frame into cells: a 32-colour palette per scene (32 × 32 is 1024), each cell the quadrant glyph and the two colours that fit its four pixels best, a cell reusing its left neighbour's colours when they fit nearly as well, and no blank cells at all.

Claude Code stops drawing when nothing moves

The first live run froze for 300 ms at a time. $.ui.blit repaints a Raster at Claude Code's next frame, and with nothing else on screen moving, Claude Code draws only about three frames a second. The game was sending 30.

The fix is a heartbeat: the red strip under the game is a Client, and it redraws itself every 30 ms, swapping one blank character for another. That keeps Claude Code drawing, and it costs far less than redrawing the whole pane from the hooks module. One more trap on the way: a blit resolves when it has been painted, not when it has been taken, so the frame loop must not await it before fetching the next frame.

On a machine with other work running (load 5–6 on 8 cores), the picture changed 35–40 times a second in a plain terminal and 31–32 times a second in kitty. The block picture costs Claude Code about a full core; the kitty picture about a third of one.

The keyboard that never lets go

Doom wants to know when a key goes down and when it comes up. A terminal reports the press, then, after its repeat delay, the same press again every 30 ms or so, and never the release. Claude Code turns on kitty's keyboard protocol with flags 5 only, so a mod gets no release events and can't even tell a repeat from a new press. The terminal also repeats only the newest key: hold w, press a, and w goes quiet whether your finger is still on it or not.

So every terminal Doom fakes the release, and my first attempt was a guess. A turn key held for 220 ms, so a tap would be a small turn. Then the terminal's first repeat came at 500 ms, and a held turn key stopped dead for 308 ms before it started turning for real. I measured it by reading the player's facing out of the engine every 10 ms. Then I patched it, and patched the patch.

What fixed it was reading how the others do it:

port	fakes the release how
doom-cli	learns the terminal's repeat delay and rate per key; a fresh press holds until the first repeat is due, a repeat until the next is due
intermission	550 ms after a fresh press, 120 ms while repeating; turning is mouse-only
claude-doom	a 160 ms pulse per press
doom-braille	released after 100 ms with no bytes

doom-cli's model is the one that holds up, so the engine now does the same. A movement key holds until its next repeat is due. The repeat delay is learnt from the gap between a press and its first repeat (the median of the last five, capped at 600 ms), so it fits GNOME's 500 ms as well as anyone's faster setting:

static uint32_t freshHold(int key)
{
    return isMovement(key) ? s_RepeatDelay + DELAY_MARGIN_MS : OTHER_HOLD_MS;
}

That has a cost doom-cli's own source admits in a TODO: a tap now lasts as long as the repeat delay, so one tap of d turned 61.5°. The TODO also names the fix: "just turn more slowly outside of state repeat? so it's still possible to do some precision aiming". So a turn key in play doesn't press Doom's arrow key at all. It turns through Doom's mouse, slowly until the terminal starts repeating it, then at the arrow keys' full speed, with the same half-speed first six tics Doom gives a held key:

    if (!k->isRepeating)
    {
        s_KeyTurnTics = 0;
        return sign * TAP_TURN;
    }
    return sign * (s_KeyTurnTics++ < SLOW_TURN_TICS ? KEY_TURN / 2 : KEY_TURN);

A tap of d now turns 10.5°, about what a quick tap gives in Doom with a real keyboard, and a held d never stops for longer than 28 ms. In a menu, a pause or the title demo, the arrows stay arrow keys, because menu sliders want them.

The mouse is the only exact hold

A pointer is the one input that does report its release. So dragging sideways on the game turns, and letting go stops at once. It only turns: walking stays on w and s, and the keys and the mouse work together, so you can walk and turn at the same time, which the keyboard alone can't do.

The first version of the stick walked too, and turned up to 2.5 times faster than the keys the further you dragged. Now any sideways drag past a small dead zone turns exactly as fast as a and d:

export function stickOf(pad: Pad | null): Stick {
  if (!pad) return { turn: 0, forward: 0, buttons: 0 }
  const dx = pad.isHeld ? pad.dx : 0
  const turn = Math.abs(dx) > STICK.dead ? Math.sign(dx) * STICK.turn : 0
  const buttons = (pad.isFiring ? STICK.fire : 0) | (pad.isHeld && pad.isStrafing ? STICK.strafe : 0)
  return { turn, forward: 0, buttons }
}

80 is Doom's mouse turning at 640 units a tic, the same as a held arrow key, and the engine gives a drag the same half-speed start. A drag and a held d stayed within a tic of each other at every point I measured: 51.0° against 52.8° at half a second, 114.3° against 112.5° at one.

Escape belongs to the prompt

A Client gets the keyboard only after a click, and Escape always hands it back to Claude Code's prompt. No mod and no keybinding can take Escape: it never reaches the mod at all. So the menu is m or backspace. Before the first click, space and the digits land in the prompt too.

While you play, then, the prompt is Doom's. A prompt.edit hook takes game keys out of the prompt and hands them to the game, and drops the rest:

    state.isPromptOurs = true
    const keys = e.key ? [e.key] : Array.from(String(e.inputText ?? '')).map((ch) => ({ key: ch }))
    const codes = keys.map(doomKeyOf).filter((code) => code !== null)
    if (codes.length > 0) {
      state.gameInputAt = now
      state.queuedKeys.push(...codes)
    }
    state.promptCheckAt = now + PROMPT_CHECK_MS
    return { text: '', cursor: 0 }

Answering { text, cursor } without calling next consumes the key. The hook decides without a single $ call, because Claude Code sometimes lets the key through anyway when the hook is slow. Type / and the prompt is yours again at once, ten seconds without a game key gives it back too, and a draft you had typed before is never touched.

This makes Doom different from the Minesweeper in one way that matters: it hooks the prompt. claude plugin validate lists it before any of the mod's code runs:

❯ ./register.ts hooks: session.start, command.run{command=doom}, ui.render{component=Pane}, ui.message, prompt.edit, ui.close, session.end
❯ ./register.ts calls: $.clock.after (via fitPane, focusSoon, watchEngine), $.clock.every (via startPulling), $.command.register, $.env.get (via readEnv), $.fs.exists (via findEngine), $.fs.write (via watchEngine), $.http.fetch (via pullFrame, sendKeys, sendStick, stopEngine), $.process.run (via findEngine, startEngine), $.process.spawn (via startEngine), $.prompt.fill (via clearLeakedPrompt), $.prompt.read (via clearLeakedPrompt), $.session.surfaces, $.ui.blit (via paint), $.ui.close, $.ui.invalidate, $.ui.open (via fitPane, openPane), $.ui.resolve

It reads nothing the model sees and adds nothing to it, and its only network traffic is to its own engine on your machine.

What the test kit missed this time

The mod has 20 tests under claude plugin test, typechecked under the same strict config as the code. A review still found two bugs in them that a player would have hit in the first minute:

A held drag stopped after 1.5 s. The engine lets go of a stick it hasn't heard about for 1.5 s, in case the mod died mid-drag. The strip re-sends a held stick on its heartbeat, but the layer over the game, where you actually drag, had no heartbeat. Hold still while turning or firing, and you stopped.
A restarted engine replayed old keys. Each pane numbers its keys so a post that replaces an undelivered one loses nothing. Quit Doom from its own menu and run /doom again, and the hooks module forgot the numbers while the pane kept counting: the new engine got the last 24 keys again, menu and quit included.

The first one is a lesson about the kit. The new test for it failed with the bug in place only once it stepped the frame clock one frame at a time: the kit delivers one post per ui.advance, so a two-second advance collapsed six re-sends into one and passed anyway.

Play it

In a Claude Code session:

/plugin marketplace add reporails/arcade
/plugin install doom@reporails-arcade

Then start Claude Code in the fullscreen layout, which the mouse needs, and run /doom:

CLAUDE_CODE_NO_FLICKER=1 claude

Mods load by default from Claude Code 2.1.287; on 2.1.285 and 2.1.286, add CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1. Run it in kitty for the real picture (Ghostty should work the same, untested); every other terminal gets the blocks, and so does Windows, where no terminal the mod detects speaks kitty's picture protocol. It has been played on Linux. If you run it on a Mac or on Windows, tell me how it went.

The mod's code is MIT, in reporails/arcade on GitHub. The engine is doomgeneric, GPL-2.0-or-later, and the game data is Freedoom, BSD. "Doom" is id Software's name; this plays Freedoom and contains nothing of id's.

Claude Code mods: Minesweeper and testkit

Gábor Mészáros — Sat, 03 Oct 2026 17:30:29 +0000

My own harness, the tooling I run around Claude Code, comes with a custom trust score. That trust score decides whether I can leave the agent alone yet, without supervision or if it's in my best interest to babysit it. As you see in the header image, it's babysitting era, so I built a Minesweeper to kill time between turns.

From Claude Code 2.1.287, mods load by default. A mod is a plugin whose hooks are JavaScript or TypeScript functions running inside Claude Code instead of shell commands, and it can open and draw its own panes. Minefield is Minesweeper as a mod: /mines opens a pane beside the transcript, and you clear the board while Claude works.

It is one 9×9 board with 10 mines, a game for the few minutes Claude works. The first reveal is always safe and opens an area, clicking a fully flagged number opens the cells around it, and the best time is kept between sessions. The orange face follows your cursor. Stop for six seconds and it pretends to read the transcript beside it, eyes half shut, line by line. It only looks; the mod sees nothing of the transcript. It winks at flags and puts on sunglasses when you win. This was the most fun part to implement.

It ships with 31 tests that run through claude plugin test, and CI runs them on two pinned Claude Code builds. Four of its bugs passed the test kit anyway and only showed up in a real session: the pane couldn't take the keyboard, the hotkeys did nothing, the face wrapped, and the mouse wasn't there.

In claude plugin test, nearly every engine call your mod makes (ui.open, ui.panes, store.get) is answered by an on(...) stub you write in the test file; the kit answers a few itself, such as $.ui.invalidate. That is why it runs fast and without credentials. It also means the host in your tests behaves exactly as well as your doubles do.

The pane and the keyboard

/mines opened the pane, and the keys kept going to the prompt.

Seen in live sessions on 2.1.285: a pane takes the keyboard only over an empty prompt. Anthropic's docs list focus: true from a command as one way a pane gets the keyboard, but while command.run runs, the command's own text is still in the prompt, and on 2.1.285 the request was refused. The pane opens and the keyboard stays where it was.

In the tests, ui.open is answered by my own double, and my double says yes:

  on('ui.open', (_$, e) => {
    opened.push({ rows: e.rows, columns: e.columns, closeOnEscape: e.closeOnEscape })
    return { value: { isPlaced: true } }
  })

The fix is to open the pane, then ask for the keyboard again once /mines has returned. register.ts waits 250 ms, then 500, then 1000 between tries (FOCUS_RETRIES_MS), three tries inside two seconds, and every retry first asks $.ui.panes() whether the pane is still open and still without the keyboard. If the pane is gone, the person closed it, and a retry must not bring it back.

// Ask for the keyboard again once /mines has returned, while the pane is open
// and still without it; never reopen a pane the person has closed.
function focusSoon($: EngineInterface, attempt: number): void {
  const wait = FOCUS_RETRIES_MS[attempt]
  if (wait === undefined) return
  try {
    $.clock.after(wait, () => void refocus($, attempt))
  } catch {
    // No timer; a click on the pane gives it the keyboard.
  }
}

async function refocus($: EngineInterface, attempt: number): Promise<void> {
  try {
    const pane = (await $.ui.panes()).find((p) => p.id === PANE)
    if (pane === undefined || pane.isFocused) return
    await openPane($)
    focusSoon($, attempt + 1)
  } catch {
    // The panes cannot be listed; a click on the pane gives it the keyboard.
  }
}

The retry logic is testable, with mock.clock standing in for $.clock:

test('a pane the person closed is not reopened by the focus retries', async ($, on) => {
  const opened: Opened[] = []
  const clock = world(on, { opened, pane: { isOpen: false, isFocused: false } })
  await $.session.start(SESSION)
  await $.command.run(mines())
  await clock.advance(5000)
  expect(opened.length).toBe(1)
})

What no test here can check is the refusal itself. isFocused in that test is whatever my double says it is.

Hotkeys that did nothing

A pane has two places to draw from. The hooks module (register.ts) answers the ui.render hook and returns elements: boxes, text, buttons. A Client is a surface module (board.ts) with its own state, a frame timer, and pointer and key handlers, which is where a game wants to live. So the control buttons went in the board, next to the cells they act on, each with a one-letter hotkey.

None of the hotkeys fired. A Button's hotkey fires only for buttons the hooks module draws, never for buttons a Client draws.

The tests had no way to notice. ui.press({ key: 'flag' }) presses a button by its element key ('flag', where the hotkey is f), so a press in a test never goes through the hotkey at all.

The fix moved the buttons into register.ts. That raised the next problem: the buttons now live in the hooks module, the game lives in the board, and the board learns about presses only through its props. Several presses can arrive between two redraws of the board, so handing over only the latest move drops the others. Each press gets a number instead, and the hooks module keeps the last 32:

// Moves kept for the board, so presses faster than its redraws all arrive.
const MAX_ACTS = 32

function ask(type: MoveType): void {
  const n = (state.acts.at(-1)?.n ?? 0) + 1
  state.acts = [...state.acts, { n, type }].slice(-MAX_ACTS)
}

The board plays every move newer than the last one it played, in order, once:

// Every move newer than the last one played, in order. Presses can outrun
// the board's redraws, so one redraw may bring several. Numbers lower than
// the last one played mean the hooks module started counting again, as it
// does when the plugin reloads, so every move it lists is new. The same game
// back when there is nothing new.
export function applyActs(game: Game, acts: readonly Act[]): Game {
  const last = acts.at(-1)?.n ?? 0
  let next = last < game.acted ? { ...game, acted: 0 } : game
  for (const move of acts) {
    if (move.n > next.acted) next = { ...act(next, move.type), acted: move.n }
  }
  return next
}

A mounted test can't catch the race this guards against. The kit redraws after every press, so it never coalesces presses, and a mounted test of the queue passes even with the bug in place. So the race is tested as a pure function, with the presses that land in one redraw written out by hand:

test('every move newer than the last one played is played, in order, once', async () => {
  const ready = newGame(SEED)
  // Three presses that arrive in one redraw, the first one already played
  const acts = [
    { n: 1, type: 'right' },
    { n: 2, type: 'right' },
    { n: 3, type: 'down' },
    { n: 4, type: 'reveal' },
  ] as const
  const played = applyActs({ ...ready, acted: 1 }, acts)
  expect(played.cursor).toEqual({ x: 5, y: 5 })
  expect(played.acted).toBe(4)
  expect(played.marks[5 * 9 + 5]).toBe(OPEN)
  // Nothing newer: the same game back
  expect(applyActs(played, acts)).toBe(played)
  // After a reload the hooks module counts its moves from 1 again: every move it lists is new
  const reloaded = applyActs({ ...played, acted: 15 }, [{ n: 1, type: 'left' }])
  expect([reloaded.cursor, reloaded.acted]).toEqual([{ x: 4, y: 5 }, 1])
})

The face that wrapped

The face is four rows of text, nine columns wide (FACE_WIDTH = 9), drawn in Claude Code's own orange: the theme's claude colour, so it follows your theme. The status sits beside it in a row of boxes.

A row of boxes shrinks every box to fit. In a real pane the face's column came out one column short, and each of its nine-column rows wrapped in two. Eight rows of orange, and a face that looked like something had sat on it.

The tests find the face by its text (eyes(' ● ● '), a ui.find for that Text in the board), and the text was right. The strings were nine columns wide; the column holding them was eight.

The fix is a fixed width plus flexShrink: 0 on the face's column. The status column beside it shrinks and truncates (wrap: 'truncate-end'), so the long status is the part that gets cut, and the face's own rows truncate rather than wrap:

  // The face's column keeps its width, so long text beside it is cut and the
  // face is not.
  const face = faceRows(game).map((row) => Text({ ...row.style, wrap: 'truncate-end', children: [row.text] }))
  const faceColumn = Box({ flexDirection: 'column', width: FACE_WIDTH, flexShrink: 0, children: face })

The board's own rows carry flexShrink: 0 for the same reason.

The mouse that wasn't there

On Claude Code's main screen, the pane gets no clicks. Claude Code asks the terminal for pointer reporting only in the fullscreen layout: CLAUDE_CODE_NO_FLICKER=1 at start, or /tui fullscreen in a session. On the main screen it asks for none at all.

In the kit, ui.pointer({ type: 'down', ... }) hands the board a click directly. In a real terminal the click has to be asked for first. To see whether Claude Code asked, tmux display-message -p '#{mouse_any_flag}' prints the terminal's mouse flag.

So the game is keyboard-first, and every action has a key. The letter keys (n new, r reveal, f flag, w a s d to move) are the hotkeys of the control buttons from the previous bug, drawn by the hooks module, so they work as soon as the pane has the keyboard, with no click. Arrow keys, h j k l, space and return reach the board through onKey, which a Client gets only after a click gives it the keyboard. Escape hands the keys back to the prompt.

The line under the buttons says which screen you are on:

// One line under the controls, for the screen the pane is on: the mouse
// exists only in the fullscreen layout, and a pane without the keyboard
// takes them back with ctrl+x tab.
function hintFor(isFocused: boolean, isFullscreen: boolean): string {
  if (!isFocused) return 'ctrl+x tab gives the pane the keys again.'
  if (isFullscreen) return 'Click reveals, right-click flags; click a fully flagged number to open around it.'
  return 'Keys only on this screen: /tui fullscreen adds the mouse.'
}

The loop that found them

So the test kit gets the same treatment as the agent: I don't leave it alone either. Before a mod counts as done, it runs in a real interactive session, driven by a script. tmux does the driving: start Claude Code detached at a fixed size, type the command, send mouse escapes for clicks, and read the screen back as text.

tmux new-session -d -s mod -x 160 -y 50 "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 CLAUDE_CODE_NO_FLICKER=1 claude --plugin-dir <mod>"
tmux send-keys -t mod -l '/<command>'; tmux send-keys -t mod Enter
tmux send-keys -t mod -l $'\e[<0;COL;ROWM'; tmux send-keys -t mod -l $'\e[<0;COL;ROWm'   # left click (SGR); button 2 is right
tmux capture-pane -t mod -p        # the screen as text; -e keeps the colours

A few notes on it:

Run it from an empty trusted folder, so no project hooks fire.
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 is the switch mods need on 2.1.285 and 2.1.286. From 2.1.287 they load by default.
\e[<0;COL;ROWM is an SGR mouse press at that column and row, and the lowercase m is its release. Swap the 0 for a 2 to right-click.
capture-pane -p prints the screen as plain text, which means Claude can read its own UI back and check it.

One rule for the loop: never script a win. The best time lives in the plugin's $.store, which survives sessions, so a scripted win writes a record to the real store, and my best time would belong to tmux. The live sessions played through a loss. The wins, and the stored best time, are covered by tests with a store double.

Pin the build, and show what your mod can see

claude -p "/plugin-types" writes .claude/types/claude-code.d.ts for the installed build, so one pinned Claude Code build serves the typings, the engine and the test kit, and the three can't disagree. Typecheck against those, and leave the typings on the main branch of anthropics/claude-code alone: the two drift. On main, ui.open answers void. On 2.1.285 it answers { isPlaced }.

# Claude Code writes these: `/plugin-types` into .claude/types/, and loading a
# mod into its own folder. Each build writes its own, so none is committed.
.claude/types/
*/.claude-plugin/types/
*/tsconfig.json

/plugin-types runs without a login on 2.1.285, behind the switch. From 2.1.287, claude -p asks for a login. So CI runs two jobs on every push to main and every pull request. The first writes the typings, typechecks, validates and tests on 2.1.285:

  # The typecheck, on the one build that writes its mod typings without a
  # login: one build for the typings, the engine and the test kit, so they
  # cannot disagree. Mods are early access on it, behind the switch.
  typecheck:
    runs-on: ubuntu-latest
    env:
      CLAUDE_CODE_VERSION: 2.1.285
      CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: '1'
      DISABLE_AUTOUPDATER: '1'
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: 22

      - name: Install Claude Code
        run: npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"

      - name: Write the mod typings for that build
        run: claude -p "/plugin-types" < /dev/null

      - name: Typecheck
        run: npx -y -p typescript@5.9.3 tsc -p .

      - name: Validate and test each game
        run: |
          for manifest in */.claude-plugin/plugin.json; do
            game="${manifest%/.claude-plugin/plugin.json}"
            claude plugin validate --strict "$game"
            claude plugin test "$game"
          done

The second installs 2.1.288, where mods are on by default, validates the marketplace, and runs claude plugin validate --strict and claude plugin test again, on the kind of build players run.

Then there's what the mod can see. The host reads on(...) and $.noun.method(...) from the hooks module's source before it runs any of it, which is why register.ts spells them literally and keeps every helper that takes $ at the top level. claude plugin validate ./minefield prints what it read:

❯ ./register.ts hooks: session.start, command.run{command=mines}, ui.render{component=Pane}, ui.message
❯ ./register.ts calls: $.clock.after (via focusSoon), $.clock.now (via deal), $.command.register, $.session.surfaces, $.store.get, $.store.set (via recordWin), $.ui.invalidate, $.ui.open (via openPane), $.ui.panes (via refocus), $.ui.resolve
❯ ./register.ts surface modules: hooks/board.ts

Four hooks: session start, its own /mines command, pane drawing (it draws its own and passes every other pane on untouched), and messages from its board. No prompt, tool or attachment hook, and no network call. The "By Reporails" at the end of the status line is a Link element; your terminal opens it, and the mod makes no request.

When I pulled the awesome-claude-code-mods data on 3 October 2026, 479 of its 1,018 mods were listed as seeing every prompt or every tool call. Plenty need to: the tool-call counter on Anthropic's own mods overview has to see every tool call. A Minesweeper has no use for either. The count, if you want to re-run it:

curl -sL https://raw.githubusercontent.com/karanb192/awesome-claude-code-mods/main/data/mods.json | python3 -c "import sys,json;m=[x for x in json.load(sys.stdin)['mods'] if x['kind']=='mod'];print(sum(any(k in ' '.join(x['sees']) for k in ('every prompt','every tool call')) for x in m),len(m))"

Bonus: making a 9×9 board fill a docked pane

In a wide fullscreen layout the pane docks beside the transcript and opens floor to ceiling, at the 60 columns it asks for. A 9×9 board at one row a cell uses a corner of that. fitFor picks the biggest cell the room holds, from the pane's columns and rows, biggest cells first and the face under the board before beside it:

// Every fit, biggest cells first; under the board before beside it.
const FITS: readonly Fit[] = [
  ...SCALES.flatMap((k) => [
    { width: 2 * k, height: k, side: false },
    { width: 2 * k, height: k, side: true },
  ]),
  { width: 3, height: 1, side: false },
  { width: 3, height: 1, side: true },
  { width: 2, height: 1, side: false },
  { width: 2, height: 1, side: true },
  { width: 1, height: 1, side: false },
  { width: 1, height: 1, side: true },
]

// The biggest fit the room holds; with the room unknown, or too small for
// any, a row a cell, two columns wide where the room has them, the face under
// the board.
export function fitFor(cols: number, rows: number, room: { columns: number; rows: number }): Fit {
  const fit = FITS.find((f) => columnsFor(f, cols) <= room.columns && rowsFor(f, rows) <= room.rows)
  return fit ?? { width: cellWidthFor(cols, room.columns), height: 1, side: false }
}

SCALES is [3, 2], so the big fits are cells six columns by three rows, or four by two. A terminal cell is about twice as tall as it is wide (the reason a board at one row a cell already spends two or three columns a cell where it can), so 2k columns by k rows is square on screen. The gaps need the same care. Each tile is width - 1 columns of colour with a one-column gap after it, and its last row is an upper half block, ▀, so the gap between rows is half a row tall, the same size as the one-column gap between tiles. At the six-by-three fit that's five columns by two and a half rows of colour, square again:

  const across = fit.width - 1
  const glyphRow = Math.floor((fit.height - 1) / 2)
  const glyphAt = Math.floor(across / 2)
  for (let y = 0; y < game.rows; y++) {
    const tiles: Tile[] = []
    for (let x = 0; x < game.cols; x++) tiles.push(tileOf(game, x, y))
    for (let r = 0; r < fit.height; r++) {
      const runs: Run[] = []
      for (const { glyph, ink, fill } of tiles) {
        if (r === fit.height - 1) pushRun(runs, '▀'.repeat(across), { color: fill })
        else if (r === glyphRow) pushRun(runs, ' '.repeat(glyphAt) + glyph + ' '.repeat(across - glyphAt - 1), { ...ink, backgroundColor: fill })
        else pushRun(runs, ' '.repeat(across), { backgroundColor: fill })
        pushRun(runs, ' ', {})
      }
      out.push(runs)
    }
  }

Since fitFor is a pure function, the sizes are tested without a pane:

  // A docked pane: square tiles three rows tall, or two, where they fit
  expect(fitFor(9, 9, { columns: 60, rows: 36 })).toEqual({ width: 6, height: 3, side: false })
  expect(fitFor(9, 9, { columns: 60, rows: 25 })).toEqual({ width: 4, height: 2, side: false })

Above the prompt, rows are what's scarce, so the pane asks for the rows of the most compact fit the terminal's width holds: one row a cell, a hidden tile drawn as a short box (▆▆), and the face and the status beside the board where they fit there.

Play it

In a Claude Code session:

/plugin marketplace add reporails/arcade
/plugin install minefield@reporails-arcade

Then /mines. It needs Claude Code 2.1.287 or later. For the docked pane and the mouse, start Claude Code with CLAUDE_CODE_NO_FLICKER=1, or run /tui fullscreen. If minefield doesn't load, run claude plugin test in an empty folder: no hooks module to load means mods load for you. hooks modules are turned off here means a setting blocks them: disableAllHooks in your settings, or your organization's policy. hooks modules are turned off in this process means Anthropic has them off for your account, and no local setting changes that.

The repo is MIT, reporails/arcade on GitHub. Post your best time in the comments.

Progressive Disclosure: Claude Code Hooks, Events and Telemetry

Gábor Mészáros — Wed, 30 Sep 2026 12:49:50 +0000

The last piece (Progressive Disclosure: Shaping Claude Code's Output) ended on one small move. Every reply opens with its kind, [status], [analysis] or [narration], and that token decides which reply-shape rules apply and which checks run when the reply ends. One Stop hook read the token and did the rest.

That's also where the approach runs out. Stop fires once the reply is written, so a hook there can judge the reply and send it back, but anything it wants the agent to know arrives after the words are already on the screen. And the one script keeps growing: the length check, the kind check, a counter for how often the kind goes missing, and next a rule for the docs folder that has nothing to do with the end of a reply.

The first piece in the series (Progressive Disclosure: What, Where, When, and Why) left two promises open: when to move a rule off the page and onto an event, and how you'd know it loaded. This piece keeps both.

Different moments, different rules

A rule set is several lists, one per moment of a turn, and Claude Code can run a script of yours, called a hook, at each of those moments (hooks):

A prompt arrives (UserPromptSubmit). Whatever a hook prints here goes in front of the model before it starts. That's the place for a rule about the work ahead: while you're on a database migration, every migration ships with a down step.
A tool is about to run (PreToolUse). A hook here sees which tool and which file. A documentation rule belongs on the write under docs/, not on every prompt. What it adds lands next to the tool's result, so it shapes the edits after the first one. When even the first write has to follow the rule, the hook blocks the call and puts the rule in the reason.
The reply ends (Stop). The reply is finished and can be judged, so this is where checks live. The right check depends on the kind of reply: a status report gets 180 words, a narration 150, an analysis no cap. A reply over its limit goes back once.

Checks split the same way. A migration's down step can't be checked until the file exists, so that check runs after the write, on a fourth moment, PostToolUse. The length check waits for the finished reply and takes its limit from the reply's kind. Claude Code supplies the moments, and matching each rule and check to its moment is left to you.

Why one rule per hook stops scaling

The obvious way to wire this up is one hook per rule: a script and a settings.json entry each. Anthropic's hookify plugin tidies that up. Each rule is a markdown file naming an event, a pattern and an action, and the plugin's own hooks check every rule file on each event. For a handful of rules that warn or block on what the harness can see, a command, a file, a prompt, it's the right start.

Around rule twenty, or once a rule needs to know what the last reply said, the cracks show:

Each rule sees only the one event in front of it, and can match only what that event carries: a command, a file path, the prompt text.
Nothing remembers anything between events. Sure, every hook gets a transcript_path, so a rule could go digging for the last reply itself. Then every rule digs on its own, on every event, and you're back to twenty scripts parsing the same file.
Nothing records what fired, so there's nothing to count.
With a script per rule, a rule's condition also ends up in three places: a pattern in the script, a matcher in settings.json, and the rule's text somewhere else.

The fix is to send every event through one place. Here that place is an event bus, a single script Claude Code calls for every hook event you care about. It reads the event once, works out which rules asked for it, and answers the harness. Your settings.json shrinks to one script, registered on each event:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/bus/bus.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/bus/bus.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/bus/bus.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/bus/bus.sh"
          }
        ]
      }
    ]
  }
}

Put telemetry on it first

Before you move a single rule onto the bus, have it write down what happens. It's the cheapest step, and it changes what you can see.

The agents that build Reporails open every reply with its kind and get checked on it when the reply ends. In the 13 days before I wrote this, across four of our repositories, they made 1,979 reply attempts, resends included, and 106 of them opened without a kind. That's about 1 in 19. All our end-of-reply checks together sent back 497 of those attempts, about 1 in 4. From the terminal you'd catch the odd resend scrolling past and never put a number on it. We have the number because a hook wrote every attempt down.

Claude Code already hands you part of this. Its InstructionsLoaded hook fires whenever a CLAUDE.md or .claude/rules/ file enters context and reports why: session_start, nested_traversal, path_glob_match, include or compact (hooks). Rulestack has a good write-up on logging it by itself (Did Claude Code actually load your rules?). On the bus it's one more event going into the same log.

Here's the whole first version of the bus, .claude/bus/bus.sh:

#!/usr/bin/env bash
# Every hook event comes through here. Step one: write down what happened.
jq -c '{ts: (now | todate), event: .hook_event_name, tool: .tool_name,
        file: (.tool_input.file_path // .file_path), reason: .load_reason,
        kind: ([(.last_assistant_message // "") | scan("^\\[([a-z]+)\\]")[0]] | first)}
       | with_entries(select(.value != null))' >> "$(dirname "$0")/log.jsonl"

Make it executable with chmod +x .claude/bus/bus.sh, and make sure jq is on your PATH. From then on, every event becomes one line in log.jsonl:

{"ts":"2026-09-30T09:27:55Z","event":"InstructionsLoaded","file":"/repo/CLAUDE.md","reason":"session_start"}
{"ts":"2026-09-30T09:27:55Z","event":"UserPromptSubmit"}
{"ts":"2026-09-30T09:27:55Z","event":"InstructionsLoaded","file":"/repo/.claude/rules/docs.md","reason":"path_glob_match"}
{"ts":"2026-09-30T09:27:55Z","event":"PreToolUse","tool":"Write","file":"/repo/docs/cache.md"}
{"ts":"2026-09-30T09:27:55Z","event":"Stop","kind":"status"}
{"ts":"2026-09-30T09:27:55Z","event":"Stop"}

And two questions you can already answer, how often each event fires and how many replies skipped their kind:

$ jq -s 'group_by(.event) | map({(.[0].event): length}) | add' .claude/bus/log.jsonl
{"InstructionsLoaded":2,"PreToolUse":1,"Stop":2,"UserPromptSubmit":1}
$ jq -s 'map(select(.event == "Stop"))
    | {replies: length, missing_kind: map(select(.kind == null)) | length}' \
    .claude/bus/log.jsonl
{"replies":2,"missing_kind":1}

That's the telemetry layer: which rule files loaded and why, which tools ran on which files, and which replies skipped their kind.

With great responsibility comes great power

Concentrating the events in one place and adding your own logic on top of the harness is a huge responsibility. The power it gives you is just as big.

The scattered pieces come together. Once your rules move onto it, they live in one folder, each with its moment in its own header, and one log records what happened. Listing every rule with its condition is a grep. Seeing what fired last Tuesday is a jq query.

You can bend it to what you need. A settings.json matcher can only filter on what Claude Code puts there: the event, plus one field it picks per event, such as the tool name. InstructionsLoaded's five reasons are all about files or the session. A script can match on anything it can read, and the bus sees every event, including what the last reply declared. Put a domain next to the kind, [status][migration], save it when the reply ends, and a rule can load for the work instead of for a file:

---
on: PreToolUse
tool: Write|Edit
path: */docs/*
declared: migration
---
When you document a migration, name its down step and the release that stops reading the old column.

on is when, tool and path are where, declared is why, and the body is what gets delivered. This rule loads when the agent writes under docs/ while the work is a migration, and stays out of every other turn. The bus can only read the declaration once the reply is finished, so it applies from the next turn on. The domain sticks until another one is declared; the kind belongs to one reply. Getting there takes one more step in the bus: for each rule, check its on, tool, path and declared against the event and the saved declaration, and deliver the body of every rule that matches.

You stop being locked to one agent. The rules and the log are plain files in your repository. The only part of the bus that knows it's talking to Claude Code is the part that reads the hook's input. The other agents that ship hooks send the same kind of input. Codex reads hooks from .codex/hooks.json with largely the same event names as Claude Code, and passes the finished reply as last_assistant_message, the same field the bus reads (Codex hooks). Cursor reads .cursor/hooks.json with names of its own, such as beforeSubmitPrompt, preToolUse and stop (Cursor hooks). Gemini CLI reads hooks from its settings.json, with BeforeTool and AfterAgent (Gemini CLI hooks). All of them pass a JSON payload on stdin with a hook_event_name field, and all of them read exit code 2 as "block this". The answers they expect back differ, so one small adapter per agent maps its event names in and its answers out, and the same rules and the same log serve all of them.

Agent	Hooks live in	A few of its event names
Claude Code	`.claude/settings.json`	`UserPromptSubmit`, `PreToolUse`, `Stop`
Codex	`.codex/hooks.json`	`UserPromptSubmit`, `PreToolUse`, `Stop`
Cursor	`.cursor/hooks.json`	`beforeSubmitPrompt`, `preToolUse`, `stop`
Gemini CLI	`settings.json`	`BeforeTool`, `AfterAgent`

The responsibility part

For the rules in .claude/rules/, Claude Code decides when they load. For the rules on your bus, you do. Nothing tells you which moment a rule belongs to, which two rules now say opposite things on the same turn (Opus 5: Cost of Instruction Conflicts), or which one hasn't loaded since you renamed a folder. Rename docs/ to doc/ and the docs rule never matches again. Start declaring [db] where you used to declare [migration], and the migration rules go quiet the same way. Either silence looks exactly like a week where nobody touched the docs or a migration.

The log shows what loaded. It can't show a rule that should have loaded and didn't, or whether a rule that did was worded well enough to steer anything. How you keep a rule set organized once the harness stops doing it for you is the next piece.

Progressive Disclosure: Shaping Claude Code's Output

Gábor Mészáros — Wed, 23 Sep 2026 13:26:12 +0000

Opus 5.5 shipped on September 22, and its replies read differently: answer first, less throat-clearing. Box, testing it before launch, found its answers "40% less verbose without losing accuracy", and Factory measured "20 to 25% fewer output tokens" (Introducing Claude Opus 5.5). Those are two teams' numbers on their own workloads, and they point the same way.

The shape of the reply is still yours to set. A shorter default helps the rename and shortchanges the design question, and what you actually want is both: two lines when you ask for a rename, the full walkthrough when you ask whether the cache belongs in Redis, on every turn, without saying which each time. That makes it a loading problem. The instruction that shapes the reply has to be in front of the model on the turn it applies and out of the way on the others.

The first piece in this series split progressive disclosure into three handles: what loads, where it loads, and when (Progressive Disclosure: What, Where, When, and Why). This one takes a single concern, the shape of the reply, and walks it up through every place Claude Code will load an instruction from. Each step gets further than the last and ends on its own limit. Then we go one level up.

Output style: one shape for the whole session

Claude Code has a setting for exactly this. An output style is "a set of instructions that sets Claude's role, tone, and response format for every response in a session", and the built-in Concise style is pure reply shape: the first sentence states the answer, the lead-in, the step-by-step narration and the closing recap go, a simple question gets one to three sentences, and the engineering work stays as thorough as in the default style (output styles). Pick it with /output-style concise, or write your own as a markdown file in .claude/output-styles/.

The reason to reach for it is where it sits. The style's instructions travel with the system prompt on every request. Your CLAUDE.md "is delivered as a user message after the system prompt, not as part of the system prompt itself" (memory), and Anthropic's prompting guide, for this exact problem, says to "use direct instructions in the system prompt: 'Respond directly without preamble'" (prompting best practices). The rule reads the same in both places; the output style gives it the higher seat.

This is the lean root from the first piece: a rule that applies to every reply earns its always-on slot. Its limit is built into the definition, though. It's one shape for the whole session, so the rename and the design question get the same one.

Path rules: triggered by the file

Rules that apply only sometimes go in .claude/rules/, one topic per file. Give a rule a paths field and it becomes conditional: path-scoped rules "trigger when Claude reads files matching the pattern", and stay out of context otherwise (memory).

---
paths:
  - "docs/**"
---
When answering about documentation, open with the context the reader needs, then the change.

That rule shows up when Claude reads a file under docs/ and stays out of the rename in src/app/nav.tsx. What triggers it is the file the agent touches. A design question can arrive while the agent has any file open, and no glob tells a design question from a rename.

Auto memory: the model decides what loads

Auto memory is the built-in handle that comes closest to loading on relevance. Claude saves "corrections you give Claude and approaches you confirm" into one directory per project, ~/.claude/projects/<project>/memory/. The first 200 lines (or 25KB) of the MEMORY.md index load at the start of every session. The topic files behind it don't: Claude "reads them on demand using its standard file tools when it needs the information" (memory). Correct the shape of a design answer a couple of times and you may find a one-line entry, design answers: trade-offs first, with the full note behind it.

The index is always there and the detail comes in when it's needed. Which detail, and when, is Claude's call, made from a line Claude wrote. You can open and edit every one of these files with /memory, but by default Claude does the writing, and the docs call auto memory "machine-local": the laptop that learned how you like design answers is the only machine that knows.

UserPromptSubmit: you decide, inside a regex

To take the routing back, Claude Code runs a UserPromptSubmit hook on every message before Claude sees it. The hook gets your text in the prompt field on stdin, and plain stdout on a clean exit is added as context Claude can see (hooks). So you classify the turn yourself, in .claude/hooks/reply-shape.sh:

#!/usr/bin/env bash
# UserPromptSubmit hook: add the reply shape that fits this kind of turn.
prompt="$(jq -r '.prompt // ""')"

if grep -qiE '\b(why|should we|trade-?offs?|design|architecture|compare)\b' <<<"$prompt"; then
  echo "Reply shape for this turn: a design question. Lay out the options and their trade-offs, then recommend one."
elif grep -qiE '\b(rename|typo|bump|move|delete)\b' <<<"$prompt"; then
  echo "Reply shape for this turn: a routine edit. Make the change, then answer in one or two sentences."
fi
exit 0

Wire it under hooks.UserPromptSubmit in .claude/settings.json. The event takes no matcher, so it runs on every prompt:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/reply-shape.sh" }] }
    ]
  }
}

Now the decision is yours, made the same way on every turn. Look at what happened to the rule on the way. "Lay out the trade-offs, then recommend" is a string inside an echo, its condition is a regex two lines above it, and whether any of it runs is decided in a JSON file somewhere else. "Rename the design tokens" matches both lists, and the first match wins.

Stop: a check after the fact

The last handle runs once the reply is written. A Stop hook receives the finished reply as last_assistant_message; exit with code 2 and the stop is blocked, with your stderr fed back to Claude to try again. stop_hook_active is true when a Stop hook already sent the reply back, which is your loop guard (hooks). Save this one as .claude/hooks/gate-length.sh and wire it under hooks.Stop:

#!/usr/bin/env bash
# Stop hook: send an over-long reply back once.
input="$(cat)"
[ "$(jq -r '.stop_hook_active // false' <<<"$input")" = "true" ] && exit 0

words="$(jq -r '.last_assistant_message // ""' <<<"$input" | wc -w)"
if [ "$words" -gt 180 ]; then
  echo "Your reply ran ${words} words; the budget is 180. Put the result first and cut the recap." >&2
  exit 2
fi
exit 0

This one is a check. It loads nothing into the model's context before the reply; it measures what came out and sends it back. It also shares the output style's blind spot: 180 words is the budget for the rename and the design question alike.

Where the harness comes short

This claim is easy to overstate, so here it is precisely. The harness does load on relevance: memory topic files and skills come in when they're needed. Rules can declare paths. A hook can route by the kind of turn, as reply-shape.sh does. Each handle did its job. What the harness does is deliver rules. Organizing them is left to you, and that shows up in four places:

A rule's text and its loading condition live apart. The design-answer rule is an echo string, its condition is a regex in the same script, and its switch is an entry in settings.json.
Loading conditions come in five forms. Always on, a path glob, the model's judgment, a regex on the prompt, a check on the finished reply. Each form follows what the harness exposes at that point (a file read, the prompt text, the reply), and none follows the situation you care about, which is what kind of turn this is.
Nothing lists every rule with its condition, and nothing tests whether two collide. The output style says result first; the docs rule says context first; on a design question about the docs, both are in the window. The model picks one and raises no error (Opus 5: Cost of Instruction Conflicts).
Nothing lets the reply's shape change with the kind of turn and bring its own checks along. The Stop hook's budget has no idea the turn was a design question.

One level up: the reply declares its kind

So we moved the problem up a level in our own setup. The agents that build Reporails open every reply with a declared kind: [status] for a work report, [analysis] for reasoning, [narration] for how something works, [handover] for the brief a session hands its successor, plus domain tokens such as [surface] when the work is the public site. That one token decides two things: which reply-shape rules apply, and which checks run when the reply ends.

In practice, [narration] relaxes the check that counts separate blocks in a reply, since an explanation reads as paragraphs, and keeps the 150-word length check. [handover] relaxes seven checks that a recap of finished work would trip by construction, and the check that stops a reply from handing new work back to me still runs. [surface] switches on a periodic re-read of our visual-review rules, but only while that domain is the current work, so a research session never pays for it. A mislabelled reply still hits every check its label doesn't relax, so the token scopes the checks without becoming a way around them.

That's output style done as progressive disclosure. The shape rules load according to the kind of turn, the rules and the map from kind to rules live outside the harness as plain files, and the harness only delivers them, through one Stop hook. Each of those files states the situation it applies to next to its own text, which also covers rules that no harness handle can express directly. One of ours reads, in effect, "load this before the agent writes a file in our knowledge base". Path rules fire when Claude reads a matching file, and the moment we need comes before it writes one. You could build that with a PreToolUse hook, with the glob in yet another script. In our setup the condition sits in the rule's own header.

One Stop hook is the naive version of this. Look at what it needs underneath. Each rule names the moment it applies to: before a write to the knowledge base, at the end of a reply of a given kind, every few turns while a domain is the current work. The harness fires its own events (a prompt arrives, a tool is about to run, a reply ends), and none of them is one of those moments. Something has to sit between the two, turning each harness event into the moment it represents and handing over only the rules that asked for that moment. That something is an event bus, and why a rule set outgrows its harness without one is the next piece.

Once the rules live one level up, the question you ask changes from where a rule goes to what the whole set does on this turn.

Progressive Disclosure: What, Where, When, and Why

Gábor Mészáros — Wed, 16 Sep 2026 18:01:55 +0000

Do you remember when we first started using AGENTS.md files?

You would have a project root file describing the project, and some nested ones describing the content in the folder where they reside. This opened up exciting possibilities for everyday users: For the first time you could put a rule where the work was and trust it to show up only there. I ran an entire project this way once, one small instruction file sitting in each layer of the codebase.

You only had to keep the mental model locked, and you could manage your instructions so they loaded only when the agent was working in the folders they belonged to.

This was one of the earliest forms of progressive disclosure, and coding agents still support it to this day. It comes with a price, though. Relevant instructions only load if the agent is working in your folder. So you hit the classic context rot problem right away, because you might be working on the backend while some frontend pieces need adjusting along with it. Having the coding agent work front and backend at once always causes mayhem: the instructions compete for attention, and the system has to split its attention between the two big areas.

Cursor and Claude were quick to offer a finer-grained solution here. Instead of scattering some number of AGENTS/CLAUDE.md files through the subfolders, you use a harness artifact that carries the path configuration for where to load. Not just folder level, but file level. Dandy. Problem solved? Not even close.

The problem

So what is the problem itself? To see why even file-level scoping is not the finish line, go back to the crudest option for a second. Wouldn't it be easier to just load everything into the context at one go and leave the LLM to figure out the rest?

That is what most of us tried first, and it is the reason your CLAUDE.md is three hundred lines long, the kind of file people now argue you should just delete (Opus 5: Delete your CLAUDE.md?). Every rule you ever wrote, in the window every turn, always in reach. It feels like the careful choice, but it is the expensive one, and tokens are the smallest part of the bill.

A model does not work through your instructions the way you work through a checklist, line by line, giving each one its moment. It spreads a fixed amount of attention across everything in front of it, and every line you add is one more thing pulling on that same budget. Ten rules and each gets a real share. A hundred, and the one rule that matters for this turn is a single voice in a crowded room, shouting over ninety-nine others that have nothing to do with the task at hand. It is the front-and-backend problem again, the one from a moment ago, except now you have signed the agent up for it permanently: every turn, every rule, all at once.

This is not just a hunch about attention. When we went through 28,721 real repositories, the median instruction file carried about fifty items and only a dozen of them were actual directives. The rest was scaffolding the model still reads past on every turn: most of your always-on file is not even telling the agent to do anything, and all of it competes for the same budget. We wrote that up as The State of AI Instruction Quality.

So "load everything" does not dodge the problem. It is the problem, turned all the way up.

That is what the path configuration was for. Loading the payments rule only when the agent is actually in the payments code is the honest fix: keep each rule out of the crowd until the turn it belongs to. Real progress, and still only part of the answer, because where a rule lives is one lever and there are others.

A rule can be the wrong thing to load, not only loaded in the wrong place. It can be something you want at a moment rather than in a folder. What you actually want is a way to decide, for every rule you have, what loads, where, and when. That already has a name.

The solution: Progressive Disclosure

What is progressive disclosure? It is the procedure for how you gradually introduce the relevant instructions and context to the coding agent. Instead of one always-on file, you hand the agent each rule at the moment it is about to matter, and keep it out of the way the rest of the time. That is the whole idea. What makes it something you can build with is that it comes apart into three handles, and once you can see them separately you stop reaching for the root file by reflex.

This is also the fix Anthropic now writes down in as many words. In its guidance for the Claude 5 generation, Anthropic's Thariq Shihipar names the habit that grew your file, the "myth ... that you want to make these a central repository for every known practice," and the cure, to "use progressive disclosure heavily" and let the rest load from skills the file points at (the new rules of context engineering).

What loads

A rule does not have to be a line in a file the agent reads top to bottom. Package it as a skill: a self-contained instruction the agent pulls in when the task calls for it and never sees otherwise. Your commit conventions have no business in the window while the agent is chasing a layout bug, and a skill keeps them out of it until you reach for git.

Where it loads

You have already met this one. A rule that only governs the payments code lives next to the payments code: folder level with a nested file, or file level with the path configuration Cursor and Claude added. It shows up on the turns the agent works there and is not in the room the rest of the time. The rule did not get weaker; it got aimed.

When it loads

Some rules only matter at a moment, not in a place. Tie them to the moment: pull a rule in when a session starts, or when a certain kind of work begins, and keep it dark until then. Same rule, later entrance. You are not rewriting it; you are deciding when it walks on.

Why

None of the three changes what a rule says. They change when the agent has to carry it. And what you are short on is not disk space or even tokens; it is the agent's attention on the turn that counts. What, where, and when are three ways to spend that attention on the rule that matters instead of the ninety-nine that do not. Get them right and the three-hundred-line always-on file comes apart into a lean root plus a set of rules that show up on cue: the crowded room empties, and the rule for this turn is one of three in the window instead of one of a hundred. That is the loading problem solved, or as solved as loading gets, the right rule in front of the agent, uncrowded, exactly on the turn it applies.

The file was never the unit

Something changed while you were splitting that file, and it is bigger than the file. You did not tidy a document. You built a system: a lean root, and a set of rules that each load on cue, some pinned to a path, some to a moment. And a system has a shape you can no longer take in by scrolling one file. Is this rule still loading where you think it is? Did you scope that one so tightly it now reaches nobody? Are two of them set to load on the same turn, back to competing for attention, the crowded room rebuilt in miniature? Or worse, are two of them quietly telling the agent opposite things, the kind of contradiction we put a price on in Opus 5: Cost of Instruction Conflicts?

"Is it in the file" was the right question when there was one file. There is no one file now. The question is what actually loads, where, and when, and whether that still matches what you meant. None of it lives in your root file anymore, because you moved it out yourself.

That is the ground the rest of this series stands on. Each piece takes one handle and goes deep, with the code to run it: what loads, and how you would know it did; where to scope a rule so it stops diluting every unrelated turn; when to move a rule off the page and onto an event. (And a rule can load perfectly and the agent can still ignore it. That is a different problem with a different fix, and it earns its own piece.)

When you want to see the shape of what you have built, which rules still load and where two of them now collide, that is the read Reporails gives you: free, on your own machine, on the files you wrote. It reads what you author; it never touches your agent while it runs.

DEV Community: Gábor Mészáros

State of AI Instruction Quality: Repos Split on Co-Authored-By

What the rules go after

Who writes them

Some want a different disclosure

The trailer is a default

A hook catches the rest

A rule every agent reads

Check yours

State of AI Instruction Quality: Files With Persona Lines Score Lower

A file that reads like a prompt

Where the line sits

What to write instead

Check yours

Claude Code mods: Brickfall, a brick breaker that's loud without getting in the way

Loud, but never in the way

Every pixel goes through Claude Code

The paddle follows the pointer

What recording the clip taught me

What it touches

Play it

State of AI Instruction Quality: A Third of Repos Shout

Who has them

ALL-CAPS: a third of repos

Emoji, "please", and thinking out loud

TODOs and hallucinations

Never force-push

The 129,121-word CLAUDE.md

Check yours

State of AI Instruction Quality: /init Files Score Higher

A map, then a few rules

Where its rules go wrong

What to do with yours

The State of AI Instruction Quality: Q3 2026

91% of repos carry at least one vague instruction

Stars don't predict the score

Who writes for which agent

Sub-agent files score lowest

7.6% of repos back their instructions with a hook

What held from April

How we measured

Check your own files

Next in this series

Progressive Disclosure: Why Isn't Claude Code Following My Instructions?

Same spec, two wordings

What came back

It did what the spec said

Where the fade comes in

Checking what you load

And the organizing part

Claude Code mods: but does it run Doom?

Doom runs in a process of its own

Pixels that never pass through Claude Code

Claude Code stops drawing when nothing moves

The keyboard that never lets go

The mouse is the only exact hold

Escape belongs to the prompt

What the test kit missed this time

Play it

Claude Code mods: Minesweeper and testkit

The pane and the keyboard

Hotkeys that did nothing

The face that wrapped

The mouse that wasn't there

The loop that found them

Pin the build, and show what your mod can see

Bonus: making a 9×9 board fill a docked pane

Play it

Progressive Disclosure: Claude Code Hooks, Events and Telemetry

Different moments, different rules

Why one rule per hook stops scaling

Put telemetry on it first

With great responsibility comes great power

The responsibility part

Progressive Disclosure: Shaping Claude Code's Output

Output style: one shape for the whole session

Path rules: triggered by the file

Auto memory: the model decides what loads

UserPromptSubmit: you decide, inside a regex

Stop: a check after the fact

The 129,121-word `CLAUDE.md`