Glossary | Intent-First Development

Altitude: A metaphor for the level of abstraction at which design work occurs, ranging from 50,000 ft (vision) down to 1,000 ft (implementation).
IFD uses five altitude levels to structure design conversations:

50,000 ft — Vision and problem definition

30,000 ft — Capability mapping (what the system can do)

10,000 ft — Architecture (component boundaries, integration points)

5,000 ft — Component design (internal structure, API contracts)

1,000 ft — Implementation (code, tests, deployment)

Each altitude has a gate check that must pass before descending to the next level. This prevents premature implementation — teams cannot write code until intent has been captured at every higher altitude.
CLAUDE.md: The AI entry point for an IFD project — a structured document that orients any AI agent to the full intent corpus, key documents, active Skills, and project conventions.
Every IFD project includes a CLAUDE.md file at the repository root. It serves as the starting point for any AI tool working in the codebase, providing links to architectural documentation, design decisions, active Skills, and project-specific conventions. Think of it as an onboarding document — but written for AI agents rather than human developers.
Design Decision Document (DDD): A structured record of an architectural decision, capturing the scenario, options evaluated, recommendation, and final decision with its driver.
DDDs are the primary governance artifact in IFD. Each document separates the recommendation (what the team's analysis suggests) from the decision (what was actually chosen and why). This separation preserves the reasoning process — future team members can see not only what was decided but what alternatives were considered and rejected, and whether the decision was made on technical, business, or timeline grounds.
Deterministic Work: Development tasks that can be reliably automated or pattern-generated because their inputs, rules, and expected outputs are well-defined.
IFD explicitly categorizes work as deterministic or non-deterministic. Deterministic work — boilerplate generation, CRUD scaffolding, test harness creation, configuration transforms — follows known patterns and produces predictable outputs. AI tools excel at this category. Recognizing which work is deterministic allows teams to delegate it confidently to AI while reserving human judgment for non-deterministic work.
Diataxis: A documentation framework that organizes content into four types — Tutorials, How-To Guides, Explanations, and Reference — each serving a distinct cognitive mode.
Created by Daniele Procida, Diataxis provides the structural backbone for IFD documentation. By separating learning-oriented content (tutorials) from task-oriented content (how-to guides), understanding-oriented content (explanations), and information-oriented content (reference), the framework ensures documentation remains navigable and useful as it scales. In IFD, Diataxis structure also benefits AI tools, which consume each documentation type differently.
Explanation (Diataxis): Understanding-oriented documentation that discusses why things work the way they do — the reasoning, context, and design intent behind architectural choices.
Explanations answer the question "why?" They provide the conceptual background that makes other documentation types meaningful. In IFD, explanations capture architectural reasoning, design rationale, and system context — the information that is hardest to reconstruct after the fact and most valuable for both human developers and AI tools making implementation decisions.
How-To Guide (Diataxis): Task-oriented documentation that provides step-by-step instructions for accomplishing a specific goal, assuming the reader already understands the underlying concepts.
How-to guides answer the question "how do I...?" They are practical, goal-directed, and assume prerequisite knowledge. In IFD, how-to guides document implementation patterns, process workflows, and operational procedures. They serve as direct instructions that AI tools can follow when implementing specific tasks within an established architectural context.
Intent: The documented reasoning behind a system's design — the decisions, constraints, trade-offs, and goals that define what the system should do and why.
Intent is the central concept in IFD. It encompasses architectural decisions, design constraints, business requirements, and the reasoning that connects them. Unlike code (which shows what was built) or comments (which offer ad-hoc explanations), intent is a structured, inspectable artifact that persists across team changes, AI sessions, and project evolution. Captured intent is what transforms AI-generated code from "code that compiles" to "code that belongs."
Intent Fidelity: The degree to which a codebase's implementation remains aligned with its documented design intent over time.
Intent fidelity is the governance metric at the heart of IFD. High intent fidelity means the code reflects the decisions, conventions, and architectural boundaries that were deliberately designed. Low intent fidelity means the codebase has drifted — through expedient shortcuts, undocumented changes, or AI-generated code that ignored context. IFD practices (DDDs, Skills, structured documentation) are designed to maintain intent fidelity as systems evolve.
Intent-First Thinking: The practice of articulating design intent through collaborative sessions before any code is written, using documentation as the design medium.
Intent-First Thinking inverts the traditional development sequence. Instead of building first and documenting later (if at all), teams articulate what they intend to build, why, and under what constraints — then use that captured intent to guide implementation. The design conversation often involves an AI partner that surfaces options, challenges assumptions, and helps explore the solution space before committing to code.
Non-Deterministic Work: Development tasks requiring creative judgment, trade-off evaluation, or contextual reasoning that cannot be reliably reduced to a repeatable pattern.
Non-deterministic work includes architectural design, trade-off analysis, domain modeling, and integration strategy. These tasks have no single correct answer — the right choice depends on constraints, priorities, and organizational context that AI tools cannot fully evaluate on their own. IFD uses AI as a collaborative partner for non-deterministic work (surfacing options, challenging assumptions) while keeping the decision authority with human architects.
Practice-Level Skill: A Skill that encodes methodology conventions applicable across all projects — how DDDs are structured, how documentation is organized, how design sessions are conducted.
Practice-level Skills are shared across an organization's projects. They encode the IFD methodology itself: how to write Design Decision Documents, how to structure Diataxis documentation, how to run altitude-gated design sessions. When a team adopts IFD, practice-level Skills provide the baseline conventions that every project inherits.
Project-Level Skill: A Skill that encodes conventions specific to a single codebase — its technology stack, naming patterns, architectural constraints, and domain terminology.
Project-level Skills capture the decisions and patterns unique to one project. They might specify that all React components use a particular file structure, that database migrations must be backward-compatible, or that API endpoints follow a specific naming convention. AI tools consume these Skills to generate code that fits the existing codebase rather than following generic patterns.
Reference (Diataxis): Information-oriented documentation for looking up specifications, API contracts, data structures, and other factual details — structured for quick retrieval, not sequential reading.
Reference documentation answers the question "what is...?" It is austere, factual, and organized for lookup rather than narrative flow. In IFD, reference materials include API contracts, data model specifications, configuration schemas, and Design Decision Document indexes. AI tools rely heavily on reference documentation for accurate implementation details.
Skill: A structured artifact that encodes conventions, constraints, and patterns in a form that AI tools can consume directly — bridging human documentation and machine-actionable guidance.
Skills are what make IFD portable and machine-actionable. They distill project conventions (naming patterns, architectural boundaries, testing strategies, error handling approaches) into structured documents that AI implementation partners consume alongside the documentation corpus. Skills operate at two levels: practice-level (methodology conventions) and project-level (codebase-specific patterns).
Software Factory: A development environment where deterministic work is systematically delegated to AI tools operating within captured intent, freeing human developers for non-deterministic design and decision-making.
The software factory concept describes the end state of a mature IFD practice. When intent is thoroughly captured, documentation is well-structured, and Skills encode project conventions, a significant portion of implementation becomes reliably delegable to AI. The factory metaphor emphasizes repeatability and quality control — AI-generated code is produced within defined constraints, not in a vacuum.
Tutorial (Diataxis): Learning-oriented documentation that guides a newcomer through a complete workflow, building understanding through hands-on experience.
Tutorials answer the question "can you teach me?" They are structured as learning experiences — a series of steps that a beginner follows to achieve a working result while building mental models. In IFD, tutorials help new team members (and AI agents) learn the project's development workflow from end to end rather than piecing it together from scattered references.