Plan Docs as Contracts
Plans survive context compaction. Conversation memory doesn’t.
In an 8-hour Claude Code session, the agent’s recall of early decisions degrades as context is compressed. A plan doc — with its Decisions, Notes, and Discussion sections — becomes the durable record. The agent writes to it during implementation; you review it during debrief.
Plan doc structure
Section titled “Plan doc structure”Every milestone gets a plan doc at docs/epics/<epic>/plans/<milestone>.md. The structure:
| Section | Filled when | By whom |
|---|---|---|
| Context | During planning | Agent + human |
| Scope | During planning | Agent + human |
| Acceptance Criteria | During planning | Agent + human |
| Scenarios | During planning | Co-designed |
| Steps | During planning (checkboxes ticked during execution) | Agent |
| Decisions | During execution | Agent |
| Notes | During execution | Agent |
| Discussion | During execution (items for human review) | Agent |
| Verification | Post-milestone | Agent |
The first five sections are the contract — what will be built and how we’ll know it’s done. The last four are the execution record — what actually happened.
Why this matters
Section titled “Why this matters”The plan doc serves four purposes:
- Scope agreement. The human and agent align on what “done” means before code gets written. No negotiating after the fact.
- Progress tracker. Checkboxes in the Steps section show where things stand. Useful in long sessions and for async review.
- Decision record. When the agent makes a choice autonomously — a library, an approach, a tradeoff — it’s logged with alternatives and rationale. The debrief reviews these.
- Compaction insurance. In a long session, the plan doc is the single source of truth. If context has been compressed, the plan doc hasn’t.
Decisions in practice
Section titled “Decisions in practice”In one session building a CLI tool, the agent hand-rolled a .env parser instead of using the dotenv package. It logged the decision: “15 lines didn’t justify a dependency.” During the debrief, the human caught it and pushed back — the project’s principle is reuse over reinvention, and the real cost wasn’t 15 lines but the entire surface area around them (edge cases, maintenance, testing).
Because the decision was logged, the correction was specific and trackable. Without the log, it would have been an unnoticed deviation — or a vague “why didn’t you use dotenv?” with no record of the reasoning.
Information flow
Section titled “Information flow”The plan doc is the single place the agent writes during a session. No need to think about which tier or which file. Write to the plan doc. The debrief sorts it later:
- Decisions that reveal patterns →
docs/reference/patterns.md - Decisions that should be permanent rules → CLAUDE.md
- Notes with domain gotchas → epic’s
journal.md - Discussion items → resolved, deferred, or promoted to project-level
- Scenarios with ongoing value → epic’s scenario catalog
This separation — capture everything in one place during execution, curate it during debrief — is deliberate. It keeps the agent focused on implementation, not filing.