write-tech-spec

To write a tech spec aligned with your codebase, analyze existing modules, entry points, and patterns first, then document the problem, proposed changes, and architectural tradeoffs in a structured layout. This grounds the specification in actual implementation constraints.

You need a design doc when a feature spans multiple modules or architectural layers, requiring coordination on implementation plans, tradeoffs, and ownership boundaries. It translates product intent into concrete technical plans to reduce ambiguity and rework.

A TECH.md implementation plan should include sections for the problem, code references, current state, proposed changes, end-to-end flow, risks, testing, and follow-ups. This structure enforces comprehensive coverage of architectural decisions and constraints.

Yes, you can generate an architecture spec for multi-module features by researching current codebase patterns and mapping out the end-to-end flow. This captures cross-layer dependencies, ownership boundaries, and implementation risks in a single document.

The best way to document technical tradeoffs and risks in a spec is to dedicate specific sections for risks, testing, and follow-ups alongside proposed changes. This aligns product intent with implementation constraints and clarifies ownership boundaries for reviewers.

Your feature implementation plan lacks clear code references because it likely skips analyzing current codebase entry points and existing patterns. Grounding the spec in actual module structures and architectural decisions resolves this disconnect and streamlines collaboration.