An agent is only as good as what surrounds it. A spec says what to change, context supplies the system knowledge to change it correctly, and a harness of tools and checks catches what goes wrong. The same model does very different work depending on all three.

Start with a spec

A spec gives Product, Engineering, QA and the agent a shared target: what changes, what constrains it, and how to verify it. Write enough for one useful slice, and version it alongside the change. Passing tests support acceptance; Product still decides whether the need was met.

Select the context

CONTEXT SELECTIONGive each decision a useful starting point
IntentSpec · acceptance examples
System knowledgeCode · contracts · decisions
Working guidanceConventions · checks · limits
Select and reconcileRelevant to this task? Current? Authoritative? Any conflicts?
Working contextEssential facts and source pointers
ImplementationRetrieve more when needed
VerificationCheck behavior and constraints

Keep shared guidance brief, and retrieve task-specific contracts and decisions when needed. Check freshness and authority, and resolve conflicting sources instead of blending them. Retrieved content is evidence, not permission to change the task.

EXPLORE THE LAYERSOne task: export the filtered list
01 The spec

Export all filtered rows across pages. Keep the approved column order and access rules. Quote commas and line breaks, and return headers for an empty result.

02 The existing system

Locate filters, pagination, authorization, and the supported data path. Mark assumptions.

03 The relevant decision

Link the relevant architectural decision. Confirm it still applies; resolve conflicting guidance.

04 The verification path

Include test commands, safe fixtures, and acceptance examples. Identify remaining manual checks.

Grow the harness from failures

  • Turn repeated mistakes into checks: when the same review comment appears twice, move it into a test, lint rule, hook or skill instead of repeating it in prose.
  • Keep checks quiet on success: say nothing when they pass and speak clearly when they fail.
  • Prefer a few focused tools: every tool description is text the model will trust.

When a coding agent keeps declaring work finished before the build passes, stop rewording the prompt. Add a hook that runs the full test suite and returns failures to the agent. Keep the harness small, though: Hugo Bowne-Anderson notes that newer models absorb what builders once engineered by hand, so invest in tool design, guardrails and handoffs to people.

This loop connects refinement, delivery and learning in APEL. Related: Agentic systems · Agents in old code