Frame the Task Before the Agent Writes Code
A coding agent can implement a clear task quickly. It can also implement an unclear task quickly. The speed is the same. The cost is not.
Lesson 43 of 54Learn + Build~60 minutesPython (stdlib)
Before this: Lessons 31 and 36 of Phase 14
On this page
Learning Objectives
- Turn a request into a bounded task frame before editing.
- Separate repository facts from assumptions and open questions.
- Define allowed paths, forbidden paths, and acceptance evidence.
- Decide when reconnaissance is sufficient to begin work.
The Expensive Failure
“Add duplicate email protection” sounds specific. It is not. Does uniqueness belong in the API, domain service, or database? Is comparison case-sensitive? Which error shape is already public? Is a migration allowed? Which test proves the behavior?
A capable agent will fill those gaps with plausible choices. That is the dangerous case because the implementation can be clean, tested, and still incompatible with the system.
The first unit of coding-agent work is therefore not an edit. It is a task frame backed by repository evidence.
The Task Frame
A useful frame has six fields:
| Field | Question |
|---|---|
| Goal | What observable behavior must change? |
| Repository facts | What did you verify in code, tests, config, or history? |
| Allowed paths | Where may the change land? |
| Forbidden paths | What must remain untouched? |
| Acceptance evidence | Which commands or observations prove the goal? |
| Unknowns | Which decisions still need evidence or human judgment? |
Facts need receipts. “The API uses 409 for duplicates” is not a fact until you can point to the existing test or handler. A file path and line is enough. A command result is better when behavior matters.
Reconnaissance Is a Search for Constraints
Do not read the entire repository. Search for the surfaces that constrain the change:
- The current behavior and its caller.
- The closest existing test.
- The public contract or serialized shape.
- The project instructions that govern the path.
- The build and verification commands.
- Similar completed changes that reveal local patterns.
Stop when every planned decision is either supported by evidence, explicitly delegated, or listed as an unknown. More reading after that point is often avoidance.
Unknowns Are Not Failures
An unknown is a controlled gap. An assumption is an uncontrolled answer to that gap.
Classify each unknown:
- Discoverable: the repository or running system can answer it.
- Decidable: the task contract gives the agent authority to choose.
- Human: the choice changes product behavior, cost, risk, or public compatibility.
- Deferred: the choice is outside this slice and belongs in non-goals.
The agent should continue through discoverable and delegated unknowns. It should pause at human unknowns before the choice is buried in code.
Acceptance Before Implementation
Write the proof before the patch. The proof can be:
- a focused unit or integration test command;
- a browser journey with a named viewport and expected state;
- a wire request and exact response contract;
- a performance measurement with a threshold;
- a scope check that confirms no unrelated file changed.
“Tests pass” is not a proof plan. Name the authoritative test and the claim it supports.
Build It
The lab creates a TaskFrame, validates its boundaries and evidence, and writes outputs/task-frame.md.
Run from this lesson directory:
python3 code/main.py
python3 -m unittest discover code/tests -vBreak the example in four ways: remove the goal, remove a fact receipt, overlap an allowed and forbidden path, and remove the acceptance command. The validator should refuse each frame for a different reason.
Use It in a Real Repository
Before asking an agent to edit:
- Write the goal as a behavior, not a file change.
- Record two or three facts with exact evidence.
- Name the smallest allowed path set.
- Name negative space explicitly.
- Write the command or observation that closes the task.
- List the decisions you have not earned yet.
The frame should fit on one screen. If it cannot, the task may contain multiple independently verifiable changes.
Exercises
- Frame a real bug from one of your repositories without proposing a solution.
- Find one claim in the frame that is actually an assumption. Replace it with evidence.
- Add a human unknown whose answer would change the public contract.
- Split one broad allowed path into the smallest safe set.
- Add a scope receipt to the acceptance evidence.
Further Reading
- Nuseibeh and Easterbrook, Requirements Engineering: A Roadmap, for anchoring implementation to real-world goals and evolving constraints.
- Yang et al., SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering, for evidence that the interface around a coding agent changes its effectiveness.
What You Keep
Keep outputs/task-frame.md. It is the input to the next lesson, where the frame becomes an evidence-backed execution plan.
Check yourself
Quick quiz
What should be the first unit of reliable coding-agent work?
- A task frame backed by repository evidence
- A model call
- An edit
- A pull request
Show the answer
A. A task frame backed by repository evidence The task frame establishes facts, boundaries, unknowns, and proof before implementation.
Which of these statements is a repository fact?
- The duplicate-response test expects 409 at tests/test_accounts.py:44
- The API probably uses 409
- 409 feels conventional
- The API should use 409
Show the answer
A. The duplicate-response test expects 409 at tests/test_accounts.py:44 A fact carries a concrete receipt that can be inspected.
Why name forbidden paths?
- To select a model
- To define the negative space of the change
- To make the prompt longer
- To avoid running tests
Show the answer
B. To define the negative space of the change Allowed paths alone do not state what tempting adjacent work must remain untouched.
When should a human unknown pause the agent?
- Whenever any file is unfamiliar
- Before every command
- Only after deployment
- When it changes product behavior, risk, authority, or irreversible cost
Show the answer
D. When it changes product behavior, risk, authority, or irreversible cost High-consequence choices require an explicit checkpoint before they are buried in code.
What makes acceptance evidence strong?
- It is written after coding
- It uses many tools
- It names the exact command or observation and the claim it proves
- It says tests pass
Show the answer
C. It names the exact command or observation and the claim it proves Specific proof lets another session reproduce task closure.
When is reconnaissance sufficient?
- When the context window is full
- When every planned decision has evidence, delegated authority, or an explicit unknown
- After one search
- After reading every file
Show the answer
B. When every planned decision has evidence, delegated authority, or an explicit unknown Reconnaissance stops when decisions are grounded or visibly unresolved.
Questions people ask
How do you write a good task for an AI coding agent?
State the goal and why it matters, the current behavior, the expected behavior, constraints, what is out of scope, and the exact check that proves it is done. Concrete examples of input and output help a lot.
Why do AI agents build the wrong thing?
Usually because the request left gaps the agent filled with guesses. Missing goals, unstated limits or unclear success checks all lead to confident work aimed at the wrong target.
Lessons from AI Engineering from Scratch by Rohit Ghumare and contributors, MIT license. Notes for owners by Lozo. License