DEV Community: Reporails

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.

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: /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.

Opus 5: How to Review Generated Code

Gábor Mészáros — Thu, 27 Aug 2026 15:56:58 +0000

So, just another Tuesday. You ask Opus 5 for a one-line fix: a date parser is choking on a timezone suffix, change the format string. Twenty seconds later the agent reports done. You open the diff and it is not one line. It is eleven files. It rewrote the parser, renamed a helper three modules over, tidied an import block you never mentioned, and added a caching layer nobody asked for. Every test is green (actually have 11 more). The check passed, everyone's happy, except you, who now have to decide whether to read four hundred lines to approve a change that was supposed to be one.

The first half of this pair named why that decision is the hard part now. Opus 5 made writing nearly free and moved the whole cost onto review, and the reflex fix, pointing a second model at the first one, rebuilds the problem one guess at a time. That piece stopped at the diagnosis. This one is the other half: what you put in place of the second model, so the eleven-file surprise gets caught by something other than your attention at 6pm.

Anthropic documents that scope blowout as expected behavior. Its own Opus 5 guidance names it plainly: the model "can also expand the scope of a task, adding steps that weren't requested or applying its own judgment about what the task should be." A more capable model that runs longer and finishes more of the job also finishes more of the job you did not ask for. Catching that reliably takes three controls, and they are the ordinary layers of defense in depth: steer the model off the mistake, review what it did, and put a deterministic gate under both. Two of the three keep the mistake out and differ only in how far you can trust them, steering by moving the odds and the gate by refusing outright; review is how you catch what slips between them. What follows names each layer for an agent, ordered by cost rather than by when each runs, but the layered shape itself is the standard one.

Layer one: steering, and the instruction to delete

The instinct, when the agent overreaches, is to write a rule telling it to check itself. Add verify your work before finishing to your CLAUDE.md and move on. On Opus 5 that line costs you and buys nothing. The same Opus 5 guidance is blunt about it: "Claude Opus 5 verifies its own work without being told to. If your prompt contains explicit verification instructions ... remove them," because "instructions like these cause over-verification," and removing them "reduces wasted tokens with no loss in quality." The model already double-checks. Your instruction just makes it burn tokens double-checking louder, and none of that self-checking sees the problem you actually have. A model verifying its own work confirms the eleven files do what the model intended. It has no way to know the model was asked for one.

What belongs in the steering layer is the scope constraint, not the verification order. Anthropic gives you a starting shape for it:

Deliver what was asked, at the scope intended. Make routine judgment
calls yourself, and check in only when different readings of the request
would lead to materially different work. If the request seems mistaken or
a better approach exists, say so in a sentence and continue with the task
as asked rather than quietly narrowing, widening, or transforming it.
Finish the whole task, and stop short of actions that are clearly beyond
what was asked.

That block points the model the right way, and its last line already binds: it names three specific failure modes (narrowing, widening, transforming) and says what to do instead. Two of its other lines lean on words the model has to interpret, and a rule the model interprets is a rule it can set aside. "At the scope intended" asks the model to measure its edits against an intention nobody wrote down as anything checkable. "Check in only when different readings would lead to materially different work" leaves material for the model to define, so the threshold floats. "Stop short of actions clearly beyond what was asked" makes clearly the reader's judgment rather than a line the model can hold an action against.

Give the model a target it can check every edit against instead, starting with the one thing only you can supply: the set of paths this task is allowed to touch.

Write this task's scope as a named set of paths before you change
anything. For this date-parser fix the set is `src/dates/` and its
tests; write your own and keep it in view.

Change only files in the named set. Touch a path outside it only when
the change will not run otherwise, and say so before you edit it.

Make the smallest change that satisfies the request: no caching layer,
no helper rename, no refactoring pass, no new abstraction, even when it
would improve the code.

Check in before starting only when the request could mean different
files, and finish every file in the set the change needs.

If a larger change would help, name it in one sentence and make only the
asked-for one.

Every line now points back at one concrete anchor, the named set, and a rule pinned to a name you wrote down keeps its grip as the context around it grows; an abstract rule fades into it. That is the filter: a line that cannot cite the named set does not earn its place, which is what dropped the vague check-in and the maybe-later hedge from the version above. The block ships pointing at that set; you make it bind by writing your real paths into the top.

That same named set is what Layer three turns into a hard gate, so steering and enforcement guard the same line: one asks the model to stay inside it, the other refuses the write when it strays.

