From the free book Delta: Closing the Specification Gap (Dhuri, 2026). The PDF is the canonical edition — figures, tables, and code formatting are simplified online.
The Model Context Protocol: your codebase, database, and tools connected to AI in an afternoon
“Before MCP: you described your codebase to the AI. After MCP: the AI reads your codebase. The difference is the difference between describing a photograph and handing someone the photograph.” — MCP is not a feature. It is infrastructure. Build it once and every AI interaction in your organization improves simultaneously. Note on MCP version
MCP is evolving rapidly. The patterns in this chapter target the protocol as it stood at the time of writing. Note in particular that the 2026-07-28 specification makes MCP stateless at the protocol layer — it removed the initialize handshake and the Mcp-SessionId, moved protocol/client info into per-request _meta, and hardened authorization onto OAuth 2.1 / OpenID Connect (API-key auth is being deprecated for enterprise). Consult the current specification at modelcontextprotocol.io for breaking changes introduced after publication. Crucially, the structural recommendations in this chapter (separation of concerns, scoped access, audit logging, least privilege) are stable across every version to date; only the wire-level details change.
A development team adopted Claude Code enthusiastically. They used it for four sprints without writing a CLAUDE.md. In that time, they accumulated the following without initially realizing it: seventeen files that used field injection instead of constructor injection (their standard was constructor injection only), twenty-three methods that threw generic exceptions instead of returning Result<T> (their standard was Result<T> for business errors), and one migration that dropped a column without a tested rollback path. All of these were consistent with average enterprise Java codebase patterns. None of them were consistent with their team’s standards. The team discovered all of it during their quarterly architecture review. Remediation took four sprints. The root cause: the agent was very good at writing Java. It was not good at writing their Java, because they had not told it what their Java looked like.
THE COST OF THIS MISTAKE Incident: Claude Code without CLAUDE.md: four sprints of code ,→ violating team standards (DI pattern, error handling, migration ,→ safety)
Total cost: 4 sprints of remediation work for one developer: ~80 ,→ hours of correction and review Time to resolve: 4 sprints to identify and fix, 1 sprint to write the ,→
Prevention: "Write CLAUDE.md before running the agent. Include stack, ,→ architecture rules, and Hard Constraints section."
A note on AGENTS.md (current as of mid-2026). The CLAUDE.md files in this chapter follow Claude Code’s native convention, but the same instruction layer now has a cross-tool open standard: AGENTS.md — a plain Markdown file in the repository root, stewarded by an open foundation since late 2025 and read natively by dozens of coding agents and IDE assistants, from Claude Code and Codex to Copilot and Cursor, across tens of thousands of repositories. The pragmatic pattern many teams have settled on is AGENTS.md as the canonical instruction file, with a thin CLAUDE.md that simply references it. Everything this chapter says about constraint-bearing instruction files — name the domain types, state the invariants, declare what must never happen — applies to AGENTS.md verbatim; only the filename changes. The companion repository ships both. BEFORE — Tier 1 (What most developers type) Using Claude Code with no CLAUDE.md: "Refactor the payment module to ,→ improve error handling" AFTER — Tier 3 (Specification Frame) CLAUDE.md defines: stack (Java 21, Spring Boot 3.3), DI standard ( ,→ @RequiredArgsConstructor only), error handling standard (Result ,→ <T> for business errors), hard constraints (never modify pom. ,→ xml, never modify shared libraries, all new code needs tests) ,→ Then: "Refactor the payment module to improve error handling" Result: Without CLAUDE.md: generates changes using field injection ,→ and exception throwing. With CLAUDE.md: generates changes using ,→
constructor injection and Result<T> returns — consistent with
,→ your standards on the first attempt.
13.1 CLAUDE.md — The Project Specification File .NET 9 Project CLAUDE.md # Project: PaymentService ## Stack .NET 9 / C# 13 / Clean Architecture / MediatR 12 / EF Core 9 / ,→ NSubstitute ## Architecture Rules - Commands: IRequest<Result<T>>. Queries: IRequest<TResponse>. - Domain events: IDomainEventDispatcher AFTER SaveChangesAsync. - Money<USD> for all monetary values — never decimal directly. - Constructor injection only — never property injection. ## Hard Constraints — NEVER break these - Do NOT modify .csproj without explicit instruction. - Do NOT modify appsettings.json — use Options pattern. - CardToken must NEVER appear in log statements. - All new code needs unit tests in tests/Application.Tests. ## Where Things Live - Domain: src/Domain/ - Application: src/Application/ - Infrastructure: src/Infrastructure/ - Tests: tests/Application.Tests/ Java Project CLAUDE.md # Project: InsuranceService ## Stack Java 21 / Spring Boot 3.3 / Maven / Spring Data JPA / Flyway / JUnit ,→ 5 ## Architecture Rules - Constructor injection: @RequiredArgsConstructor. NO @Autowired ,→ fields, ever. - Result<T> for all service returns. No checked exceptions in ,→ application layer.
99
investment for enterprise AI adoption. Filesystem + GitHub + PostgreSQL eliminates most manual context-gathering effort. + CLAUDE.md is the specification file that makes coding agents safe for your codebase. Without it, the agent uses statistical defaults. With it, the agent uses your standards. + The Hard Constraints section of CLAUDE.md is non-negotiable. Agents are very good at following constraints when they are explicit. Without explicit constraints, scope creep is not a failure mode — it is the default. + Eight security controls for MCP. The two most critical: filesystem scoped to src/, read-only database user with no PHI/PCI table access. + Write CLAUDE.md before running Claude Code on your project. This is the single highest-ROI action in Part III.
Choosing the right AI tool for enterprise development is not about which model is ’best’. Chapter 14 maps the full toolchain — from agentic coding tools to evaluation frameworks — and the Organizational Maturity Model that tells you which investments to make in which order.