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)
Map out which files will be created or modified and what each one is responsible for before defining tasks.
- Each file has one clear responsibility.
- Prefer smaller, focused files. 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.
Each task should produce self-contained changes that make sense independently.