make-agents-cheaper AGENTS.md

AGENTS.md

Project guidance for Codex and other coding agents working in this repository.

Project Identity

make-agents-cheaper is the audit/eval and research-instrumentation repo for harness-level prompt-cache experiments.

Keep these roles separate:

• Codex: development assistant used to build the tooling and write docs.
• Claude Code: current studied coding-agent harness.
• MiMo: current backend model/provider route, for example mimo-v2.5-pro.
• make-agents-cheaper: Rust audit/eval instrumentation and paper-facing evidence.
• skills/cheaper-skill-for-claude: in-repo Claude Code skill adapter for reusable runbooks.
• cheapcode: possible future native cheaper-agent harness, not the current experiment.

Do not describe current experiments as Codex-cache experiments unless Codex is actually the harness under test.

Core Claim Discipline

The project tests a narrow claim:

When dynamic harness state would otherwise disturb the early prompt prefix,
moving that dynamic state later preserves a longer reusable prefix,
increases prompt-cache hit rate,
and can reduce observed input cost without reducing task success.

Do not claim:

• universal savings;
• lower total input tokens unless measured;
• quality preservation without validation;
• skill-layer savings as main evidence;
• cost savings when cache accounting is not observable.

Preferred wording:

reduces paid uncached input

not:

uses less context

Product Layers

Use the right layer for the task:

• Rust CLI: implement audit/eval commands, token accounting, fingerprinting, trace import, and reports.
• docs/: write protocol, task-suite, trace-capture, and metric specifications.
• paper/: write conservative paper-facing claims grounded in logs.
• taskplan/: manage roadmap, subtasks, and evolution notes.
• runs/: keep local raw experiment logs and fixtures; do not commit raw traces.

Evaluation Rules

• Separate warm-up calls from measured calls.
• Use paired A/B comparisons: baseline warm-up, candidate warm-up, baseline measured, candidate measured.
• Keep provider, model, route, MCP, hooks, task prompt, and validation command fixed across paired runs.
• Record token usage per task: input, cached input, cache creation input, uncached input, and output.
• Check task success and validation before counting a cheaper run as a win.
• Preserve failed or anomalous runs in notes instead of silently replacing them.