The Four Lines Every AI Coding Agent Instruction File Should Start With
Most project instruction files fail for the same reason: they try to describe every possible behavior. A better approach is to define the agent’s operating mode in a few lines.
The Golden Rule
Achieve the objective through the most direct safe, verifiable path, while strictly respecting explicit instructions and project constraints.
Apply progressive disclosure to everything written: start with a clear tree/outline, show only the smallest useful layer, keep each visible section or artifact under 200 lines unless explicitly asked otherwise, and expand only the needed branch.
For non-trivial work, define done, use the relevant existing project harness, proceed in small reviewable increments, and stop only when evidence shows done is met.
Briefly justify material trade-offs; when a mistake reveals a reusable lesson, acknowledge it, fix it, and record it at the narrowest appropriate project scope.
If your CLAUDE.md, AGENTS.md, or equivalent agent instruction file contains only one rule, make it this one.
Why This Rule Matters
AI coding agents are no longer just autocomplete systems. They can inspect a repository, edit files, run commands, use tools, call external context, review diffs, and iterate until a task is complete. That power is useful only if the agent knows how to control itself.
The rule above gives the agent a simple operating contract: pursue the objective, respect the constraints, write with progressive disclosure, verify the result, and learn from mistakes.
Do Not Optimize for Obedience Alone
A weak instruction tells the agent to follow orders. A stronger instruction tells it to reach the intended result safely.
In real projects, the literal request is often incomplete. The agent may need to inspect the codebase, discover the correct test command, find the relevant documentation, or reject a shortcut that would satisfy the prompt while damaging the system.
“The most direct safe, verifiable path” gives the agent permission to be efficient without becoming reckless.
Write With Progressive Disclosure
Agents often fail by writing too much at once: huge plans, long specs, sprawling documentation, or explanations that bury the next useful step.
This line inserts the PDD principle directly into the Golden Rule, but generalizes it beyond documentation. It applies to everything the model writes: docs, specs, plans, reviews, reports, explanations, prompts, and generated artifacts.
The purpose is simple: start from a clear tree or outline, expose only the smallest useful layer, keep each visible section or artifact under 200 lines unless explicitly asked otherwise, and expand only the branch that is needed.
This makes the agent’s output easier to read, review, reuse, and continue.
Define Done Before Doing the Work
For any non-trivial task, the agent should first understand what completion means.
Done can mean that tests pass, a bug no longer reproduces, a migration succeeds, a UI state is visible, a benchmark stays within limits, or a reviewer can inspect a small coherent diff.
Without a definition of done, the agent is only producing output. With a definition of done, it can close the loop.
The Harness Is the Real Workflow
A coding agent is not just a model. It is a model operating inside a project environment.
The project harness is everything already available in that environment: tests, scripts, linters, hooks, documentation, memory, MCP servers, skills, subagents, reviews, logs, screenshots, and any other feedback mechanism that helps the agent verify its work.
The important word is “available”. The agent should not invent infrastructure that does not exist. It should use the relevant harness that is already present in the repository.
Small Increments Beat Big Swings
The more autonomous an agent becomes, the more important it is to keep its work reviewable.
Small increments make failures easier to isolate. They make diffs easier to review. They make tests more meaningful. They also make it easier for the agent to repair its own mistakes before those mistakes compound.
The goal is not to slow the agent down. The goal is to prevent it from moving fast in the wrong direction.
Evidence Before Completion
An agent should not declare success because the answer looks plausible. It should stop only when there is evidence that the definition of done has been met.
Evidence can be a passing test suite, a successful build, a clean lint run, a reproduced-and-fixed bug, a reviewed diff, a screenshot comparison, a type check, a log, or a documented manual verification.
If there is no evidence, the work may still be useful, but it should not be treated as complete.
Mistakes Should Improve the Project
A useful agent is not an agent that never makes mistakes. It is an agent that recognizes mistakes, fixes them, and reduces the chance of repeating them.
But every lesson should not go into the global instruction file. That quickly turns CLAUDE.md or AGENTS.md into a junk drawer.
The lesson should be recorded at the narrowest appropriate scope: a test, a local README, a path-specific instruction, a skill, a runbook, or the root instruction file only when the lesson applies broadly.
Where to Put It
For Claude Code, put this rule near the top of CLAUDE.md.
For Codex, put it near the top of AGENTS.md.
For other tools, place it in the repository instruction file that is actually loaded by the agent. The filename matters less than the behavior: the agent should see this rule before it starts working.
The Point
The best agent instruction file is not the longest one. It is the one that makes the agent consistently more useful.
Start with the objective. Respect the constraints. Write with progressive disclosure. Define done. Use the harness. Work in small increments. Verify with evidence. Learn from mistakes.
That is the difference between a model that generates code and an agent that can be trusted with work.
