Summary: Key Architectural Principles

You've learned five foundational principles for architecting systems that enable effective AI-assisted development. Let's crystallize the key takeaways into actionable guidelines you can apply immediately.

The Five Core Principles

1. Digestibility: Fit Within Context Windows

The Principle: Design components that both humans and AI agents can fully understand without excessive file navigation or external context.

In Practice:

• Target 200-500 lines per component - Large enough to be meaningful, small enough to digest
• Self-contained units - Minimize cross-file dependencies for understanding
• Clear naming - File and function names reveal purpose at a glance
• Explicit dependencies - Document what a component needs from outside

When You Know It's Working:

• Claude Code understands your components without extensive prompting
• You can review a component in one sitting
• New team members grasp components quickly

2. Component Decomposition: Break by Business Capabilities

The Principle: Divide systems into components based on what they do (business capabilities), not implementation details.

In Practice:

• Identify natural boundaries - User management, payments, notifications are separate capabilities
• Single responsibility - Each component has one clear purpose
• Stable interfaces - Components expose well-defined contracts
• Independent evolution - Can modify one component without cascading changes

When You Know It's Working:

• Changes are localized to 1-2 components
• You can develop components in parallel
• Component purposes are obvious from names

3. Interface Boundaries: Make Contracts Explicit

The Principle: Define exact expectations for how components interact using specifications, not assumptions.

In Practice:

• Use OpenAPI for REST APIs - Explicit contracts for HTTP interfaces
• Use AsyncAPI for events - Clear schemas for event-driven communication
• Use JSON Schema for data - Precise validation rules
• Document error cases - Not just happy path, but all failure modes

When You Know It's Working:

• AI agents generate code that matches specs perfectly
• Integration bugs are rare
• New developers understand interfaces without asking questions

4. Separation of Concerns: Layer Your Architecture

The Principle: Keep different types of work in different places—don't mix HTTP handling with business logic with database access.

In Practice:

• API layer - HTTP handling, request validation, response formatting
• Domain layer - Pure business logic, free from infrastructure
• Data layer - Database queries, persistence
• Infrastructure layer - External service clients, email, queues

When You Know It's Working:

• Tests run fast (no database needed for business logic)
• Changes to infrastructure don't break business rules
• Each file has a single, clear responsibility

5. Testability: Design for Fast Feedback

The Principle: Architecture that enables fast, reliable testing of AI-generated code through isolation and dependency control.

In Practice:

• Dependency injection - Pass collaborators in, don't create them internally
• Pure functions - Deterministic logic without side effects
• Test boundaries match component boundaries - Each component independently testable
• Fast unit tests - Run in milliseconds, not seconds

When You Know It's Working:

• Test suite runs in < 10 seconds
• You can test components without databases or external services
• Refactoring doesn't break tests (they test behavior, not implementation)

The Quick Architecture Checklist

Before finalizing an architecture, verify:

Digestibility:

• Largest component is < 1,000 lines
• Can understand any component in < 30 minutes
• File organization is intuitive

Decomposition:

• Components aligned with business capabilities
• Each component has single, clear purpose
• No circular dependencies

Interfaces:

• All component contracts documented (OpenAPI, AsyncAPI, or JSDoc)
• Error cases explicitly defined
• Data schemas validated

Separation:

• Business logic is pure (no I/O)
• Layers clearly defined (API, domain, data, infrastructure)
• Infrastructure concerns at edges

Testability:

• Dependencies injected, not hard-coded
• Unit tests run in < 10 seconds
• Each component independently testable

Common Questions Answered

Q: Do I need to follow ALL five principles for every project?

A: The principles scale with project complexity. Small projects benefit from 3-4 principles (digestibility, interfaces, testability). Larger projects need all five. Start simple, add structure as needed.

Q: Isn't this over-engineering for an MVP?

A: No. These principles accelerate MVPs by making AI collaboration effective. The alternative—poorly structured code—slows you down when Claude can't understand your system.

Q: How much time should I spend on architecture vs. coding?

A: For a 6-week MVP, spend week 1 on architecture (requirements → design). Claude Code helps you implement faster, but only if the architecture is clear first.

Q: What if requirements change after I've architected?

A: Good architecture is flexible. Well-defined interfaces let you swap implementations. Separated concerns let you modify one layer without breaking others. Change is easier, not harder.

The Architecture-Velocity Relationship

Here's the key insight: Good architecture multiplies AI agent velocity. Bad architecture divides it.

With clear architecture:

• Claude Code generates correct implementations on first try
• Integration is straightforward (specs guide the way)
• Testing validates quickly (fast feedback loops)
• Changes are localized (minimal ripple effects)
• Result: 5-10x velocity gains with AI

With unclear architecture:

• Claude Code guesses at intent (often wrong)
• Integration requires manual coordination
• Testing is slow and brittle
• Changes cascade unpredictably
• Result: Velocity gains evaporate in debugging

Applying These Principles

Starting a new project:

1. Identify business capabilities → components
2. Define interfaces (OpenAPI, AsyncAPI) → contracts
3. Layer within components (API/domain/data) → separation
4. Keep components digestible (200-500 lines) → digestibility
5. Inject dependencies → testability

Refactoring existing code:

1. Start with testability (enable fast feedback)
2. Extract clear interfaces (reduce coupling)
3. Separate concerns (pure business logic)
4. Decompose large components (increase digestibility)
5. Iterate with AI assistance

Working with Claude Code:

Phase 1 - Architecture:
"Review this architecture diagram. Are components properly
sized and bounded? Are interfaces explicit?"

Phase 2 - Implementation:
"Implement UserService according to the architecture.
Use dependency injection and keep it under 500 lines."

Phase 3 - Testing:
"Generate unit tests for UserService. Mock external
dependencies (database, email service)."

What's Next

You now understand the foundational principles for architecting systems that work beautifully with AI agents. These principles enable you to move from abstract concepts to concrete systems.

In the next chapter, Digestible Interfaces (coming in Part 1, Chapter 4), we'll dive deeper into interface design—how to create APIs and contracts that serve both human developers and AI agents effectively.

Key Takeaways

Remember these five principles whenever you architect software:

1. Digestibility: Components fit in human memory and AI context windows (200-500 lines)
2. Component Decomposition: Break by business capabilities, not implementation details
3. Interface Boundaries: Make contracts explicit using OpenAPI, AsyncAPI, JSON Schema
4. Separation of Concerns: Pure business logic, infrastructure at edges, clear layers
5. Testability: Dependency injection, fast unit tests, independent components

The meta-principle: What helps humans understand and maintain code also helps AI agents work with it effectively. Design for clarity, and velocity follows.