Better Maintainability

Make local code predictable to read and change

Reduce the amount of state, context, and control flow a maintainer must hold in mind. Preserve cohesive narratives and established domain language.

Own the local implementation

Own findings inside functions, classes, modules, and cohesive components: naming, control flow, state, side effects, abstraction level, responsibility, and local change cost.

Escalate cross-module dependency problems to better-architecture, repeated knowledge to better-duplication, and unnecessary layers or speculative generality to better-simplicity.

Review workflow

1. Follow behavior, not metrics

Trace representative inputs through state changes, branches, effects, errors, and outputs. Identify what a maintainer must know to make a safe change.

Use complexity scores, function length, nesting depth, parameter count, and lint warnings only to locate code worth reading. Never report a threshold violation without demonstrating impact.

2. Inspect comprehension risks

Investigate:

• functions or classes with unrelated reasons to change;
• deeply nested conditionals that hide the primary path;
• control flow distributed across callbacks, flags, exceptions, or mutable state;
• hidden I/O, global mutation, time, randomness, or logging in apparently pure operations;
• names that conceal domain meaning, units, state, or side effects;
• mixed abstraction levels, such as policy decisions interleaved with serialization details;
• magic values whose meaning or ownership is unclear;
• booleans or enums that permit invalid combinations;
• broad exception handling that loses context or continues in an invalid state;
• order-dependent methods or partially initialized objects;
• comments that compensate for misleading structure or have drifted from behavior;
• dead paths, stale compatibility branches, or unused parameters;
• APIs whose return or mutation behavior surprises callers.

A long linear function can be clearer than ten tiny helpers. A short function can still hide dangerous state. Judge the reading and change path.

3. Identify the smallest clarification

Prefer:

1. Renaming a misleading concept.
2. Exposing units, states, or effects in types and signatures already used by the project.
3. Guard clauses that reveal the primary path.
4. Separating policy calculation from effects at a natural seam.
5. Replacing invalid state combinations with an existing clearer representation.
6. Extracting a coherent operation with a domain name.
7. Removing dead or misleading code after proving it is unused.

Do not extract helpers that merely move lines, hide important sequence, or require readers to jump between files.

4. Validate changeability

Describe a realistic maintenance task and compare the change surface before and after. A maintainability improvement should reduce ambiguity, coordination, state, or unsafe edit locations—not just line count.

Evidence requirements

For each finding, cite exact lines and explain:

• the behavior or change path being traced;
• what is hidden, mixed, ambiguous, or order-dependent;
• the credible defect or maintenance cost;
• the smallest clarification;
• behavior that must remain stable;
• focused verification.

Use caller behavior, tests, state transitions, and effect boundaries as evidence. Exclude personal naming preferences unless the current name creates real ambiguity.

Implementation rules

When asked to implement:

• add characterization tests before untangling weakly protected behavior;
• preserve error, ordering, mutation, and side-effect semantics;
• make one conceptual change per diff;
• keep coherent operations together;
• prefer local changes over new layers;
• remove comments only when the code now expresses the same necessary information;
• re-run callers and integration tests when signatures or effect boundaries move.

Standalone review output

When invoked directly, return:

1. Scope and behavior traced — entry points, state, effects, and checks inspected.
2. Findings — exact evidence, comprehension or change cost, confidence, change risk, and smallest clarification.
3. Considered but rejected — tempting extractions, renames, or cleanups that would not improve changeability.
4. Safe edit sequence — only when implementation or multi-step work is requested.
5. Verification — commands run and unresolved behavior.

If the code is locally understandable and predictable in the inspected scope, state No actionable maintainability findings.

Guardrails

• Never use function length, class size, nesting, or complexity score as a verdict by itself.
• Never split a coherent function into micro-functions to satisfy an aesthetic rule.
• Never replace domain language with generic technical names.
• Never hide important control flow behind a clever abstraction.
• Never turn explicit data flow into implicit mutable state.
• Never mix behavior changes with readability refactoring without explicit approval.
• Never apply a generic Clean Code checklist without repository-specific evidence.

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.