ARCHITECTURE.md Generator

Generate high-quality ARCHITECTURE.md files that give newcomers a mental map of a codebase. Based on matklad's article: the biggest contributor bottleneck is not writing code, it's figuring out where to change it. ARCHITECTURE.md bridges that gap.

Core Principles

1. Short and stable -- Only describe things unlikely to change frequently. Don't synchronize with code. Revisit a couple of times a year.
2. Bird's eye first -- Start with the problem being solved, not the solution.
3. Codemap over prose -- Answer "where's the thing that does X?" and "what does this thing do?" for every module.
4. Name, don't link -- Name important files, modules, types. Don't hyperlink (links go stale). Encourage symbol search.
5. Invariants are gold -- Explicitly call out what's deliberately absent. Important invariants are often expressed as absence, and are impossible to divine from reading code.
6. Mark boundaries -- API boundaries between layers constrain all possible implementations behind them. Finding a boundary by randomly reading code is hard.
7. Cross-cutting concerns last -- After the codemap, address things that are everywhere and nowhere (error handling, testing, config).

Workflow

Step 1: Explore the Codebase