AI Agentic Development | React Router Supabase Turbo

The kit ships with pre-configured agent rules for Claude Code, Cursor, Windsurf, Codex, and Gemini. These rules teach AI agents the codebase patterns, monorepo structure, and MakerKit conventions so they generate code that fits your project.

Agent Configuration Files

MakerKit uses a hierarchical system of instruction files. Global rules live at the project root, and package-specific rules live in subdirectories.

File Locations

Hierarchical Structure

AI agents read instructions from multiple files based on context. When you work in apps/web, the agent reads:

1. Root AGENTS.md (global patterns, commands, tech stack)
2. apps/web/AGENTS.md (route organization, component patterns)
3. apps/web/supabase/AGENTS.md (database migrations, RLS policies)

This hierarchy means agents get more specific instructions as they work deeper in the codebase.

AGENTS.md                          # Global: tech stack, commands, patterns
├── apps/web/AGENTS.md             # App: routes, components, config files
│   ├── apps/web/supabase/AGENTS.md    # Database: schemas, migrations, RLS
│   └── apps/web/app/admin/AGENTS.md   # Admin: super admin features
├── packages/ui/AGENTS.md          # UI: components, design system
├── packages/supabase/AGENTS.md    # Supabase: clients, auth, types
├── packages/features/AGENTS.md    # Features: feature packages

What Agents Learn

The root AGENTS.md teaches agents:

• Tech stack: React Router 7, React 19, Supabase, Tailwind CSS 4, Turborepo
• Multi-tenant architecture: Personal accounts vs team accounts, account_id foreign keys
• Essential commands: pnpm dev, pnpm typecheck, pnpm supabase:web:reset
• Authorization: RLS enforces access control, admin client bypasses RLS

Package-specific files add context for that area:

# packages/supabase/AGENTS.md
## Client Usage
### Server Components (Preferred)
import { getSupabaseServerClient } from '@kit/supabase/server-client';
const client = getSupabaseServerClient();
// RLS automatically enforced
### Admin Client (Use Sparingly)
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';
// CRITICAL: Bypasses RLS - validate manually!

Editor Configuration

Claude Code

Claude Code reads CLAUDE.md files automatically. The root file references @AGENTS.md to include those instructions.

No configuration needed. Start Claude Code in your project directory:

claude

Claude Code discovers and reads the instruction files on startup.

Cursor

Cursor reads AGENTS.md files automatically when you open a project. The agent instructions appear in context when you use Cursor's AI features.

For the best experience:

1. Open the project root in Cursor (not a subdirectory)
2. The agent rules load automatically
3. Use Cmd+K or the chat panel to interact with the agent

Windsurf

Windsurf uses the same AGENTS.md files as Cursor. Open your project and the rules apply automatically.

Codex

Codex reads AGENTS.md files. Open the project root and the agent instructions apply to generated code.

Gemini

Gemini reads from .gemini/GEMINI.md. This file points to the AGENTS.md files:

# .gemini/GEMINI.md
- Check for the presence of AGENTS.md files in the project workspace
- There may be additional AGENTS.md in sub-folders with additional specific instructions

MCP Server (Optional)

The Makerkit MCP Server gives AI agents additional tools for working with the codebase. See the MCP Server documentation for setup instructions.

MCP tools help agents:

• Understand the project structure
• Navigate between related files
• Apply MakerKit-specific patterns

Customizing Rules

The default rules cover MakerKit patterns. Add your own rules for application-specific logic.

Adding Business Logic Rules

Create or edit AGENTS.md files to include your domain knowledge:

# apps/web/AGENTS.md (add to existing file)
## Business Logic
### Subscription Tiers
- Free: 1 team member, 3 projects
- Pro: 10 team members, unlimited projects
- Enterprise: Unlimited everything, SSO
### Project Limits
Check limits before creating projects:
- Use `checkProjectLimit(accountId)` from `~/lib/server/projects`
- Returns { allowed: boolean, current: number, limit: number }
### Naming Conventions
- Projects use kebab-case slugs: "my-project-name"
- Team accounts use slugs, not IDs, in URLs

Adding Feature Flags

Document which features are gated:

