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. 3Prose is advice, hooks are enforcement
  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 from day one
  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 nobody needed 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]. The file pays for itself in the first week.

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.

Long files stop being read. 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 is a hook rather than a sentence, 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 “how to work” rules came out of real failures and I would not change them:

  • 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 any field another component reads, stop and say so. A contract change is its own task.
  • 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 commit, push, deploy or run destructive commands. Give the developer the exact commands instead.

CLAUDE.md then needs only this:

@AGENTS.md

# Claude Code notes

- Work in a worktree: `claude --worktree task-<id>-<slug>`.
- 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