AI Agents

How AGENTS.md tells an AI coding agent the rules of a zap.ts codebase, and how to extend it for your own product.

An AI coding agent is a tool that reads your code and writes code for you. Claude Code, Cursor and Copilot are three of them.

An agent that does not know your rules will guess. It will add a version number where the project forbids one. It will write a mock where the linter blocks mocks. zap.ts stops that with one file.

What AGENTS.md is

AGENTS.md sits at the root of the zap.ts folder. It holds the rules of the codebase, written for an agent to read.

Most agents open it on their own when they start. You do not have to paste it into a chat. You do not have to ask.

It is short on purpose. An agent reads it before every task, so every extra line costs something.

Why CLAUDE.md exists too

Claude Code looks for a file named CLAUDE.md. In zap.ts, that file holds one line:

@AGENTS.md

That line means “read AGENTS.md”. Nothing else.

So the rules live in one file, and every tool finds them. When you change a rule, you change it once. CLAUDE.md never goes out of date, because there is nothing in it to go out of date.

If your team uses a tool that wants its own file name, do the same thing: create the file and point it at AGENTS.md.

What the rules say

AGENTS.md has four parts.

The check commands

A table of the commands to run before finishing a piece of work:

pnpm run lint:fix and pnpm run format fix what they can.

The table also tells the agent it can check one package on its own, with pnpm --filter <package> run <script>. That is much faster than checking everything.

The test rules

Where a test goes, what to name it, and how it gets a database. These are the same rules a person follows. See Testing for the long version.

The last rule matters most: do not mock modules. The linter blocks it, so an agent that tries will fail the check. The file says what to do instead. Pass the dependency in, or write a small fake.

The dependency rules

Three lines, and they are absolute:

• A library from outside the repository uses catalog:.
• A package from inside the repository uses workspace:*.
• Never write a version number in a package.json.

This is the rule an agent breaks most often, because almost every other project does it the normal way. See Dependencies.

The writing-code rules

Five short rules about how to build:

1. Write the test first. Watch it fail, make it pass, then clean the code.
2. YAGNI: write only what the task asks for. Do not add an abstraction that has one caller.
3. DRY, but not too early: move code out when you see it a third time, not a second time.
4. Choose the smallest change that works. Use the standard library first, then a helper that already exists. Add a new dependency last.
5. Comments say why. The code says what.

These exist because an agent tends to build too much. It will add a settings option nobody asked for, or a wrapper around one function. Rule 2 and rule 4 are there to stop it.

Skills go next to it

AGENTS.md holds the rules. The recipes for single tasks — adding a feature, swapping a provider, deploying — live in .claude/skills, one folder each.

An agent loads a skill only when that task comes up, so a recipe costs nothing until it is needed. See Skills.

Keep it true

AGENTS.md is only useful while it matches the code.

A rule that has gone stale is worse than no rule. The agent follows it with full confidence and writes something that does not work.

So when you move a package or rename an export, check whether AGENTS.md mentions it. Treat it like any other file that can go out of date.

Extending it for your product

AGENTS.md covers zap.ts. It does not know your product. Add your own rules under the ones that are there.

Good things to add:

• Words your product uses. If a “workspace” in your app is not the same as an organisation, say so. An agent that guesses this wrong writes confusing code everywhere.
• Where new code goes. “New API routes go in apps/api/src/routes.” An agent will otherwise put the file somewhere reasonable but wrong.
• What not to touch. Generated files, for example. auth.schema.ts in @zap-ts/database is written by a script. An agent that edits it by hand loses the change on the next run.
• Commands you added. If you add a script, add it to the table.

Two things to avoid.

Do not write long explanations. The agent reads the whole file every time. One short line beats a paragraph.

Do not repeat what the code already says. If TypeScript types enforce a rule, the agent already sees it. Write down only what the code cannot show.

Related

• Skills — the task recipes that ship with zap.ts
• Testing — the full test rules
• Dependencies — the catalog rule
• Project structure — what each folder holds
• Local development — running the checks