architecture-quality

name

architecture-quality

description

Keep web applications, APIs and services readable as they grow: choose feature or domain seams, assign state ownership, enforce dependency direction, keep adapters thin, and verify file shape. Use when starting or extending a web app, backend, frontend, API or multi-page product; when a change makes a module hard to read; when architecture review finds a god file, cross-feature imports, a circular dependency or a framework-heavy domain. Load architecture-first first for a new system, and refactoring-safely for an existing oversized module. Do not use for a one-file script, throwaway spike or a purely local naming change.

Architecture quality — readable by construction

This skill turns the architecture decision into a small, repeatable delivery contract. It complements architecture-first; it does not add layers for their own sake.

Working contract

Before a non-trivial web or service change, record these five facts in ARCHITECTURE.md or docs/architecture/README.md:

1. Feature/domain modules — name them by reason to change, not by a generic utils, helpers or services bucket.
2. Ownership — each mutable state, database table boundary and external side effect has one owner.
3. Dependency direction — policy/domain code is independent of the web framework, ORM, queue and filesystem; adapters point inward through small ports.
4. Vertical slice — prove one user-visible path from entry point to state and test before multiplying layers or pages.
5. Verification boundary — list the architecture checks and the test command that must remain green after the change.

If the project is a small script or a single-module experiment, state that scope and skip the document. A missing document is a finding only once the project has enough shape to need one, not a reason to create ceremony around a toy.

Web application shape

• Keep routes/controllers thin: parse input, call a use-case or feature API, map the result and return. Do not put business policy, SQL and provider retries in a route.
• Keep domain/use-case code framework-free where practical. Inject ports for storage, clocks, queues and providers; keep concrete adapters at the edge.
• Organize user-facing behavior by feature or bounded context. A page may compose features, but one feature must not reach into another feature's private state.
• Give each page a stable route-level composition boundary. Shared UI primitives are visual primitives, not a second business-logic layer.
• Treat a utils or common import that keeps growing as a boundary question. Move code to the module that owns its reason to change; do not create a universal bag.
• Prefer a modular monolith until an independently deployable or scalable boundary is proven. A microservice split is not a substitute for a missing internal boundary.

Shape checks

Run the repository audit before broadening a new app and after a structural change:

python scripts/architecture_audit.py --root .

The audit is intentionally conservative. It reports, rather than invents, findings:

• a sizeable application with no ARCHITECTURE.md or architecture directory;
• a source file crossing the calibrated shape thresholds;
• an explicitly declared project marker without a readable architecture anchor.

The live module-shape-advisor.py hook repeats the file-shape check after Write|Edit|MultiEdit in both Codex and Claude. It is advisory: acknowledge the finding, split at an ownership boundary, or record why the file is intentionally large. CLAUDE_ALLOW_BIG_MODULES=1 is an explicit, reviewable escape hatch, not a default.

For dependency rules, use the tool native to the stack when the project has earned it:

• Python: import-linter contracts for allowed import direction;
• JavaScript/TypeScript: dependency-cruiser for cycles, orphans and forbidden folder edges;
• Java: ArchUnit architecture tests alongside unit tests;
• C/C++: compiler/include tooling plus explicit CMake target boundaries; do not infer a domain architecture from a raw include graph alone.

Do not install all four. Pick one boundary mechanism, commit its rules, and run it in the same CI lane as the tests that prove the behavior.

Review questions

• Can a new feature be changed without editing an unrelated feature's internals?
• Does a route, page or controller own policy that belongs inside a use-case/domain?
• Is state ownership named, or are modules reaching into shared mutable objects?
• Are imports crossing a documented boundary? If yes, is the exception recorded with a reason and expiry?
• Is the file becoming large because one change is crossing multiple reasons to change? If yes, split the seam before adding more behavior.
• Did the change update the architecture document and the focused architecture/test evidence together?

Gotchas

• Folders are not boundaries. Moving files without changing imports or ownership only makes the same coupling harder to see.
• Thin controllers can still hide a fat service. Inspect the next boundary; a generic ApplicationService is often a god module with a nicer name.
• A metric is a signal, not a verdict. Generated code, migrations and large declarative tables need explicit exemptions; production logic needs an explanation before an exemption.
• Microservices can multiply unreadability. Network boundaries add failure, deployment and observability costs; prove the module boundary first.

Troubleshooting

Symptom	Likely cause	Action
The audit reports a missing architecture anchor	An app marker and several source files exist, but the boundary is implicit	Write the small module/ownership/dependency map before adding more features
module-shape-advisor reports a large file	Local edits accumulated in one ownership boundary	Add characterization tests, split one named slice, then rerun the audit
A cycle appears	Two modules own part of the same concept or one imports an implementation detail	Move the concept behind an inner port or extract a genuinely shared concept
Every change touches many folders	Layer-first layout scatters a feature across technical layers	Recut the next slice by feature; migrate incrementally with tests
The guard is noisy on generated code	The file is outside the built-in exemption list	Add a narrow, documented project exemption; do not silence the whole hook