clean-code

Installation
SKILL.md

Clean Code

Write code a senior engineer would merge without comment. The enemy is slop: code that works, passes a glance, and still degrades the codebase (narration comments, dead branches, one-call helpers, defensive paranoia, copy-pasted blocks, abstractions for futures that never arrive, tests that cannot fail). Slop is complexity added at machine speed.

Three ideas govern everything below. Every line earns its place: a line stays when deleting it would lose behaviour or information. Match the codebase, then these defaults: mirror the surrounding comment density, naming, idiom, and structure; a repo's CODING_STANDARDS.md (or CONTRIBUTING.md, CLAUDE.md, AGENTS.md) overrides this skill. Evidence over confidence: the burden of proof is on the author; a change ships with the command that proves it, the test that went red before it, and a plain statement of what was not verified.

The loop

Sized to the change: seconds for a one-line fix, deliberate for a feature.

  1. Understand. Read the code and its callers; reuse the existing pattern. Name the seam (the interface the change lives behind) and the check that proves it. For a library outside the standard library, read its current docs or types; recalled APIs go stale. When two readings of the request lead to different code, present both with a recommendation and ask. Done when one sentence says what changes, where, and how it is verified.
  2. Shape. The smallest change that fully solves the request, behind the smallest interface that hides it. Sketch a second, radically different shape for any non-trivial interface. Naive and obviously correct first; optimize only against a measurement.
  3. Write. Apply the gates and rules below.
  4. Verify. Typecheck, focused tests, lint, then the full suite once. Close the loop with real execution where it applies (the program, the request, the browser). Read the output. "Tests pass" means they ran in this session with zero failures.
  5. Interrogate. What is unnecessary, over-complicated, or resting on a weak assumption? What can be deleted entirely, and what simplifies once it is gone? Prefer deleting over simplifying, simplifying over optimizing, optimizing over automating. Make the cuts; if it is already right, leave it alone.
  6. Report. End with the block in Report.

Hard gates

Installs
5
GitHub Stars
1
First Seen
Sep 29, 2026