September 12, 2026
GIVE A CODING AGENT A JOB IT CAN ACTUALLY FINISH

Lesson 36.1 taught you to direct the work: inspect first, approve a small plan, review evidence. This lesson teaches the second half of directing — converting a wish into a job a coding model can complete without quietly inventing the decisions you never made.
A model left with a vague request does what it was built to do: it fills the gaps with plausible guesses. Sometimes the guess is right. When it is wrong about the user, the data shape, the permission model, or the API contract, a small request becomes the wrong feature built confidently.
The fix is not a longer chat. It is a written task.
The anatomy of a good coding task
Every task you hand to a coding agent should answer six questions:
Goal: what user outcome changes?
Current state: where does the relevant behavior live?
Scope: which files/systems may be touched?
Constraints: what must not change?
Acceptance checks: how will we know it works?
Out of scope: what tempting extras must be left alone?
Write it down in a short file — TASK.md works well — and give that file to the agent. A Markdown task file is not old-fashioned prompting. It is project input, the same habit from Part II: research, constraints, examples, and acceptance criteria the agent can return to consistently instead of reconstructing your intent from a long transcript.
A task file is a request, not a permission slip. It never authorizes hidden production changes, broad refactors, or new services.
Acceptance checks, in plain language
Acceptance checks are observable facts that make the task complete. They are not aspirations like "make it nice" or "improve the dashboard." They are statements you can verify by looking, clicking, or running a command:
- The source publication date appears beneath every linked source in the research brief.
- A source with no date shows "Date unavailable" instead of a blank space.
- The existing export button still downloads the brief unchanged.
Two or more checks per task is a good minimum. One check invites corner-cutting; five precise checks keep the work honest. Each check should name the behavior, the edge case, and what must keep working.
Weak requests versus bounded jobs
| Weak request | Why it drifts | Better bounded job |
|---|---|---|
| "Make the dashboard better." | No success definition; invites redesign. | "On the research brief page, add the source publication date beneath each linked source. Do not change navigation or data fetching." |
| "Fix auth." | No observed failure or environment. | "In local development, password reset returns a blank screen after submission. Inspect first; propose the smallest fix. Do not change production settings." |
| "Add AI." | No user job, model boundary, or cost rule. | "Add a button that creates a draft summary from already-approved sources. Do not auto-publish or call any unapproved source." |
Each better version does three things the weak version does not: it names the location, it states the observable outcome, and it draws a "do not change" boundary. The boundary is as important as the goal — it is what stops a date-display task from becoming a navigation rewrite.
When implementation reveals a planning problem
Sometimes the agent discovers something real mid-task: the assumed API field does not exist, the data model cannot support the requirement, the workflow needs a decision you never made, or the proposed approach creates an unacceptable cost or security tradeoff.
It must not quietly rewrite the implementation and leave the plan false. That produces code that works against yesterday's assumptions while every document still describes the old decision.
Run the plan-change loop instead:
New discovery
→ stop the current task
→ state the impact on behavior, architecture, data, cost, security, and timeline
→ update the PRD / architecture note / roadmap as appropriate
→ human approves the changed decision
→ create a newly bounded task and resume
Example: the source-date task reveals that half the approved sources have no publication-date field at all. Stopping is correct. The impact statement is short: "Display-only change is now a data change; we need a backfill rule and an empty-state design." Update the product note, approve the "Date unavailable" fallback explicitly, then write the resumed task with the new acceptance check included.
The source-of-truth rule
If code, task notes, and the roadmap disagree, do not ask the next AI to guess which one is right. Pause and reconcile them. The written product and architecture decisions are how a project remembers *why* code exists; when the decision truly changes, update the documents first, then resume coding.
Use this hierarchy when sources conflict:
- Existing working code and written project docs outrank a model's memory. The model may confidently recall a library API that changed two years ago. The repo and the docs in front of you win.
- User requirements outrank generic framework habits. "That is how this framework usually does it" loses to "our product decided otherwise for a reason."
- Official documentation outranks a guessed API method. If the model invents a parameter, check the provider's current docs before accepting it.
This reinforces Parts II, IV, and V: files carry context, models have limits, and tools have contracts. Guesses are cheap; contracts are not.
Exercise: write TASK.md and demand a critique
Pick one vague feature request — real or invented — and turn it into a TASK.md using the six-part template above. Include at least two acceptance checks and at least one explicit "do not change" boundary.
Then, before any code is written, hand it back to the AI with this instruction:
A good critique names the gaps you left: which page, which user role, what the empty state shows, which files are in scope, what "done" excludes. Fold the answers into the task file. Only then authorize implementation — and authorize only the bounded task, in a session with only the context it needs.
Check your understanding
- What are the six parts of a task, and which one most directly prevents scope creep?
- The agent discovers the data model cannot support the task. What is the very next step?
- Code says one thing, the roadmap says another, and the model remembers a third. What wins, and what do you do?
Finish line
You are done when you have a TASK.md with a goal, current state, scope, constraints, two or more acceptance checks, and at least one explicit out-of-scope boundary.
Verify: read each acceptance check aloud and ask "could I observe this pass or fail in under five minutes?" If any check is a matter of taste ("cleaner," "nicer," "smarter"), rewrite it as an observable fact. Confirm the "do not change" list names real areas (navigation, auth settings, production config), not vague ones ("other stuff").
Common failure mode: writing acceptance checks that describe effort rather than outcome — "update the component," "refactor the helper," "improve handling." The agent completes the motions and nothing verifiable changes. Recovery: rewrite every check as a user-visible or test-verifiable fact, add the missing boundary, and run the critique pass again before any edit.
Next, you will learn where bounded tasks come from: the model hierarchy that turns an idea into a PRD, an architecture decision, a roadmap, and only then a task.
ARTICLE DISCUSSION
JOIN THE
CONVERSATION.
Got a question, a take, or a better way to do this? Log in and leave a comment.