That is steering: it moves the odds that the next diff stays inside the ask. It does not set them to one, because everything on the context surface is an input to a probabilistic process, an instruction the model is free to weigh and set aside on the exact turn it decides the caching layer is a good idea. Steering is the first layer because it is the cheapest and it handles the common case. Lean on it for the routine change, and reach past it for the one you cannot afford to get wrong.

Layer two: procedure, and reviewing what actually ran

When a human does open the diff, the skim is the failure mode the previous article identified as well: the LGTM speedrun, a 300-line diff approved in under three minutes on a gut feeling. The reflex answer is "read more carefully," and it runs out the moment the diff is larger than what fits in your head, which is exactly the diff a scope-expanding agent produces.

A review that scales is a sorting job. Some of what a reviewer checks has a definite answer a rule can settle: whether the suite passes, whether the types hold, whether the change touched a path it was never scoped to, whether a secret landed in the diff. The rest needs a model of the world the change lives in, and only a person has that. The process is to send the first pile to something that runs every time without you, which is Layer three, and spend your own reading on the second.

What is left once the machine-checkable part is routed away is a real review, and two practices carry most of it. Neither trusts the diff on sight.

Review by executing. Run the code the agent wrote against the case you cared about in the first place. A diff can read as plausible and still behave differently once it runs, so the caching layer it added stays a claim until you exercise it. An executing reviewer, a person or a CI job that runs the change, tests what it actually does.
Probe the tests with a mutation. A green suite tells you the tests pass. It does not tell you the tests would fail if the code were wrong. Change one thing the code should care about, revert a guard, flip a comparison, delete a branch, and confirm a test goes red. If nothing does, your tests pass no matter what the code does, and a scope-expanding agent leaves exactly that behind: new code, new tests, all green, and not one test that would notice if the new code were broken. This is mutation testing done by hand; tools like mutmut, cosmic-ray, and Stryker automate the same probe, and practitioners reach for it precisely when an agent wrote both the code and the tests that vouch for it.

A model can take the first pass over what remains, in one specific role. Anthropic's note on Opus 5 as a reviewer is worth reading against the "a model checking a model" warning from the first half: the model "reviews code with high precision and recall," and the guidance is to "ask it to report everything and filter in a separate pass." Use it as a fast first reader that surfaces candidates cheaply, with one rule: the reviewer cannot be the author. A model grading its own diff carries the blind spot that produced it, the same reason you do not review your own code by rereading it. A fresh instance of the same model clears the context it sat too close to, though not the blind spots baked into the model itself, so the strongest version of this pass is a different model or a person. Point a fresh reader at the change and filter its findings yourself, because deciding which of them matter, and whether the scope was even right, is judgment a second model cannot hand you.

Layer three: enforcement, the gate that just refuses

The instinct is to put the reviewer last, as the final gate before main. That instinct is the bug. A reviewer, a person skimming at 6pm or a model grading a model, is exactly what you cannot trust as the last word, so the deterministic gate goes under the review, not the reviewer over the gate.

Steering moves the odds; the review reads what steering let through. The third layer runs every machine-checkable question automatically, so no person re-runs it. A rule that runs this way forms no opinion about the diff, so it returns the same verdict on the hundredth change as on the first, however large the change grows.

Most of this layer is enforcement you may already own and may be running as advice instead of as a floor. The test suite, the type checker, the linter, a secret scanner: wire them as required checks in CI and put branch protection in front of the merge, so a failing check refuses the merge rather than leaving a red mark a tired reviewer waves through. Then add the checks the agent's own failure modes call for, a scope guard and a mutation gate among them. That is the outside enforcement, and it runs after the change is written, at the pull request.

One piece of this layer CI cannot give you, because CI only sees the change after it is written: a gate that fires inside the agent loop, before the write lands. That is the one that fits the scope blowout.

The gate for an agent that touches files it was never asked to touch is a blast-radius guard: refuse a write to any path outside the set this task was scoped to. Claude Code fires a PreToolUse hook before a tool call executes, and an exit code of 2 blocks the call and hands your message back to the model (per the hooks docs). Save this as .claude/hooks/guard-blast-radius.sh and make it executable:

