# Engineering notes

> Notes on how vawe is built for coding agents, from the blog. Each note has its measurements.

Canonical: https://vawe.dev/docs/engineering-notes

These blog posts say why vawe works the way it does. Each one gives the data behind a decision. For the rules themselves, read [Checks](https://vawe.dev/docs/quality-gates) and the [CLI](https://vawe.dev/docs/cli).

| Note                                                                            | What it covers                                                                                |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [AI agent tooling: design for the weaker model](https://vawe.dev/blog/weaker-model)             | Six films from a weaker model: how defaults, checks and one command per step make it succeed. |
| [AGENTS.md best practices: how long should it be?](https://vawe.dev/blog/read-load)             | Cutting what an agent reads first from 5,402 to 2,239 words, and what that did.               |
| [LLM as a judge: start at reject, a video example](https://vawe.dev/blog/judge-design)          | A judge that starts at reject and caps scores against reference films.                        |
| [Reward hacking in AI: 18 of 36 agent runs gamed a check](https://vawe.dev/blog/loophole-audit) | 18 of 36 runs gamed a check; how the checks changed.                                          |
| [AI agent guardrails: when a check should refuse](https://vawe.dev/blog/advise-refuse)          | When a check advises and when it refuses.                                                     |
| [Agent skills for UI design: a blind test of 6 combos](https://vawe.dev/blog/skill-combos)      | A blind test of 6 UI skill combos on 2 frame types.                                           |
| [Verbalized sampling for AI agents: method and test plan](https://vawe.dev/blog/ideate)         | Verbalized sampling for ideas: method and test plan.                                          |
| [Motion graphics benchmark: 167 cuts measured](https://vawe.dev/blog/quality-bar)               | The measured bar for motion from 167 cuts in 17 reference films.                              |
| [CLI design for AI agents: one binary, one verb per step](https://vawe.dev/blog/one-binary)     | One binary with 29 verbs, one-line errors and a hook that names the next step.                |
| [AI agent observability: one JSONL line per command](https://vawe.dev/blog/run-logs)            | One JSONL line per command, so time and failures are measured, not guessed.                   |