104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# Token economy
|
||
|
||
Quality per token beats raw token spend. The expensive part of a swarm is usually **input context and
|
||
repeated reading**, not the code a worker writes. Measure, budget, then cut redundancy — never cut
|
||
the independent checks that catch real defects.
|
||
|
||
## Measure before optimizing
|
||
|
||
Record usage per phase and per agent in `.swarm/state.json`:
|
||
|
||
```json
|
||
{
|
||
"budget": { "tokens": 600000, "soft_cap": 0.7, "reserved_for_verify": 0.2 },
|
||
"usage": [
|
||
{ "phase": "recon", "agent": "R01", "tokens_in": 18000, "tokens_out": 4000 },
|
||
{ "phase": "build", "agent": "T03", "tokens_in": 24000, "tokens_out": 9000 }
|
||
]
|
||
}
|
||
```
|
||
|
||
If the runtime does not expose usage, estimate from context size and output length and mark the value
|
||
as `estimated`. The point is a feedback loop, not accounting precision.
|
||
|
||
Useful ratios:
|
||
|
||
- tokens per accepted task;
|
||
- verifier tokens per confirmed defect;
|
||
- rework tokens caused by a missed contract;
|
||
- share of spend on recon / build / verify / integration.
|
||
|
||
## Budgets and reserves
|
||
|
||
- Set a **hard budget** for the milestone and a **soft cap** at ~70%. At the soft cap, stop expanding
|
||
scope; finish the current slice and verify.
|
||
- Reserve **20–30%** for verification, integration and one round of fixes. Do not spend the whole
|
||
budget on generation.
|
||
- Budget per phase, not only per wave: recon, build, verify, integrate.
|
||
- Stop at the cap and report partial results plus unverified areas. Silent overspend is worse than a
|
||
partial result.
|
||
- Calibrate from the first measured milestone; do not copy invented numbers from a template.
|
||
|
||
## Context discipline
|
||
|
||
The biggest savings without quality loss:
|
||
|
||
1. **Small files.** Split modules above ~800 lines (UI panels, viewport, inspector). A worker should
|
||
read 300–800 relevant lines, not 3,000. Smaller modules also compile and verify faster.
|
||
2. **Read ranges, not repositories.** Use `path:line`, symbol search and grep first. Do not read a
|
||
whole crate to change one function.
|
||
3. **Point to artifacts, do not paste them.** Task cards reference `.swarm/brief.md`,
|
||
`.swarm/contracts.md` and exact ranges; they do not duplicate them in the prompt.
|
||
4. **Cap reports and reviews.** Worker report: summary, files/artifacts, evidence, issues,
|
||
assumptions. Review: findings + commands + evidence; target 5–8k tokens, raw logs stay in files.
|
||
5. **One page per task.** If a card needs more, the task is too broad.
|
||
6. **No full-suite runs per worker.** Workers run targeted checks; the lead runs the full gate once
|
||
per wave.
|
||
7. **Fresh context only where independence matters.** The final verifier needs a clean read. A fix
|
||
re-check can be a **delta review**: diff + findings + acceptance commands, not the whole repo.
|
||
|
||
## Verification ladders
|
||
|
||
Do not spend LLM review tokens on a red build:
|
||
|
||
1. compile / typecheck / lint;
|
||
2. targeted tests;
|
||
3. artifact/render/source check;
|
||
4. independent verifier on the diff and evidence;
|
||
5. final full review once, on a frozen integrated build.
|
||
|
||
Freeze before step 4. If code changes, re-check only the affected delta; mark the old review stale.
|
||
This preserves quality while avoiding repeated full reviews.
|
||
|
||
## Orchestration shape
|
||
|
||
- **Fixed overhead dominates small tasks.** Each child carries system prompt, tools, brief and task
|
||
context. 30 small agents can cost more than 8 substantial ones.
|
||
- **Right-size:** 2–4 implementers + 1 verifier for a vertical slice; 6–10 agents for a broad
|
||
milestone; 30 only for genuinely independent breadth.
|
||
- **Model routing:** strong model for architecture, difficult fixes and final review; cheaper/faster
|
||
model for tests, docs, screenshots and mechanical edits.
|
||
- **Vertical slices:** ship one end-to-end feature at a time (selection → transform → undo → save),
|
||
with a checkpoint and verification after each. Do not generate the whole product and verify at the
|
||
end.
|
||
- **Reuse:** do not regenerate a working core, format or codegen. Extend it.
|
||
|
||
## Anti-patterns
|
||
|
||
| Pattern | Cost | Fix |
|
||
|---|---|---|
|
||
| 3k-line file edited by several agents | repeated reads, merge conflicts | split before dispatch |
|
||
| Full repo read for a one-function change | huge input | path:line + grep |
|
||
| Full re-review after every fix | duplicate verifier spend | delta review |
|
||
| Verifier runs on a failing build | wasted review | automated gate first |
|
||
| 20 tiny tasks | fixed overhead per child | merge into coherent units |
|
||
| Reports/reviews as essays | output + lead input | schema + evidence lines |
|
||
| Whole product in one wave | late integration, huge rework | vertical slices + checkpoints |
|
||
| Vague "max quality" with no budget | unbounded spend | hard/soft caps + reserve |
|
||
|
||
## Minimal operating rule
|
||
|
||
> Measure per phase, reserve for verification, keep files and packets small, verify the diff after
|
||
> fixes, and spend the saved tokens on one strong independent review rather than many redundant
|
||
> agents.
|