From Writing Code to Leading Agents: A Development Paradigm Shift

The Evolution of a Relationship

A developer shared his personal experience on his blog: at first, his interaction with Claude Code was simple—enter a request, read the feedback, correct mistakes, enter again. This approach worked, but all coordination was done by the human. He was the one who remembered decisions from three messages ago, he was the one who noticed when the model drifted off course, and he was the one who judged when a task was "done."

Today, most of his prompts no longer ask for code—they describe a process: which stages run in order, who executes each stage, what counts as evidence, and when to stop. The agent writes the code, while the human defines the rules under which it works.

This is not a story about "better prompts," but about a different kind of work.

Phase One: The Bottleneck of Prompt Interaction

Initially, all work happened in a single long conversation. Request a feature, get a diff, point out issues, repeat. Problems emerged slowly:

• The chat log became the sole source of truth. Decisions existed only in the scrollback. As context grew longer, the model would quietly "forget" previously reached consensus.
• Every fix contaminated the next step. When the developer asked for tests, the model had already seen the implementation code, so the tests matched the code, not the requirements.
• "Done" meant "the model said it was done." No evidence, just confidence.

None of this was the model's fault. The problem was cramming analysis, architecture, development, testing, and review into a single context while still trying to remember everything.

Phase Two: The Breakthrough of Spec-Driven Development

The first real change was adopting Spec-Driven Development (SDD), using Spec Kit to break work into explicit stages, each producing a file:

spec → clarify → plan → tasks → analyze → implement → verify

Two rules changed everything that followed.

Rule One: State Passes Through Files, Not Chat

Clear the context between each stage. Sounds wasteful, but the effect is striking: plan must read a real, approved spec.md; tasks must read a real plan.md. Each stage stays aligned with what was actually written down, not with half-formed decisions accumulated in conversation. If it's not in a file, it didn't happen.

Rule Two: The Implementer Doesn't Write Tests

This is the most surprising point. The implementation stage writes only product code. Tests are written during the verification stage, based on the acceptance examples in the spec, by an agent that is not allowed to read the product source code. The reasoning is simple: a context that has already seen the implementation writes tests that confirm the implementation, while a "blind tester" writes tests that confirm the requirements. There is even a review step that specifically flags tests whose expected values cannot be traced back to acceptance examples.

Blind tester refers to an agent or person who is not allowed to read the product source code while writing tests. This practice draws on the "black-box testing" idea from software engineering: tests should verify behavior based solely on requirement documents and acceptance criteria, not reverse-engineer expected values from implementation details. When a context has already seen the implementation code, the tests it writes tend to accommodate the code's actual behavior—for example, writing an accidental erroneous return value as the expected value, or bypassing branches that are hard to trigger. Such tests may pass, but they cannot prove the requirements are met; they only prove the code hasn't changed. Having an isolated sub-agent that has never seen the source code write tests based on acceptance examples, then having a third role review whether the test's expected values can be traced back to acceptance examples, forms an independent verification chain of "requirements → tests → implementation." This also explains why the orchestration process must assign a fresh, minimal context to each role—context contamination itself is the source of test failure.

Two Entry Points, One Pipeline

New features start from requirements: the spec is written, and code follows. Bugs start from existing code and symptoms: the spec is reverse-discovered from code behavior and reported issues. Crucially, both paths produce the same spec.md, so bug fixes rejoin the same pipeline. The reverse path is allowed to stop rather than guess at three checkpoints: reproduction, expected behavior, and attribution. Teaching an agent when to stop is just as valuable as teaching it what to do.

Spec Kit is an open-source GitHub toolkit for Spec-Driven Development (SDD). Its core idea is to make spec files the single source of truth for development, rather than scattering requirements across chat logs, issues, or developers' heads. It breaks the development process into a series of verifiable stage commands: spec defines what problem to solve, clarify eliminates ambiguity in the spec, plan provides a technical approach, tasks breaks it into executable tasks, analyze performs consistency checks, implement generates code, and verify validates the results. Each stage produces a file on disk, and the next stage must read the previous stage's real file to continue. The significance of this design is that both humans and AI work against the same written contract, rather than against half-formed consensus in their respective memories. When Spec Kit collaborates with agents like Claude Code and Copilot, it is typically embedded in the workflow as slash commands or prompt templates, making "write the spec first, then write the code" an automatable pipeline rather than just an aspiration.

Phase Three: Becoming an Orchestrator

Even with SDD, the developer still manually ran each stage: clear the context, run the next command, read the output, decide whether to continue. He described himself as a very focused for loop. So he wrote that loop as a prompt. The main session no longer does the work—it becomes the orchestrator:

