How do I write requirements an AI coding agent can follow?

Write each requirement as one testable statement with its own ID, spell out the business rules and the exceptions, say what's out of scope, and attach acceptance criteria the agent can turn into tests. Then tell the agent, in writing, to ask when something is missing instead of guessing.

AI coding agents are fast and literal. They build what the words say, and where the words are silent, they fill the gap with something plausible. Good requirements leave fewer gaps to fill.

What does a good requirement look like?

• One thing per statement. "The system records each tool checkout with who, what and when" is one requirement. "The system handles checkouts and returns and sends reminders" is three.
• Testable. "Fast" and "easy" can't be checked. "An overdue tool shows on the attendant's list the morning after it was due" can.
• Its own ID. A trace ID lets the agent, the tests and the people all refer to the same thing.
• Plain words. Name roles and records the way the business does, and use the same name every time.

What do agents most often get wrong?

The parts nobody wrote down: the business rules and the exceptions. Approval limits, what happens when a record is incomplete, who may change what, what happens when another system is down. If the requirement doesn't say, the agent decides, and it won't tell you it did.

What else should the agent get?

• The data: the records the software keeps and how they relate.
• Access rules: who can see and change what.
• Error handling: what the user sees when something goes wrong.
• What's out of scope, so it doesn't build features nobody asked for.
• A build order, so foundations come first.
• Acceptance criteria for each requirement, so it can write tests and check its own work.

Does the format matter?

Structure helps. A readable document is for the people who approve it; a structured file with IDs on every piece is easier for a tool to read without misreading. Many teams keep both, generated from the same source so they can't drift apart. An instructions file at the root of the repository, such as AGENTS.md, tells the agent how to work and where the boundaries are.

How do I make it ask instead of guess?

Say so in its instructions, and give it a way to ask: a person to message, or a channel where questions are answered and recorded. Review its assumptions as you review its code.

Mochlion produces requirements in this shape, as a readable specification and a structured build package; see which tools can use it.