AGENTS.md Generator

Generator / Templates / Next.js + Supabase

AGENTS.md for Next.js + Supabase

Next.js App Router on Supabase with Row Level Security. This AGENTS.md template combines 136 rules from 16 packs and runs to 185 lines.

Open this template in the AGENTS.md generator

What is inside

The generated AGENTS.md

This is the file the generator produces for the Next.js + Supabase preset, before you add your project name and commands.

# AGENTS.md

## Agent behavior

- For changes touching more than three files, outline the plan and wait for confirmation before editing.
- Ask a clarifying question when requirements are ambiguous instead of guessing.
- Keep diffs small and focused on the request; do not refactor unrelated code.
- Run the relevant tests, linter and type checker before reporting a task as done, and report failures honestly.
- Never delete, skip or loosen a failing test to make it pass; fix the cause.
- Do not add new dependencies without explicit approval; prefer the standard library and existing packages.
- Do not edit generated or vendored files; change the source and regenerate.
- Never read, print or commit secrets, .env files or credentials.
- Read the relevant code and tests before proposing a change; do not edit files you have not read.
- Fix the root cause rather than suppressing the symptom with a workaround or silenced warning.
- Do not add lint or type suppressions to get a clean run; fix the underlying issue.
- Report failing tests, skipped steps and unverified claims plainly; never claim success without evidence.
- Verify library APIs in the installed version or its docs before using them; do not invent functions.
- Do not change public behavior, file formats or APIs unless the task asks for it.
- Never hardcode values or special-case inputs to satisfy a test.
- If an approach fails twice, stop and ask instead of trying increasingly invasive workarounds.
- Before editing a directory, read the nearest AGENTS.md and follow it over the root file where they differ.
- Preserve unrelated working tree changes. Never revert or rewrite edits you did not make.

## Design system and UI

- Use design tokens for colors, spacing, typography and radii; never hardcode them.
- Reuse existing components before creating new ones; extend variants instead of duplicating.
- Meet WCAG 2.1 AA: semantic HTML, visible focus, keyboard operability, sufficient contrast, labelled controls.
- Design mobile-first and verify layouts at phone, tablet and desktop widths.
- Handle loading, empty, error and disabled states for every data-driven view.
- Use the spacing scale for margins and padding; no one-off pixel values.
- Use the typography scale for sizes and weights.
- Add a variant or prop to an existing component instead of copying it.
- Use semantic color tokens (text-primary, surface) instead of palette values in components.

## Testing

- Add or update tests for every behavior change and bug fix.
- For bug fixes, write a failing test that reproduces the bug before fixing it.
- Prefer many fast unit tests, fewer integration tests and a small number of end-to-end tests.
- Mock only external boundaries (network, clock, filesystem); use real collaborators otherwise.
- Keep tests deterministic: no real time, randomness or network without control.
- Keep tests independent; no shared mutable state or required execution order.
- Structure tests as arrange, act, assert with one behavior per test.
- Build test data with small factories instead of large shared fixtures.
- Treat a flaky test as a bug: find the cause instead of adding retries or sleeps.
- Use snapshot tests only for small stable outputs and review snapshot diffs carefully.
- Test public behavior rather than private functions or implementation details.
- Make assertions specific enough that the test fails if the behavior breaks.

## Git and pull requests

- Write commit messages in Conventional Commits format (feat:, fix:, docs:, refactor:, test:, chore:) and mark breaking changes with ! or a BREAKING CHANGE footer.
- Keep pull requests small and focused on one change.
- Write commit subjects in the imperative mood, 72 characters or fewer.
- Never force-push to shared branches and never rewrite published history.
- Run lint, type check and tests before committing.
- Never commit secrets, build output or large binaries.
- Describe motivation, approach and testing in the pull request description.
- Make each commit one logical change that builds and passes tests.
- Do not amend or rebase commits that are already pushed to a shared branch.
- Add build output, local env files and editor files to .gitignore instead of committing them.
- Open pull requests only when CI is green and the diff is self-reviewed.
- Never bypass commit hooks or signing with --no-verify unless explicitly instructed.

## Security

- Load secrets from environment variables or a secret manager; never hardcode them.
- Use parameterized queries and safe APIs; never build SQL, shell commands or HTML by string concatenation with user input.
- Enforce authentication and authorization on the server for every protected operation.
- Pin dependency versions, commit lockfiles and review new packages before adding them.
- Grant the minimum permissions needed for tokens, service accounts and containers.
- Use well-reviewed cryptographic libraries; never invent your own algorithms or store plain passwords.
- Encode output for its context and avoid injecting raw HTML; sanitize rich text with a vetted library.
- Protect state-changing browser requests with CSRF tokens or SameSite cookies.
- Configure CORS with explicit origins; never reflect arbitrary origins with credentials.
- Use HttpOnly, Secure, SameSite cookies and rotate session identifiers on login.
- Validate and allow-list URLs before fetching user-supplied addresses to prevent SSRF.
- Hash passwords with Argon2id, or scrypt or bcrypt where it is unavailable, with a unique salt; never use fast hashes such as SHA-256.
- Run secret scanning in CI and rotate any credential that has been exposed.
- Validate untrusted input against a schema. Never run eval, exec or unpickling on it.

## Workflow and tooling

