Spec-Driven Development: How to Control AI Coding Agents

TL;DR

• AI coding agents work best with structured guidance, not vague instructions
• Break work into three artifacts: requirements.md (what), plan.md (how), and tasks.md (execution)
• Execute in bounded phases — complete 1-2 tasks, review, then continue
• This approach gives you control while keeping AI momentum

The Big Picture

AI coding agents promise to accelerate development. But there's a gap between promise and practice.

Hand an agent like Junie a vague instruction — "refactor this module" or "add tests" — and you'll get unpredictable results. The agent might rewrite half your codebase, introduce breaking changes, or wander off into implementation details you never asked for.

The problem isn't the agent. It's the lack of structure.

Spec-driven development solves this by forcing you to think before the agent acts. You start with clear requirements, refine them into a development plan, then break that plan into discrete tasks. The agent executes one task at a time. You review. You approve. You move forward.

This isn't about micromanaging AI. It's about staying in control while letting the agent do what it does best: rapidly implementing well-defined units of work.

How It Works

The methodology has three phases, each producing a concrete artifact.

Phase 1: Write requirements.md

Start by documenting what needs to happen. Not how — just what. This is your North Star.

Maybe you're replacing an outdated algorithm. Maybe you're adding persistence for new data. Maybe you're cleaning up legacy code. Write it down in a file called requirements.md. Keep it short. Three to five bullet points is usually enough.

This file gives you and the agent a shared starting point. It sets boundaries. It defines priorities. Without it, the agent is guessing what matters.

Phase 2: Generate plan.md

Once requirements are clear, ask the agent to create an implementation plan. This is the bridge between what and how.

The prompt is simple: "Read requirements.md and create a detailed development plan in plan.md. Do not write code yet."

Enable Junie's "Think More" toggle here. It forces deeper reasoning by adjusting the LLM's parameters and workflow. The result is a document that outlines the approach, sequence of work, and potential risks.

A good plan might include small code examples to illustrate ideas. That's fine. But if you want strategy only, tell the agent explicitly: "Focus on what needs to be done, not how to do it."

This checkpoint matters. You're reviewing the strategy before any code changes happen. If the plan misses something or goes in the wrong direction, you catch it here.

Phase 3: Create tasks.md

Plans are abstract. Tasks are concrete.

Ask the agent to convert plan.md into an enumerated task list saved as tasks.md. Each task should be specific enough to mark complete, but not so granular it becomes busywork.

Good task: "Implement new data repository."

Bad task: "Write a function."

The task list becomes your control panel. It's persistent. It's external to the agent's context. You can review it, reorder it, refine it. You can tell the agent to complete task 1, mark it done, then stop.

This is how you move from theory to execution without losing visibility.

Execution: Work in bounded phases

Now you execute. But not all at once.

Don't ask the agent to "do everything in tasks.md." Instead, work in phases. Start with tasks 1-2. Require the agent to mark them complete in the file. Review the changes. Run tests. Confirm correctness.

Then move to the next phase.

This controlled iteration keeps you in the driver's seat. The agent implements rapidly, but you approve every step. If a task uncovers unexpected complexity, you update the task list before proceeding.

The prompt structure enforces this naturally: "Complete tasks 1-2 from tasks.md and mark them as completed."

What This Changes For Developers

Spec-driven development shifts how you interact with AI agents. Instead of treating them like magic boxes, you treat them like junior developers who need clear direction.

The workflow is transparent. Every decision is documented. Every change is scoped. You're not debugging mysterious agent behavior — you're reviewing work against a checklist you approved.

This matters for complex features. When you're touching multiple files, managing dependencies, or refactoring legacy code, vague instructions lead to chaos. Structured tasks lead to predictable outcomes.

It also makes collaboration easier. If you're working with a team, requirements.md, plan.md, and tasks.md become shared artifacts. Everyone knows what's happening. The agent's work is auditable.

And if something goes wrong? You know exactly which task caused the problem. You can roll back, adjust the task, and try again.

Try It Yourself

Here's a complete prompt that sets up the entire workflow. It creates all three artifacts plus updates Junie's guidelines file to enforce the methodology.

# Spec-Driven Development Prompt

Transform the provided high-level requirements into a complete set of project planning artifacts for spec-driven development.

## Instructions:

You must produce **four files** inside the `docs/` and `.junie/` directories:

- `docs/requirements.md`
- `docs/plan.md`
- `docs/tasks.md`
- `.junie/guidelines.md`

Follow the methodology below step by step:

---

### Step 1: Create `docs/requirements.md`

- Title: **Requirements Document**
- Introduction: Summarize the application purpose and key functionality.
- Requirements section:
  - Use sequential numbering (1, 2, 3, …).
  - Each requirement must include:
    - **User Story** in the format:
      > As a user, I want [goal] so that [benefit/reason]
    - **Acceptance Criteria** in the format:
      > WHEN [condition] THEN the system SHALL [expected behavior]

---

### Step 2: Create `docs/plan.md`

- Analyze `docs/requirements.md`.
- Develop a **detailed implementation plan**:
  - Link each plan item explicitly to the corresponding requirements.
  - Assign priorities (e.g., High, Medium, Low).
  - Group related plan items logically.

---

### Step 3: Create `docs/tasks.md`

- Based on the implementation plan in `docs/plan.md`, produce a **detailed enumerated technical task list**:
  - Each task must have a placeholder `[ ]` to mark completion.
  - Link each task both to:
    - the development plan item in `docs/plan.md`
    - the related requirement(s) in `docs/requirements.md`
- Group tasks into **development phases**.

---

### Step 4: Update `.junie/guidelines.md`

- Add **concise technical instructions** on how to work with the `docs/tasks.md` checklist.
- Instructions should include:
  - Mark tasks as `[x]` when completed.
  - Keep phases intact but add new tasks if needed.
  - Ensure every new or modified task stays linked to a requirement and plan item.

---

## Input:

[INSERT YOUR HIGH-LEVEL REQUIREMENTS FOR THE APPLICATION YOU WANT TO CREATE]

## Output:

1. `docs/requirements.md` – structured requirements document
2. `docs/plan.md` – implementation plan with priorities and links
3. `docs/tasks.md` – detailed enumerated task list grouped into phases
4. `.junie/guidelines.md` – updated concise instructions for working with the task list

Paste this into Junie's input, add your high-level requirements, and let it generate the artifacts. Then start executing phase by phase.

The Bottom Line

Use this if you're building complex features with AI agents and need predictable outcomes. Use it if you're refactoring legacy code, adding test coverage, or implementing multi-file changes where dependencies matter.

Skip it if you're prototyping throwaway code or making trivial one-file edits. The overhead isn't worth it for simple tasks.

The real opportunity here is control without sacrificing speed. You get AI momentum — rapid implementation, fewer keystrokes — but you stay in the loop. You approve the strategy, review the plan, and execute in phases you define.

The real risk is thinking you don't need structure. That's when agents go rogue, rewrite half your codebase, and leave you debugging changes you never asked for. Spec-driven development prevents that. It turns ambitious goals into manageable, trackable units of work.

If you're already using Junie's unified interface, this methodology plugs right in. If you're evaluating AI coding agents, this is the workflow that separates useful tools from expensive distractions.

Source: Junie