Feature Design Doc

A Feature Design Doc (FDD) is the source of design decisions for a feature — the artifact a code agent should read first to understand what the feature is and why. It earns its keep whether written before implementation or right after a feature was built: in iterative work, the doc saved at the end of one session is the decision source for the next.

This skill creates, updates, or fact-checks an FDD against a fixed template, and protects the boundary between design decisions and implementation actions. That boundary is the single most common failure mode for this artifact, so most of the guidance below is about defending it.

Core principle

Feature Design Doc is the decision source. Implementation Plan derives task ordering from it. Task Breakdown comes out of the Implementation Plan.

Concretely, an FDD captures:

• Product behavior, user flows, domain concepts
• Policy decisions that resolve ambiguity
• Cross-cutting concerns (security, privacy, permissions, observability, accessibility, i18n)
• Alternatives considered and why they were rejected
• Version-specific scope, risks, and open questions
• Platform constraints when they materially shape the design