Skill: code-quality

Purpose

Keep code cohesive, explicit, maintainable, testable, and appropriately small.

This skill encodes SOLID, KISS, DRY, YAGNI, cohesion, coupling, and size discipline as practical rules rather than motivational office posters.

Single Responsibility at Every Level

Function

A function should do one coherent thing.

A function is suspicious when it:

• validates input;
• performs I/O;
• applies domain rules;
• mutates persistence;
• formats output;
• logs business events;
• handles retries;

all in one place.

Split by responsibility, not by arbitrary line count.

Class / Type

A class/type should represent one role:

• domain state;
• lifecycle;
• policy;
• adapter;
• interface implementation;
• dependency grouping;
• stateful workflow.

Avoid god objects, vague managers, and classes that are just bags of unrelated methods.

File / Module

A file/module should have one cohesive theme.

A file is suspicious when it contains:

• unrelated domain concepts;
• mixed layers;
• many independent public entry points;
• repeated section headers needed to understand it;
• several classes that change for unrelated reasons.

Do not create a utils, helpers, common, or misc dumping ground unless the repository already has that convention and the new code still has a cohesive purpose.

Package / Component

A package/component should expose a clear public boundary.

It should not be a directory-shaped junk drawer.

Prefer package boundaries around:

• domain subareas;
• application use cases;
• infrastructure adapters;
• integration clients;
• UI/presentation areas;
• hardware responsibilities.

Layer

A layer should have one architectural responsibility.

Do not mix transport, domain, persistence, configuration, and presentation concerns.

Bounded Context

A bounded context should own one domain language and one model of reality.

Do not leak terms and invariants across contexts accidentally.

Size Limits

Human-authored 10k-line files are forbidden.

Default thresholds for human-authored source:

• function over 60 logical lines: suspicious;
• function over 100 logical lines: split or justify;
• class/type over 300 logical lines: suspicious;
• class/type over 500 logical lines: split or justify;
• file/module over 800 logical lines: split or justify;
• file/module over 1,500 logical lines: strong refactor candidate;
• file/module over 10,000 logical lines: unacceptable except generated/vendor/lock content.

Generated, vendored, lock, and machine-produced migration files may be exceptions.

If a large file is unavoidable, document why and isolate growth behind clear sections or generated boundaries. Better yet, do not make it unavoidable. Humanity has suffered enough.

KISS

Prefer simple, direct solutions.

Avoid:

• abstraction before evidence;
• clever generic code for one caller;
• framework-shaped code without a framework-sized problem;
• dynamic behavior that hides control flow;
• configuration-driven everything.

A 100-line TODO app should still be clean, typed, and testable. It does not need a fake enterprise architecture ceremony.

DRY

Avoid duplication of knowledge, not merely duplicated text.

Duplication is acceptable when:

• abstractions would hide important differences;
• two things are currently similar but likely to evolve separately;
• local clarity matters more than premature reuse.

Refactor duplication when it represents the same domain rule, validation rule, policy, protocol behavior, or integration contract.

SOLID as Practical Rules

• Keep units cohesive.
• Keep dependencies explicit.
• Prefer composition over unnecessary inheritance.
• Separate policies from mechanisms.
• Make extension possible without modifying unrelated behavior.
• Depend on stable abstractions when the architecture justifies them.
• Do not create abstractions with only imaginary future users.

Naming

Names should communicate domain meaning.

Prefer:

• create_user
• sync_device_state
• temperature_sensor
• retry_policy
• command_handler
• payment_authorization

Avoid vague names:

• do_stuff
• process_data
• handle_thing
• manager
• helper
• utils
• temp
• obj

Generic names are acceptable only when the scope is tiny and obvious.

Comments

Comments should explain why, not repeat what the code says.

Good comments explain:

• non-obvious constraints;
• protocol quirks;
• business rules;
• compatibility requirements;
• hardware behavior;
• security decisions.

Bad comments narrate obvious code.

Structural Search And Mechanical Changes

Use parser-aware tooling when the task depends on code structure rather than raw text:

• ast-grep for syntax-aware search, linting, and mechanical rewrites;
• tree-sitter or tree-sitter-backed tooling when grammar-level inspection is needed;
• rg for broad text search and fd for file discovery before slower alternatives.

Do not use broad regex rewrites for syntax-sensitive changes when a structural tool is available and practical.

Prohibited Quality Failures

• god files;
• god objects;
• hidden mutable globals;
• mystery side effects;
• fake TODO implementations;
• broad catch-and-ignore error handling;
• unrelated refactors during bug fixes;
• dependency additions for trivial code;
• public API changes without explicit intent.

Extended References

For deeper quality work, read the relevant documents:

• ../../engineering/06_responsibility_model.md
• ../../engineering/07_complexity_budget.md
• ../../engineering/08_engineering_smells.md
• ../../engineering/10_antipattern_catalog.md
• ../../engineering/12_naming_bible.md