COMPLEX.md spec 0.1

COMPLEX.md is a markdown file at the root of a repository that tells a coding agent where the structural risk in the codebase lives. It is computed from the repository's own git history and file graph, not written from memory. The format follows the shape Google uses for DESIGN.md: YAML front matter carries the machine readable data, prose sections carry the rationale.

AGENTS.md tells an agent how to behave. CLAUDE.md tells an agent what the project is. COMPLEX.md tells an agent where it is likely to break something.

Where the file lives

Commit COMPLEX.md at the repository root, next to README.md and any agent context files. Reference it from AGENTS.md or CLAUDE.md with one line, for example: "Read COMPLEX.md before editing anything it lists as a hotspot."

The four signals

Every number in COMPLEX.md is computed locally from the repository. Spec 0.1 defines four signals.

Lines of code (loc). The line count of each tracked file, from git ls-files. Size is not risk by itself, but risk scales with it.

Churn (churn). The number of commits that touched the file in the last 12 months, from git log --name-only. Churn is the strongest single predictor of where the next change will happen.

Co-change. Pairs of files that appear together in the same commits more often than a threshold. Co-change reveals coupling the import graph cannot see: a schema and a serializer, a config and the code that assumes it.

Fan-in (fan_in). How many files import or require the file, from a plain text search of import statements. High fan-in means an edit propagates.

Hotspot score (score). Churn multiplied by lines of code, the method Adam Tornhill describes in Your Code as a Crime Scene. A hotspot is a file that is both large and frequently changed. Hotspots are where refactoring pays and where an unbriefed agent does the most damage.

Front matter

The front matter is YAML between --- fences at the top of the file. All fields are required. Numbers are copied verbatim from the analysis, never estimated. The table is capped at 15 hotspot rows and 10 co-change pairs because COMPLEX.md is selective over complete.

---
complex_md: "0.1"
generated: 2026-09-02
commit: 4f2a91c
tool: complex-md/0.1.0
window_months: 12
files_analyzed: 412
hotspots:
  - path: src/router.js
    loc: 1240
    churn: 87
    fan_in: 23
    score: 107880
  - path: src/state/store.js
    loc: 980
    churn: 64
    fan_in: 31
    score: 62720
co_change:
  - files: [src/router.js, src/routes/table.js]
    count: 31
---

Prose sections

Four sections, all required, in this order. The prose is written from the computed data plus the actual text of the top hotspot files. Total prose stays under 600 words. If a section has nothing worth saying, it says so in one sentence.

## Where the risk lives names where change risk concentrates, in three to six sentences that each stand alone when quoted.

## Why these files are hot gives one short paragraph per top hotspot, at most five: what the file does, why it keeps changing, what an edit there tends to break.

## Change coupling explains which files move together and whether the coupling is by design or by decay, so an agent updates them in tandem.

## What to read first is an ordered list of three to seven files an agent should read before editing anything hot, each with a reason.

Example section

## Where the risk lives

Risk concentrates in the request path: src/router.js and
src/state/store.js account for a third of all commits in the last year.
Both are god files that grew by accretion; neither has an owner module.
Serialization is the second cluster: schema.js and its three consumers
change together in 31 commits. The test suite covers the router shallowly,
so behavioral drift there ships silently.

Generating the file

Three ways to produce a conforming COMPLEX.md:

1. The skill. Download the complex-md skill and run it with any coding agent inside the repo. The agent computes the signals with git and writes the file using the same prompt the CLI uses.
2. The CLI. npx complex-md computes the signals locally and makes one model call to write the prose. Nothing but the top hotspot files and the signals table leaves the machine.
3. By hand. Compute the numbers with the git commands above, fill the front matter honestly, write the four sections, set tool: by-hand.

The generation prompt is a single versioned file, prompts/generate.md, shared by all three paths.

FAQ

How is this different from AGENTS.md or CLAUDE.md? Those files carry instructions and project context written by a person. COMPLEX.md carries measurements. They complement each other; COMPLEX.md is referenced from them, not a replacement for them.

How is this different from DESIGN.md? DESIGN.md records intent at design time. COMPLEX.md records reality as of a commit: where change actually concentrates. Intent and reality diverge, which is exactly what an agent needs to know.

How often should it be regenerated? When it stops matching reality. A practical rule: regenerate after any refactor of a listed hotspot, or monthly on an active repo. The commit field makes staleness visible.

Why cap the tables and the prose? Because the file is read inside an agent's context window. A COMPLEX.md that lists every file is a worse map than one that names the ten places that matter. Selective over complete; bloat is the failure mode.

Does the whole repo get sent to a model? No. The signals are computed locally by git and grep. Only the signals table and the text of the top 5 to 10 hotspot files go into the model call, capped around 15k tokens.

Can I write one for a repo I do not own? Yes. The analysis needs only a clone. The catalog publishes COMPLEX.md files for well known open source repos.