#!/usr/bin/env bash
# guard-blast-radius.sh: refuse a Write/Edit/MultiEdit outside the files this
# task was scoped to. Runs as a Claude Code PreToolUse hook. Exit 2 blocks it.
# Requires jq.
payload=$(cat)   # the pending tool call arrives as JSON on stdin
path=$(jq -r '.tool_input.file_path // ""' <<<"$payload")
cwd=$(jq -r '.cwd // ""' <<<"$payload")

# Claude Code passes file_path relative to cwd, but strip cwd anyway so the
# allow-list holds whether the path arrives relative or absolute.
rel="${path#"$cwd"/}"

# Reject .. traversal, or src/dates/../../etc/passwd slips through the prefix.
case "$rel" in *..*) echo "blocked: '$path' uses .. path traversal." >&2; exit 2;; esac

# The blast radius for this task: the only paths a write is allowed to touch.
# Keep it somewhere you edit per task, or read it from a file.
allowed='^(src/dates/|tests/dates/)'

[ -z "$path" ] && exit 0                      # no path in this call, nothing to guard
  if ! grep -qE "$allowed" <<<"$rel"; then
    echo "blocked: '$path' is outside this task's blast radius ($allowed). \
  If the change genuinely needs this file, widen the scope on purpose, not in passing." >&2
    exit 2   # exit 2 == hard block; the stderr message goes back to the model
  fi
exit 0

Wire it to the write tools in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/guard-blast-radius.sh" }
        ]
      }
    ]
  }
}

Now the agent that was asked to fix a date parser tries to rename a helper three modules over. The transition fires before the write, the path fails the allow-list, and the write never lands. The model sees the refusal in the same turn and has to either stay in scope or say out loud that it needs to widen it, which is the conversation you wanted to have before eleven files changed, not after. The gate ignores the diff's contents and its size alike. It checks one path rule, the same way on the thousandth call as on the first.

One line in that script carries the point: the allowed set is yours to write, never the model's. The tempting shortcut is to let the agent write its own blast radius and have the hook read it back, but a boundary the model can edit is not a gate, it is one more instruction it can set aside. The set has to come from a human who knows what this task is allowed to touch.

Two honest limits sit on this gate. It matches the file-editing tools, Write, Edit, and MultiEdit; an agent that writes by shelling out, a sed -i or a > redirect, goes around it until you put the same rule on a Bash matcher or refuse writes from the shell. And it guards where the change lands, not what it does: the stray file it stops from being touched is the cheap failure, while a wrong line inside a file you did ask it to change is Layer two's job, never the gate's.

Advisory or blocking

A gate has two settings, and the difference is whether it can be argued with. Swap the exit 2 for a printed line and exit 0, and you have an advisory layer: it tells you the agent stepped outside the lines and trusts you to notice. Keep the exit 2 and you have a floor the model cannot route around. Advisory is the honest default while you are still learning where your own blast radius is, because a gate keyed too broadly refuses clean work, and a false block is work that cannot proceed until someone fixes the gate. Run it advisory first, watch what it would have blocked over a week, and promote the rule to a hard block once you trust it refuses only what you meant. A layer-three control that only warns is real work; the promotion to one that refuses is a separate decision you make once the evidence is in.

What none of the three can do

Be exact about the boundary, because this is easy to oversell. A gate checks the diff against a rule you wrote, and it has no model of reality to check against. Whether the caching layer was worth adding, whether the rename makes the next change cheaper or the codebase worse, whether the one-line fix was even the right fix for the bug you actually had: each of those needs a model of the world the change lives in, the product, the people using it, where the whole thing is headed. None of the three layers has that. Steering can ask for it and procedure can surface candidates, but the judgment itself stays with you.

The enforcement layer is rarely one hook. It is a set of them you design for your own blast radius, your own must-hold constraints, the paths a change should never cross, the same move as writing the architecture rules you already keep for your codebase, one level down. You are deciding, once and in advance, which of the agent's choices are yours to make and which it can make on its own.

Read the rules once, gate the rest

Three layers: the steering you write, the procedure you run, the gate you own. We run all three on our own agents, for the same reason you would: the agent is fast enough now that no single reader at the end of the day is the thing standing between its output and main.

You reached for Opus 5 to write more and decide less. Pointing a second model at the first one feels like progress and quietly hands the deciding back to a guess. The way to actually spend less of your attention is to hand the machine-checkable parts to the machine: scope, format, a forbidden path, a test that no longer bites. What is left is the one question none of the three layers can answer, whether the change was worth making at all. That is the review the eleven-file diff still needs, and it was always the point. The layers do not shrink that review; they clear the noise around it, so the judgment is what is left on your desk instead of being buried under four hundred lines.

