Give Your Coding Agent a Bundle Budget: Fail the Branch Before It Lands
A coding agent can add 90 kB of JavaScript to your app in a single, clean, well-formatted pull request. The diff looks innocent: one new import, a date-picker, a charting helper. Tests pass. Types check. Lint is quiet. Nothing in the review surface tells you that the initial route now takes 400ms longer to become interactive on a mid-tier phone.
This is the class of bug that agents are structurally good at producing and structurally bad at noticing. They optimize locally against the instructions they were given: make the test pass, make the component render, make the error go away. Bundle weight is a global, deferred cost — it doesn't fail anything today, so it never enters the loop. The fix is not a longer prompt reminding the agent to "be careful about performance." The fix is a budget with a hard exit code, wired so that the agent sees the failure in its own terminal before it ever opens a PR.

Figure: Editorial context image from the source page (preview only; rights remain with the publisher) · Credit / further reading: dev.to
Budgets beat review for this class of regression
Human review catches bundle regressions roughly never, for two reasons. First, kilobytes are invisible in a diff: import { format } from "date-fns" is one line whether it pulls 2 kB or 70 kB. Second, review attention is spent on logic, not on the transitive closure of the module graph. Reviewers approve the picker; they don't open the sourcemap.
An agent has the same blind spot, multiplied by volume. If you're running a fleet of agents across a monorepo, "occasionally a human notices" degrades into "nobody notices until Core Web Vitals tank or a customer complains about the mobile app."
A bundle budget converts an invisible global cost into a visible local one. That's the whole trick. size-limit (or any equivalent — bundlemon, Lighthouse CI budgets, a custom script over dist/) does three useful things at once:
- It's deterministic. Bytes don't flake the way timing assertions do.
- It's fast. A gzip measurement over a few files runs in under ten seconds, which matters enormously for agent loops.
- It fails with a number. "app shell: 184.2 kB > 180 kB limit" is feedback an agent can act on without human interpretation.
Architecture: what to budget, and at what granularity
Don't budget one opaque total. Bullet the surfaces that map to user-perceived cost, and give each its own limit so a regression points at a cause:
- Entry / app shell JS — everything on the critical path for the primary route.
- Route-level chunks — per-route ceilings catch "one heavy page became heavy" without penalizing legitimate lazy routes.
- Shared vendor chunk — where framework and polyfill drift shows up first.
- CSS — the forgotten axis; a UI library import can double your stylesheet.
- Fonts — bytes and file count, if you self-host.
{
"size-limit": [
{ "name": "app shell", "path": "dist/assets/index-*.js", "limit": "165 kB" },
{ "name": "app shell css", "path": "dist/assets/index-*.css", "limit": "38 kB" },
{ "name": "vendor", "path": "dist/assets/vendor-*.js", "limit": "120 kB" },
{ "name": "editor route", "path": "dist/assets/editor-*.js", "limit": "90 kB" }
]
}
Three configuration rules that save a lot of pain later:
Pick one compression and never mix it. Gzip, Brotli, or raw — but the same one in local, CI, and the PR comment. Agents happily "fix" a budget by flipping gzip: true to false, and you won't catch it in a 400-file diff.
Set limits from a measured baseline, not a round number. Take the current size of main, add a deliberate headroom (2–5%), round up. A budget that's already breached on day one is ignored forever.
Ratchet downward only, deliberately. Either a bot periodically proposes limit = ceil(current × 1.02) in a dedicated chore: tighten bundle budget PR, or increases require an explicit label and a table of before/after numbers in the description. The important property: the default path is refactor, not raise.
Delivery: fail the branch, not the release
The operational question is where the check runs. The answer that actually shapes agent behavior is: locally, fast, on every edit; and in CI, authoritatively, blocking the merge.
Locally, expose one command:
{
"scripts": {
"size": "npm run build && size-limit",
"size:why": "npm run build && size-limit --why"
}
}
Then put this in the file your agent reads first — AGENTS.md, CLAUDE.md, .cursor/rules, whatever your tool uses:
## Bundle budget (non-negotiable)
- Before proposing any change under `src/`, run `npm run size`.
- If a budget fails, do NOT raise the limit in `package.json` or the size-limit config.
Refactor, split the import, or lazy-load the feature.
- If a limit genuinely must move, open a separate `budget:` PR containing the
before/after table from `size-limit --json`. Never bundle a limit bump with a
feature change.
- Never change the `gzip`/`brotli` setting to satisfy a limit.
That last rule matters more than it looks. Without it, a sufficiently creative agent will discover that switching measurement configuration is the shortest path to green.
In CI, the check should compare against the merge base, not the tip of main — otherwise a stale branch passes while the combined result regresses:
- run: npm ci
- run: npm run build
- run: npx size-limit --json > size.json
- run: npx size-limit # exits non-zero on breach
Store size.json as a build artifact and post the delta as a PR comment. Agents read PR comments; giving them "app shell 158.1 kB → 184.2 kB (+26.1 kB, limit 165 kB)" closes the loop even when the run happened remotely.
One delivery detail worth stealing from test infrastructure: mirror the local/CI split by scope. Pre-push should measure only what the branch touched if your bundler supports partial builds; the full matrix runs on CI. A 90-second size command is an agent skip; a 10-second one is an agent habit.

