AGENTS.md — the canonical guide

AGENTS.md at the repo root is the single source of truth for AI tools. It’s deliberately lean: a repo map, the tech stack, full-stack build/run commands, a short list of “golden rules” that must never be broken, and an index pointing into .agents/rules/. Conventions are edited there — not in the bridges.

CLAUDE.md (Claude Code) and GEMINI.md (Gemini CLI) are one-line bridges that import it:

# Claude Code
The canonical project guide is **`AGENTS.md`** (tool-neutral). It is imported below; edit conventions there, not here.

@AGENTS.md

So every tool — and every contributor — reads the same guide, and there’s exactly one place to update.

The `.agents/` folder

AGENTS.md                     ← canonical guide (CLAUDE.md / GEMINI.md import it)
.agents/
├── rules/                    ← conventions & footguns (read on demand)
│   ├── architecture.md          module boundaries, registration, middleware order
│   ├── api-conventions.md       endpoints, CQRS, validation, exceptions, permissions
│   ├── database.md              EF Core, migrations, tenant isolation, query filters
│   ├── eventing.md              domain vs integration events, Outbox/Inbox
│   ├── caching.md  jobs.md  resilience.md  storage.md
│   ├── security.md              CORS, security headers, rate limiting, idempotency, quotas
│   ├── realtime.md  logging.md  testing.md  integration-testing.md
│   ├── modules/                 one file per module (identity, multitenancy, chat, files,
│   │                            webhooks, auditing, billing, catalog, tickets, notifications)
│   └── frontend/                shared.md · admin.md · dashboard.md (the two React apps)
├── skills/                   ← task recipes (see Skills & Workflows)
│   └── {skill}/SKILL.md
└── workflows/                ← review / orchestration playbooks
    └── {workflow}.md

Rules — conventions, read on demand

A rule is knowledge the agent reads before working in an area — the conventions and the footguns that are easy to get wrong. Rules don’t restate what the code or tests already enforce; they point at the enforcement and capture the non-obvious. The root AGENTS.md carries the index, e.g. “before EF or migration work, read database.md.”

Working on…	Rule
Module structure, boundaries, registration, middleware order	`architecture.md`
Endpoints, CQRS, validation, exceptions, permissions	`api-conventions.md`
EF Core, entities, migrations, tenant isolation	`database.md`
Cross-module events, Outbox/Inbox, idempotent handlers	`eventing.md`
Caching · jobs · HTTP resilience · file storage	`caching.md` · `jobs.md` · `resilience.md` · `storage.md`
CORS, security headers, rate limiting, idempotency, quotas	`security.md`
SignalR / SSE · logging & OpenTelemetry	`realtime.md` · `logging.md`
Unit tests · integration tests (Testcontainers)	`testing.md` · `integration-testing.md`
A specific module’s quirks	`modules/{module}.md`
Any React work · the operator app · the tenant app	`frontend/shared.md` · `frontend/admin.md` · `frontend/dashboard.md`

A few examples of the kind of footgun these capture: registering a module touches four places (Mediator assemblies + module array, in both the API and DbMigrator hosts); tenant isolation is default-on via BaseDbContext; new entity ids use Guid.CreateVersion7(); log messages must be structured (no string interpolation). Each is one read away when the agent needs it.

Next: the Skills & Workflows that turn these conventions into repeatable actions.