How to Make an Agent Know It Screwed Up

AI agents write code fast. They also leak null through every layer, create 2,000-line router files, leave bugs in production, and generate dead code once the happy path compiles.

This isn’t malice; LLMs optimize for plausible output, not production durability. You won’t stop them from making mistakes, but you can build a system where the agent finds out it screwed up before a human has to tell it.

I’ve implemented features and maintained code quality through an AI agent on a production TypeScript monorepo (10+ packages, 3+ apps). These are the layers that made it work.

Layer 0: Documentation

Write down what, how, and why; otherwise the agent guesses.

Agent context windows can’t hold the full codebase, so layered documentation delivers just-in-time context: project overview, package-specific rules, task specs. Write it once; the agent stops asking “what’s the structure?” on every task.

Layered Agent Instructions

A root-level AGENTS.md covers project overview, tech stack, filesystem structure, build system, and scripts. Each app and package has its own file with domain conventions: the API package documents router patterns, the database package documents schema, the frontend package documents components.

Files concatenate from root downward (OpenAI’s discovery pattern 1 ), deeper files override shallower ones. An agent gets project context plus localized rules without reading every file.

Layer 1: Test-Driven Development

Tests first, then code. An agent can’t fake coverage when CI enforces thresholds.

Agents make tests pass, but they don’t know which tests to write. The configurations below remove that choice: passing tests mean working code, not well-mocked code.

Base Test Configuration

A shared config centralizes test settings: global utilities, dependency optimization, and coverage thresholds. In CI, the floor is 80% across branches, functions, lines, and statements.

Tests live next to the code they test ( tests/ directories co-located with source…