AGENTS.md & CLAUDE.md

Intent

AGENTS.md and CLAUDE.md are persistent instruction files that an agent reads at the start of every session, seeding the context window with project-specific knowledge before you type a word.

Problem

A fresh session starts with an empty context window, so the agent knows nothing about how your project builds, the conventions you follow, or the gotcha that bit you last week. You explain it, the session ends, and next time you explain it again. Every teammate does the same, paying in their time and the model's first turns.

Solution

You write the explanation once in a file that the agent loads automatically. This is The Project Context File, better known as AGENTS.md (or CLAUDE.md): a Markdown file at the root of your repository that the agent reads before your first message. It is the shared, cross-agent convention that Codex, Cursor, and a growing list of tools read from the same spot. Put your build commands, architecture notes, and conventions there, so every session starts with them.

Real World Analogy

Think of a well-run guest house. The owner writes the essentials once in a welcome binder on the counter: the wifi password, how to work the quirky heating, which bin goes out on Tuesday. Every guest reads it on arrival, gets straight to their stay, and the binder stays in the house for whoever comes next.

AGENTS.md is that binder for your project. The house is the repository, each guest is a fresh session, and the binder is the file the agent reads before it touches anything. Write the house rules down once, and every visitor starts informed.

Structure

Directory Structure

The file lives at the root level of your project. You can add more AGENTS.md files in nested folders to give instructions for working within them, and the agent merges them, with the most specific file winning.

Project-Level Context

<your-project>/
├── AGENTS.md
└── <your-module>/
    └── AGENTS.md   # optional, refines this folder

File Structure

A standard Markdown file in which you place the most common instructions.

<Your intructions>

## <Your-Section>
<Section-Instructions>

Example

Here is a context file for a small web app, shown across tools. The content is identical; the filename is the only thing that changes with your tool. Every line is something the agent cannot cheaply read off the code, and the whole file costs only a few hundred tokens per turn.

Payments dashboard. Next.js frontend, Go API, Postgres. Monorepo.

## Commands
- `make dev`: starts the API (:8080) and web (:3000) together. Always use this to run both.
- `make test`: runs Go and frontend tests. Run before opening a PR.
- `make lint`: golangci-lint and eslint. CI rejects anything they flag.
- `make migrate`: applies pending DB migrations to your local Postgres.

## Architecture
- `api/` is the Go service: handlers in `api/http`, logic in `api/core`, DB access in `api/store`. Handlers go through `core`; they never touch the DB directly.
- `web/` is the Next.js app. Server components by default; mark a file `"use client"` only when it needs state or effects.
- API and web share types via generated `web/lib/api.ts`. Run `make gen` after changing an API response shape.

## Conventions
- Money is always integer cents. The `Money` type in `api/core/money.go` enforces it.
- Times are UTC in the DB and API; convert to local only in the browser.
- A new endpoint needs a test in the matching `_test.go` file and an entry in `docs/api.md`.

## Gotchas
- Postgres runs in Docker. If `make migrate` hangs, the container is down: `make db-up` first.
- The Stripe webhook handler must stay idempotent; Stripe retries on any non-2xx and double-sends.
- `web/lib/api.ts` is generated. Edit the source shape and run `make gen`; CI overwrites hand edits.

The gotchas earn their place: each one steers the agent away from a wrong move before it makes it.

Tips

• ✓Keep it short and specific, and re-read it as a budget line you pay on every request.
• ✓Write imperative instructions and include the why, so the agent can generalize past the exact case.
• ✓Prune on a schedule; a file that only ever grows eventually rots.
• ✓Add a rule, then test that the agent actually follows it before you trust it.

Pros and Cons