Feature Design Doc

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

It does not capture:

• File paths, function names, module names
• Task ordering, PR breakdowns, ticket IDs
• "Step 1: create X. Step 2: modify Y." sequences
• Code-agent commands ("run pnpm test", "edit auth.ts")

When in doubt: would a code agent reading this doc need to make a product decision, or take a coding action? FDD is about the first; everything else is downstream.

Decide the mode first

Scope gate before anything else: this skill documents a single product feature. If the request is actually a system/architecture design doc, a DB or API schema design, an RFC, an implementation plan, or a README, say that the FDD format does not fit and stop — do not force the template onto a non-feature subject.

When invoked, identify which mode applies. Each mode has a different shape of output:

| Mode | Trigger signal | What to produce | | --- | --- | --- | | Create (default) | User describes a new or just-built feature, gives a problem statement, or asks to "write/draft/generate" a doc — or the signal is ambiguous | A complete Markdown FDD saved to docs/FDD/.md | | Update | An FDD already exists for the feature and the user asks to reflect new decisions, changed behavior, or a just-modified implementation | The same file revised in place (append-oriented — see "Update workflow") plus a new Revision History entry | | Fact-check | User points at an existing doc and asks to "review/validate/audit/check"; or attaches a doc path explicitly | A findings report grouped by severity, citing affected section names and external sources | | Normalize | User has a doc that mixes design + implementation, or sections are mislabeled — usually surfaced from a Fact-check first | A revised doc plus a short prose summary of what moved where |

Default to Create when uncertain — but if a file already exists at the target path, default to Update instead. Only ask which mode to use if there is literally no feature signal and no document attached (e.g., the user just typed "기능 문서" with no context). For everything else, infer and proceed — wrong-mode cost is recoverable, but interrogation is not.

The reference template

Load [references/feature_design_doc_template.md](references/featuredesigndoc_template.md) before creating or fact-checking. That file is the canonical structure; this SKILL.md only adds how to use it well.

Section optionality:

• Sections 1–13 are required in the default full profile (see "Profiles" below).
• 14. Platform Design is required when the feature is cross-platform, OS-sensitive, hardware-sensitive, browser-sensitive, runtime-sensitive, or platform API-heavy. Otherwise omit — but keep the remaining section numbers unchanged; never renumber.
• 15. Result Semantics is required when the feature has meaningful operation states (partial success, restore results, sync states, migration outcomes, user-visible failures). Otherwise omit.
• 16. Future Extensions is for plausible future product directions only. Do not duplicate every Out of Scope bullet here.
• Revision History is optional at first save, required from the first update onward (see "Update workflow").
• Appendix is for supporting material that does not belong in the main narrative, including the non-normative Code Map (see the leakage exception below).

Profiles

The frontmatter profile key selects the required-section contract; the validator enforces whichever is declared.

• profile: full (default) — sections 1–13 required as listed above.
• profile: compact — for small features. Sections 2, 3, 4, 7, 8, 9, 10, 12, 13 stay required; 1, 5, 6 become optional; section 11 stays required but may be condensed to one line per concern (- Security: Not applicable: ). Section numbers never change — omit, don't renumber.

Use compact only when ALL of these hold:

• single platform, no platform-conditional behavior
• no new or changed persisted data model
• no auth/permission surface change
• no external standard or compliance involvement (OAuth, WCAG, GDPR, ...)
• one primary user flow

If any fails, use full. When unsure, use full — compact exists to keep small docs honest, not to make big docs cheap.

Section responsibility map

The hardest mistake to catch is putting the right content in the wrong section. The three sections most often confused are Feature Definition, Non-Goals, and Scope. Use this map to keep them separate:

| Statement type | Belongs in | | --- | --- | | "This is a kind of X" / "This is not a kind of Y" (identity) | Feature Definition → "This feature is" / "This feature is not" | | "We could have done X but chose not to" (rejected aspiration) | Goals & Non-Goals → "Non-Goals" | | "Not in v1.0, planned later" (release boundary) | Scope → "Out of Scope for [Version]" | | "We considered approach X but chose Y" (rejected design path) | Alternatives Considered | | "When situation is ambiguous, decide this way, because..." (rule with rationale) | Policy Decisions | | "The system needs to handle this failure category" (design-level) | Design → "Failure Handling" | | "User-visible outcome state" (success/partial/failed) | Result Semantics |

