AGENTS.md example

# Project rules Stack: TypeScript, Next.js, Tailwind CSS, Vitest, pnpm. Follow these rules on every task. If a rule disagrees with existing code, match the code and mention the difference. If a rule disagrees with a direct user instruction, follow the user. ## Working agreement - Read the files you will change before editing them. Do not invent the project layout from memory.- Change only what the task needs. No drive-by refactors, renames, or formatting of untouched lines.- Match the patterns already in the repo over a generic style guide.- Do not add dependencies, config files, or abstractions the task did not ask for.- Do not commit secrets, and do not paste `.env` values, tokens, or private keys into code or chat.- If a requirement is ambiguous, choose the smallest reading, state that assumption, and continue. ## Commands - JavaScript package manager is pnpm. The lockfile to commit is pnpm-lock.yaml. Do not add a second lockfile.- Install: `pnpm install`.- Dev server: `pnpm dev` when that script exists.- Lint: `pnpm lint` when that script exists. Typecheck with the project's typecheck script or `tsc --noEmit` if the repo uses it.- Build: `pnpm build` when you changed a build path.- Tests: `pnpm test`. Single pass, not watch mode: `pnpm exec vitest run`.- Run the narrowest command that checks the change. Do not loop install, build, or the full test suite. ## TypeScript - Leave `strict` on. Do not weaken `tsconfig` to make a build pass.- No new `any`, and no `// @ts-ignore`. Use `unknown` and narrow. `@ts-expect-error` needs a reason on that line.- Match the file's style for `type` versus `interface`. Prefer a string union over a new `enum` unless the file already uses enums.- Use `import type` for type-only imports. Await promises. Do not leave a promise floating.- Do not use a non-null assertion on a value that came from outside the function. Narrow it instead. ## Next.js - Use the App Router. Do not add a `pages/` router unless this repo already has one.- Server Components are the default. Add `"use client"` only for state, effects, browser APIs, or event handlers.- Await `params`, `searchParams`, `cookies()`, `headers()`, and `draftMode()`. On Next.js 15 and later they are async.- Do not assume `fetch` is cached. Add a cache flag or the `use cache` directive only where the surrounding code already does.- Mutations go through Server Actions or route handlers and are validated on the server. Client checks are not the source of truth.- Set metadata with the Metadata API. Use `next/link` for links and `next/image` with width and height, or `fill` plus `sizes`.- Do not import the database or secret env vars into a client component. A module that must stay on the server starts with `import "server-only"`.- Only `NEXT_PUBLIC_` variables may reach client code. Never prefix a secret with `NEXT_PUBLIC_`. ## Tailwind CSS - Style with Tailwind utilities. Do not add a CSS file or a CSS-in-JS library for a one-off.- Tailwind v4 is configured in CSS with `@theme` and usually has no `tailwind.config.js`. Tailwind v3 uses that config file. Do not add the other version's config.- Use the project's color, spacing, and radius tokens. Do not invent a second palette of arbitrary values.- Mobile-first breakpoints. Every control keeps a visible focus style. Icon-only buttons need an accessible name.- If `prettier-plugin-tailwindcss` is installed, let it order classes. Use `dark:` only when the project already has a dark theme. ## Vitest - Put tests next to the code as `*.test.ts`, or in the folder the repo already uses.- Use `describe`, `it`, and `expect`. A test name states the behavior.- Assert on values, text, or roles. Do not snapshot a whole component tree.- Mock only network, time, or the filesystem. Do not mock the function under test.- Run one pass with `vitest run` or the project's test script. Do not leave watch mode running. ## pnpm - pnpm is the package manager. The lockfile is `pnpm-lock.yaml`. Do not commit another JavaScript lockfile.- Add packages with `pnpm add <pkg>` and dev packages with `pnpm add -D <pkg>`. Run scripts with `pnpm <script>`. ## Testing expectations - When you fix a bug, add a test that fails before the fix and passes after, in the repo's current test style.- When you change behavior a caller can observe, update or add a test for that behavior.- Do not test private helpers, framework internals, or third-party libraries. ## Code style - Keep strict type and lint settings on. Do not weaken them to get a green build.- No new `any`, and no empty catch blocks. Prefer `unknown` and narrowing. Handle every fallible call.- Give exported functions an explicit type when the inferred type is not obvious.- Follow the repo formatter. Do not hand-format files the formatter owns.- Do not add comments that restate the code.- Comment only a constraint, invariant, or tradeoff the code itself cannot show.- No file-header banners and no changelog comments. ## Safety - Never commit `.env`, keystores, or credential files. When a new variable is required, add an empty placeholder to the example env file.- Do not disable authentication, authorization, or TLS checks to make a test pass.- Do not force-push, `reset --hard`, drop a database, or delete a directory tree unless the user asked for that exact action.- Do not edit vendored or generated output (`node_modules`, `dist`, `.next`, `vendor`, `Library`, `.godot`). Change the source and regenerate. ## Done when - The change does what was asked and nothing extra.- New or changed behavior is covered at the level in Testing expectations.- The commands in this file that apply to the touched files have been run, or you say which command you could not run.- The diff has no unrelated files, lockfile churn, or secrets.