Fewer Skills, Shorter Rules: Setting Up a Coding Agent That Does Not Drown in Its Own Instructions

Part 2 of 9 in the series on agentic software development. Part 1, The Agent Writes the Code has the two settings, the numbers, and the ten sentences the series works through.

For nine months an AI coding agent has written nearly all the code of a multi-product SaaS platform, and in a client project it built an event-driven service in eleven days. The agent writes the code; what makes the code trustworthy is the structure around it. The innermost layer of that structure is the toolbox the agent gets and the file that tells it how to behave. Both have the same failure mode: they grow until they cost more than they give, and every session pays for the growth.

Start with Superpowers, then adapt it

I start every project with Superpowers, a collection of process skills for coding agents: brainstorming, writing plans, executing plans, test-driven development, systematic debugging, verification before completion, and so on. It is a good starting point, and I have never used it unchanged. Each project gets its own adaptation along three lines.

• Paths and conventions. “Write a plan” has to mean something concrete: write it to REQUIREMENTS/<PRODUCT>/plan/, with the file-name pattern of this project, with a mandatory ## User job section. A generic skill does not know where plans live or what a plan must contain here; the adapted one does.
• Project language. The skills speak the vocabulary of the project, not a generic one.
• Project-specific skills on top. In the SaaS platform, most skills are ours: onboarding a new country into the e-invoicing pipeline (pin the official specification by SHA-256, scaffold catalogue and validation gates, wire generator and validator into the backend), drift checks against pinned legal sources, deployment to the VPS, building decision tables, running the autonomous plan pipeline, a browser QA walkthrough, dependency cascades across repositories.

The process skills are the smaller part of the toolbox. The larger part encodes what this particular project does over and over, in the order it has to happen, with the checks that belong at each step. That part cannot be downloaded, and it is the part the agent uses most.

A browser for anything with a frontend

When the software has a user interface, the agent gets a browser through the Playwright MCP server. The difference is between claiming and checking. Without a browser, the agent can only claim that a screen works. With one, it can click through the screen as a user would, read console errors, count network requests, and take screenshots.

Counting network requests turned out to matter, because what a page reports about itself is not evidence; that story belongs to part 8. Two lessons from running the browser at scale:

• One browser per parallel session. When several agent sessions share one Playwright MCP instance, they share the browser, and one session navigates away from the page another session is testing. We run several named instances (playwright, playwright-2, playwright-3) and assign them to sessions.
• A walkthrough answers “does it work?”, not “is it correct?” A walkthrough as the owner account will never find a missing permission check, because the owner is allowed to do everything. That class of defect, the absence nobody reports, gets its own part later in the series.

The token diet

Every skill, agent, and command has a description that travels with every single request, so that the model knows the capability exists. Twenty unused skills are twenty paragraphs of noise in every call: paid for in tokens, and paid for again in attention, because the model has to pick from a longer list each time.

My rule: whatever is not needed gets deleted or moved to an archive folder outside the path the agent loads.

On 3 September 2026 I measured this in the SaaS platform. 14 skills had not been invoked once in 91 sessions over a month. Five of them were original Superpowers process skills: test-driven development, systematic debugging, verification before completion, subagent-driven development, dispatching parallel agents. Not because the ideas are wrong; the project’s own pipeline had absorbed them. They went into .claude/skills-archiv/ with a README that names the replacement for each and how to reactivate it. As of 17 September 2026, the platform runs 24 active skills with 14 archived.

Unused capability is not free. It costs tokens on every call and dilutes the selection the model has to make.

An instruction file of 170 lines

Every coding agent reads a project instruction file at the start of a session: CLAUDE.md for Claude Code, AGENTS.md for others. It is the most important file in the project, and it rots faster than any other.

The mechanism of the rot is simple. Each incident adds a paragraph. After a few months the file is thousands of lines long, the important rules are buried among the merely useful ones, and every session pays for all of it, whether or not it touches the area a paragraph is about.

The instruction file in the SaaS platform is now 170 lines. Each mandatory rule is one sentence, the sentence on which the rule holds or fails, plus a pointer to its long version:

- **A test checks the payload** — 🔴 it contains what I sent: each value read from the input,
  never from a constant. → `tests-payload-spec-table.md`
- **Database migrations expand/contract** — feature releases are additive; DROP/RENAME/SET NOT NULL
  only in their own contract release; 🔴 never by hand. → `migrations-expand-contract.md`

The shape is the same for every rule: the bold phrase names it, the clause after the marker is the test that decides whether it was followed, and the arrow points to the file that explains why. Nothing else is allowed on the line. If a rule cannot be reduced to that sentence, it is not yet a rule; it is a discussion, and it does not go into the file.

The long versions live in .claude/rules/: ten files, 913 lines in total, with the rationale, precedents from the codebase, test questions, and measurements. That is more than five times the length of the instruction file, and none of it is loaded by default. Each file carries a path filter in its frontmatter:

---
paths:
  - "**/tests/**"
  - "**/*.test.ts"
  - "**/*.xlsx"
---

The rule about test payloads loads only when the agent touches a test file or a table. The rule about database migrations loads only near migrations. The session pays for what it needs.

One caveat, written into the instruction file itself: if you decide something in an area without opening a file there, read the long version by hand — otherwise the binding never fires. A path filter is a trigger, and a trigger that is never pulled does nothing; the file has to say so, because the agent cannot notice a rule it never loaded.

What belongs in the instruction file at all

Three kinds of content, and only these:

• What is always true. The project overview, where things live, the push gate.
• The one-sentence version of each hard rule. The sentence, the marker that it is binding, the pointer.
• Pointers, not content. Where the architecture docs are, where the requirement folders are, where the knowledge base is.

What does not belong: history, measurements, examples, one-off decisions. Those go into the long rules, the knowledge base, or the lesson memory. The question for every new paragraph is whether it holds for every session. If it does not, it is a long rule with a path filter, or a knowledge article, and the instruction file gets one line pointing at it.

Cost is a design constraint

Agentic development at this scale is not cheap, and cost turned out to be a design constraint rather than an afterthought. Most of the measures above were introduced for attention: a shorter list to select from, a shorter file to read. They turned out to be budget measures as well, and the budget added a few of its own. Five decisions came out of it, and the first came out of a surprise.

• The weekly limit was reached after three days. An analysis showed that the orchestrator, running on the most expensive model, consumed 30 % of the weekly budget by itself. The orchestrator moved to a strong but cheaper model; implementation stayed on a strong model; routine cascades moved to a fast model.
• At most three sub-agents at the same time, across all types.
• Briefs with line ranges, not whole files. An agent brief that says “read lines 120–180 of X” costs a fraction of “read X”.
• The ledger is read by its head only. The plan pipeline keeps a ledger of every plan and its status; a resuming run reads the head of it, and the old part is archived by size. The pipeline is part 7.
• Unused skills are archived, and the instruction file is short with path-bound long rules. Attention and budget are the same measure seen from two sides.

None of these numbers is a recommendation for another project. The three sub-agents, the 30 %, the day on which the limit was hit: they are what this setup measured, on this budget, with this mix of plans. What carries over is the habit of measuring where the tokens go before deciding where the work goes.

The cheapest token is the one that never enters the context.

The rules this part comes down to are three. Whatever the agent does not use leaves the path it loads from; measure that, do not guess it. Every hard rule is one sentence in the instruction file, and everything behind that sentence lives in a file that loads only where it applies. And every brief, every ledger read, and every model assignment is chosen with the budget in view, because the budget will otherwise choose for you, on day three.

Previous: Part 1, The Agent Writes the Code. Next: Part 3, One Root, Many Repositories.