Overview
AGENTS.md is the instruction file that governs how AI coding agents (Claude, Copilot, Cursor, etc.) behave when working inside the NextAdmin codebase.
It acts as a contract between the project and any AI agent touching it. Before an agent writes a single line of code, it should already know the folder layout, the styling rules, the component patterns, and the hard boundaries it isn't allowed to cross. This keeps AI-generated contributions indistinguishable in quality and convention from hand-written ones.
Purpose
AGENTS.md exists to:
- Define where things live in the codebase, so agents don't guess at file placement
- Standardize component architecture (composition, typing, file splitting)
- Lock in styling rules so no agent introduces hardcoded colors or one-off CSS
- Point agents to project-specific skills for API integration and accessible components
- Draw explicit boundaries - package installs, primitive overwrites, CSS utilities - that require human sign-off
Keeping these rules in one file means the team updates AI behavior in one place instead of re-explaining conventions in every prompt.
What's Inside
| Section | Key Rule |
|---|---|
| Project Structure | Route groups under (with-layouts); kebab-case files, PascalCase exports; drill into folders rather than assume |
| Next.js | Breaking changes vs. training data - check node_modules/next/dist/docs/ first |
| Conventions | Client Components by default, SSR only for layout.tsx |
| Styling | Semantic Tailwind tokens only - no hardcoded hex, no new CSS utility classes |
| Components | No monolithic files - split into single-responsibility sub-components with typed props; use tailgrids/core primitives; no raw SVG icons |
| Data & State | API calls via the api-integration skill; state via context/URL params, no new libraries |
| Forms/Charts/Tables | React Aria + Sonner for forms, Recharts in ChartContainer with unique gradient IDs, TanStack Table with flexRender |
| Don'ts | No new packages, no overwriting tailgrids/core primitives, no new CSS classes, no pages outside (with-layouts) - without asking first |
Maintaining This File
Update AGENTS.md whenever the folder structure, primitives, or conventions change - stale rules lead agents to confidently produce inconsistent code.
