A skill for AI coding agents (and the humans who review them) that keeps code at human scale — small enough, and shaped so a person can read it, hold it in their head, and debug it without giving up and saying "I guess I'll let the computer figure it out."
AI agents now write enormous amounts of code, fast. Too often it arrives as 1,200-line files and 300-line functions — technically working, but no human wants to read it. This skill is a set of parameters and judgment rules you can hand to Claude (or apply yourself) so that generated code stays legible, maintainable, and debuggable by a person.
It works at three moments: design, coding, and review.
Most "code size" advice fails because it treats a line count as a rule. It isn't. The governing law here is:
Length is a trigger to look, never a rule to obey.
When a function or file crosses a threshold, that's a signal to stop and look for a natural seam — a point where an independent, single-name-able responsibility separates cleanly. You split there and only there. If no honest seam exists, you keep the code whole and leave a one-line note saying why. You never split code just to hit a number — an artificial split is worse than one honest long function.
A 12,000-line function isn't wrong because it's 12,000 lines. It's wrong because something that big was never designed to be understood — and there are certainly seams in it waiting to be found. Conversely, a 70-line linear state machine with no clean mid-point should be left alone. The skill is the judgment to tell those apart.
Defaults live in thresholds.yml and are fully tunable per
project. Read every number as "look here," not "obey here."
| Dimension | Soft target | Stop and look | Split-or-justify |
|---|---|---|---|
| Function length (LOC) | 50 | 60 | 80+ |
| File length (LOC) | 400 | 600 | 800+ |
| Cyclomatic complexity | ≤5 | >10 | >15 |
| Nesting depth | ≤3 | 4 | 5+ |
| Function arguments | ≤4 | 5 | 6+ |
Why these numbers. They're anchored in the empirical clean-code literature — well-regarded functions cluster around ≤40–50 LOC, cyclomatic complexity ≤5, and ≤6 arguments, with complexity above 10–15 a reliable "this is now hard to follow" signal. The classic "if it doesn't fit on one screen, look at splitting it" heuristic lands at ~40–50 visible lines — which is also about a printed page. See Sources.
When a unit trips a threshold, run these tests. All must pass to justify a split — otherwise keep it whole.
- Reason-to-change — Can you name two different reasons this code would change? Each is a candidate seam.
- One-noun / one-verb — Can you name the extracted piece with a single
honest word (
parseHeader,validateAddress)? If the best you've got ishelperor needs an "and," there's no seam. - Altitude — Is high-level orchestration tangled with low-level mechanics? Lift the mechanics into named steps.
- Parameter — Would the extracted piece need 6+ args or constantly reach back into the parent's locals? Then the two halves are one responsibility.
- Dependency-cut — A good seam reduces what you must hold in your head. If both sides can only be understood together, it's shrapnel — don't cut.
See examples/split-at-a-real-seam.md and
examples/no-seam-keep-whole.md — the second
is the one that matters most: knowing when not to cut.
Clone into your skills directory so Claude can invoke it by name:
git clone https://github.com/jwmurray/human-readable-code.git \
~/.claude/skills/human-readable-codeThen, in any session:
- Design: "Plan this feature with human-readable-code — decompose by responsibility seam."
- Coding: "Write this using human-readable-code conventions."
- Review: "Review this PR with human-readable-code and report findings."
Override any parameter inline for the session:
"Review with human-readable-code, but allow 1000-line files — it's a Django models module."
You can also drop the rules into a project's CLAUDE.md, or paste
CHECKLIST.md into a code-review prompt.
| File | What it is |
|---|---|
SKILL.md |
The skill itself — the three modes and the full method. |
thresholds.yml |
Tunable parameters, with per-language overrides. |
CHECKLIST.md |
One-page quick reference for reviews. |
examples/ |
A real-seam split and a keep-it-whole case. |
- Clean Code in Practice — Challenges and Opportunities (arXiv 2025)
- Managing Code Complexity — Trimble Developer Guidelines
- Why code and cyclomatic complexity metrics mislead teams — getDX
- 5 tips for reducing cognitive complexity — Sonar
- Single Responsibility Principle — Startup House
- 7 signs to spot LLM-generated code — DEV
- What developers think about code readability in the age of LLMs — Atlassian
MIT — see LICENSE.