Ugrás a fő tartalomhoz

Execution Plans: From Epic to Verified Change

Basic Advanced

Applies to: any change bigger than one sentence, and every epic you deliver with an agent · Time to learn: 40 min reading + 20 min exercise · Lever: context + feedback

Large changes fail in agent sessions for a simple reason: the work does not fit in one focused context. The fix is the same one engineers have always used. Write the plan down, cut it into pieces that can each be finished and verified, and let the agent execute one piece at a time.

TL;DR
  • Follow explore, plan, implement, verify, commit. Use plan mode for the first two steps.
  • Keep the plan in a file in the repo, not in chat. It survives /clear, handoffs, and a teammate picking the work up.
  • For an epic, write several small plans, not one giant one: docs/plans/<epic>/ with a README index and 01-...md, 02-...md. Each plan is one session or one PR.
  • Every step in a plan has a verification the agent can run. No verification, no step.
  • Run independent plans in parallel with worktrees or subagents. Run dependent plans in order.

Why it matters in the AI age​

An agent is only as good as the context it gets, the feedback loop it can run, and the guardrails around it. An execution plan serves two of those: it is focused context for one session, and it holds the verification commands that close the loop.

  • Anthropic's core constraint: the context window fills up fast, and performance degrades as it fills (best practices). A plan sized to one session keeps the window small.
  • Anthropic's long-running agent work found that a fresh session orients itself well from a progress file, git history, and a structured task list (harnesses for long-running agents).
  • As an FDE you will often inherit half-finished work in a client repo. A plan file lets you, a teammate, or a new agent session resume without replaying a chat.

Core concepts​

The Anthropic workflow​

Anthropic recommends four phases: explore, plan, implement, commit, with plan mode separating exploration from execution (best practices). Add an explicit verify step, because Anthropic's top tip is to give Claude a way to check its own work: tests, a build, a linter, or a screenshot.

PhaseWhat happensTool in Claude Code
ExploreRead code, find conventions, no editsPlan mode, Explore subagent
PlanWrite the steps, files, and checksPlan mode, then save to docs/plans/
ImplementDo one step at a timeNormal mode, one plan per session
VerifyRun the checks from the planTests, linters, hooks
CommitOne logical change, clear messageGit, PR

Skip the plan for changes you could describe in one sentence (best practices).

Plan mode in Claude Code​

Plan mode tells Claude to research and propose changes without making them: it reads files, runs shell commands to explore, and writes a plan, but does not edit your source (permission modes).

ActionHow
Enter during a sessionShift+Tab to cycle default, acceptEdits, plan; the status bar shows plan mode on
Enter for one promptPrefix the prompt with /plan
Start in plan modeclaude --permission-mode plan
Make it the project defaultSet defaultMode to plan in .claude/settings.json
Edit the planCtrl+G opens it in your editor
LeaveApprove the plan (choose how edits are approved) or choose to keep planning

Source for all rows: permission modes and common workflows. Approving a plan exits plan mode. Other harnesses have similar read-only modes; the file-based plan below works in all of them.

Why a written plan beats a chat plan​

A plan in chatA plan in docs/plans/
Lost on /clear or when the window compactsReloaded from disk by any session
Only you can see itReviewed in a PR by the client team and by teammates
Hard to resume after a breakProgress log says what is done and what is next
Drifts silently as the agent worksAgent updates it; the diff shows drift
Cannot be handed to another agentAny agent, or a subagent, can execute it

This is the plan-side version of structured note-taking: keep persistent notes outside the window and reload them (effective context engineering). Plans live with the rest of your project knowledge; see Scratchpads, Memory, and Markdown Knowledge Bases.

Plan formats in use​

You do not need a framework to start. These are the shapes you will meet:

FormatShapeWhere it fits
OpenAI ExecPlans (PLANS.md)One living design document per feature. AGENTS.md tells the agent when to write one; PLANS.md defines the format. Mandatory sections: Progress, Surprises and Discoveries, Decision Log, Outcomes and Retrospective (cookbook)Multi-hour single-feature work
GitHub Spec KitConstitution once, then per feature spec.md, plan.md, tasks.md under specs/<branch>/ (repo, spec-driven.md)Teams that want a spec-first process and a CLI scaffold
Kiro specsThree files per spec: requirements.md (or bugfix.md), design.md, tasks.md (Kiro docs)Work inside the Kiro IDE
Anthropic long-running harnessAn init.sh, a progress file (claude-progress.txt), and a JSON feature list where each entry has passes: false until tested; one feature per session; git commits as checkpoints (Anthropic)Long autonomous runs with many small features

The template below borrows the best parts: ExecPlan's living progress and decision logs, Spec Kit's separation of what from how, and the harness's rule that nothing is done until it is verified. Spec Kit's own guidance is that a plan should "remain high-level and readable" (spec-driven.md). The command prefix differs between Spec Kit docs (/speckit.* and /speckit-*), so check the version you install.

One epic, several plans​

One plan for a whole epic becomes a long file that no single session can hold. Split it.

  • An epic is the business outcome (for example, "move auth to the client's SSO").
  • A plan is one slice of it that one agent session can finish and one PR can contain.
  • A session executes one plan, starting from a clean context.
  • A PR is the reviewable result of one plan.

