Better Architecture

Improve architecture without imposing a template

Make the system easier to change by putting responsibilities and dependencies in the right places. Judge architecture relative to the product, team, scale, runtime, and existing constraints.

Own the system-level boundary

Own findings about relationships between modules, packages, services, layers, and public contracts.

Do not own:

• local readability or control flow inside a module — better-maintainability;
• textual repetition or repeated business knowledge — better-duplication;
• unnecessary indirection in an otherwise valid boundary — better-simplicity;
• weak behavioral protection — better-testing;
• version or package health — better-dependencies.

Report a cross-domain issue once under the skill that owns its root cause.

Review workflow

1. Map the actual system

Identify entry points, deployable units, packages, internal modules, public APIs, persistence, external services, event flows, background work, and ownership boundaries. Inspect imports, calls, configuration, schemas, and tests rather than inferring architecture from folder names.

State whether the codebase is a small application, modular monolith, library, service collection, plugin, or another shape. Do not evaluate every shape against enterprise architecture.

2. Trace important change paths

Follow representative behavior end to end. Ask:

• Which modules know about which other modules?
• Where is policy decided and where are effects performed?
• Does a small business change require edits across unrelated layers?
• Do high-level rules depend directly on volatile infrastructure details?
• Are public contracts explicit and stable?
• Can a subsystem be understood and tested through a narrow surface?

Use repository history when available to support claims about files that change together. Do not require history for a finding when current dependency evidence is sufficient.

3. Inspect architectural risks

Treat these as investigation leads:

• dependency cycles or dependency direction that contradicts ownership;
• modules that expose internal storage or framework details;
• domain policy embedded in controllers, UI, persistence, or transport adapters;
• god objects or central modules that coordinate unrelated responsibilities;
• feature work scattered by technical layer rather than cohesive behavior;
• unstable shared modules that many unrelated areas depend on;
• hidden cross-module side effects or implicit global state;
• abstractions that erase domain meaning or leak every implementation detail;
• inheritance or interface hierarchies that make substitution unsafe;
• duplicate orchestration or transaction boundaries across entry points.

A large file, many imports, or a familiar pattern name is not evidence by itself. Demonstrate the harmful dependency or change consequence.

4. Test the proposed boundary

Before recommending a new module, interface, service, repository, or layer, answer:

1. What distinct responsibility or volatility does it isolate?
2. Which dependency should reverse or disappear?
3. Which callers become simpler?
4. How can the boundary be tested through behavior?
5. Why is a local function or direct dependency insufficient?

Reject the abstraction when these answers are weak.

Apply SOLID contextually

• Use single responsibility as a change-reason test, not a one-method rule.
• Use open/closed only where repeated variation is demonstrated or strategically required.
• Use substitution to protect behavioral contracts, not to justify inheritance trees.
• Split interfaces around actual client needs, not arbitrary method counts.
• Invert dependencies at volatile or policy/effect boundaries, not everywhere.

One implementation can justify an interface when it protects a real external boundary, enables deterministic testing of effects, or supports an approved migration. One implementation alone is not a reason.

Evidence requirements

For each finding, cite exact defining and affected locations and show:

• the dependency path or violated contract;
• the resulting change cost, test obstacle, correctness risk, or operational coupling;
• the smallest viable boundary correction;
• migration and compatibility risk;
• a verification method.

Prefer dependency-graph output, import paths, representative call paths, tests, and coupled-change evidence. Label inferred runtime consequences.

Implementation rules

When asked to implement:

• protect current behavior first;
• move one responsibility or dependency edge at a time;
• keep public APIs stable where possible;
• introduce compatibility adapters only with a clear removal path;
• avoid simultaneous folder rewrites, renaming campaigns, and framework changes;
• run focused tests after each dependency move.

Do not create a target architecture diagram that requires a rewrite before value appears. Produce an incremental path whose intermediate states are valid.

Standalone review output

When invoked directly, return:

1. Scope and system map — architecture shape, boundaries, and evidence inspected.
2. Findings — root cause, exact locations, impact, confidence, change risk, smallest correction, and verification.
3. Considered but rejected — plausible patterns or boundaries deliberately not introduced.
4. Migration sequence — only when findings exist or implementation is requested.
5. Verification — commands run, results, and gaps.

If no evidence crosses the finding gate, state No actionable architecture findings.

Guardrails

• Never require Clean Architecture, DDD, hexagonal architecture, microservices, or a layer count by default.
• Never call a class a god object without showing unrelated change reasons and harmful reach.
• Never replace direct, stable code with indirection solely for mockability.
• Never split a cohesive small application into services without operational evidence.
• Never confuse directory organization with runtime or dependency boundaries.
• Never recommend a broad rewrite when an edge can be corrected incrementally.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NicolasYusim
• Source: NicolasYusim/better-codebase
• License: MIT

Install and usage instructions live in the source repository linked above.