Adoption Guide
The layers are incremental. Adopt them in order, one at a time.
Layer 0 - Code
Establish coding standards. Not documentation
about coding, but enforceable rules: naming
conventions, project structure, error handling
patterns. make build or equivalent enforces
style and structure. No warnings, no exceptions.
Layer 1 - Observability
Add distributed tracing. OpenTelemetry + whatever backend fits your stack (Aspire for .NET, Jaeger, Grafana). Every HTTP request should produce a trace with spans for DB queries, external calls, and message handlers.
Layer 2 - Documentation
Write three short documents: Problem (what you are solving), Vision (what success looks like), Scope (what is in and what is out). Keep them brief. AI loads these into context.
Layer 3 - AI Instructions
Create instruction files that load automatically
when AI works with specific file types. In VS
Code: .instructions.md files with applyTo
patterns. In Claude Code: CLAUDE.md. In Cursor:
.cursorrules.
Layer 4 - Callable Surface
Expose the system through a callable surface that AI agents can invoke: MCP server, REST API, gRPC, or CLI. An AI agent should be able to perform any user-facing action without touching internal code.
Layer 5 - Journey Verification
Design a journey, walk the system through the callable surface, analyze the trace, evaluate against human-defined criteria. Fix violations. Re-walk until zero violations remain.
How long does this take?
Layers 0-2: you may already have these. If not, a day each.
Layer 3: an hour to create initial instruction files. Refine over the first week.
Layer 4: depends on your system. If you already have a REST API, you are done. An MCP server takes a few days.
Layer 5: first journey takes an hour to design, minutes to walk, an hour to fix findings. After that, each new journey takes less time.