How I actually ship with AI agents

The word "vibe coding" suggests chaos. My version is the opposite: a strict split of responsibilities that never changes.

Always mine: scope, architecture and key decisions, technology choices, business logic, security, and reading every diff before it's committed. Always the agents': boilerplate, refactoring, tests (I describe the scenarios), first drafts of documentation, CI/CD configs, and styling.

Several agents work in parallel, each in its own copy of the repository. What keeps them consistent is not a long prompt but three documents they all read before touching code:

• A versioned PRD - what the product does and for whom, with numbered requirements. When the product changes, the PRD changes first, and the code follows.
• A domain glossary - one name per concept, used the same way in the PRD, the code and the UI. Most agent mistakes I see start with two words for one thing.
• Architecture decision records - why things are the way they are, including the options that were rejected.

A plan is written against these documents and critiqued before a single line is executed. Catching a wrong assumption in a plan costs minutes; catching it in a merged diff costs a day.

An agent can change 20-30 files in one session, and it will sometimes confidently break working code. So the system assumes failure:

• A commit is refused until a review pass is recorded for it; the review checks the change against the task's definition of done, not against the agent's own summary.
• Every logical block is a separate commit (Conventional Commits), so I can read exactly what an agent changed - and roll it back.
• CI runs lint, type-check, tests and build on every change; deploys end with an automated smoke test.

Output quality is set by context quality, not by model choice. Even with million-token windows, models lose focus - more context is not better context.

My setup is a hierarchy: global coding standards and a planning protocol at the machine level, then a short per-project entry file, then modular per-topic rules, plans, and custom commands. Specialized work goes to purpose-built agents - a writer, an independent reviewer, a judge that gives the verdict on a finished task - each with its own narrow brief.

The habit that pays back most. The due-diligence engine I built at Proxity has 101 ADRs across 564 commits - context, options considered, the decision, and crucially the rejected alternatives. That last section is what stops an agent from re-proposing ideas that were already rejected for good reasons three weeks ago.

What I deliberately keep out of AI-facing docs: style rules (linters do that), volatile file paths, anything derivable from the code, and secrets.

From shipping three production projects with this system: TypeScript, React and Tailwind are where agents are strongest - huge training base, few hallucinations. Python with FastAPI and typed schemas works well, because the contracts are machine-readable. Vue is noticeably weaker than React; fresh frameworks get their APIs hallucinated unless you feed the docs; complex SQL and raw CSS still need more human iterations.

• Write the spec before the prompt. Agents are only as consistent as the documents they share.
• Git is non-negotiable. AI development without version control is Russian roulette.
• Never use the agent for work you couldn't review yourself. The code got cheap; knowing what "correct" means didn't. That part is still the job.