awesome-architecture-audit
Architecture Audit
Read an entire project — code, documentation, and the other files that make it buildable — and report how sound its design is, whether the docs still describe the code, whether it holds to YAGNI/KISS/SOLID, and how easily a newcomer could build it and extend it. Read-only: it produces a prioritized, scannable recommendations report and a verdict; it never edits code. Hand the report to a dev workflow to act on. Framework- and language-agnostic: it reasons about layers, contracts, and seams, not any one stack.
Read the real flow, don't guess. Every finding cites its evidence — a file:line, a command whose output you read, a grep with zero hits, a missing drift-guard. Trace the flow end to end before judging it. A file that "looks like a god-module" is a lead; confirm it by counting the distinct concerns it fuses, not its line count.
Bundled file (load on demand):
references/design-vocabulary.md— the shared words for a module's shape (module, interface, implementation, depth, seam, adapter, leverage, locality), the tests that use them (the deletion test, "the interface is the test surface", one adapter means a hypothetical seam and two mean a real one), the dependency categories that decide how a deepened module is tested, and the design-it-twice pass. Read it before writing any Track A or Track C finding, and use these words rather than inventing synonyms — sibling skills report against the same vocabulary.
Five audit tracks — run the ones in scope:
- A. Architecture & boundaries — layering, dependency direction, cohesion.
- B. Documentation fidelity — do the docs still match the code, scripts, and config?
- C. Design principles — YAGNI / KISS / SOLID, as concrete violations.
- D. Extensibility & buildability — can a newcomer build from source and add a new provider/plugin/module by the docs?
- E. Tests & guardrails — are checks at the right layer, and do they fail loudly on drift?