If the same statement seems to fit multiple sections, re-read this map. It almost always belongs in only one.

Creation workflow

Phase 0 — Identify the input source

Create has two entry paths. Pick one before doing anything else:

• Post-implementation (the common case) — the feature was just ideated and built in this session (vibe-coding), or already exists in the codebase. The primary sources are the session conversation, the implementation diff, and git history. Harvest first, ask second: extract the Phase 1 answers, policy decisions, and rejected alternatives from those sources, present everything you inferred as one confirmation batch, and ask only for what genuinely cannot be recovered.
• Pre-implementation — the feature is still an idea; there is no code or session record to harvest. Run Phase 1 as an interview.

Phase 1 — Required inputs (single batched round)

Before drafting, settle the 5 minimum decisions:

1. Feature name (short label that becomes the filename in kebab-case)
2. One-sentence definition ("[Feature] is ...")
3. Problem statement — what's broken without it
4. Primary users / actors — who experiences this feature
5. Target version or release — the scope boundary for "v1 vs later"

In the post-implementation path, fill all five from the session and the code first; the "batch" becomes a single confirmation message ("here is what I inferred — correct anything wrong") rather than five questions.

When you do need to ask, group everything into one round. AskUserQuestion accepts at most 4 questions per call, so either reduce the open items below five first (infer what you can) or split 4+1; free-text items (name, definition, problem statement) work better as a single grouped plain message than as option lists. Do not interrogate one-by-one — that frays the conversation and the user already knows roughly what they want to tell you. If the user's initial message already answers some of these, only ask for the gaps.

If no live user is reachable (subagent, CI, automation), do not stall in Phase 1: fill the five from available sources, mark inferences explicitly, and use [NEEDS INPUT: ...] for true unknowns — Phase 4 defines how marked drafts hand off.

For item 5, solo or continuous-delivery work with no release train defaults the boundary to as implemented (YYYY-MM-DD).

Phase 2 — Research before drafting

After Phase 1, do targeted research in parallel so the draft isn't built on speculation. Scope the research by what the feature actually touches.

Post-implementation features — read the implementation first. The just-written code is the primary source of truth: extract Behavior, Policy Decisions, and Failure Handling from what the code actually does, not from memory of the discussion. Where the session decided one thing and the code does another, surface the mismatch — ask the user when interactive, otherwise record it in Risks & Open Questions as a known deviation. Mine the session conversation for approaches that were tried or discussed and dropped; they feed Alternatives Considered (evidence gate in Phase 3). The research below still applies, but it grounds a record of what was built rather than speculation about what might be.

Always do — codebase research:

• Identify existing features named in Relationship to Existing Features and verify they exist in the repo. Use Serena/Grep to find their primary modules.
• For data-model design: look for existing schemas, models, types that this feature will interact with.
• For policy decisions involving config/flags: search for current configuration sites.
• For platform-sensitive features: check what platforms the repo already supports.

The point of codebase research is to ground the FDD in what is actually true now, so design decisions reference reality rather than guesses.

Conditional — web research:

Do web research only when the feature touches a well-known external standard or protocol. Examples that warrant it:

• Auth: OAuth 2.0, OIDC, PKCE, FIDO2/WebAuthn, JWT, SAML
• A11y: WCAG, ARIA
• API/protocol: OpenAPI, JSON-RPC, gRPC, MQTT
• Privacy/compliance: GDPR, CCPA, HIPAA
• File formats / cryptography / browser APIs that have a public spec

If the feature is purely internal (e.g., "Q4 internal reporting dashboard", "admin-only user search panel"), skip web research. It introduces hallucinated "best practices" that don't match the actual product, and the cost is real.

Phase 3 — Draft

