Specialized agents

The concept

By default, Claude Code is a generalist. It can do everything, but without specific instructions, it can make inconsistent choices: using the wrong color palette, putting a file in the wrong place, or forgetting a business rule.

Specialized agents solve this problem. Each agent is briefed on its domain: which files it touches, which rules it follows, how it verifies its work.

The analogy: instead of having a single employee who does everything (cooking, serving, accounting, cleaning), you have a head chef, a server, an accountant, and a janitor. Each one excels in their specialty and knows their rules.

How to create them

1. Create the folder

Create a .claude/commands/ folder at the root of your project. Each .md file in this folder automatically becomes a slash command.

your-project/
  .claude/
    commands/
      front.md       → /front (interface agent)
      back.md        → /back (business logic agent)
      database.md    → /database (database agent)
      qa.md          → /qa (quality agent)
      orchestrate.md → /orchestrate (project lead)

2. Structure of an agent file

Each file answers 4 questions:

1. Who are you? The role and specialty
2. What do you work on? The relevant files and folders
3. What rules do you follow? The domain-specific conventions
4. How do you verify? The validation commands

The 6 standard agents for a SaaS

Frontend Agent, /front

Handles everything visible: pages, components, layouts, design.

# /front - Frontend Agent

You are the frontend agent. You handle UI components,
pages, layouts and the design system.

## Scope
- src/app/ (all pages and layouts)
- src/components/ (reusable components)
- src/app/globals.css (global styles)

## Palette
- Primary: #E8634A - buttons, active links
- Background: #FFFBF7 - page background
- NEVER use colors outside the palette

## Rules
- Server Components by default
- shadcn/ui for all base components
- Interface in English with proper grammar
- One component per file, kebab-case

## Verification
After each change: npm run typecheck && npm run lint

Backend Agent, /back

Handles business logic, APIs, authentication.

# /back - Backend Agent

You are the backend agent. You handle Server Actions,
business logic, and integrations.

## Scope
- src/lib/actions/ (Server Actions)
- src/lib/validators/ (Zod schemas)
- src/app/api/ (API routes)
- src/middleware.ts

## Rules
- Every mutation goes through a Server Action, not an API route
- Zod validation required on every input
- Check authentication in every action
- Never expose an API key on the client side

## Verification
After each change: npm run typecheck && npm run lint

Database Agent, /database

Handles SQL schema, migrations, and security (RLS).

# /database - Database Agent

You are the database agent. You handle the PostgreSQL schema,
migrations, and RLS policies.

## Scope
- supabase/migrations/ (numbered SQL files)
- src/lib/types/database.types.ts (auto-generated types)

## Rules
- Any change → new numbered SQL migration
- RLS enabled on every table, filtered by organization_id
- NEVER use supabase db reset

## Verification
npx supabase migration up --local
npx supabase gen types typescript --local > src/lib/types/database.types.ts
npm run typecheck

AI Agent, /ia

Handles AI API integration, prompts, streaming.

# /ia - AI Agent

You are the AI agent. You handle Claude API integration,
prompts, and streaming.

## Scope
- src/lib/ai/ (client, prompts, rate-limit)
- src/app/api/ai/ (AI endpoints)

## Rules
- Always server side, NEVER expose the API key
- Streaming via the Anthropic SDK
- Usage tracking in ai_usage after every call
- Rate limiting per user plan

QA Agent, /qa

Handles tests, lint, typecheck.

# /qa - Quality Agent

You are the QA agent. You handle tests and code quality.

## Quality Gates
| Gate | Command | When |
|------|---------|------|
| TypeScript | npm run typecheck | After each change |
| Lint | npm run lint | After each change |
| Unit Tests | npm run test | Before commit |
| Build | npm run build | Before deploy |

## Rules
- Unit tests for all business logic
- No tests for trivial boilerplate
- Minimum coverage: 80% on critical modules

Orchestrator Agent, /orchestrate

Coordinates all the other agents. The project lead.

# /orchestrate - Project Lead

You supervise all agents and the workflow.

## Workflow
1. Read the plan in docs/plans/
2. Dispatch tasks to agents
3. Independent tasks → in parallel
4. Dependent tasks → sequential
5. Check typecheck + lint after each group

## Quality Gates
- TypeScript: 0 errors
- Lint: 0 errors
- Build: success
- Tests: all pass

How to use the agents

You type the slash command in the chat, followed by your request:

/front Create a notification banner component that shows a temporary message at the top of the page, with a close button and a slide-in animation.

The /front agent automatically knows it should:

• Work in src/components/
• Use the project palette
• Use shadcn/ui
• Verify with typecheck + lint afterward

Without the agent, you would have had to spell all that out in your prompt.

When to use which agent

Create your own agents

You're not limited to the 6 agents above. Create agents for any recurring need:

• /email: to generate email templates with the right tone
• /seo: to optimize meta tags and content
• /security: to audit vulnerabilities
• /deploy: for production rollout checklists
• /content: to generate marketing content aligned with your brand

The rule: if you repeat the same instructions more than 3 times, create an agent.

Sub-agents: beyond slash commands

Slash commands (/front, /back) are your manual workflows. You type, off it goes. Sub-agents work the other way around: you describe a goal, Claude delegates to one or more agents that run in parallel, each in its own isolated context.

The difference in one line:

• Command-agent (/front): you drive, the agent executes your precise request.
• Sub-agent: Claude dispatches several agents in parallel, each with its own memory, files, result.

The Task tool and worktree isolation

To launch a sub-agent, Claude uses the Task tool. The key option is isolation: "worktree". Each sub-agent gets its own git worktree, a separate copy of the repo on a dedicated branch. Two agents can modify the same file without conflicts, since they work in different folders.

Without a worktree, two agents writing to app/page.tsx at the same time trip over each other. With worktrees, each has its sandbox, you merge at the end.

When to use what

The rule: sub-agent when tasks are independent. If they step on each other, stick to sequential via command.

Example: translate 3 articles from FR to EN

Three MDX articles to translate, each independent of the others. Perfect for 3 sub-agents in parallel, each on its own worktree.

Dispatch pseudo-code:

Task({
  description: "Translate article 1",
  prompt:
    "Translate content/fr/article-1.mdx to content/en/article-1.mdx. Keep MDX structure and frontmatter. Use an informal tone.",
  isolation: "worktree",
});

Task({
  description: "Translate article 2",
  prompt:
    "Translate content/fr/article-2.mdx to content/en/article-2.mdx. Same rules.",
  isolation: "worktree",
});

Task({
  description: "Translate article 3",
  prompt:
    "Translate content/fr/article-3.mdx to content/en/article-3.mdx. Same rules.",
  isolation: "worktree",
});

The 3 run in parallel, each writes its file in its worktree. At the end, Claude merges the results back into the main context. Time divided by 3 versus sequential.