Opus 5: Review bottleneck

Gábor Mészáros — Wed, 19 Aug 2026 17:23:07 +0000

The pitch for Opus 5 was that the model checks its own work now. Anthropic's Opus 5 guidance says as much: the model verifies by default, and the verify and double-check lines you used to write now only make it over-verify. Checking its own work as it writes is one job; reviewing the finished diff is another. Opus 5 got better at the first, and that quietly excuses you from the second: the four-hundred-line change it just produced lands on your branch behind a green check nobody actually read.

If you run Claude Code with a few agents at once, you know the shape of it. One developer on Hacker News put the volume plainly: "Once AI starts generating code, it flows out like water through a burst dam. It's impossible for any human to fully understand it all." Another, running the same setup I do: "I also fire off tons of parallel agents, and review is hands down the biggest bottleneck." (Hacker News)

Opus 5 was supposed to make this faster. What it did was move the work. You write less and review more, and reviewing what a machine wrote is harder than reviewing your own, because none of the context is already in your head. Robert Laszczak said it cleanly this month: "Reviewing code written by an agent is much harder than reviewing code that you have written by hand." You reached for a faster writer. You got a full-time reviewer of code you cannot fully hold in your head.

The green check is not a review

When the queue backs up, the review stops being a review. Shmulik Cohen has a name for what replaces it: vibe merging, "where developers, overwhelmed by the volume of AI-generated code, simply skim the diff or hit Approve based on a gut feeling." The tell they point to is the one you have already done: "the LGTM speedrun, approving a 300+ line diff in under three minutes." The green check did the reviewing. You just signed it.

None of this is new. Developers skimmed diffs and waved through a quick LGTM long before agents wrote code. But a fifty-line changeset you skimmed, you mostly still caught; the skim was cheap because the change was small. The skim has not changed. The changeset has. Four hundred lines written in two minutes and approved in three, and the same gut-feel pass now lands on a fraction of what it used to cover. AI did not invent the rubber stamp. It multiplied what rides on it.

This is not a private feeling, either. The industry instrumented it. Faros AI read two years of telemetry from 22,000 developers and found median time in code review up 441.5%, and pull requests merged with no review at all up 31.3%. LinearB, across 8.1 million pull requests, found AI-assisted PRs run 2.6 times larger than hand-written ones and sit more than five times longer before a reviewer even picks them up. The code arrives faster; the reading does not. And the quality gap underneath it is one developers can feel: in Stack Overflow's 2025 survey, 46% now distrust the accuracy of AI output against 33% who trust it, only 3% highly, and the single biggest frustration, cited by 66%, is the answer that is "almost right, but not quite." That is precisely the kind of bug that survives a three-minute skim.

The reflex is to point a model at the model

So the obvious move is to automate the reading. If a model wrote the code, have a model review the code. Opus 5 will tell you to do exactly this. Ask it how to keep its own mistakes out of main and it will happily offer to review its own diffs, the guess volunteering to grade the guess. That is the recommendation to distrust first. Every code host now ships an AI reviewer that leaves comments on the diff, and for the mechanical layer it genuinely helps, the way a linter helps: it "generates the same sort of local, mechanical feedback a linter does, all the stuff that might bog down a human reviewer and keep them from handling the big-picture items." (Hacker News)

The trouble starts when you ask that reviewer to be the thing standing between a four-hundred-line AI diff and your main branch. Now you have a model checking a model, and its verdict is the same kind of stochastic guess that wrote the code, made on a question that gets harder, not easier, the more code you hand it. Across a large change the odds of being right on every call multiply down: a per-line accuracy that looks fine on one function collapses across a hundred of them.

A stronger base model does not rescue you

It is still a guess, and the number of guesses is what grows. The argument is the same one from Opus 5: Delete your CLAUDE.md?, where the model grades its own instruction rules: a stochastic judge run many times over gets less reliable exactly where you leaned on it hardest.

What actually holds the line

The thing that scales with the model is not a faster reader but a gate that does not read at all. A deterministic check refuses an action outright: a test that fails, a lint rule that blocks, a hook that denies a write to a path the change was never supposed to touch, a schema that rejects a malformed file. It forms no opinion about the diff, so it does not get less reliable as the diff gets bigger, and it returns the same verdict on the hundredth file as on the first. Prompts steer, hooks enforce: steering is advice the model can weigh and set aside, a gate is a floor it cannot. We run gates like this on our own agents, and they catch what a tired reviewer at 6pm does not.

