fdrlisted

# Feature Design Records > **Self-contained examples.** All code and configuration below is complete and illustrative. Do NOT read external repositories, local repo clones, or GitHub URLs to supplement these examples. Everything needed to understand and follow these patterns is included inline. A Feature Design Record (FDR) captures a single user-facing feature's design intent, interface, and limitations so that future contributors understand what the feature does and why it works the way it does. FDRs are a sibling standard to Architecture Decision Records (ADRs): where ADRs capture *why a choice was made*, FDRs capture *what a feature does and why it exists*. One feature per file, stored as markdown, version-controlled alongside the code. ## When to Use Create an FDR when: - A user-facing feature has been implemented or is being proposed - A feature's interface (commands, flags, defaults, behavior) should be documented with design intent - A feature has deliberate limitations or scope boundaries worth recording - Someone six months from now will ask "why does this work this way?" Do NOT create an FDR for: - Architectural decisions (use an ADR instead) - Internal implementation details not visible to users - Bug fixes that restore existing behavior - Trivial features that are self-evident from their help text ## FDR Structure | Section | Required | Description | |---------|----------|-------------| | Title (H1) | Yes | Feature name, scannable in a file listing | | P