In the diagram, plan 01 comes first, plans 02 and 03 depend only on 01 and can run side by side, and plan 04 waits for both.


How to do it​

1. Explore and draft in plan mode​

Start Claude Code in plan mode (claude --permission-mode plan) and ask for the breakdown (prompt below). Review the proposed slices. Edit them yourself; you know the client context.

2. Lay out the epic directory​

docs/plans/sso-migration/
docs/plans/sso-migration/
README.md # epic overview + plan index (status, dependencies)
01-user-model.md # one session / one PR
02-auth-endpoints.md
03-admin-ui.md
04-cutover.md

The README is the only file every session reads first. Keep it short.

docs/plans/sso-migration/README.md
# Epic: SSO migration

**Goal:** All users sign in through the client's identity provider; local passwords are removed.
**Non-goals:** Changing roles or permissions; mobile app.
**Links:** `docs/adr/0007-sso.md`, ticket [PROJ-123], IdP docs.

## Plan index

| # | Plan | Depends on | Status | PR |
|---|---|---|---|---|
| 01 | User model and IdP link table | none | done | #41 |
| 02 | Auth endpoints (OIDC callback) | 01 | in progress | #44 |
| 03 | Admin UI for linking | 01 | not started | none |
| 04 | Cutover and password removal | 02, 03 | not started | none |

## Epic-level acceptance
- E2E login through the staging IdP passes.
- No code path reads `password_hash`.

## Epic decisions
- 2026-10-20: Use OIDC, not SAML (client IdP supports both; OIDC has a maintained library here).

3. Write each plan from the template​

docs/plans/sso-migration/02-auth-endpoints.md
# Plan 02: Auth endpoints (OIDC callback)

**Epic:** [SSO migration](./README.md) · **Depends on:** 01 · **Status:** in progress

## Goal
One sentence: what is true when this plan is done.

## Context and links
- Relevant code: `src/auth/`, `src/api/routes.py`
- Decisions: `docs/adr/0007-sso.md`
- Plan 01 added the table `idp_links`.

## Non-goals
- No UI changes (plan 03). No removal of password login (plan 04).

## Steps
1. Add `/auth/oidc/login` and `/auth/oidc/callback` handlers.
- Verify: `make test tests/auth/test_oidc.py` passes.
2. Link the IdP subject to the user through `idp_links`.
- Verify: new unit test for first login and repeat login passes.
3. Return the same session cookie as password login.
- Verify: `make e2e-auth` passes against the stub IdP.

## Acceptance criteria
- [ ] All steps verified, with commands and results recorded in the progress log.
- [ ] `make lint` and `make test` pass.
- [ ] No change outside `src/auth/` and `tests/auth/` except the route registration.

## Risks
- The IdP clock skew may break token validation. Mitigation: allow 60 s leeway, add a test.

## Progress log
- 2026-10-21: Plan drafted.

## Decisions log
- 2026-10-21: Store the IdP subject, not the email, as the link key (emails change).

Why each part is there:

SectionPurpose
Goal and non-goalsStops scope creep; tells a fresh session when to stop
Context and linksJust-in-time pointers instead of pasted code
Steps with verificationCloses the feedback loop per step; Anthropic's key lever
Acceptance criteriaThe definition of done a reviewer can check
RisksNames what to watch so it is not discovered in review
Progress logLets the next session resume; the agent updates it as it works
Decisions logRecords why, so nobody reverses it by accident

4. Size each plan​

A plan is the right size when one session can execute it and a reviewer can read the PR in one sitting.

SignalAction
More than about 6 steps or more than one subsystemSplit into two plans
Steps need different areas of expertise or different test suitesSplit along that line
The context fills up or you need /compact mid-planThe plan was too big; split it and start a fresh session
A single step is "implement everything"Break it down until each step has one check

5. Execute one plan per session​

Start with a clean context for each plan (/clear or a new session). One plan per session keeps the window focused; see Context Engineering. Anthropic's long-running harness uses the same discipline: one feature per session, verify end to end, then update the progress file and commit (Anthropic).

6. Run independent plans in parallel​

ApproachCommand or settingUse when
Worktree sessionsclaude --worktree plan-02 (or -w) creates .claude/worktrees/plan-02/ on a new branch worktree-plan-02Plans touch different files; you want separate PRs (worktrees docs)
Subagent in a worktreeisolation: worktree in the subagent's frontmatterThe main session coordinates and delegates plans
Subagent for research"Use subagents to investigate X"Reading and exploration, not edits (sub-agents docs)

Practical notes from the worktrees docs: a worktree needs at least one commit in the repository, add .claude/worktrees/ to .gitignore, and list files such as .env in .worktreeinclude to copy them into new worktrees. By default new worktrees branch from the default branch (worktree.baseRef set to fresh); set it to head to branch from your current commit, which you will want when plan 02 builds on an unmerged plan 01 (worktrees docs).