Bryan Finster, who has argued for years that code review was always the weak point, lands in the same place: "The answer is to automate all the things that can be automated, and reserve human judgment for what genuinely requires it."

What a gate cannot do

It is worth being exact about the boundary, because this is easy to oversell. Judging whether this is the right feature, whether the architecture will still hold in six months, whether the code does what the ticket actually meant: each of those needs a model of the world the change lives in, the product, the people using it, where the whole thing is headed. A gate has none of that. It checks the diff against a rule, never against reality, so that call stays human.

And some of the pushback on the whole "review is the new bottleneck" framing is warranted. One developer's flat response to the panic was "was anyone claiming it is the bottleneck? Seems like a straw man," and they are right that review was always a constraint. What changed is the ratio. When you wrote the code, your judgment went mostly into writing and a little into review. Now the writing is nearly free and the judgment is the whole job, so the mechanical load that used to hide inside your review has to move somewhere the model cannot talk its way past. That somewhere is a gate.

Read the rules once, gate the rest

You reached for Opus 5 to write more and decide less. The way to actually get that is to stop spending human attention on the parts a check can settle, format, conflicts, a forbidden call, a write outside the blast radius, and spend it on the one thing a model cannot hand you, which is whether this was worth building at all. Pointing a second model at the first one feels like progress and quietly rebuilds the problem one guess at a time. A gate the model cannot argue with is the boring answer, and it is the one still standing on the hundredth pull request of the day.

Opus 5: How to Fix Verbose Output

Gábor Mészáros — Fri, 14 Aug 2026 18:17:39 +0000

You might have noticed that Opus 5 is extremely eager to talk. It is like the uncle at the family party who always has an overly long, boring story about literally anything, and no request is too small to set one off.

Ask said uncle for a one-line change and you'll get the long history of why the code needed changing, why he never spotted it sooner, how it was not his change in the first place, and how this whole thing reminds him of a story... which was the right call, mind you, and here is how you might approach the problem next time. Your CLAUDE.md has said Be concise. No preamble. near the top for a year. On 4.x it mostly listened. On 5 the line is still sitting there, in the same file, in the same position, and the model reads straight past it.

I gave someone four paths for this in a Reddit thread. Here they are again, weakest lever first.

CLAUDE.md instructions

Write the rule down first. It is the obvious move and the weakest one. Be concise on its own barely registers, because it names nothing the model can act on. A rule that names the shape you want does better. Here is the one I use for reply verbosity, paste-ready for your own CLAUDE.md:

## Reply shape
- Lead with the answer in the first sentence, before any table, list, or caveat.
- Carry status, comparisons, and any multi-item result in a `table` or `bullet` list, never a prose paragraph.
- Cap unbroken prose at two paragraphs; if a third starts, convert the run to a `bullet` list or `table`.
- Give each item its own `bullet` row, not a clause buried across sentences.
- Compose in this shape from the start; do not draft prose and reshape it afterward.

One caveat to keep in mind: a short confirmation is already the answer. Done. or Yes, that works. should not get tabulated into a wall. The rule is about shape when there is something to shape.

Even written this tightly, a CLAUDE.md line is advice, and it competes against everything else the model is holding. On Opus 5 there is more of that than there used to be. I went into why a line that worked on 4.x can go quiet on 5 in a separate piece, Opus 5: Delete your CLAUDE.md?: the model reaches for more of your rules at once and checks its own work by default, so even a sharp rule gets crowded out. Write the rule, but do not expect it to hold on its own.

Output styles

An output style is a step up, and the reason is where it lands. A CLAUDE.md file rides in as a user message after the system prompt; an output style modifies the system prompt itself, and Claude Code adds its instructions to the end of that prompt (per the output-styles docs). Same kind of instruction, but it travels through the session better. Being in the system prompt, it is not one more user-turn line competing with everything else you have said, and the docs note Claude Code re-reminds the model to follow the active style during the conversation, so the rule gets re-surfaced rather than decaying after one appearance.

You can switch to a terser built-in style, or write your own. To turn the reply-shape rule from the last section into a style, save it at .claude/output-styles/reply-shape.md and give it a frontmatter header. The header is the part that makes it an output style rather than plain text:

