lean-coding-loop

A Claude Agent Skill: get premium-model outcomes on long coding tasks from a cost-efficient model — by supplying the structure externally.

The idea

Frontier "autonomous" coding models earn their price premium mostly through internal structure: they plan the whole task, hold the codebase in working memory, review their own output, and iterate before responding. That structure can be supplied from the outside instead — decompose the task into small verifiable units, hand each unit only the context it needs, verify every unit with tests, checkpoint against the written goal, and measure real cost before escalating tiers.

A cheaper model wrapped in this discipline matches premium output on most decomposable work, at a fraction of the cost — because on small, well-scoped units the capability gap between model tiers nearly disappears. This skill teaches Claude to run that loop, and includes an honest rule for the narrow case where paying for the premium model genuinely is the right call.

What's inside

lean-coding-loop/
├── SKILL.md                     # the loop: 6 phases + escalation rule + anti-patterns
├── references/
│   ├── templates.md             # goal statement w/ NON-GOALS, state note, checkpoint,
│   │                            #   written self-review, halt summary
│   ├── verification-ladder.md   # 4-rung verification fallback for codebases
│   │                            #   with no test harness
│   └── cost-log.md              # how to read the cost report; escalation decision rules
└── scripts/
    └── log_cost.py              # stdlib-only CLI: log cost-to-acceptable-output
                                 #   per task per model; per-model + head-to-head reports

The loop in one screen

1. Decompose — restate the goal (and NON-GOALS), map the blast radius, cut into small independently verifiable units, order smallest-blast-radius first.
2. Curate context — each unit sees only its relevant slice of the codebase, never the whole repo.
3. Execute — one unit at a time; adjacent discoveries become new units, not scope creep.
4. Verify — tests where possible; a proportional rung of the verification ladder where not; a fixed floor always.
5. Checkpoint — at every boundary ask "does this still match the goal?" A human reviews the diff; unsupervised runs do a written self-review and halt cleanly on drift.
6. Measure — log cost-to-acceptable-output (retries included) and escalate model tier only on evidence, never anxiety.

Escalate to a premium model only when: a task class demonstrably fails on the cheaper model (after trying a raised thinking budget and best-of-N), or the task is genuinely indivisible and must run unsupervised end-to-end. Everything else: run the loop.

Don't use it for small, well-scoped tasks — a one-function refactor or a typo fix needs no ceremony, and the skill says so itself.

Install

Claude Code

Skills are folders on disk (docs). Personal install (available in every project):

git clone https://github.com/llcortex/lean-coding-loop ~/.claude/skills/lean-coding-loop

Project install (shared with your team via the repo you're working on):

git clone https://github.com/llcortex/lean-coding-loop .claude/skills/lean-coding-loop

Update later with git pull from inside the folder.

Claude apps (claude.ai, desktop, mobile)

Download lean-coding-loop.skill from this repo's Releases and upload it as a custom skill in Claude's settings (Capabilities/Skills). The .skill file is simply a zip of this folder. Current upload steps: support.claude.com.

Claude API

Custom skills can be uploaded and used via the Skills API (they run in a sandboxed container without network access). See the Agent Skills docs.

Usage

The skill triggers automatically when a coding task matches its description — multi-file refactors, migrations, cross-cutting features, anything past ~15 minutes of manual work. You can also invoke it explicitly:

Use the lean-coding-loop skill to plan and execute this migration.

In Claude Code it's also available as /lean-coding-loop.

The cost log

The measurement half of the loop is a tiny stdlib-only CLI:

# after each substantial task
python scripts/log_cost.py add --task migrate-grpc-2 --model opus-4.8 \
    --retries 1 --tokens 140000 --accepted yes --notes "2nd pass fixed proto imports"

# when deciding whether a premium model is worth it
python scripts/log_cost.py report

The report prints a per-model summary (one-shot rate, average retries, acceptance rate, average tokens), flags escalation candidates, and shows head-to-head results for task classes run on more than one model. Decision rules for reading it: references/cost-log.md.

Origin

Built collaboratively with Claude: the loop was designed in conversation, drafted as a skill, critiqued, and patched — including a verification ladder for harness-poor legacy codebases, a self-review + halt protocol for unsupervised runs, and the cost-measurement tooling. Every design choice in SKILL.md explains why, not just what, so the model applying it can generalize rather than pattern-match.

License

MIT (see LICENSE).