Agent Calibration

Why Vibe Coding Needs Calibrated Tools

A mechanic uses a torque wrench, not feel. An electrician checks the multimeter against a known source. A pharmacist's scale has a sticker with the date of its last calibration. The tools are ordinary. The check against a standard makes them professional.

Coding agents are the new tool on the bench, and most people use them uncalibrated. Without project rules, an agent falls back to the average of the internet. Monday's session stores dates as strings, Wednesday's as timestamps. One route validates input, the next trusts it. A password ends up in Git. A developer sees the drift. A non-technical founder does not, until the first professional they hire says "rewrite".

Two Instruments

Calibration lives in the repository, not in a chat. Two kinds of file do the work:

• AGENTS.md at the root: what the project is, where things live, the rules that hold everywhere. Most agents read it at the start of every session.
• Skills, one SKILL.md per role (database, security, deploy). The agent loads a skill only when the task touches that area.

An example for a physiotherapy clinic booking site:

## Conventions

- Store dates in UTC (ISO 8601). Show them in Europe/Athens.
- Validate every request body with Zod before other logic.
- Secrets are in `.env`. Do not commit or print them.
- Warn before you delete files, run a migration or deploy.
- After each change, run `bun test`. Report what passed and what you did not verify.

And the project part of a db-engineer skill:

## Project Instructions

- SQLite through `bun:sqlite`. The file is `data/clinic.db`.
- Do not delete appointments. Set `cancelled_at`. The clinic needs the history for insurance claims.

Now the request "let patients cancel an appointment" gives a POST route with validation, a soft delete and a question before the migration. Without the files, the result is often a GET /cancel?id=42 that deletes the row.

Tips

• Write rules in ASD-STE100. Simplified Technical English was made for aircraft maintenance manuals: one meaning per word, short sentences, active voice, one instruction per sentence. An agent follows "Do not delete appointments" more reliably than a paragraph that explains why deletion is usually a bad idea. That is why the rules stay in English.
• Set a token budget. Every token is paid on every request, and long files get skimmed. I keep AGENTS.md under 1,024 tokens and each skill under 512.
• Share headers, keep overlays small. A skill has a generic header (identical in every project) and about six project bullets. Write the header once, copy it everywhere, never edit it in place.
• Write the one rule only you know. A regulation, records you must keep, an invoice format. It is the most valuable line in the kit.
• Put the house rules in AGENTS.md once. No em-dashes, no emojis, a list of banned clichés, warn before destructive actions. Do not repeat them in skills.
• Ask the agent to state what it did not verify. A silent gap is worse than a known one.
• Fix the file, not the chat. A correction in a chat lasts one session. A correction in AGENTS.md lasts for the life of the project.
• Audit for drift. I keep the shared headers in one agents repository with a script that reports files over budget and headers that differ from the source. That is the calibration sticker.

Calibration Is the Handover

A professional who takes over a project spends the first week finding out which conventions exist and which are accidents. A calibrated project answers that on day one. The stack, the layout and the rules are in AGENTS.md and a few short skill files, and the code was written against them, so it is consistent.

A non-technical founder does not need to know every rule. They need the rules to exist before the code does. One hour with a developer to write AGENTS.md and a few skills costs less than the rewrite.