---
name: Reply shape
description: "Answer-first, scannable replies; tables and bullets over prose walls"
keep-coding-instructions: true
---

... the instructions from the first point ...

The same five reply-shape lines from the last section go in the body below that header. keep-coding-instructions: true keeps Claude Code's built-in engineering behavior and changes only how it communicates. Then pick the style from /config under Output style. (The standalone /output-style command was removed; it lives under /config now.) It is read once at session start, so a change takes effect after /clear or a new session. Still instruction, so the model can still drift, but it drifts less than from a line buried in a file.

A hook that gates the output

The rule and the style are both instruction, and the model can weigh instruction and set it aside. A hook is different. It is a script the harness runs at a fixed moment, and it can refuse. That makes it the strongest of the three levers, and the one worth showing in full.

Claude Code fires a Stop hook the moment the model finishes a turn, and hands the hook the finished reply on stdin as last_assistant_message, so it can read what was just written. If the reply runs long, exit 2 blocks the stop and sends a line back to the model telling it to answer again, shorter. Drop this in .claude/hooks/gate-length.sh and make it executable:

#!/usr/bin/env bash
# Stop hook: if the reply ran long, send it back once to tighten up.

# The Stop event hands us the finished reply on stdin.
reply="$(jq -r '.last_assistant_message // ""')"

# Your bar. Word count here; a line count or a preamble check works the same way.
limit=180
words="$(printf '%s' "$reply" | wc -w | tr -d ' ')"

if [ "$words" -gt "$limit" ]; then
  # Exit 2 blocks the stop; this line goes back to the model as its instruction.
  echo "Your reply ran ${words} words; the budget is ${limit}. Rewrite it under ${limit} words: put the answer in the first sentence, then cut the preamble, the recap, and the summary of what you did." &gt;&amp;2
  exit 2
fi

exit 0

Then wire it in .claude/settings.json. A Stop hook takes no matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/gate-length.sh" }
        ]
      }
    ]
  }
}

Change limit, or swap the word count for a line count or a grep for opening filler. It cannot loop forever: Claude Code caps a Stop hook at five consecutive blocks with no tool call between them, then lets the turn end.

We run a version of this on our own agents. The system that writes and reviews the Reporails codebase has a Stop-boundary check that reads each reply and sends it back when it runs too verbose or breaks format. It fired on the drafts of this article more than once.

Custom plugins

By now you have three levers: a rule, a style, and a hook. A plugin is how you stop rebuilding them. It bundles any of the three so the setup travels with you across projects instead of getting re-pasted into each repo, and a Claude Code plugin can carry hooks, output styles, and rules together. It adds no strength of its own; the job is portability.

To make one, drop a .claude-plugin/plugin.json manifest next to your hooks/ and rules, test it with claude --plugin-dir ./your-plugin, then install it, yours or someone else's, from a marketplace with /plugin install. Anthropic's plugins docs carry the manifest fields and the marketplace steps.

Which one to reach for

Reach for the least you can get away with. A CLAUDE.md rule for the parts a human reads too. An output style when you want the model leaning terser by default. The hook when you want a floor on length the model cannot talk its way past. A plugin once you are tired of setting those up again in every repo.

The three levers are one move underneath: they decide what the model is holding when it answers, and whether anything checks the answer after it lands. The plugin only carries them. Reply length is the version of that you notice first. The harder version is which of your rules the model actually follows once you have written a hundred of them that quietly disagree, and that one is worth its own piece. It is the one I am writing next.

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 diagnoses why your steering drifts, with measured evidence: which instructions couple to behavior, which name nothing the model can bind to, and where two rules cannot both hold. It does not run your model, and it does not vote; it measures the file.

DEV Community: Reporails

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

Where the harness comes short

One level up: the reply declares its kind

Progressive Disclosure: What, Where, When, and Why

The problem

The solution: Progressive Disclosure

What loads

Where it loads

When it loads

Why

The file was never the unit

Opus 5: How to Review Generated Code

Layer one: steering, and the instruction to delete

Layer two: procedure, and reviewing what actually ran

Layer three: enforcement, the gate that just refuses

Advisory or blocking

What none of the three can do

Read the rules once, gate the rest

Opus 5: Review bottleneck

The green check is not a review

The reflex is to point a model at the model

The 129,121-word `CLAUDE.md`