Intent-First Development Glossary

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. Unlike code (which shows whatwas built) or ad-hoc comments, 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-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, 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 and challenges assumptions before code is committed.

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 fidelity means the code reflects the decisions, conventions, and architectural boundaries that were deliberately designed. Low fidelity means the codebase has drifted — through shortcuts, undocumented changes, or AI-generated code that ignored context. IFD practices are designed to maintain intent fidelity as systems evolve.

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 analysis suggests) from the decision (what was 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 whether the choice was made on technical, business, or timeline grounds.

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 tools consume alongside the documentation corpus. Skills operate at two levels: practice-level and project-level.

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.

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 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 conventions. Think of it as an onboarding document — written for AI agents rather than human developers.

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).

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.

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 here, not as the decision authority.

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, task-oriented, understanding-oriented, and information-oriented content, the framework ensures documentation remains navigable 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 and design rationale — 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 — direct instructions that AI tools can follow when implementing specific tasks within an established architectural context.

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 DDD indexes. AI tools rely heavily on reference documentation for accurate implementation details.

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 learn the project's development workflow from end to end rather than piecing it together from scattered references.