AGENTS.md: [Project name]

Ready-to-fill AGENTS.md: the README for AI coding agents. It follows the open AGENTS.md convention (agents.md): a plain Markdown file at the repository root that tells any coding agent how to set up, build, test and change this project safely. Replace every [bracketed] value and every line marked Example.

Project overview

[Project name] is a [one-line description, for example "multi-tenant invoicing API with a React admin console"]. It is used by [audience] and runs on [platform, for example "Kubernetes in two regions"].

Critical behaviours that must never regress:

• Example: Invoices are immutable once issued; corrections create credit notes.
• Example: Every database query is scoped by tenant_id.
• [Behaviour that must not break]

Setup commands

Prerequisites: [Node.js 22 LTS], [pnpm 9], [Docker 27] and [any other tool].

# Install dependencies
pnpm install --frozen-lockfile

# Start local services (database, cache)
docker compose up -d db redis

# Apply migrations and seed development data
pnpm db:migrate && pnpm db:seed

# Start the development server on http://localhost:3000
pnpm dev

Local configuration lives in .env.local, created from .env.example. Never commit real values.

Build, test and lint commands

All required commands must pass with zero errors and zero new warnings.

Code style and conventions

• Formatting is enforced by [Prettier / Ruff / rustfmt]; do not reformat untouched files.
• Use [named exports only; no default exports].
• File names: [kebab-case for files, PascalCase for React components].
• Errors: [throw typed errors from src/lib/errors.ts; never throw strings].
• Logging: [use logger from src/lib/log.ts; never console.log in committed code].
• Dependencies: [do not add a dependency without asking; prefer the standard library].
• Example: Dates are stored in UTC and formatted only at the UI edge.

Architecture map

Data flows from [entry point] through [service layer] to [storage]. See [docs/architecture.md] for the full description.

Testing instructions

• Every bug fix includes a test that fails before the fix and passes after.
• New modules in src/lib/ need unit tests with [80%] line coverage.
• Use the factories in tests/factories/; do not hand-build fixtures.
• Tests must not call real external services; use [MSW / respx / test doubles].
• Do not delete or skip a failing test to make the suite pass. Report it instead.
• Snapshot updates (-u) are allowed only when the visual change is intended and described in the PR.

PR and commit conventions

• Branch from [main] using [type]/[short-description], for example fix/invoice-rounding.
• Commit messages follow [Conventional Commits]: type(scope): summary in the imperative mood, at most 72 characters.
• One logical change per PR. Keep diffs under [400] changed lines where possible.
• PR description: what changed, why, how it was tested, and any follow-up.
• Run all required commands from the table above before opening a PR.
• Never force-push to [main] or rewrite shared history.

Security and secrets

• Never print, log or commit secrets, tokens, keys or .env files.
• Never paste production data or personal data into prompts, fixtures or tests.
• Do not disable authentication, authorization, CSRF or input validation, even temporarily.
• Do not run commands against production systems or production databases.
• New external network calls, new dependencies and changes to CI permissions require human review.
• Report suspected vulnerabilities through [SECURITY.md], not in public issues.

Do and don't

Monorepo notes

This repository uses [pnpm workspaces / Nx / Turborepo]. Packages live in packages/ and apps in apps/.

• Run a command in one package: pnpm --filter [package-name] test.
• Find a package name in its package.json name field, not the folder name.
• A nested AGENTS.md (for example apps/web/AGENTS.md) overrides this file for files below it.
• Shared types live in packages/[shared]; changing them requires running the full test suite.

Further reading

• CONTRIBUTING.md for the human contribution process.
• docs/architecture.md for design background.
• SECURITY.md for vulnerability reporting.

Standard and licence note

Based on the open AGENTS.md convention described at agents.md (a plain Markdown file at the repository root, with nested files taking precedence for their subtree) and on common industry practice for contributor documentation. Original text written for this collection. Template licence: MIT.