Principles Library

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 that no one can diagnose.

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.

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 (explanations, DDDs, Skills) is itself the design activity. Code is the output of documented intent, not the source from which documentation is derived.

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. Design sessions begin at the appropriate altitude and descend through increasing detail. 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.

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 precisely to make these implicit conventions explicit, ensuring AI-generated code follows the team's actual standards rather than inventing its own.

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 perfect documentation corpus that delays delivery by months provides less value than a pragmatic one that ships with the product and evolves alongside it.

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.

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 and convention design. 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.

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 that notes "this is a two-way door" signals that the team can change course with low cost. A DDD that notes "this is a one-way door" signals that the decision warrants deeper analysis and broader review before commitment.

Each module or component should address a single concern — a distinct aspect of the system's functionality or behavior. Mixing concerns in one component makes the component harder to understand, test, and modify.

In IFD, separation of concerns operates at multiple levels: documentation types are separated by Diataxis (tutorials vs. reference vs. explanations), design decisions are separated from implementations, and Skills separate practice-level conventions from project-level conventions. This structural discipline ensures that each artifact has a single, clear purpose.

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. The CLAUDE.md file serves as a single entry point that indexes all authoritative sources.

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. Document decisions you are making now. Do not create speculative architectural documentation for systems you might build someday. The methodology grows with the project, not ahead of it.