## Feature Flags
Check `config/feature-flags.config.ts` for current flags:
- `enableTeamCreation`: Users can create teams
- `enableBilling`: Subscription billing enabled
- `enableAI`: AI features available
Use in components:
import { useFeatureFlags } from '@kit/shared/feature-flags';
const { enableAI } = useFeatureFlags();

Claude Code Directory Structure

Claude Code uses a .claude/ directory for additional configuration:

.claude/
├── agents/               # Custom agent definitions
│   └── code-quality-reviewer.md
├── commands/             # Slash commands
│   └── feature-builder.md
├── evals/                # Evaluation scripts
├── skills/               # Reusable skills
│   ├── playwright-e2e/
│   ├── postgres-expert/
│   ├── react-form-builder/
│   └── server-action-builder/
└── settings.local.json   # Local permissions (git-ignored)

Built-in Skills

The kit includes skills for Claude Code that provide specialized guidance for common tasks.

Skills don't activate automatically. Type /skill-name at the start of your message when you need specialized guidance.

Using Skills

Invoke a skill by typing its command at the start of your message:

/postgres-supabase-expert Create a projects table with RLS policies for team access

/server-action-builder Create an action to update user settings

Feature Builder Command

The /feature-builder command orchestrates multiple skills for end-to-end feature implementation:

/feature-builder Add a projects feature with CRUD operations

This command guides you through:

1. Database schema with /postgres-supabase-expert
2. Forms with /react-form-builder

Adding External Skills

The Agent Skills project provides additional skills you can install:

npx add-skill vercel-labs/agent-skills

Available skills:

• react-best-practices: Performance optimization guidelines from Vercel Engineering (40+ rules across 8 categories)
• web-design-guidelines: UI audit with accessibility checks (100+ rules covering accessibility, performance, UX)
• vercel-deploy-claimable: Deploy directly from conversations with live preview URLs

Verification Workflow

Agents are instructed to run verification after making changes:

pnpm typecheck        # Must pass
pnpm lint:fix         # Auto-fix issues
pnpm format:fix       # Format code

If an agent skips verification, remind it:

Run typecheck and lint:fix to verify the changes

Common Patterns Agents Know

Database Queries

Agents prefer Server Components with the standard client:

import { getSupabaseServerClient } from '@kit/supabase/server-client';
async function ProjectList() {
  const client = getSupabaseServerClient();
  const { data } = await client.from('projects').select('*');
  // RLS enforced automatically
}

Best Practices for Using AI Agents

After extensive use of AI agents with MakerKit, we've identified what works:

Keep AGENTS.md Files Focused

Long instruction files cause context drift where agents forget earlier rules. Keep each file under 500 lines. Split by concern rather than cramming everything into the root file.

Use Rules as a Router

Rather than documenting every API, tell agents where to find things:

## Where to Look
- Need a UI component? Check `packages/ui/src/` first
- Building a form? See `packages/ui/src/shadcn/form.tsx` for patterns
- Adding a Server Action? Reference `apps/web/app/home/_lib/server/`

Agents are excellent at reading code once they know where to look.

Explicit Constraints Beat Implicit Conventions

"Always use enhanceAction" works better than "We prefer using enhanceAction for most cases." Agents follow explicit rules; they guess at preferences.

Let Agents Learn from Your Codebase

With a consistent codebase like MakerKit, agents pick up patterns automatically. You don't need to document that Server Components fetch data or that forms use Zod. Focus your rules on project-specific decisions and gotchas.

Troubleshooting

Agent Ignores Rules

1. Verify files exist at the expected locations
2. Check file names match exactly (case-sensitive)
3. Restart your editor to reload configuration

Agent Generates Wrong Patterns

Add explicit examples to your AGENTS.md when you notice the agent is generating code that doesn't match your patterns.

Agent Misunderstands Structure

Add a quick reference section:

## Quick Reference
- App routes: `apps/web/app/`
- Shared components: `packages/ui/src/`
- Database schemas: `apps/web/supabase/schemas/`
- Feature packages: `packages/features/*/`

Next Steps

• Configure the MCP Server for enhanced agent capabilities
• Add LLM rules for additional context from documentation
• Review conventions to understand the patterns agents follow