# AI Agentic Development

> Use the built-in AI rules, Claude skills, and MCP config shipped with the TanStack Start Drizzle SaaS Kit.

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/installation/ai-agents*

---

The repo ships with AI-facing project context for Claude Code, Codex, Cursor, Gemini, and other agents that read repo instructions automatically.

## Included Files

| File | Purpose |
|------|---------|
| `AGENTS.md` | Main project rules and repo conventions |
| `CLAUDE.md` | Claude entrypoint that references `AGENTS.md` |
| `GEMINI.md` | Gemini-specific instructions |
| `.claude/` | Claude commands, skills, and local settings |
| `.mcp.json` | MCP server wiring for tools that support it |

## Claude Setup

The repo includes:

```text
.claude/
├── agents/
│   └── code-quality-reviewer.md
├── commands/
│   └── implement.md
├── skills/
│   ├── bug-hunt/
│   ├── bug-hunt-lite/
│   ├── drizzle-expert/
│   ├── frontend-design/
│   ├── playwright-e2e-expert/
│   ├── react-form-builder/
│   └── reviewer/
└── settings.local.json
```

These skills are specific to Claude Code. Other agents can still use `AGENTS.md` and the MCP server.

## Useful Repo References for Agents

When you customize prompts or rules, point agents at real code paths in this repo:

- server/API routes: `apps/web/src/routes/api/...`
- authenticated pages: `apps/web/src/routes/_authenticated/...`
- public pages: `apps/web/src/routes/_public/...`
- auth pages: `apps/web/src/routes/auth/...`
- app components: `apps/web/src/components/...`
- server functions and loaders: `apps/web/src/lib/...`
- schema and migrations: `packages/database/src/schema/`
- UI components: `packages/ui/src/`

Avoid referencing legacy Next.js paths like `apps/web/app/[locale]/...` or `apps/web/app/home/[account]/...`; they are not part of this codebase.

## Verification Commands

The repo exposes these main checks:

```bash
pnpm healthcheck
pnpm test:unit
```

Today `pnpm healthcheck` runs linting, formatting, type-checking, and `manypkg fix`. It does **not** run unit tests, so keep `pnpm test:unit` separate.

## MCP Integration

If your agent supports MCP, use the built-in config in `.mcp.json` together with the local MCP server described in [MCP Server](./mcp-server).

## Common Pitfalls

- Assuming every agent understands Claude skills. Only Claude uses `.claude/skills`.
- Treating `pnpm healthcheck` as a full test command. Run `pnpm test:unit` separately.
- Pointing custom instructions at old Next.js route trees (`apps/web/app/[locale]/...`); routes now live in `apps/web/src/routes/...`.

---

**Next:** [MCP Server →](./mcp-server)