1. Draft top-down following template order: Document Intent → Background → Feature Definition → Goals/Non-Goals → User Model → Relationship → Flows → Design → Policies → Alternatives → Cross-cutting → Scope → Risks → (optional sections as required by their trigger conditions).
2. Numbered template headings stay in English — sections ## 1. through ## 16., the Cross-cutting subsections ### 11.1 through ### 11.6, and the literal ## Appendix / ## Revision History headings. The validator keys on the H2 section numbers/titles and the 11.x subsection numbers; keeping the numbered skeleton in English keeps it stable for the validator and for downstream agents.
3. Author-named fill-in headings may use the user's language. Headings the author invents to populate template slots — for example, the policy names under section 9 (the template shows ### 9.1 [Policy Area] as a placeholder), the platform names under section 14, the alternative names under section 10 — should match the team's natural vocabulary. The validator only inspects the numbered skeleton, so this does not break anything.
4. Body content is written in the user's primary language — the language the user has been conversing in. Tables, bullets, prose narrative all in user-language; numbered headings, section numbers, frontmatter keys stay English.
5. Apply the responsibility map as you write. If you catch yourself putting "we will not support iOS yet" under Feature Definition, that's a Scope statement; move it.
6. Cross-cutting concerns must be answered, not skipped. For each of Security, Privacy, Permissions, Observability, Accessibility, Internationalization: write either concrete content or Not applicable: — with the colon and a real reason. The validator flags both colonless - Not applicable and reasonless - Not applicable: forms. The Not applicable marker itself stays in English even in non-English documents — the validator only recognizes the English form; the reason text may be in the user's language.
7. Mark unresolved gaps inline with [NEEDS INPUT: ] rather than hallucinating. Phase 4 resolves these.
8. Alternatives need evidence. Record only alternatives traceable to a source: discussed in this session, visible in git history (reverted or abandoned commits), or supplied by the user. If none exist, write "No alternatives were recorded during development." An invented strawman alternative is worse than an honest blank — future agents treat this section as real decision history.
9. Fill the frontmatter metadata. feature-name, profile, created and last-verified (today), verified-against (git rev-parse --short HEAD), tags, and related (paths of FDDs this feature touches). Future agents use these to judge freshness and to find the doc.

Phase 4 — Resolve gaps, validate, save

1. Resolve gap markers. If a live user is present (interactive Claude Code session), surface every [NEEDS INPUT: ...] marker as a single follow-up batch — ask all gap-fills together in one round. If no live user is reachable (subagent, CI, automation), the draft with [NEEDS INPUT] markers is itself the deliverable: do not loop trying to ask, just hand off the marked draft so the downstream caller (or a future interactive pass) can fill them.
2. After filling gaps, run the structural validator. It ships with this skill at scripts/validate_fdd.py, next to this SKILL.md — resolve the path from wherever the skill is installed (for marketplace installs that is NOT the project repo):

``bash python3 /scripts/validate_fdd.py docs/FDD/.md ` The authoritative list of what it checks is the script's docstring (frontmatter and freshness metadata, required sections per profile, empty sections, duplicate/misplaced headings, Cross-cutting answers). It is structural only — content judgement is yours. If python3` or the script is unavailable in the environment, skip it and check the structure against the template manually; do not block on the tool.

1. Resolve what the validator reports: critical findings always; major findings either fix or explicitly accept, each with a one-line reason in your summary to the user. PASS (N major unresolved) is not a clean pass.
2. Run the leakage sweep manually (see "Implementation leakage" section below) — the validator does not catch this.
3. Save the final document to docs/FDD/.md. Create docs/FDD/ if it does not exist. If a file with that name already exists, that is almost always an Update, not a Create — switch to the Update workflow instead of forking copies. Never create -v2 or date-suffixed duplicates: parallel versions of the same FDD destroy discoverability and leave future agents guessing which one is current.
4. Update the index. Maintain docs/FDD/index.md (create it if missing) with one line per document: feature name (linked), one-sentence definition, profile, status, last-verified. This is

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buYoung
• Source: buYoung/skills
• License: MIT

Install and usage instructions live in the source repository linked above.