archdrift

Architecture contract for AI coding agents. A curated ARCHITECTURE.md that agents read, humans edit, and CI enforces — so your architecture docs never rot.

The problem

Tools like Repomix and CodeGraph are descriptive: they read your code and tell agents what exists. But no tool captures what your architecture is supposed to be — the intent behind it. So agents guess, ARCHITECTURE.md files rot within weeks, and nobody notices until an agent (or a new dev) builds on top of stale assumptions.

The idea

archdrift makes your ARCHITECTURE.md normative:

1. Generated map — folder tree, detected stack, responsibilities table. Curated for token efficiency: code files listed, assets collapsed.
2. Human curation that survives — edit any description in the responsibilities table, add ADRs and notes anywhere outside the managed sections. Regeneration never destroys your edits.
3. Drift detection in CI — archdrift check exits 1 when reality diverges from the documented contract. The doc can't rot, because rot breaks the build.

┌─────────────┐   generate    ┌─────────────────┐   read    ┌────────────┐
│  Filesystem │ ────────────▶ │ ARCHITECTURE.md │ ────────▶ │  AI agent  │
└─────────────┘               │  (you curate)   │           └────────────┘
       ▲                      └─────────────────┘
       │                               │ check (CI)
       └───────── drift? exit 1 ◀──────┘

Quick start

uvx archdrift .          # or: pipx run archdrift .

This generates ARCHITECTURE.md (the contract) and structure.json (the graph, for tooling). Folders without a known role get marked _(preencher)_ — fill them in, they're preserved forever.

Then enforce it in CI:

# .github/workflows/ci.yml
- name: Architecture drift check
  run: uvx archdrift check .

Now every PR that adds an undocumented folder, deletes a documented one, or changes structure without regenerating the map fails the build until someone updates the contract.

How merging works

Managed sections are delimited by markers:

<!-- map:begin tree -->
...regenerated by the tool...
<!-- map:end tree -->

## ADR-001                      ← yours, never touched

<!-- map:begin contract -->
| Folder | Responsibility |
| `src/models` | Prisma entities — NEVER import from controllers |  ← your edit, preserved
<!-- map:end contract -->

Priority for each folder's description: your edit > name-based heuristic > pending placeholder.

Why not just use a repo packer / knowledge graph?

Use both. Repomix, CodeGraph, aider's repo-map are excellent at telling agents what the code is. archdrift covers the piece they can't infer: what the architecture is meant to be — and keeps that promise honest via CI. It's dependency-cruiser energy, rethought for the agent era, in a single zero-dependency Python file.

Roadmap

• Managed sections + merge (human curation survives regeneration)
• check mode — drift detection with meaningful exit codes for CI
• Stack detection, token-efficient tree (type-aware truncation)
• AGENTS.md integration (pointer section into the emerging convention)
• Declarative rules (src/controllers must-not-import src/repositories)
• MCP server mode
• Semantic graph: declared dependencies vs. real imports — the diff is the product

Development

pip install -e ".[dev]"
pytest -v

MIT licensed. Issues and PRs welcome.