• Acts only as orchestrator, never personally performing any stage's work
• Runs stages in order, creating an isolated sub-agent for each stage
• Reads the progress file before each stage, records results after completion
• Sub-agents report in at most 10 lines: status, artifacts, blockers
• If a stage fails or is blocked, record it and stop; do not run subsequent stages

Building the Trust Mechanism

A fresh sub-agent for each stage, given only necessary information: objective, stage instructions, relevant artifacts, constraints, and acceptance criteria. No prior conversation history or reasoning is passed in. The orchestrator itself retains only the state needed to decide the next step—it is a state machine, not a workspace.

Standard handoff format: each sub-agent returns a unified report including status (PASS/FAIL/BLOCKED), summary, artifacts, verification, blockers, and suggested next steps. One key principle: PASS is only valid when acceptance criteria have actually been checked. No reported errors does not equal evidence.

Progress as structured state: the progress file is the orchestrator's memory, recording the current stage, completed stages, artifacts, verification results, blockers, and review rounds. If the actual repository state contradicts the file, the orchestrator investigates rather than trusting either side.

Review loop with hard limits: after an SDD stage passes, a fresh sub-agent performs a code review of the entire change. If there are issues, a new agent fixes them, relevant tests are re-run, and an independent review checks the result. Two guardrails: a maximum of three review rounds, after which it stops and reports rather than declaring success; and no self-certification—it cannot mark issues as resolved based on its own explanation, nor edit the spec just to make legitimate findings disappear.

Explicit exit conditions: the process ends only when all of the following are simultaneously satisfied—no actionable review findings, relevant tests run and pass, verification reports pass, spec/code/tests remain consistent, the final diff has no unexpected changes, and there are no blockers. Only then does it commit, push, and create a PR. If it cannot determine the target branch, it stops and asks. "Do not guess the branch" is written into the prompt.

Handoff format is a critical interface design in multi-agent orchestration: after an upstream agent completes its task, it must report to the downstream agent according to an agreed structured template, rather than freely writing a summary. In this article's process, the standard handoff format includes status (PASS/FAIL/BLOCKED), summary, artifacts, verification, blockers, and suggested next steps. The value of structured handoff lies in three points: first, it lets the orchestrator judge whether the process can continue without reading the entire reasoning process; second, it forces the agent to attach checkable evidence when claiming completion; third, it turns "reporting" itself into a constrained output, preventing the agent from blurring failures and uncertainties with natural language. Paired with this are length limits like "10-line reports," designed to prevent sub-agents from pouring context back into the main session and thus breaking isolation. The more specific the handoff format design, the less the orchestrator's trust in the process depends on trusting the model's "feel."

Phase Four: Planning for Agents

Once execution became agentic, the weak point moved upstream: the plan itself. Plans written for humans ("refactor the module," "fix the tests") are too vague for agents working in isolated contexts with no history.

So a second prompt is needed, whose sole job is to produce a plan the orchestrator can execute. Each task carries its own execution contract: objective, context to load, scope, implementation guidance, dependencies, acceptance criteria, verification method, and handoff artifacts. It also produces a dependency graph (what runs sequentially, what can run in parallel, where conflicts might occur) and execution state checkpoints.

The criterion for a good plan: Can another agent execute this task using only the task spec and referenced files, without the original investigation process? If not, the task isn't fully planned yet.

What Actually Changed

Looking back at the whole process, the code did get better—but that's not the main difference. The work itself changed.

Prompt Phase	Leading Agents Phase
Write requests	Write processes
Chat logs hold state	Files hold state
One context does everything	Each role has a fresh, minimal context
"Done" is the model's opinion	"Done" is a checklist of verified conditions
Errors found by reading everything	Checkpoints, limits, and reviews catch them
More agents feel like progress	Delegate only what the objective requires

A few lessons worth passing on:

• Context is a resource to be managed. Treat it like memory in a constrained system: load only what's needed, persist the rest.
• Teach agents to stop. Blockers, checkpoints, and round limits make the process trustworthy. An agent that pauses and explains is more valuable than one that guesses and continues.
• Separate builders from checkers. Blind testing and independent review only work when the checker hasn't seen the builder's reasoning.
• Demand evidence, not confidence. Write this into the prompt, or the agent will happily report success.
• You are still responsible. Review the spec, the plan, and the final diff. Leading agents doesn't mean leaving the room.

Redefining the Developer's Role

The core of this shift is not a tool upgrade, but a restructuring of responsibilities. When agents take over code generation, human value shifts to process design, trust mechanism construction, and quality gatekeeping. Moving from "the person who writes code" to "the person who sets the rules and verifies the results" may be the most profound paradigm shift of the AI programming era.

Are you still in the long-conversation phase, or have you started writing processes for agents? The key question is: Are the guardrails you've designed strong enough for the process to remain trustworthy without you watching it?