architecture-md-writer

ARCHITECTURE.md Writer

ARCHITECTURE.md tells an agent what it cannot work out by reading the code: where the boundaries sit, which rules must hold, how the main flows cross modules, why a choice was made, and which places move together for a given change. An agent reads it before it changes structure, then goes back to the code. This skill writes it, updates it, or audits an existing one.

Scope: one file (or the split files the size rule names), plus one pointer line in the rules file. It does not edit code, README or CHANGELOG, and it does not write the project's why and scope (the project-md-writer skill), its commands and conventions (write AGENTS.md by hand) or how a UI looks (the design-md-writer skill, which owns DESIGN.md). Report adjacent problems instead of fixing them.

Why the file is thin

Three sources decide the shape, and the first two argue against the file most people picture.

• Agents read the repository themselves. Anthropic's Claude Code best-practices page lists "describe your architecture and file layout" in the rules file as advice that is gone, and its memory page says the cleanup check cuts "directory layouts, dependency lists, and architecture overviews" while keeping "pitfalls, rationale, and conventions that differ from tool defaults".
• A 2026 study of context files (arXiv 2602.11988) found that they did not generally raise task success, added over 20 percent inference cost, and that repository overviews were not helpful. Files written by a model did worse than files written by developers.
• matklad's essay and rust-analyzer's document show what survives: a short codemap of the modules whose boundaries are not obvious, invariants (many of them absences), and the cross-cutting rules.

So the file records only what code and git history do not show, and every line is checked against the code. A model writes this file, which is the case the study measured as weakest: take facts from files you opened or from the user, never from inference.