Complexity Budget
Checks whether a change is more complicated than the problem needs.
What it does
It looks at how much complexity a plan, PR or diff adds and compares that with what the requirement needs. It counts new layers, dependencies, config, state and ways things can fail, then suggests the simplest design that still meets the requirement.
Why it's useful
Every abstraction is something the next person has to learn, and every dependency or new service has to be updated and looked after. Agents add these easily because they're quick to write.
It doesn't count lines. It picks a small, moderate or substantial budget based on the risk and expected lifetime of the problem, then checks the change against that. Anything needed for security, correctness or reliability stays, and everything else needs a reason.
Use it alongside Scope Creep Detector, which checks whether something was asked for at all. This one checks whether it was built bigger than it needed to be.
How it rates each addition
- Essential
- Needed to meet the requirement or keep things correct and secure.
- Justified investment
- Not strictly needed today, with real evidence it pays off soon.
- Questionable
- The benefit is speculative, or the cost isn't explained.
- Excessive
- Clearly out of proportion to the problem.
Audit mode (default)
It only reads and reports. It doesn't edit or revert anything, so what happens next is up to you.
Strict mode (ask for it)
The agent stops and asks you before doing anything the skill would flag. This is an instruction to the agent rather than something enforced, so it depends on the agent following it.
What a report looks like
illustrative example
Mode: Audit · Scope: PR #142, notification preferences
Budget: Small. One settings page, one table, low traffic.
Verdict: Over budget
Findings
Excessive · new queue + worker service
Saving a preference is one write. The queue adds a deploy,
retries and a new way to fail.
Fix: write straight to the table in the request handler.
Justified investment · input validation schema
Keeps bad data out of the database. Keep it.
Smallest version that works: one table, one endpoint, existing form.
Not checked: load tests, production traffic.Install
The skill is a folder with a SKILL.md in it, following the Agent Skills format. There's nothing to build or run, and it doesn't need an API key.
01Claude Code
Clone it into your personal skills folder to use it in every project.
$ git clone https://github.com/ritenv/complexity-budget ~/.claude/skills/complexity-budgetTo use it in a single repo, clone it into
.claude/skills/complexity-budgetat the project root instead. If you commit that folder, everyone working on the repo gets the skill.02Claude apps
Zip the folder and upload it as a custom skill from Settings in claude.ai or the desktop app.
$ git clone https://github.com/ritenv/complexity-budget && zip -r complexity-budget.zip complexity-budget -x "*.git*"03Codex, Cursor and other agents
If your agent supports Agent Skills, drop the folder into its skills directory. If it doesn't, paste the contents of
SKILL.mdinto your project instructions (AGENTS.md, a rules file, or a system prompt) and the agent can follow it from there.
What's in the folder
- complexity-budget/
- SKILL.md
- README.md
- references/classification-guide.md
- templates/complexity-audit.md
Example prompts
Agents can pick the skill up on their own when a task matches its description, but naming it in your prompt is more reliable.
- Use Complexity Budget to audit this implementation plan.
- Review this Git diff for unnecessary abstractions and operational complexity.
- Use Complexity Budget in strict mode before implementing this feature.