AGENTS.md for Code Quality: What Belongs in the File vs CI

Fabien Sanglard did not start with a grand theory of AI coding instructions. He started with an irritating review loop. In mid-2025, an LLM could not produce compiling Rust for his libadbmdns work. By January 2026 it could solve much harder problems, but the output still arrived as spaghetti code. By March, he was repeatedly typing the same review comments: remove magic numbers, explain the non-obvious part, reduce indentation, keep the change narrow.

His August 21 post, “My agent.md to improve LLM-assisted code quality”, explains the obvious next move: write those recurring corrections down once and let the coding harness load them for every session. The post crossed 160 points on Hacker News, where the discussion sharpened the idea into a production rule: an instruction file is useful, but it should not be asked to do work that a linter, hook, test, or CI job can do with certainty.

That distinction is the missing companion to explainx.ai's broader agent markdown files guide. The question is no longer merely what can I put in an agent instruction file? It is which rules deserve scarce context, and which should become executable constraints?

TL;DR: what people are asking

Sanglard's useful idea is the feedback loop, not the template

Sanglard's file is opinionated. It asks for concise prose, private-by-default members, early returns, enums instead of boolean parameters, short function names, strict adjacent-layer communication, braces on every conditional, seven-part commit messages, and test-first bug fixes. He reports that this moved his review time away from local style cleanup and toward architecture and design.

The article also keeps the right limit in view: the file did not make review optional. Sanglard says he still verifies and iterates because models hallucinate. The instruction layer raised the floor; it did not certify the result.

Hacker News commenters pushed on the individual rules, and those objections matter:

• “Less than 30 characters” is measurable but arbitrary. It can encourage abbreviations that make names worse.
• Comments that explain “what” often duplicate code. A stronger rule asks for rationale, constraints, or surprising behavior only.
• “Use enums instead of booleans” is too absolute. An enum helps when a boolean hides meaning at the call site; it adds clutter when isReady is already the domain concept.
• ASCII diagrams can help architecture docs but become noise inside small functions. The right home may be a design artifact, not the source file.
• Many style rules already have deterministic equivalents. Asking a probabilistic model to remember braces is weaker than configuring the parser or linter to reject missing braces.

The transferable method is therefore not “copy Fab's taste.” It is: observe repeated defects, record the smallest useful guidance, then graduate enforceable rules into tooling. That is also consistent with the thin prompts, thick artifacts, thin skills framework: the always-loaded entry point should route the agent, not become the whole engineering system.

AGENTS.md versus linters, hooks, tests, and CI

Use one test: can a program decide whether the rule was violated without asking for taste or intent? If yes, encode the decision in software. Keep prose for facts and judgments that the program cannot infer reliably.

This is the same division explainx.ai uses in skills vs hooks vs prompts: instructions provide reasoning context, while hooks react to events and run deterministic commands. A hook that prints “remember to use braces” is still a reminder. A linter that exits non-zero changes the system's state.

A five-step process for deriving rules from review feedback

1. Capture the correction after it happens twice

One mistake can be noise. Two or three occurrences across separate tasks indicate a stable gap between your expectations and the model's defaults.

Keep a short review ledger:

| Date | Task | Repeated correction | Candidate control |
| --- | --- | --- | --- |
| Aug 20 | Auth fix | Edited unrelated comments | AGENTS.md scope rule |
| Aug 21 | Cache fix | Missing braces | ESLint rule |
| Aug 22 | API change | UI imported DB client | Boundary test |

This avoids turning every annoyance into permanent prompt debt.

2. Ask whether the rule is fact, judgment, procedure, or invariant

The categories can overlap. For example, AGENTS.md should name the canonical focused test command, but the test runner remains the authority on whether the code works. The agent needs the map; the machine owns the verdict.

3. Write a positive, local, testable instruction

Prefer a rule that names the desired state and its scope:

## Change scope

- Limit edits to files required by the requested behavior.
- Report unrelated defects without fixing them.
- Preserve public visibility unless the task explicitly requires an API change.

This is stronger than a page of abstract “clean code” advice. It names observable behavior, tells the agent what to do with adjacent discoveries, and limits the blast radius.

4. Add the cheapest verifier

The loop engineering guide frames the core idea well: a useful agent loop needs a check and an exit condition. Choose the cheapest reliable verifier first:

1. Parser or formatter
2. Static linter
3. Type checker or compiler
4. Focused unit test
5. Structural architecture test
6. Integration or browser test
7. Human or model review for semantics and taste

Do not spend a frontier-model review call checking whether every if has braces. Do not use a regex to decide whether an abstraction is appropriate. Match the verifier to the claim.

5. Review the rule after five real tasks

Ask four questions:

• Did the defect recur?
• Did the rule cause a new failure mode?
• Can the rule move into tooling now?
• Is the instruction still true in the current architecture?

Delete redundant or stale rules. A growing file is not evidence of a maturing workflow. Sometimes it is evidence that nobody removes sediment.

A lean AGENTS.md starter that leaves room for code

The open AGENTS.md project describes the file as a README for agents and uses the uppercase plural filename. Sanglard's article uses the lowercase singular agent.md for his personal setup and suggests symlinking tool-specific files toward it. These are related conventions, not proof of one universal loader contract.

