Why a contract
Without explicit conventions, an agent will guess. Guesses become inconsistent files, env drift, and PRs that don’t merge cleanly. AGENTS.md answers the questions agents ask first — branch flow, form endpoints, naming, file locations — so the rest of the prompt can be about what not how.
The schema
md · AGENTS.md
# AGENTS.md
This is a Caddi-managed project. Read this file before writing code.
## Project shape
- Framework: Next.js 15 (app router)
- Language: TypeScript, strict
- Package manager: pnpm
- Test runner: vitest
## Branches
- main: production
- staging: staging
- dev: in-progress work
Open PRs against `dev` unless told otherwise. Never push to main directly.
## Env vars
- Public values are prefixed `NEXT_PUBLIC_`. Secrets are not — and
should never appear in client bundles.
- Don't read env vars at import time. Use a typed config module.
## Forms
- The form endpoint URL is in `NEXT_PUBLIC_CADDI_FORM_URL`.
- Use `@caddi/forms-sdk`. Do not write a custom fetch.
## Pages
- App pages live at `app/`.
- Marketing copy is MDX in `content/`.
## What never to do
- Commit secrets.
- Hard-code URLs that vary per environment.
- Edit `.caddi/` — that's Caddi's metadata directory.
- Edit env vars on Vercel directly. Use `caddi env set`.
What Caddi auto-injects
## Branches — based on your project’s configured branches.## Forms — only if the template includes the forms SDK.## What never to do — the universal don’ts.
Everything else you write — and own.
AGENTS.md is just markdown. Agents read it because you tell them to (or because they’re trained to). Caddi’s contribution is making sure the file is consistent across every project so prompts are portable.
Validating
bash
caddi agents lint
# ✓ AGENTS.md present
# ✓ branches section
# ✓ env-var section
# ✓ forms section (template uses forms-sdk)
# ! warning: no "## Pages" section
Next
Caddi Auto →