Article Summary (Model: gpt-5.2)
Subject: Plan-first Claude workflow
The Gist:
The author describes a Claude Code workflow that separates thinking from typing: Claude first researches the relevant code, then writes a detailed plan in a persistent markdown file, and only implements after the human reviews and annotates that plan until it’s correct. The key mechanism is using research.md and plan.md as durable artifacts and a “shared mutable state,” so misunderstandings are corrected before any code is generated, avoiding the common failure mode of locally-correct changes that break surrounding systems.
Key Claims/Facts:
- Research →
research.md: Instruct Claude to read specific folders “deeply” and produce a detailed written report you can verify before planning. - Plan + annotation cycle: Claude drafts
plan.md; the human adds inline notes (constraints, corrections, rejections); Claude updates the plan; repeat 1–6 times with an explicit “don’t implement yet.” - Execution from a frozen plan: Once approved, ask Claude to implement the whole plan, mark TODOs complete in the plan, keep code clean (e.g., no
any/unknown), and continuously run typechecks.
Discussion Summary (Model: gpt-5.2)
Consensus: Cautiously Optimistic—many find plan-first + iterative review highly effective, but there’s debate about how much is real methodology vs prompt superstition.
Top Critiques & Pushback:
Better Alternatives / Prior Art:
PLAN.mdinto stages and forcing the model to implement one stage at a time, updating the plan as it goes (c47107999, c47108066).plan.mdfiles that might be deleted, some prefer having the model create a GitHub issue (viaghCLI) containing the plan for permanence and tracking (c47108348).Expert Context: