Clean Code

Code is for people to read, modify, and delete. Run four checks: design, naming, complexity, comments. Each has a concrete bar, not a vibe.

Route to sub-skill

For a behavior-preserving refactor within a function, class, or file, read refactoring/SKILL.md. It supplies the smell catalog, technique selector, and guardrails. Do not use it for behavior changes (tcrdd) or cross-file dependency untangling (mikado-method).

1. Design for a human-sized mental model

Prefer the concrete solution until the same need has appeared independently at least three times. An abstraction is cheap to write and expensive for every later reader to learn and trace. A hypothetical future need is not a reason to add one.

Fix defects at their cause, not with another special-case branch around the symptom. A good fix should reduce paths through the code or repair the shared rule that created the problem.

Chunks are containment boundaries — repository → service → module → function — that let a reader ignore what is outside the task. Keep each chunk coherent enough to understand locally. Slices cross those boundaries: observability, recoverability, accessibility, security, and similar concerns. Make their path through the affected chunks easy to find and follow; do not hide a cross-cutting concern just to make one chunk look tidy.