A Working AGENTS.md, Annotated

Every AI coding tool reads an instruction file - CLAUDE.md, AGENTS.md, the name varies by tool, the job does not. It is the model's onboarding document: the standards, boundaries, and working agreements a new engineer would absorb in their first weeks, made explicit because the model has no hallway to ask in.

Plenty of advice exists about what such a file should contain. Published examples from files used daily on production codebases are rarer. This is ours - generalized from a real one, with the project-specific sections removed and an annotation under each part explaining why the rule exists. Treat the rules as a worked example, the annotations as the method. Your rules will differ; the shape should not.

Interaction rules

## How We Interact

- Be short and clear. State the fact or the answer; skip preambles and framing.
- Do not restate what the question already implies.
- Answer, then stop. No summaries of what you just said, no closing
  questions to keep the conversation going.
- If an answer is incomplete or carries doubt, say so before the answer,
  not after it.
- Do not present a guess as a decision. No decision is made until I
  confirm it.

Why it exists: verbosity is the default failure mode of every model, and its cost is sneakier than wasted time. Walls of restatement and self-protective hedging exhaust the reader - and an exhausted reader changes stance: skimming, skeptical, looking for the end. In that stance the one flag that mattered scrolls past unread, and the team later concludes the model never raised it. It did - we keep finding the flag in the transcript (see The Session Review). Brevity is review infrastructure, and so is the rule that doubt goes before the answer rather than trailing it. The decision rule at the end is the other load-bearing one: models present options as if one had been chosen, and making "no decision until confirmed" explicit keeps the human owning direction.

When to code

## When To Code

- Do not write code unless asked. Code snippets that illustrate a point
  in a discussion are fine.
- Do not enter planning mode unless asked.
- Match the altitude of the conversation: architecture questions get
  architecture answers, not variable naming.

Why it exists: the model's strongest instinct is to finish the conversation with an implementation. During design discussion that instinct converts open questions into premature code, and the code then anchors the discussion. The altitude rule is the same idea sideways: a conversation about system boundaries should not come back with feedback about naming conventions.

Working style

## Working Style

- Small cycles. A feature never completes in one turn.
- Start with the smallest possible piece; confirm before adding more.
- Prefer two simple passes over one clever one. We optimize for
  readability, not performance.
- Do not extract a one-use helper just to make a method shorter. Use
  step comments to keep the flow readable in one place. Extract when
  something is a repeated operation, a meaningful concept, or hides
  mechanical work: resource loading, parsing, integration calls.

Why it exists: small cycles are both a quality discipline and a context-budget discipline - the full argument is in Make the Change Easy. "A feature never completes in one turn" sets the expectation that stops the model from over-building: given a feature request, a model will deliver its idea of complete, which is usually three steps past what was asked. The helper-extraction rule trades textbook decomposition for local readability - a method you can read top to bottom beats four single-use fragments you have to chase.

Code style

## Code Style

- Blank lines between logical steps. Space inside loops: first how it
  iterates, then what it does to each item.
- Step comments keep the business flow readable top to bottom.
- When editing a file already formatted this way, preserve and extend
  the spacing. Never collapse it back into a dense block.

Why it exists: code that humans review line by line - which in this workflow is all of it - has to be formatted for human reading. Air between logical steps is what makes a ten-minute review cycle actually take ten minutes. The preservation rule matters more than it looks: models reformat by habit, and a model that collapses your spacing is quietly undoing review infrastructure.

House rules

## House Rules

- Objects over primitives in signatures.
- No stream/map/filter chains; write the loop.
- No optionals on repository methods.
- Every DTO is its own class; no nested public static classes.
- If/else over case statements.
- Do not add defensive null handling on first write unless the schema
  is nullable. Assume the data is there and fail.

Why it exists: these are ours, and several are minority positions - that is the point. A rules file is not a style guide for the industry; it is the specific, enforceable house style of one codebase. Rules this concrete are checkable in review at a glance. And they are written strict on purpose: a strict rule that over-corrects occasionally is a known, budgeted cost, while a nuanced rule full of "unless it makes sense" clauses leaks unpredictably - the model will use every inch of flexibility you write into it. We accept the over-corrections as error budget and keep the rules absolute.

Hard boundaries

## Hard Boundaries

- Never create or modify database tables or DDL. If a change seems to
  require it, stop and say so.

Why it exists: every agent file needs at least one absolute - a line with no judgment clause attached, where the correct behavior is to stop rather than interpret. Ours is schema: tables and DDL carry consequences that outlive any single change, so that decision stays human, always. Pick yours by asking what change would be expensive to discover after the fact rather than before.

Model adjustments

# Turn Rules

- Lead with the answer, not setup.
- Surface doubt before the answer, not after it.
- No restatement of what the question already implies.
  Answer, then stop.
- Do not edit files unless explicitly asked. Discussion
  and validation are not permission to code.

Why it exists: some rules in the onboarding file push against inherent model behaviors - verbosity, eagerness to code during a discussion, trailing hedges that cover every possible objection. The model reads the file at the start of a session and follows it. Then, as the context grows and the conversation gets longer, it drifts back toward its defaults. The rules are still in the file; they are just no longer the loudest signal.

Hooks solve this. A hook fires on every prompt submit and re-injects the rules that matter most as a system-level reminder - the same rules, restated at the point where the model is about to respond. The onboarding file sets the standards; the hook keeps them active across every turn, not just the first one. The combination is the difference between a model that knows what you want and a model that does what you want, consistently.

The rules in the hook are deliberately a subset. Not every rule needs reinforcement - house rules about code style hold fine once stated. The rules that need hooks are the ones where the model has a strong built-in pull in the opposite direction: verbosity, unsolicited coding, and the instinct to hedge answers with trailing caveats. Those are the behaviors that survive the onboarding file and re-emerge under pressure.

Two files, one onboarding

The onboarding file sets the standards. The hook file keeps the ones that fight model defaults active on every turn. Neither uses prompting tricks, personas, or "you are an expert engineer." Both read like notes for a new team member, because that is what they are.

These files govern behavior. Navigating a large codebase takes a second artifact - per-area code-reading guides, covered in Context Modeling.

None of it stays static. Most rules were added after watching something go wrong, in the cleanup passes where recurring mistakes get reverse-engineered into written standards - the loop described in The Stabilization Pass. A rules file that has not changed in months is not finished; it is unread.