Figure: HEXOPS original illustration inspired by the topic (not a copy of the source article imagery) · Credit / further reading: dev.to
Ops: making the signal trustworthy
A budget is only useful if the number is stable. Guard the determinism of the measurement:
- Lockfile-pinned installs (
npm ci), same Node major in local and CI. Different Node can produce different output. - Cache keyed on the lockfile hash, not on time, so a cold-cache run can't shift chunk boundaries.
- Single build path. If local
npm run buildand the CI build use different env flags (NODE_ENV, minifier, source-map settings), the local budget is a lie and agents learn to distrust it. - Track the trend. Emit
size.jsonto a time-series store or just commit it next to the budget. Threshold alerts catch cliffs; a weekly slope chart catches the 1 kB-per-PR drift that no single review will ever block.
Treat budget breaches as two distinct severities. A hard breach (over limit) blocks the merge. A soft regression (under limit but up more than, say, 5% versus baseline) posts a comment and pings the owning team. Without the soft tier, you spend months at 99% of budget and the budget stops being a signal.
Security: the budget is also an attack-surface budget
Bundle size is a surprisingly honest proxy for dependency surface, and dependency surface is where supply-chain risk lives. An agent that adds a 70 kB package to avoid writing fifteen lines of fetch has added a maintainer, a lockfile entry, a transitive tree, and a new CVE feed you now have to watch — and also cost the user 70 kB. The budget forces that trade-off into the open at the moment it's made rather than at the next audit.
Two corollaries:
- Never let budgets be raised by the same commit that raises them. A
budget:PR is a review checkpoint with a human signature, which is exactly the friction you want on "add a dependency." - Cross-check with your SBOM / dependency diff. A budget failure caused by a new package should link the package. A budget failure caused by your own code should link the module.
size-limit --whygives you the map.
And keep the guardrail outside the agent's writable scope where you can: branch protection requiring the size check, CODEOWNERS on the budget config, CI config not editable by the agent's token.
Rollout in an afternoon
- Measure
main, write limits with 3% headroom, commit the config. - Add
npm run sizeand confirm it runs in under ten seconds on a warm build. - Add the agent instruction block. Test it: introduce a 30 kB import, watch the agent refactor instead of raising the limit. If it raises the limit, your instruction is too soft.
- Wire CI as a required status check; post the delta comment from
size.json. - Add the soft-regression tier and a weekly trend export.
The strategic point: an agent's competence is bounded by the feedback it can observe. Tests tell it about correctness. Type checks tell it about shape. Nothing currently tells it about weight. A budget with a non-zero exit code is the cheapest way to extend the agent's sensory range into a dimension it's currently blind to — and to make the branch fail before you land it.
Sources
- Gabriel Anhaia, "Give Your Coding Agent a Bundle Budget: size-limit Fails the Branch Before You Land It" — https://dev.to/gabrielanhaia/give-your-coding-agent-a-bundle-budget-size-limit-fails-the-branch-before-you-land-it-2hn5
size-limitdocumentation and@size-limit/file/ bundler plugins — https://github.com/ai/size-limit- Lighthouse CI budget assertions (complementary timing budgets) — https://github.com/GoogleChrome/lighthouse-ci
- Related tooling:
bundlemon,webpack-bundle-analyzer,rollup-plugin-visualizer - Companion reading: Event-Driven Architecture Pocket Guide — https://www.amazon.com/dp/B0GX3B8371 · Pocket Guides for Developers series — https://www.amazon.com/dp/B0GYLH38X4
- Tooling context: Hermes IDE — https://hermes-ide.com · https://github.com/hermes-hq/hermes-ide · Author — https://xgabriel.com



