Specification
AGENTS.md
The open format for a repository file that tells coding agents the build commands, conventions and boundaries once, so every prompt starts from the same context.
Contents Section 9, Directing Agents
Prompting and Specifying Work for Agents
Mistakes to catch in review
An agent told to 'make the tests pass' that deletes or weakens the tests.
A request to fix one module that the agent treats as permission to edit the build scripts, the CI configuration and a shared library.
A date-parsing helper reinvented because the prompt never pointed to the one that already exists.
A task so large that the agent returns a 3,000-line change nobody can review.
The acceptance criteria from Intent, plus the three things a prompt adds: the context the agent needs, the boundaries of what it may touch, and the check that proves it is done.
Topics
- Prompts as Specifications
- Writing a prompt with the same care as a requirement, stating the goal, scope, non-goals and expected output.
- Supplying Context
- Putting the files, examples, conventions and past decisions the model needs into the prompt, and leaving out what distracts it.
- Constraints and Boundaries
- Naming what the agent may change, what it must not touch, and which rules are fixed.
- Definition of Done
- Stating the checks that prove completion, so the agent can verify its own work and you can verify it again.
- Task Decomposition
- Splitting work into pieces small enough to review and verify one at a time.
You understand it when you can
- Write a prompt for a coding task that a capable stranger could complete without asking a single question.
- Break a feature into agent-sized tasks, each with its own verifiable check.
- Compare the output of two prompts for the same task and explain which instructions made the difference.
Drill
An engineer gave an agent this prompt: 'Fix the flaky tests in the payments module and clean up anything that looks wrong.' Find every way an agent could satisfy it while making the codebase worse, then rewrite it with scope, constraints, relevant context and a definition of done.
Start here
Watch
Prompting for Agents | Code w/ Claude
Anthropic's applied AI team covers how prompting an agent that runs a tool loop differs from prompting a single reply: giving it heuristics, stating its limits and describing what finished looks like.
The New Code — Sean Grove, OpenAI
Argues that the written statement of intent is now the main thing an engineer produces, and uses OpenAI's Model Spec to show a versioned spec that tests and evaluations are generated from.
Simon Willison: Engineering practices that make coding agents work - The Pragmatic Summit
Makes the case for test-driven development as the definition of done you give an agent, so it can check its own work before you check it again.
Read
Beyond Vibe Coding: From Coder to AI-Era Developer
A Google engineering leader's practical guide to directing coding agents: writing precise requests, supplying project context, and splitting features into pieces that can be reviewed.
Specification by Example: How Successful Teams Deliver the Right Software
The classic on turning intent into concrete, checkable examples. Agents need exactly that kind of executable definition of done so that 'make the tests pass' cannot be met by weakening the tests.
Primary sources
Manual
Best practices for Claude Code
Anthropic's official guide to specifying coding-agent work: pointing the agent at existing files and helpers, writing a plan before code, giving it tests to check against, and keeping each task small enough to review.