How I run this site with AI coding agents

Most of the code on this site is written by AI coding agents now. I use Claude Code the most, but Codex, Cursor, Copilot, and Gemini have all worked in the same repo.

That only works because every one of them follows the same rules. Those rules live in one file.

One file, every agent

The repo has a file called AGENTS.md at the root. It says what the site is, how it’s built, which commands to run, and what an agent must never do.

Each tool looks for its own file, so the others just point back to it:

• CLAUDE.md and GEMINI.md import AGENTS.md in one line.
• .github/copilot-instructions.md tells Copilot to read AGENTS.md, and says not to copy rules into it.
• Cursor gets two small rules of its own: keep every change strictly scoped, and start the dev server at the start of a session.

When I change a rule, I change it once. No tool drifts out of sync with the others.

Rules an agent can check

A rule like “keep it on brand” means nothing to an agent. So every rule in AGENTS.md is something it can test against the code. A few of the ten:

• Tokens only. No hardcoded colors, spacing, radii, or font sizes. If a value is missing, add a token and document it.
• One accent. Amber is the only strong color.
• Motion is transform and opacity, with no overshoot, and every animation needs a reduced-motion version.
• Sentence case for every heading, button, and label.
• Don’t invent content. No made-up stats, quotes, or claims. Ask.
• Stay in scope. Make the smallest change that does the job, and suggest unrelated fixes instead of making them.

There is also a definition of done. The build passes, formatting is clean, and the change has been checked in a browser at desktop width and at 375px.

Docs that load only when needed

AGENTS.md stays short. It ends with a table that sends the agent to the right doc for the job: motion, content, accessibility, SEO, architecture, or design tokens. An agent fixing a blog post reads the content guide. An agent touching an animation reads the motion guide. Nobody reads everything.

The content guide even lists words that read as machine-written: “delve”, “leverage”, “elevate”, “game changer”, and more. Agents write for this site too, so they need to know what not to say.

Guardrails on the tools themselves

The shared Claude Code settings allow a short list of safe commands without asking: dev, build, preview, format, link check, and read-only git. Reading .env files is blocked outright. Personal settings stay in git-ignored local files, so my preferences don’t become the project’s rules.

When the rules push back

The rules matter most when I ask for the wrong thing.

Recently I gave an agent a big brief for this site: Framer Motion, animated icons, more scroll storytelling, and copy with words like “elevate” and “cutting-edge”. It didn’t just build it. It pointed out that the site has no React, so Framer Motion doesn’t fit. Icons are meant to stay static. The home page already has its two big motion moments. And the content guide bans those words.

So it built what fit. The portrait on the home page now starts as a coarse mosaic and sharpens into the photo. That idea comes from the “Two altitudes” section, which switches between the org view and the pixel view. It built the effect inside the existing hero animation instead of adding a new one.

Then it tested its own work in a real browser. It caught one word in the headline that didn’t animate with the others, and a cache that used far more memory than it needed to. Both were fixed before I saw the code.

What stays with me

The agents write the code. The decisions are still mine.

The rules came from years of design work: how motion should feel, how copy should sound, how much is too much. An agent can follow them. It can’t decide what they should be. When a rule is missing, I’m the one who writes it, and every agent reads it the next time.

The same goes for content. Anything that says what I did, what I believe, or what I achieved comes from me. That’s why “don’t invent content” is one of the rules.

If you want to try this, start small. Write down the five rules you repeat most in design reviews, and put them where your agents will read them.