The Six Layers
Each layer is earned by the failure of the previous one. Adopt them in order. Skip none.
0 - Code
You start a project. AI generates code fast. But every request produces different patterns. Naming, error handling, file organization all vary.
Working code with consistent patterns. Coding standards, naming conventions, project structure, build rules that fail on violations. The foundation.
1 - Observability
Tests pass. Endpoints return 200. But nobody sees that a handler loads the same entity three times, or that an async consumer fails silently.
Development-time tracing, structured logging, and metrics. Not production monitoring. You need to see what happens when you exercise the system during development. OpenTelemetry traces become the verification oracle.
2 - Documentation
AI is generating code, but it does not understand the project’s philosophy, constraints, or domain. It adds a feature to the wrong module because nothing says where it belongs.
Architecture docs, module specs, design decisions. Brief, structured, alive. One concept per file. When the system changes, the doc is updated, not appended with history.
3 - AI Instructions
You wrote standards docs. AI read them once and forgot. Or the doc was not in context. Or the model’s training data overrode your preference.
Files that are automatically loaded when AI works with matching file types. The instruction discovers the AI, not the other way around. Architecture, conventions, quality rules, workflow. All enforceable, not advisory.
4 - Callable Surface
You have traces, but nobody checks them systematically. The system has dozens of endpoints and message handlers. Nobody has time to exercise every path.
Your product’s API: REST, gRPC, MCP, CLI. Whatever surface your clients use. AI can call it as a real user would. If AI can not complete a workflow through the surface, something is wrong: a tool is missing, a schema is wrong, or the workflow design is bad.
5 - Journey Verification
AI can call your API. But what is a correct end-to-end workflow? What should happen internally after each call?
End-to-end arcs from the user’s perspective. Write a journey, walk the system through the callable surface, analyze the distributed trace, evaluate against human-defined criteria. Binary pass/fail, no subjective scoring.
Read the full narrative → The day-by-day evolution of each layer, told through a real project.