Which plans must be sequential:

  • A plan that uses code, schema, or an API introduced by another plan.
  • Plans that edit the same files, or the same migration sequence.
  • Cutover, cleanup, and removal plans; they come last.
  • Anything that changes shared tooling (lockfiles, build config) before the plans that rely on it.

Which can run in parallel: plans that depend only on already-merged work and touch different directories, such as an API plan and a UI plan against an agreed contract. Record the contract in the epic README so both plans use it.

7. Prompts to copy​

Draft the epic breakdown (run in plan mode):

Prompt: draft the epic breakdown
We are planning the epic described in docs/plans/sso-migration/README.md
(goal and links are there). Explore the codebase first; do not edit source.

Propose a breakdown into execution plans:
- Each plan must be completable in one focused session and fit in one PR.
- For each plan give: title, goal, files and areas touched, dependencies on
other plans, and the verification commands.
- Mark which plans can run in parallel and which must be sequential, and why.
- List open questions for me before you write anything.

When I approve, write docs/plans/sso-migration/README.md (with the plan index
table) and one numbered file per plan using the template in
docs/plans/_template.md.

Execute plan 02 and keep the log current:

Prompt: execute plan 02
Read docs/plans/sso-migration/README.md and docs/plans/sso-migration/02-auth-endpoints.md.
Execute plan 02 only. Do not start work from other plans.

For each step:
1. Implement it.
2. Run the step's verification command and show the result.
3. Append a dated line to the plan's Progress log with what you did and the result.
Record any non-obvious choice in the Decisions log.

If a step cannot be verified, or the plan is wrong, stop and update the plan
with what you found before continuing. At the end, tick the acceptance criteria,
set the plan's status in README.md, and summarize the diff. Do not commit until
lint and tests pass.

Keep a docs/plans/_template.md in the repo with the template above, so the prompt can refer to it.

8. Point AGENTS.md at the plans​

Add two lines to the AGENTS.md, the way the ExecPlans approach does: when to write a plan, and where plans live.

AGENTS.md
## Plans
- For changes touching more than three files, write a plan in `docs/plans/` first (template: `docs/plans/_template.md`).
- Epics live in `docs/plans/<epic>/`; read its README.md before starting any plan, and update the progress log as you work.

Best practices​

  • Review the plan before the code. A mistake in a plan costs minutes; the same mistake in implemented code costs a PR.
  • One verification per step. If you cannot name the command that proves a step, the step is not specific enough.
  • Make the agent update the file. The progress log is the handoff. Ask for it in the prompt every time.
  • Keep plans short and link out. Point to ADRs and code paths rather than pasting them.
  • Commit the plan with the work. Plans are docs-as-code, reviewed in the same PR as the change they describe; see memory and knowledge.
  • Use a fresh-context reviewer. Before calling a plan done, ask a subagent with no prior context to review the diff against the plan's acceptance criteria (best practices).
  • Record decisions as they happen. The epic README holds epic-wide decisions, each plan holds local ones.
  • Match the harness. The file format is plain markdown, so the same plans work in Claude Code, OpenCode, and Codex. Add a rule in AGENTS.md for when to write one.

Pitfalls to design around​

  • Split by deliverable, not by layer of effort. A plan called "refactor everything" will not fit a session. Name plans after something a reviewer can see in one PR.
  • Plan once, then execute with a clean context. Do not carry a long planning conversation into implementation; the saved file is the handoff.
  • Keep dependencies explicit. If plan 03 needs plan 01's schema, the index says so, and the worktree branches from a commit that contains it.
  • Re-plan when reality changes. After two failed corrections on the same issue, clear the context and restart with a better prompt (best practices); update the plan with what you learned first.
  • Verify with tools, not with the agent's opinion. Agents tend to grade their own work positively; a separate skeptical evaluator or a real test is more reliable (harness design).
  • Skip the ceremony for small changes. One sentence of intent is a plan. Reserve files for work that needs them.
  • Avoid parallel plans on overlapping files. Merge conflicts cost more than the time you saved; sequence them.

Try it​

Lab (20 min)

  1. Choose a real ticket in a repo you work in that touches several files, or invent a two-day task.
  2. Start claude --permission-mode plan and use the breakdown prompt above. Aim for 2 to 4 plans.
  3. Save the output as docs/plans/<epic>/README.md and 01-...md, 02-...md using the template.
  4. Execute plan 01 in a fresh session with the "execute plan" prompt. Check that the progress log and index status are updated.
  5. If plan 02 is independent of 01, start it in a second terminal with claude --worktree plan-02 and compare timing.
  6. Review the PRs: can a teammate tell what each one is for from the plan alone?

Checklist​

  • I used plan mode (or a read-only phase) to explore before editing.
  • The plan is saved in the repo, not only in chat.
  • Each plan has a goal, non-goals, steps with verification, acceptance criteria, risks, and both logs.
  • The epic has a README with a plan index showing status and dependencies.
  • Each plan fits one session and one PR.
  • Each session starts clean and executes one plan.
  • Parallel plans touch different files and use separate worktrees.
  • Sequential plans are marked as such in the index.
  • The agent updated the progress log and decisions log.
  • AGENTS.md says when to write a plan and where plans live.

Sources​