writing-plans
Writing Plans
Write a comprehensive implementation plan assuming the implementer has zero context about the codebase and questionable test instincts. Document everything: which files to touch, complete code, exact commands, expected output, and how to verify. Deliver the whole plan as bite-sized checkboxed tasks. DRY. YAGNI. TDD. Frequent commits.
Scope Check
If the spec covers multiple independent subsystems, consider breaking it into separate plans — one per subsystem. Each plan should produce working, testable software on its own. Deeply coupled work can share a plan; independently deployable subsystems should not.
File Mapping (Before Any Tasks)
Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- Prefer smaller, focused files over large files that do too much. The agent edits most reliably when it can hold the full file in context.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns. If the codebase uses large files, do not unilaterally restructure — but if a file you are modifying has grown unwieldy, including a split in the plan is reasonable.
This structure informs task decomposition. Each task should produce self-contained changes that make sense independently.