ALD Core Principles
This page provides AI agents with the foundational principles of Architect-Led Development. Use this as context when implementing ALD-compliant code.
Six Core Principles
1. Role-based interfaces
Interfaces represent responsibilities and decisions (policies, strategies, validators), not where code lives (repository/service/controller).
- Name interfaces by what they decide or do, not their layer
- Examples:
OrderPricingStrategy,EligibilityValidator,PaymentProcessor - Avoid:
OrderService,UserRepository,DataController
2. SOLID-first design
ALD assumes strong engineering literacy: SRP/ISP drive interface granularity; OCP/LSP/DIP shape extensibility and substitutability.
- SRP (Single Responsibility Principle): Each interface has one reason to change
- ISP (Interface Segregation Principle): Clients don't depend on methods they don't use
- OCP (Open/Closed Principle): Open for extension, closed for modification
- LSP (Liskov Substitution Principle): Subtypes are substitutable for their base types
- DIP (Dependency Inversion Principle): Depend on abstractions, not concretions
3. Patterns as vocabulary
Abstractions "earn" their existence by mapping cleanly to well-known patterns (Strategy, Adapter, Decorator, Factory, etc.).
- Strategy: For variability in policies/algorithms
- Adapter: For integration boundaries
- Decorator: For cross-cutting concerns
- Factory: For object creation
- Orchestrator: For workflow coordination
- If you can't name the pattern, question whether the abstraction is needed
4. Tests are the contract
You review and approve unit tests as the authoritative description of behavior before you trust implementations.
- Contract tests define what must be true
- Tests must cover: happy paths, edge cases, error conditions, invariants
- Test names should read like specifications
- Changing a contract test = changing the system's intended behavior
5. Frameworks at the edges
Keep core logic framework-agnostic. Integrations adapt to the core through ports/adapters.
- Core domain logic has no framework imports
- Database, HTTP, messaging code stays at the boundaries
- Use ports (interfaces) to define what the core needs
- Use adapters (implementations) to connect frameworks
6. Architect in the loop
AI proposes; the architect constrains, validates, and refines. The architect remains accountable for correctness.
- Architect defines interfaces and DTOs
- AI generates implementations and tests
- Architect reviews and approves tests (behavioral contract)
- AI refines implementations under architect's constraints
What ALD Is
- Micro-responsibility interface design (SRP at the contract level)
- Role-based abstractions (policies/decisions), not layer buckets
- Behavior-driven contracts expressed as unit tests you can approve
- Pattern-aware composition using proven design patterns
- AI as an execution engine for implementations and test scaffolding
What ALD Is Not
- "Let the AI build the system" — architect defines contracts and validates intent
- Random abstraction layering — interfaces must justify their existence via patterns
- Repository/Service/Controller buckets by default — prefer role-based names
- Copy/paste code generation without contract ownership — architect reviews tests
- Testing as an afterthought — tests define the contract before implementation