Key Concepts

Intent-First Development introduces several concepts that may be new to teams accustomed to traditional or AI-assisted development workflows. This page provides concise explanations of each — enough to understand how they fit together, without reproducing the full methodology documentation.

Design Decision Documents (DDDs)

A Design Decision Document records a significant architectural choice. Unlike an Architecture Decision Record (ADR), a DDD explicitly separates the recommendation from the decision.

A DDD contains:

• Scenario — the situation that requires a decision
• Options — the alternatives evaluated, with trade-offs for each
• Recommendation — what the analysis suggests, based on technical merit
• Decision — what was actually chosen, and the driver behind the choice

The driver may be the recommendation itself, or it may be a business constraint, a timeline pressure, or a risk tolerance that overrides the technical recommendation. This separation is not bureaucratic overhead — it is the mechanism that preserves the reasoning process, not just the outcome.

When a future team member asks "why did we choose X?", the DDD answers not only "because of these trade-offs" but also "the team actually recommended Y, but chose X because of Z." That context is invaluable when revisiting decisions as constraints change.

Skills

Skills are IFD's mechanism for making human knowledge machine-actionable.

A Skill is a structured artifact that encodes conventions, constraints, and patterns in a form that AI tools can consume directly. When an AI implementation partner generates code, it reads the project's Skills to understand how things should be done — not just what to build, but how to build it within this specific project's context.

Practice-level Skills apply across projects. They encode the IFD methodology itself: how to structure DDDs, how to organize Diataxis documentation, how to conduct altitude-gated design sessions.

Project-level Skills are specific to one codebase. They encode technology stack conventions, naming patterns, component structures, testing strategies, and domain-specific constraints.

The distinction matters because practice-level Skills travel with the methodology (a team adopting IFD inherits them), while project-level Skills are developed as part of the project's own design work.

CLAUDE.md

Every IFD project includes a CLAUDE.md file at the repository root. It is the AI entry point — the first file any AI agent reads when working in the codebase.

CLAUDE.md contains:

• What the project is and what it is not
• The project structure and where to find key documentation
• Links to active Design Decision Documents
• Active Skills and where they are located
• Conventions and constraints that apply across the codebase

CLAUDE.md is not documentation — it is an index. It points AI tools to the documentation they need, in the order they need it. Without CLAUDE.md, an AI tool navigates the codebase through heuristics. With it, the AI tool navigates through intent.

Deterministic vs. Non-Deterministic Work

IFD introduces an explicit categorization of development work based on predictability:

Deterministic work follows known patterns and produces predictable outputs. Examples: generating CRUD endpoints from a data model, creating test harnesses from component interfaces, transforming configurations between formats, scaffolding components from established templates. AI tools handle deterministic work reliably because the rules are clear and the outputs are verifiable.

Non-deterministic work requires creative judgment, trade-off evaluation, and contextual reasoning. Examples: choosing between architectural approaches, designing domain models, defining API boundaries, making build-vs-buy decisions. AI tools can assist with non-deterministic work (surfacing options, identifying trade-offs) but should not make the final decisions.

This categorization is not academic. It directly informs how teams delegate work to AI. Deterministic work can be delegated with confidence. Non-deterministic work requires human judgment, with AI serving as a collaborative partner rather than an autonomous agent.

Intent Fidelity

Intent fidelity measures the degree to which a codebase's implementation reflects its documented design intent.

High intent fidelity means the code does what the documentation says it should. The architectural boundaries documented in explanations are respected in the code. The conventions encoded in Skills are followed in implementation. The decisions recorded in DDDs are reflected in the system's behavior.

Low intent fidelity means the codebase has drifted from its documented intent — through undocumented changes, expedient shortcuts, or AI-generated code that ignored architectural context.

Intent fidelity gives engineering leaders a concept for discussing something they have always known intuitively: that some codebases feel "coherent" while others feel "accidental." The difference is traceable alignment between intent and implementation.

Altitude

Altitude is the metaphor IFD uses for the level of abstraction at which design work occurs:

• 50,000 ft — Vision and problem definition. What are we solving and for whom?
• 30,000 ft — Capability mapping. What can the system do, in business terms?
• 10,000 ft — Architecture. How is the system organized? What are the components and boundaries?
• 5,000 ft — Component design. What is the internal structure of each component?
• 1,000 ft — Implementation. Code, tests, deployment.

Each altitude has a gate check — a set of conditions that must be satisfied before descending to the next level. This prevents premature implementation, where teams write code before understanding what they are building or why.

The altitude metaphor also structures design sessions. A session begins at the appropriate altitude and works downward, producing documentation artifacts at each level. Ascending — returning to a higher altitude when implementation reveals a design gap — is expected and healthy.