Skip to main content

23. Feature-Driven Development (FDD) Methodology

Status: Accepted Date: 2025-07-06

Context​

In a large, complex monorepo, understanding the purpose and boundaries of different modules, applications, and libraries can be extremely challenging. Code alone describes how something works, but often fails to clearly communicate what it is supposed to do from a high-level, implementation-agnostic perspective. This lack of clear, discoverable documentation is a major obstacle to developer productivity and AI-assisted tooling.

Decision​

We will adopt Feature-Driven Development (FDD) as the core documentation methodology for the entire monorepo. Every logical component (e.g., application, library, service module) must be accompanied by an FDD.md file located at its root.

Each FDD file serves as a "black box" description of its component, focusing on:

  • Intent / Unique Value: What is this component and why does it exist?
  • Functional Requirements: What are its primary responsibilities?
  • Architectural Decisions: What key ADRs govern its design?
  • Integration Contracts: How does it connect with the rest of the system (inputs, outputs, dependencies)?

This creates a hierarchical and traceable documentation system that mirrors the code structure, enabling both humans and AI agents to rapidly understand the purpose and context of any part of the codebase.

Consequences​

Positive:

  • Discoverability: Provides a standardized way to quickly understand the purpose of any module in the repository.
  • AI Context Recovery: The structured nature of FDDs is ideal for consumption by AI agents, enabling them to gain "instant context" on a specific part of the codebase.
  • Improved Design: The process of writing an FDD forces developers to think clearly about a component's public API and its role in the larger system.
  • Implementation Agnostic: FDDs describe intent, not implementation, so they remain relevant even as the underlying code is refactored.

Negative:

  • Documentation Overhead: Requires the discipline of creating and maintaining an FDD.md file for every new component.
  • Risk of Staleness: FDDs can become out of date if not updated when a component's public contract changes.

Mitigation:

  • CLI Tooling: Use the kaido-cli for fdd:validate to automatically check for missing FDDs, validate their structure, and check for broken links.
  • Automation: Use fdd:create and fdd:bootstrap commands to scaffold new FDD files from templates or existing code, reducing manual effort.
  • CI/CD Integration: Integrate FDD validation into the CI/CD pipeline to enforce compliance and prevent stale documentation from being merged.
  • Yugen Protocol: Enforce token limits on FDD files to keep them concise and high-level, preventing them from becoming bloated implementation descriptions.