The Four Pillars

Intent-First Development rests on four structural pillars. Each addresses a specific failure mode in AI-assisted development, and together they form a coherent system: intent is articulated, structured, made machine-consumable, and then implemented with full architectural context.

Remove any one pillar and the system degrades. Intent without structure produces ad-hoc documentation. Structure without machine-consumable artifacts leaves AI tools guessing. Machine-consumable artifacts without a methodology for creating them become stale on arrival.

1. Intent-First Thinking

Design intent is articulated through collaborative AI sessions before any code is written. Documentation is the design medium — not an afterthought produced once the code exists.

In a traditional workflow, a developer receives a requirement, writes code, and documents what they built (if documentation happens at all). Intent-First Thinking inverts this sequence. The design conversation happens first, producing structured artifacts that capture what the system should do, why specific approaches were chosen, and what alternatives were considered and rejected.

This is not waterfall. The design sessions are rapid, conversational, and iterative — often conducted with an AI partner that surfaces best practices, challenges assumptions, and generates options. The output is not a 50-page specification; it is a focused set of Design Decision Documents, explanations, and constraints that give subsequent implementation a clear target.

Why it matters: When code is generated without captured intent, every future modification requires reverse-engineering the original developer's reasoning. With captured intent, the reasoning is inspectable, reviewable, and available to both human and AI collaborators.

2. Diataxis as the Documentation Structure

All documentation follows the Diataxis framework — a system that organizes documentation into four distinct types, each serving a different cognitive mode:

• Tutorials — Learning-oriented guides that walk a newcomer through a complete workflow
• How-To Guides — Task-oriented instructions for accomplishing specific goals
• Explanations — Understanding-oriented discussions of why things work the way they do
• Reference — Information-oriented material for looking up specifications, APIs, and definitions

Most teams produce documentation that mixes these modes indiscriminately — a README that is half tutorial, half reference, and fully unhelpful when you need either one specifically. Diataxis enforces a separation that keeps documentation navigable as the corpus grows from dozens of pages to hundreds.

Why it matters for AI: AI tools consume documentation literally. When a how-to guide is contaminated with explanatory digressions, the AI either follows the wrong part or ignores context that matters. Diataxis-structured documentation gives AI tools clean, predictable artifacts to work with — each type has a known purpose and a known structure.

3. Skills as the AI Consumption Layer

Conventions, constraints, and patterns are distilled into structured artifacts called Skills that AI tools can consume directly. Skills bridge the gap between human-readable documentation and machine-actionable guidance.

A Skill encodes things like: "In this project, all API endpoints follow this naming convention," or "When creating a new React component, use this file structure and these patterns," or "Database migrations must be backward-compatible and follow this rollback strategy."

Skills operate at two levels:

• Practice-level Skills apply across projects and encode methodology conventions — how Design Decision Documents are structured, how documentation is organized, how altitude-gated design sessions work
• Project-level Skills encode the specific conventions and constraints of a single codebase — its technology stack, its architectural patterns, its domain terminology

Without Skills, AI tools rely on whatever patterns they find in the existing codebase — including patterns the team has explicitly decided to move away from. Skills make the intended conventions explicit so AI-generated code reflects deliberate choices, not inherited habits.

Why it matters: Skills are what make IFD portable across AI tools. Because they encode intent in structured, documented form rather than in tool-specific prompt templates, the same intent corpus works regardless of which AI development environment a team adopts.

4. Claude Code as Implementation Partner

Implementation is executed in an AI-native development environment where the agent has access to the full intent corpus. Code is the last artifact produced, not the first.

This pillar is not about a specific tool — it is about a way of working. The implementation partner (currently Claude Code) operates with access to:

• The Diataxis-structured documentation corpus
• All Design Decision Documents with their rationale and rejected alternatives
• Practice-level and project-level Skills
• The CLAUDE.md entry point that orients the agent to the full context

When the AI implementation partner generates code, it does so within a rich context of documented intent. The result is code that respects architectural boundaries, follows established conventions, and traces back to explicit design decisions.

Why it matters: Most AI coding tools operate in a context vacuum — they see the current file, maybe a few related files, and whatever the developer types into a prompt. An intent-aware implementation partner sees the full architectural picture. The difference is the difference between generating code that compiles and generating code that belongs.

How the Pillars Reinforce Each Other

The four pillars are not independent best practices to adopt incrementally. They form a system with reinforcing dependencies:

Intent-First Thinking produces the raw material — design decisions, architectural reasoning, constraints. Diataxis structures that material into a navigable, maintainable corpus. Skills distill the corpus into machine-actionable conventions. Claude Code consumes all three to produce implementation that reflects the full depth of captured intent.

The system's integrity comes from this closed loop. Intent captured at the top flows through structured documentation and machine-consumable Skills into code that can be traced back to the decisions that motivated it. When intent changes, the documentation and Skills update first, and the code follows — maintaining alignment between what the team decided and what the codebase does.