- Run tools through the project scripts (npm run, make, task) instead of invoking underlying binaries directly, so flags and environments match CI.
- Run the single aggregate check command (for example pre-commit or a lint script) before finishing; fix every failure and re-run until it passes.
- Run the specific test files related to your change first, and run the full suite only before handing off.
- Before editing a directory, read the README and any nested AGENTS.md that applies to it.
- Put throwaway scripts and experiment output in a gitignored scratch directory and delete them when done.
- After switching branches or pulling dependency changes, reinstall and rebuild before running tests.
- When CI fails, find the exact failing job and command, reproduce it locally, then fix the cause instead of re-running blindly.
- Stop any dev servers or watchers you started once you are done.
- Ask before running destructive or irreversible commands such as dropping databases, deleting branches, rm -rf or force operations.
- Prefer existing scripts, generators and templates in the repo over writing new ad hoc tooling.
- When the repository documents skills or runbooks for a task (migrations, releases, dependency bumps), follow them instead of improvising.
- Never start long-running dev servers or watchers in the foreground. Use targeted one-shot commands.

## Verification and CI feedback

- Run the narrowest relevant test first, then widen to the package and workspace checks as confidence grows.
- Run the project formatter and linter on changed files before committing, using the repo scripts or hooks.
- For a bug fix, reproduce the failure first, then show the regression test failing without the fix and passing with it.
- Report a task as done only after running the checks that prove it. If you could not run them, say so.
- Before finishing, re-read the full diff as a reviewer with no knowledge of this session and fix what would confuse them.

## TypeScript conventions

- Enable "strict" in tsconfig and keep it on.
- Do not use any; use unknown and narrow, or model the type properly.
- Validate untrusted data at runtime with a schema library instead of casting.
- Avoid non-null assertions (!) and unchecked type assertions (as).
- Model variants with discriminated unions and exhaustive switch checks.
- Do not use @ts-ignore; use @ts-expect-error with a reason only when unavoidable.

## React conventions

- Use function components and hooks; do not write class components.
- Follow the Rules of Hooks and keep effect dependency arrays exhaustive.
- Derive values during render instead of duplicating them in state or syncing them with effects.
- Use stable unique keys for lists, never array indexes for dynamic lists.
- Test components through user-visible behavior with React Testing Library, not implementation details.
- Do not add useMemo, useCallback or memo by default; rely on React Compiler where enabled and memoize by hand only for measured cost or stable effect dependencies.
- Prefer composition (children, slots) over long prop lists and boolean flags.
- Keep each input either controlled or uncontrolled, never switching between them.
- Use effects only to synchronize with external systems, not for data transformation.

## shadcn/ui and Radix conventions

- Treat components added by the shadcn CLI as project code: edit them in place and keep them in the shared ui folder.
- Merge conditional classes with the cn helper (clsx plus tailwind-merge) so later classes override earlier ones.
- Express component variants with class-variance-authority instead of ad hoc conditionals.
- Do not strip Radix primitives, roles or keyboard handling when restyling; extend them through props and asChild.
- Change colors and radii through the theme CSS variables rather than editing utility classes in each component.

## React Hook Form and Zod conventions

- Define one Zod schema per form, infer the TypeScript type from it and connect it with zodResolver.
- Re-validate submitted data on the server with the same schema; client validation is only a convenience.
- Pass defaultValues for every field so inputs stay controlled consistently and reset works.
- Render field errors next to the input, link them with aria-describedby and set aria-invalid.

## Next.js conventions

- Use the App Router; keep components server components by default.
- Add "use client" only to the smallest components that need interactivity or browser APIs.
- Fetch data in server components or route handlers, not in client effects.
- Expose only NEXT_PUBLIC_ variables to the browser, remember they are inlined at build time, and never put secrets in them.
- Define page metadata with the Metadata API.
- Treat server actions as public endpoints: authenticate, authorize and validate input inside every action, and return only the data the UI needs.
- Fetches are not cached by default in Next.js 15 and later; opt in with cache: 'force-cache' or revalidate, and set caching explicitly per fetch and route.
- Validate route handler input and return typed JSON with correct status codes.

## Tailwind CSS conventions

- Style with utility classes; extract components rather than long @apply blocks.
- Define colors, spacing and fonts in the Tailwind theme and use them instead of arbitrary values.
- Use responsive, dark and state variants instead of custom media queries.
- Do not build class names by interpolation such as text-${color}-600; map values to complete class names so Tailwind can detect them.
- Extract repeated utility groups into components, not into custom CSS.

## PostgreSQL and SQL conventions

- Change the schema only through versioned migrations that can run on production data.
- Index foreign keys and frequently filtered columns, and check query plans with EXPLAIN.
- Enforce NOT NULL, UNIQUE, CHECK and foreign key constraints in the schema.
- Wrap multi-statement changes in transactions and keep them short.
- Use timestamptz for time values and store them in UTC.
- Create indexes on large tables with CREATE INDEX CONCURRENTLY.
- Use a connection pool and size it to the database limits.

## Supabase conventions

- Enable Row Level Security on every table in an exposed schema and write explicit policies.
- Never ship the secret key (the legacy service_role key) to a browser or mobile app; it bypasses Row Level Security, so use it only on trusted servers.
- Base policies on auth.uid() and verify ownership in the policy, not only in the client.
- Change the schema through versioned migrations from the Supabase CLI, not in the dashboard.
- Generate TypeScript types from the database schema and use them in the client.

## Authentication and sessions conventions

- Use a vetted identity provider or library instead of building authentication from scratch.
- Keep JWTs short-lived, verify signature, issuer and audience, and never store sensitive data in them.
- Rotate refresh tokens and revoke them on logout and password change.
- Rate limit login and password reset endpoints and avoid user enumeration in responses.
- Use the authorization code flow with PKCE and validate the state parameter.

How to use it

Related guides

More AGENTS.md templates