Check the harness you actually run. AGENTS.md, CLAUDE.md, and GEMINI.md can coexist or point to a shared source, but a clever symlink is useless if the tool ignores it. For Claude-specific hierarchy and scoping, use explainx.ai's CLAUDE.md guide.

Here is a deliberately small starting point:

AGENTS.md

## Repository map

- Product code: `apps/web`
- Shared packages: `packages`
- Architecture decisions: `docs/architecture`

## Canonical commands

- Focused tests: `npm test -- path/to/test`
- Lint: `npm run lint`
- Type check: `npm run typecheck`

## Change policy

- Make the smallest change that satisfies the requested behavior.
- Report unrelated defects; do not fix them in the same patch.
- Preserve public APIs unless the task explicitly requires a breaking change.

## Verification

- For a bug, reproduce it before editing and add a regression test.
- Run the narrowest relevant checks first, then the required project checks.
- Never claim a check passed without command output.

## Architecture

- UI calls services; services call repositories; repositories own persistence.
- See `docs/architecture/boundaries.md` for allowed dependency edges.

## Safety

- Do not run migrations, production deploys, or destructive commands without
  explicit user approval.

The file says what the agent cannot infer cheaply, where deeper truth lives, and which commands produce evidence. It does not paste the linter configuration, architecture handbook, API reference, and release checklist into every turn.

Context dilution: what the research does and does not show

Sanglard connects declining instruction adherence in long sessions to Lost in the Middle. The 2023 paper by Nelson Liu and co-authors found that the language models they evaluated often performed best when relevant information appeared near the beginning or end of a long input, with weaker performance when it appeared in the middle.

That result deserves a narrower interpretation than “models ignore the middle of AGENTS.md.” The experiments covered multi-document question answering and key-value retrieval. They did not test coding harnesses, layered system prompts, repository instruction precedence, or the 2026 model generation. The paper is solid evidence that available context length and effective context use are different things. It is not a universal law assigning a safe line count to an instruction file.

Three practical mitigations follow without overclaiming:

1. Start a fresh session per feature. This is Sanglard's first recommendation and keeps the active task, diff, and evidence close together.
2. Reload only as recovery, not architecture. Re-reading the file can move instructions toward the recent end of context, but a harness should ideally preserve governing instructions itself.
3. Use progressive disclosure. Keep a short map in the always-loaded file and let the agent open the relevant architecture, security, or workflow artifact when the task requires it.

OpenAI later described the same operational lesson in its harness engineering write-up: a giant AGENTS.md crowded out task context, went stale, and was hard to verify. Its team moved to a roughly 100-line table of contents backed by structured repository docs, dedicated linters, CI checks, and automated doc gardening. That is one implementation, not a magic number, but the architecture is sound.

What people on Hacker News added

The Hacker News discussion was not a vote against instruction files. It was a vote against using prose where software has a stronger type system.

The best thread-level takeaways were:

• Lint hand-written and generated code with the same rules. A repository invariant should not depend on who typed the line.
• Use AI review as a semantic layer, not the first line of defense. One commenter suggested a cheap model inspect only added lines for unwanted comments; that is useful after deterministic checks have exhausted what they can prove.
• Keep comments about why, constraints, and surprising behavior. Blanket “add comments” rules invite novels that merely narrate the code.
• Personalize from evidence. Different developers reported opposite problems with comments, function extraction, and naming. A useful file records your project's recurring failures, not the internet's average preference.
• Do a separate quality pass. First make the behavior work; then review the diff against project guidance and run verification. That reduces the chance that a style checklist distracts from the primary defect.

This layered workflow also explains why Claude Code steering is more than one markdown file. Persistent context, task-specific skills, event hooks, tests, and human review solve different failure modes.

A practical policy for your next repository

Start with no style encyclopedia. Add the repository map, canonical commands, permission boundaries, and two or three review rules that have already cost you time. Then follow this escalation ladder:

Repeated review comment
        ↓
Small AGENTS.md rule
        ↓
Can a program decide it?
   yes             no
    ↓               ↓
lint / test / CI   keep as judgment guidance
    ↓               ↓
run on every diff  review after five tasks

For dangerous operations, do not stop at prose. Pair the instruction with tool permissions or a guard such as the patterns in explainx.ai's Destructive Command Guard analysis. For task procedures, move detail into a skill. For large design context, point to versioned artifacts. For outcomes, require executable evidence.

The best AGENTS.md is not the one that contains every lesson you have learned. It is the smallest reliable map from the current task to the right code, documentation, tools, and checks.

Related on explainx.ai

• Agent markdown files: complete guide to AGENT.md, CLAUDE.md, SKILL.md, and more
• What is CLAUDE.md? Persistent project context for Claude Code
• Thin prompts, thick artifacts, thin skills
• Skills vs hooks vs prompts: when to use each
• Loop engineering for coding agents
• Steering Claude Code with files, skills, hooks, subagents, and rules

Primary sources: Fabien Sanglard's original article · Hacker News discussion · AGENTS.md open-format site · Lost in the Middle paper · OpenAI harness engineering

This analysis reflects Sanglard's August 21, 2026 article, the Hacker News discussion visible on August 24, and the cited AGENTS.md and research documentation. Agent loaders, context composition, and model behavior change; verify filenames and precedence in the harness version you use.