Cairn: Git-Native Architecture Enforcement for Agent-Driven Development
Hook
What if your architecture documentation could fail CI the same way broken tests do? Cairn treats your blueprint files like Kubernetes manifests—declaring desired state, continuously reconciling against reality, and rejecting changes that violate contracts.
Context
Every developer has seen the pattern: someone writes a beautiful ARCHITECTURE.md explaining module boundaries and dependency rules, commits it alongside the code, and within three months it's fiction. Functions that should be private leak across boundaries. Modules that were supposed to be independent grow circular dependencies. The documentation says one thing; grep tells a different story.
The traditional solution is architectural linters—tools that parse your code and yell when you violate rules. But these operate backwards: they derive understanding from code that's already written, then complain about what they find. They can't tell you what should exist but doesn't. They can't model decisions that aren't expressed in code structure. And critically for 2025's development reality, they can't give AI coding agents a persistent, queryable memory of architectural intent that survives across chat sessions. Cairn inverts this: you declare architecture as versioned data, the system extracts reality from source files using tree-sitter parsers, and a reconciliation loop surfaces the delta. It's infrastructure-as-code for your codebase structure.
Technical Insight
Cairn's core abstraction is the blueprint file—a YAML declaration of modules, interfaces, and dependencies that lives in cairn.blueprint at your repo root. Here's what a minimal blueprint looks like:
modules:
- id: auth_service
path: src/auth/
type: service
interfaces:
- name: UserAuth
public_symbols:
- authenticate_user
- verify_token
dependencies:
- database_client
- id: database_client
path: src/db/
type: library
interfaces:
- name: QueryExecutor
public_symbols:
- execute_query
- begin_transaction
When you run cairn reconcile, tree-sitter parsers scan your actual Rust/TypeScript/Python/Go code and extract public functions, classes, and types from the paths you declared. The system computes a hash of each interface's public surface and compares it against what the blueprint expects. If src/auth/ exports a function called get_admin_privileges that isn't in the UserAuth interface declaration, reconciliation marks it as drift. If the blueprint declares verify_token but the code doesn't export it, that's drift too.
The genius is what happens next: drift gets classified into three states that mirror Kubernetes object lifecycle. Synced nodes exist in both blueprint and code with matching interfaces. Ghost nodes are declared in the blueprint but don't exist in code yet—think of them as TODO modules that agents should build toward. Orphaned nodes exist in code but aren't declared—legacy files awaiting triage or accidental architectural violations.
This state gets persisted to .cairn/snapshots/ as deterministic JSON with interface hashes:
{
"modules": [
{
"id": "auth_service",
"reconciliation_state": "synced",
"interface_hash": "a3f8e9c2d1b4f7e6",
"extracted_symbols": ["authenticate_user", "verify_token"],
"declared_symbols": ["authenticate_user", "verify_token"]
}
],
"timestamp": "2025-01-15T10:30:00Z"
}
You commit these snapshots. When a teammate changes src/auth/ to add a new public function, the next reconciliation detects the interface hash mismatch and marks it as drift. This is where the admission webhook pattern enters: Cairn's change proposal system lets you write structured deltas to meta/changes/ that declare why you're modifying the architecture.
# meta/changes/002-add-session-refresh.yaml
type: interface_extension
target_module: auth_service
proposed_changes:
add_symbols:
- refresh_session
rationale: "Support long-lived sessions per SEC-2025-03 security requirement"
informed_by:
- decision: DEC-001-stateless-auth
relationship: extends
Running cairn validate-change meta/changes/002-add-session-refresh.yaml checks whether this violates any existing architectural decisions or contract constraints. If DEC-001-stateless-auth recorded a decision that "all auth tokens must be stateless JWTs with no server-side session storage," and this change contradicts that, validation fails with a blocking finding. You have to either revise the decision or abandon the change.
The MCP (Model Context Protocol) server integration makes this queryable by Claude Code or other AI agents. An agent can run cairn query modules --format json to get the current architectural graph, identify ghost nodes that need implementation, and propose changes through the validation workflow instead of directly editing code that violates contracts. The cairn gap command gives agents a structured way to say "I don't have enough information to proceed" and surface missing decisions or underspecified interfaces, preventing hallucinated requirements.
For brownfield codebases, cairn init --from-code runs tree-sitter extraction across your entire repository and generates an initial blueprint reflecting actual structure. You then run cairn onboard to triage orphaned files—deciding whether to formalize them as modules, mark them for deletion, or leave them as unmanaged scaffolding. This creates a practical migration path from "we have 80,000 lines of undocumented TypeScript" to "we have a verified architectural model that blocks violations."
Gotcha
The most immediate limitation is language support: only Rust, TypeScript, Python, and Go have tree-sitter extractors implemented. If your codebase includes C++, Java, C#, or any JVM/CLR language, entire portions of your architecture are invisible to Cairn. There's no graceful degradation—unsupported files just become permanently orphaned nodes you have to manually track.
Interface hashing creates noise during legitimate evolution. Adding a single public function to a module changes its interface hash and triggers contract drift findings, even if the addition is backward-compatible and intentional. There's no semver-style tolerance where minor additions are permitted but breaking changes are blocked. This means you'll generate change proposals for routine work, and teams often disable validation during rapid prototyping phases, defeating the purpose.
The local-only architecture becomes a liability for teams. If two developers independently modify cairn.blueprint in separate branches—one adding a module, another changing dependency relationships—merging creates YAML conflicts that require manual resolution. There's no collaborative editing, no conflict detection beyond git's line-based diff, and no way to see pending architectural changes from teammates before they land. The system assumes a single-threaded workflow that doesn't match how distributed teams actually operate.
Verdict
Use if: You're building greenfield projects in Rust/TypeScript/Python with AI coding assistants and find yourself constantly re-explaining architectural context across chat sessions. Cairn genuinely solves the "agent memory" problem by making architecture queryable as structured data. It's particularly valuable for solo developers or two-person teams where coordination overhead is low and the discipline of declaring-before-building prevents spaghetti. If you already maintain detailed architecture docs that inevitably drift, the reconciliation loop pays for itself. Skip if: You work in languages beyond the four supported ones, need enterprise collaboration features like simultaneous editing or approval workflows, or have genuinely exploratory codebases where forcing premature architectural boundaries causes more harm than ad-hoc evolution. This is infrastructure for a workflow—agent-driven development with persistent context—that's still emerging. The engineering is solid and the Kubernetes analogy is legitimate, but you're betting on how AI coding evolves, not adopting proven tooling for current practices.