design

A design document for complex features is needed when scope is unclear before coding or upfront decisions are too complex to inline. It resolves ambiguity by specifying exact file paths, types, and testable acceptance criteria for multi-file modules.

You define testable acceptance criteria by generating a precise design document that outlines unambiguous conditions, notes for non-obvious logic, and edge cases, ensuring clear validation standards before implementation begins.

Yes, you can use this architecture documentation approach specifically when scope is unclear before coding or when a feature spans multiple files. It produces explicit file-structure plans and dependency resolution to guide implementers.

The best way to plan code structure for multi-file modules is generating an implementation blueprint that defines explicit file-structure plans and dependency resolution, reducing ambiguity and rework during the actual coding phase.

You should avoid upfront design documents for simple, single-file modifications where scope is already clear, as generating explicit file-structure plans and complete function signatures for trivial changes introduces unnecessary overhead.