The template ships with three agent instruction files at the project root: CLAUDE.md, AGENTS.md, and GEMINI.md. These are read automatically by AI coding assistants (Claude Code, Codex, Gemini CLI) when they work in this directory. They give the assistant your project's conventions upfront so you don't have to repeat them in every chat.

• CLAUDE.md — read by Claude Code (Anthropic). Contains package manager rules, Tailwind v4 syntax, color token usage, component patterns, file structure, TypeScript conventions, and commit format.
• AGENTS.md — read by OpenAI Codex agents and similar tools. Identical content to CLAUDE.md, minus Claude-specific identity lines.
• GEMINI.md — read by Gemini CLI. Identical to AGENTS.md.

All three files are kept in sync — the same rules apply regardless of which assistant you use. Only the first-person identity line differs.

Good entries for agent instruction files:

• Package manager — yarn only, never npm
• Styling rules — which color tokens are allowed, which Tailwind classes are deprecated in v4
• Component patterns — use shadcn/ui, use cva for variants, use const arrow functions
• File structure conventions — where services, hooks, types, and actions live
• Naming conventions — PascalCase components, camelCase hooks, ComponentNameProps type names
• Commit format — type + subject + Co-Authored-By footer

What not to put in them:

• File paths that change often — the assistant can read the codebase
• Secrets or API keys — never
• Task-specific instructions — use the chat instead
• Ephemeral context like "currently working on X feature"

When you fork the template and build your product, update all three files together. Typical customizations:

1. Replace the template's color token names with your brand's names if you change them.
2. Add domain-specific conventions (e.g., "all API clients go in services/api/").
3. Document any third-party integrations you've added and their patterns.
4. Remove template rules that no longer apply (e.g., if you remove Polar, remove the payment section).