design-documents

To write a technical design document, define the problem, research the current state, set goals, generate solution options, compare them, and recommend a path forward. This structured process ensures clear communication and planning before development begins.

An architecture decision record (ADR) preserves the rationale behind technical choices made during software planning. You need an ADR when documenting complex feature designs to ensure the reasoning behind architectural decisions remains accessible for future development.

Document architectural decisions by generating multiple solution options, comparing their pros and cons, and recording the final recommendation. This captures the decision rationale and serves as a blueprint for development and a clear agent-human contract.

Yes, a structured technical design document provides a clear contract for AI agents to follow during implementation. It outlines the problem, proposes solutions, and recommends a path forward, ensuring alignment before coding begins.

The best way to plan a complex new feature is generating a technical design document that analyzes the problem, explores solutions, and documents cross-cutting concerns. This ensures team alignment and provides a solid architectural blueprint before implementation.