The Foundation
The IFD Principles Library
Intent-First Development draws on established principles from software engineering, architecture, and design. Each addresses a specific failure mode in how complex systems are built and maintained — and each takes on new urgency when AI tools are in the development loop.
Documentation as Design Medium
Documentation is not a record of what was built — it is the medium through which design happens. Writing forces clarity, surfaces gaps, and makes reasoning inspectable before implementation begins.
IFD treats documentation as the primary design artifact. The discipline of articulating intent in structured form is itself the design activity. Code is the output of documented intent, not the source from which documentation is derived.
Explicit Over Implicit
When a convention, constraint, or decision can be stated explicitly, it should be — even when experienced developers might infer it from context.
AI tools cannot infer from context the way experienced developers can. An implicit naming convention that every human team member follows by habit is invisible to an AI agent. IFD's Skill system exists to make these implicit conventions explicit, ensuring AI-generated code follows the team's actual standards.
Single Source of Truth
Every piece of knowledge should have a single, authoritative representation in the system. Duplication creates opportunities for inconsistency that compound over time.
IFD applies this principle to architectural knowledge. A design decision is recorded once in a DDD, not scattered across comments, wikis, and Slack messages. A convention is encoded once in a Skill, not repeated in style guides and README files. CLAUDE.md is the single entry point that indexes all authoritative sources.
Reversibility
Prefer decisions that can be reversed over decisions that cannot. When a decision is irreversible, invest more analysis upfront. When it is reversible, decide quickly and learn from the result.
IFD's Design Decision Documents support this principle by recording the reversibility of each decision. A DDD noting a “two-way door” signals low-cost course correction; a “one-way door” signals that deeper analysis and broader review is warranted before commitment.
Principle of Least Surprise
A system should behave in a way that its users and developers expect. Surprising behavior — even if technically correct — creates cognitive overhead and increases the chance of errors.
In IFD, this principle guides Skill authoring. When AI tools generate code following project Skills, the output should look like code a senior team member would write. If AI-generated code consistently surprises reviewers, the Skills need refinement — the encoded conventions do not match the team's actual expectations.
Bounded Contexts
A bounded context is an explicit boundary within which a domain model is defined and applicable. Outside that boundary, the same terms may mean different things.
In IFD, bounded contexts inform how documentation and Skills are organized. Each component operates within a defined context, and the boundaries between contexts are where integration contracts live. AI tools respect these boundaries because the documentation makes them explicit.
Separation of Concerns
Each module or component should address a single concern — a distinct aspect of the system's functionality or behavior. Mixing concerns makes components harder to understand, test, and modify.
In IFD, separation of concerns operates at multiple levels: documentation types are separated by Diataxis, design decisions are separated from implementations, and Skills separate practice-level conventions from project-level conventions. Each artifact has a single, clear purpose.
Design for Replaceability
Components should be designed so they can be replaced without cascading changes throughout the system. Clear interfaces, explicit contracts, and documented boundaries enable replacement.
In IFD, this principle applies to AI tools themselves. By encoding intent in tool-agnostic artifacts — documentation, Skills, DDDs — rather than tool-specific prompt libraries, organizations ensure their methodology survives tool changes. The investment is in captured intent, not in vendor-specific integrations.
Evolutionary Architecture
Architecture should evolve incrementally, guided by fitness functions that assess whether the system still meets its quality attributes. Big-bang architectural decisions made early often prove wrong under real usage.
IFD supports evolutionary architecture through its altitude model. As the system evolves, teams ascend to revisit higher-level decisions, update documentation, and adjust Skills — keeping intent aligned with the architecture as it actually exists, not as it was originally planned.
You Aren't Gonna Need It
Do not build functionality until it is actually needed. Speculative features add complexity without delivering value, and the speculation is usually wrong.
In IFD, YAGNI applies to documentation and Skills as well as code. Capture intent for the work you are doing now. Do not create speculative architectural documentation for systems you might build someday. The methodology grows with the project, not ahead of it.
Conway's Law
Organizations design systems that mirror their own communication structures. The architecture of a system will reflect the boundaries and relationships between the teams that build it.
IFD takes Conway's Law seriously by making organizational boundaries explicit in documentation. When architectural boundaries align with team boundaries, documentation and Skills can be organized by team. When they do not align, the mismatch is visible and addressable — rather than silently producing integration friction.
Iterate, Then Optimize
Build a working solution first, then refine it based on real feedback. Premature optimization of code, architecture, or process addresses problems that may not exist and constrains solutions to assumptions that may not hold.
In IFD, this principle applies to the methodology itself. Start with basic DDDs and a few key Skills. Refine the documentation structure and expand Skill coverage as you learn what matters for your specific project. A pragmatic corpus that ships and evolves provides more value than a perfect one that delays delivery.
Make the Implicit Explicit
Knowledge that exists only in developers' heads — naming conventions, architectural constraints, domain rules, decision rationale — should be captured in explicit, inspectable artifacts.
This is the foundational principle of IFD. Implicit knowledge is fragile: it leaves when people leave, it cannot be consumed by AI tools, and it cannot be reviewed or challenged. Making knowledge explicit through documentation, DDDs, and Skills transforms it from tribal memory into organizational infrastructure.
Standing on Established Shoulders
IFD does not invent new principles. It applies proven thinking to a specific modern problem: the gap between AI capability and organizational intent.
These principles are not new. Dijkstra articulated separation of concerns in the 1970s. Evans formalized bounded contexts in 2003. What IFD adds is a structured practice for applying them in the context of AI-assisted development — where the cost of implicit knowledge has never been higher. AI tools amplify what they are given. Given tribal memory, they amplify inconsistency. Given documented intent, they amplify coherence.
See these principles applied in practice.
Explore the methodology →