Real Codebases in Intent Engineering

Lessons in this section

1. API Contracts

   Stop the agent from inventing public names. Declare the interface other code already expects, in a code block in spec.md, and watch a consumer test compile against it.

2. Constraints and Trade-offs

   Keep the agent's change small and in the team's style. Point it at the file to copy, list the APIs it must not change, limit the paths it may touch, and rank the trade-offs so it picks the right approach.

3. Decision Rights

   Decide which choices the agent may make alone, which it must report, which it must ask about, and which only a person may do. Add a stop rule so a failing loop ends with a report, not an empty budget.

4. Non-Functional Requirements

   Turn "fast", "accessible" and "works everywhere" into requirements a check can measure: a number, a unit, and the condition it is tested under.

5. Task Planning

   Break a feature into agent-sized tasks in plan.md, with the files each task touches and what it waits for. Land the contract first, so parallel agents never collide.

6. Subagent Briefs

   Write a brief a subagent can follow and an orchestrator can merge: goal, inputs, allowed tools, output shape and done-when.