This website was built with an AI coding agent — design port, blog engine, admin panel, security hardening, database wiring, the lot. Not by pasting snippets into a chat window, but by giving an agent a real repo, real tools and a real path to production.
The agent was fast. What made it work was the workflow around it. Here's that workflow, step by step, so you can copy it.
The mental model: you're the tech lead
A coding agent like Claude Code can read your codebase, run commands, edit files, run tests, drive a browser and open pull requests. Treat it like a very fast engineer who joined this morning: brilliant, tireless, and missing context only you have. Your job shifts from typing code to setting direction, defining done, and reviewing.
The quality of what an agent ships is capped by the quality of the loop you put it in.
1. Make the repo agent-friendly
Agents start every session cold. Give them a map. Claude Code reads a CLAUDE.md file from the repo root at the start of each session — put the things a new teammate would need in there:
# Project notes for agents
## Commands
- Dev server: `npm run dev` (http://localhost:3000)
- Typecheck + lint: `npx tsc --noEmit && npm run lint`
- Build: `npm run build` — must pass before any PR
## Conventions
- Next.js App Router, TypeScript strict, no Tailwind (CSS in src/app/*.css)
- Site copy lives in src/content/site.ts — never hardcode it in components
- Server actions must call requireAdmin() before touching data
## Don't
- Don't commit .env* files or print secret values
- Don't change the database schema without a migration note in the PR- Keep it short and specific — commands, conventions, sharp edges.
- Document how to verify a change, not just how to make one.
- Update it whenever you correct the agent twice about the same thing.
2. Plan before code
For anything bigger than a one-line fix, ask for a plan first and approve it before any file changes. It costs a minute and catches most misunderstandings — wrong file, wrong approach, scope creep — while they're still free to fix. I literally say "make a plan for this first". Good agents will also ask clarifying questions when a requirement is genuinely ambiguous.
3. One task, one branch, one PR
Keep each unit of work small enough to review in one sitting. Let the agent create a branch, commit in logical steps, push, and open a pull request with a summary and a test plan. Small PRs are easier to review, easier to revert and much easier for the next agent session to understand from the history.
4. Verification is the agent's job, not yours
"It compiles" is not done. Define done as verified behaviour, and give the agent the tools to check it:
- Typecheck, lint and build on every change.
- Automated tests for logic — the agent should run them and read the failures.
- A real browser for UI — load the page, click the thing, read the console for errors. This is how hydration bugs get caught before users see them.
- curl the endpoints for status codes, redirects and headers.
Ask for evidence in the summary: what was run, what passed, what wasn't verified. An honest "not tested on mobile" is worth more than a confident "all done".
5. CI is the gatekeeper
Never let "the agent said it works" be the last check. Every PR runs the same checks in CI, whoever — or whatever — wrote it:
name: CI
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx tsc --noEmit
- run: npm run lint
- run: npm run buildAdd your test suite and an AI review step on top if you like — a second agent reviewing the diff for bugs catches a surprising amount. But the deterministic checks come first.
6. Preview, then production
With Vercel (or any similar host) connected to GitHub, every PR gets a preview deployment and every merge to main goes to production. That gives you a clean ladder:
- Local — the agent builds and verifies against the dev server.
- Preview — you click through the PR's preview URL.
- Production — merge, then smoke-test the live URLs.
Agents can drive the deploy side too through the platform's tools: list deployments, read runtime logs, trigger a redeploy. That's how the issues in the next section got found.
7. Secrets and environment variables: the sharp edges
This is where I've seen the most real-world breakage, and two lessons came straight out of building this site:
Also watch for duplicated infrastructure: importing a repo into your host twice creates two projects that both deploy on every push. Five minutes of auditing deployments and project settings is worth it.
The whole loop on one screen
- Write or refine
CLAUDE.md. - Describe the task and what done means.
- Approve the plan.
- Agent implements on a branch, verifies locally, commits in steps.
- Agent opens a PR with summary + test plan; CI runs.
- You review the diff and the preview deployment.
- Merge → production deploy → smoke test (and redeploy if you changed env vars).
The agent writes the code. The workflow is what makes it shippable. Invest in the loop once and every task after that gets faster and safer.