MIT licensed · Open source · v1

Living Architecture

Depth-scaled architecture.md template for AI coding agents.

Living Architecture is a depth-scaled architecture.md template for AI coding agents. It gives Claude Code, Gemini CLI, Cursor, and similar tools full project context from the first second of every session. Three depth levels (L1, L2, L3) scale from 50-file static sites to 1200-file monorepos.

Get the template Read the methodology

The gap

README.md serves users. CLAUDE.md and AGENTS.md instruct agents. ADRs record decisions. None of them describe the project's actual structure.

architecture.md fills that gap: a single document covering module map, data flow, route and API structure, data model, security, constraints, known tech debt, and code hotspots.

Agents that have architecture.md in context stop guessing. They read the file, then act.

Three depth levels

Depth is chosen per section based on project size. A small static site might write every section at L1; a large monorepo writes most sections at L3 and a few at L2.

Level Project size File count Doc length Style
L1 Small under 30 ~180 lines Flat tables, one-line descriptions, single diagrams
L2 Medium 30 to 200 ~450 lines Layer grouping, per-flow diagrams, column details
L3 Large over 200 500+ lines File-level detail, edge cases, metrics, query patterns

See the Depth Guide for per-section examples at each level.

Inside the template

Ten core sections every project writes; eleven optional modules included only when relevant.

Core (10)

  1. Stack & Dependencies
  2. Module Map
  3. Data Flow
  4. Route / API Structure
  5. Data Model
  6. Configuration & Environment
  7. Security
  8. Constraints & Trade-offs
  9. Known Tech Debt
  10. Code Hotspots

Optional (11)

  1. Monorepo Structure
  2. Background Jobs
  3. i18n
  4. Membership / Access Control
  5. Webhook Processing
  6. Caching Strategy
  7. Search
  8. Content Collections
  9. Design System
  10. Infrastructure Topology
  11. Dependency Graph

Three real examples

The template was applied to three projects of different sizes before publication. Each example file is in the repo.

L1

Small static site

Astro restaurant site on Cloudflare Pages.

~50 files · ~180 lines

 L2

Medium membership

Next.js + Stripe + Neon, three-tier courses.

~180 files · ~450 lines

 L3

Large monorepo

pnpm monorepo, NestJS + Kafka + BullMQ + AWS.

~1200 files · ~500 lines

How it stays current

A "living template" claim is only credible if the document keeps up with the code. Three integration points:

  1. On change. When you add a new dependency, route, or table, update the relevant section. Roughly two minutes per change.
  2. PR check (planned, v2). A GitHub Action maps changed files to architecture.md sections and posts an advisory comment on pull requests.
  3. Daily review integration. Tools like daily-code-review take architecture.md as input and feed Tech Debt and Hotspots findings back into the file. Closes the loop.

Built on research

The template did not start from a blank page. Eleven approaches were surveyed first: Codified Context, the AGENTS.md ecosystem, the C4 Model with Mermaid, Repomix and Tree-sitter, ADRs, Spec-Driven Development, Google Code Wiki, progressive disclosure, and others. Consensus across sources: "what" is auto-generated, "why" is human-written. Living Architecture commits to that split.

Read the comparative analysis.

Read the project story

The announcement post covers why the project exists, how it was derived from three real codebases, and where it sits relative to README, CLAUDE.md, and ADRs.

Read the announcement.

FAQ

How do I add architecture.md to my project?

Clone the template repo or copy TEMPLATE.md into your project as architecture.md. Fill section by section, starting with Stack and Module Map. Use the Depth Guide to decide L1, L2, or L3 per section.

Do I need this if I already have CLAUDE.md or AGENTS.md?

Yes. CLAUDE.md and AGENTS.md describe rules ("don't use barrel imports", "run tests this way"). architecture.md describes structure (which module is where, how data flows, why this design). Different jobs. They complement; they don't replace each other.

Which depth level should I start with?

Count source files. Under 30, use L1. 30 to 200, use L2. Over 200, use L3. You can mix levels per section. A small site can still use L3 for a single complex subsystem.

Is this tied to Claude Code?

No. The template is tool-agnostic. It works with Cursor, Gemini CLI, Cline, Aider, or any agent that reads files in the repo. Reference it from CLAUDE.md, AGENTS.md, .cursorrules, or your tool's equivalent.

How do I keep it current?

Three options: update on change (two minutes per edit), wait for the v2 GitHub Action that posts PR advisories, or feed the file to a daily code review tool that closes the loop. See the "How it stays current" section above.