Edison SinaniAI implementation architectBook a call

AI Team Playbook / Rule 2 of 12

One instruction file, under 200 lines

The team keeps one instruction file for every agent tool, under 200 lines, containing only what the agent cannot learn from the code.

September 16, 2026 · About 2 minutes

Contents

The playbook

  1. Overview

Before code

  1. 1Write the constitution first
  2. 2One instruction file, under 200 lines
  3. 3Enforce the rules with settings and hooks
  4. 4Three gates before any code
  5. 5A walkable demo before any screen

Building

  1. 6One task, one worktree, one pull request
  2. 7Every contract has a file and two tests

Reviewing

  1. 8AI review first, and filtered
  2. 9Human review by risk tier
  3. 10Done means the evidence is in the pull request

Over time

  1. 11Measure five numbers, baseline first
  2. 12Protect the people who are still learning

Appendix

  1. AInstall checklist
  2. BOther tools, limits and sources
  3. CTightening the process
  4. DRun the agent with no entitlements

Get the kit

Who owns it
The lead owns it. Any developer whose change makes it wrong fixes it in the same pull request.
In the kit
AGENTS.mdCLAUDE.md.github/copilot-instructions.md
Enforced by
Nothing enforces the length. The milestone retrospective asks which lines the team did not need and removes them.

Why

A repository with an instruction file cut agent runtime by 28.6 percent and token use by 16.6 percent across 124 pull requests [6].

What an instruction file savedAgent sessions with an AGENTS.md present against the same repositories without one, across 124 pull requests. 6
  1. 28.6%Less agent runtimeWall-clock time per task, with the file present.
  2. 16.6%Fewer tokensTokens consumed per task, with the file present.

Anthropic’s guidance is to keep the file short, to include only what the agent cannot work out from the code, and to cut any line whose removal would not cause a mistake, because a bloated file makes the agent ignore the rules that matter [13]. The 200 line cap is mine. It is the point past which a file stops fitting on two screens. Anything that must be enforced goes in a hook, which is rule 3.

How

AGENTS.md is the one file. Claude Code reads it through a one-line import in CLAUDE.md. Copilot reads it through .github/copilot-instructions.md. Cursor, Codex and Kiro read it directly.

It has five parts. Read first: the constitution, the system design, and the task’s spec. Commands: the build, test and regenerate commands the agent cannot guess. Repository etiquette: branch names, commit format, the pull request template. How to work: the rules of behaviour. Where things are: five to ten lines a new developer would ask about in their first week. Leave out anything a linter already enforces. The kit’s file also carries a short definition of done and a Code Review Rules section. Keep that heading’s exact casing, because Codex looks for it.

These are the kit’s “how to work” rules:

  • Read the task’s Touches and Do not touch lines before editing. Stay inside them. If the task needs a file outside them, stop and say so.
  • Raise questions about architecture, scope or approach in prose, before code. Make smaller decisions without asking.
  • Before changing anything under contracts/, or renaming, removing or retyping a field another component reads, stop and say so. A contract change is its own task. Adding an optional field that consumers already ignore is not a contract change.
  • If you catch yourself adding a fix named after one specific failing test, stop and describe the pattern first.
  • If the same component needs a second redesign to keep working, stop and say so.
  • Never deploy or run destructive commands. Commit or push only when the developer asks; each one waits for their confirmation. Otherwise give the developer the exact commands.

CLAUDE.md then needs only this:

@AGENTS.md

# Claude Code notes

- Work in a worktree: `claude --worktree task-<id>-<slug>`. Rename its branch, `worktree-task-<id>-<slug>`, to `task/<id>-<slug>` with `git branch -m` before the first commit.
- Before opening a PR, run the reviewer subagent with fresh context.
- `/spec`, `/tasks` and `/review` are team skills. Use them instead of improvising.
- The Stop hook runs the project check before you can finish. If it blocks, fix the cause.
- Permission rules are shared in `.claude/settings.json`. Never remove a deny rule.

References

  1. 6Jai Lal Lulla et al., "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents", arXiv 2601.20404, January 2026. 10 repositories, 124 pull requests. arxiv.org/abs/2601.20404
  2. 13Anthropic, Claude Code documentation, "Best practices for Claude Code". code.claude.com/docs/en/best-practices