Main instruction files that tell the agent who it is score lower than the rest, at every file size.
One of them opens like this, on line 3 of its CLAUDE.md:
You are a senior [project] engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.
It's a familiar move from prompt writing. In the 10,000 most-starred repos of the Q3 report, 285 main instruction files have a line that starts "You are a", "You are an" or "You are the", across CLAUDE.md, AGENTS.md, GEMINI.md, Copilot's copilot-instructions.md and Cursor's .cursorrules. On ails check's 0 to 10 scale, their median is 6.6, against 7.7 for the other 20,551 main files. Fewer than one in five score 8 or above. Of the rest, more than four in ten do.
Persona files tend to be longer, so we split all main files into four equal groups by size. The gap holds in every group, from 0.9 to 1.25 points.
A file that reads like a prompt
The "You are" sentence itself reads as description to the checker. The difference is in the rest of the file. Nearly half of what a persona file says is instruction (46.6%), against 30.3% in other main files, which spend more of their lines on the repo. After the "You are" comes a list of what the agent does and doesn't do.
Compared with main files of the same size, that list picks up more of most kinds of finding. In the third size group (68 to 127 items), 80% of persona files have a "never" written more strongly than the permission that goes with it, against 49% of the others. 78% have a hedged instruction ("should", "try to"), against 60%. 59% put their instructions in the weaker order, against 40%, 45% have a heading written as an instruction, against 28%, and 25% put the forbidden thing in bold inside a prohibition, against 10%.
The "never" gap holds in all four size groups. In the largest, it reaches 98% of persona files against 75% of the rest. Persona files also carry more prohibitions in the first place: 88% have at least one, against 78%.
The smallest persona files go wrong in a different way. 71% have an instruction too short to register, such as "Be concise", against 48% of small files without the line.
One finding runs the other way. Persona files have less prose crowding an instruction, 4.2 per 100 instructions against 9.9, which fits files that carry less description.
Where the line sits
In 204 of the 285 files, the "You are" line is in the first five lines, so it's how the file opens. Of setups with a main file, 6.0% of Cursor's have the line there, against 3.5% of Copilot's and 1.0% of Claude Code's.
Claude Code's docs say where a CLAUDE.md ends up: "CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself." By the time the file arrives, the agent already has its system prompt.
Sub-agents are different. A Claude Code sub-agent file is YAML frontmatter "followed by the system prompt in Markdown", and the docs' own examples open with a persona line, such as "You are a senior code reviewer…". 57.4% of sub-agent files in the report have one. There it's the convention, and this post leaves it alone.
What to write instead
Ask what the persona line was meant to buy, and write that down. "Senior engineer who prioritizes type safety" can mean running the type checker and keeping the types strict. Each of those can name its tool, one instruction per sentence: the directives first, a line of context, and the constraint last. For the Yarn/Turbo monorepo above, that could read:
- Run `yarn type-check` before you mark a task as done.
- Use `unknown` and narrow it when a value's type is genuinely unknown.
- Strict types are how this repo catches bugs before review.
- *Never loosen a type just to get the build passing.*
The constraint is in italics and comes after the line that says what to do instead. It describes the move it rules out without naming any or @ts-ignore, so neither shows up in the agent's instructions (why that matters). In a CLAUDE.md of their own, these lines score 9.4 on ails check.
Check yours
The checker flags what the persona files carry: a heading written as an instruction, a hedged "should" or "try to", bold on the thing a prohibition forbids and a one-line trait like "Be concise". Each run checks one agent's files; the second command switches to Copilot, and cursor, codex and antigravity (for GEMINI.md) work the same way.
npx @reporails/cli check
npx @reporails/cli check --agent copilot
To find the line itself:
grep -niE "^\s*You are (a|an|the) " CLAUDE.md AGENTS.md GEMINI.md .github/copilot-instructions.md .cursorrules 2>/dev/null
From The State of AI Instruction Quality: Q3 2026: 10,000 of the most-starred GitHub repos, 15,237 agent setups, September 2026 snapshot.
"Main files" are CLAUDE.md, AGENTS.md, copilot-instructions.md, GEMINI.md and .cursorrules, each file counted once even when more than one agent's setup loads it: 20,836 files, with the 285 persona files in 189 repos. A file counts when a line outside code blocks starts with "You are a", "You are an" or "You are the". Size groups are quarters of main files by item count, cut at 32, 67 and 127 items; finding shares compare files in the same group. The hedged, ordering and bold-prohibition gaps hold in three of the four groups, and the smallest group ties or reverses.
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.
