AI Agents

Overview

This template includes comprehensive configuration for multiple AI coding assistants. All agents are pre-configured with project-specific context and development rules to help you build faster while maintaining code quality and consistency.

Supported Agents

The following AI coding assistants have dedicated configuration files:

General Configuration

The AGENTS.md file in the project root provides context for all AI assistants, serving as a fallback for agents not explicitly configured.

What Agents Know

All configured agents have access to:

Documentation Reference

Agents are instructed to consult these core documentation files:

Scaffolding Templates

Agents can reference step-by-step templates in /docs/template/:

Tech Stack

Agents are configured to work with:

• Framework: Next.js 16+ (App Router)
• Database: PostgreSQL + Drizzle ORM
• API: tRPC (type-safe)
• Auth: Better-Auth
• UI: Shadcn UI + Tailwind CSS
• Forms: React Hook Form + Zod
• State: React Query (via tRPC)

Critical Rules

All agents follow these strict conventions to maintain code quality and consistency.

ALWAYS

1. Read /docs first - Check documentation before implementation
2. Use type not interface - TypeScript type definitions only
3. Use double quotes - Prefer " over ' for strings
4. Use Shadcn UI components - Import from @/components/ui
5. Use <Icon iconKey="..." /> - Never import from lucide-react directly
6. Use declarative routing - <PageHome.Link /> or PageHome() for navigation
7. Use createDrizzleOperations - For standard CRUD operations
8. Follow 5-file pattern - schema.ts, functions.ts, fields.tsx, hooks.ts, prompts.tsx

NEVER

1. Generate summary .md files - Unless explicitly requested
2. Use raw Drizzle queries - Unless complex joins necessary
3. Use revalidatePath with tRPC - Use client-side invalidation instead
4. Use <p> or <h1> directly - Use P, H1-H6 components from @/components/ui/typography
5. Use container class - Use Section component with variants
6. Use arbitrary Tailwind values - Avoid w-[100px] patterns, use design tokens

Agent Workflow

All agents follow this structured workflow:

graph TD
    A[Receive Request] --> B[Read /docs Documentation]
    B --> C[Check Similar Patterns in src/features]
    C --> D[Apply Project Conventions]
    D --> E[Implement Changes]
    E --> F[Verify Each Part]

1. Understand

• Read relevant documentation in /docs
• Understand the task requirements
• Identify which patterns apply

2. Check Patterns

• Look at similar features in src/features/
• Reference existing implementations
• Follow established conventions

3. Follow Conventions

• Apply critical rules (ALWAYS/NEVER)
• Use correct import paths
• Follow file naming conventions
• Use proper TypeScript patterns

4. Implement

• Build step by step
• Verify each part works
• Run type checking
• Ensure consistency

Agent-Specific Features

Claude Code

Location: .claude/commands/

Custom slash commands for common tasks:

• /new-feature - Create a new feature module
• /new-page - Create a new page with routing
• /add-table - Add a database table
• /add-translation - Add i18n keys

Cursor

Location: .cursor/rules/

Project-specific rules that guide Cursor's AI:

• File organization patterns
• Import conventions
• Component structure
• Database operation patterns

Windsurf

Location: .windsurfrules

Single configuration file with:

• Development guidelines
• Code style rules
• Project structure understanding

GitHub Copilot

Location: .github/copilot-instructions.md

Instructions that appear in Copilot's context:

• Quick reference of critical rules
• Links to documentation
• Common patterns

Antigravity

Location: .agent/rules/

Google Antigravity agent configuration:

• Project conventions
• Architectural patterns
• Best practices

Working with Agents

Best Practices

1. Be specific - Clear requests get better results
2. Reference docs - Mention which pattern or template to follow
3. Review changes - Always review agent-generated code
4. Iterate - Ask for adjustments if needed
5. Stay consistent - Agents maintain project conventions

Example Requests

Good requests:

Create a new feature for managing teams following the 5-file pattern.

Add a page at /dashboard/settings following the declarative routing setup.

Create a database table for projects with timestamps and soft delete.

Less effective requests:

Make a teams feature (too vague)

Add a settings page (doesn't specify patterns)

Create a projects table (missing requirements)

When Agents Help Most

Agents excel at:

• Creating boilerplate following established patterns
• Implementing CRUD operations with standard abstractions
• Adding translations across multiple locales
• Refactoring code to match conventions
• Generating type-safe API routes

Agents may need guidance for:

• Complex business logic
• Performance optimization decisions
• Architecture changes
• Security-critical code

Configuration Maintenance

Updating Agent Rules

All agent configuration files are version-controlled. To update:

1. Edit the relevant config file (e.g., .cursor/rules/)
2. Test with the agent
3. Commit changes

Keeping Documentation in Sync

When you update project patterns:

1. Update /docs files first
2. Agent configurations reference /docs, so they stay current automatically
3. Update agent-specific commands/rules if needed

Adding New Conventions

When adding new conventions:

1. Document in /docs
2. Update AGENTS.md critical rules
3. Test with agents
4. Update agent-specific configs if needed

Troubleshooting

Agent Not Following Conventions

1. Check if /docs documentation is clear
2. Verify agent has access to config files
3. Be more explicit in your request
4. Reference specific docs in your prompt

Agent Creating Incorrect Patterns

1. Point agent to relevant /docs file
2. Show example from src/features/
3. Ask agent to review and fix

Agent Missing Context

1. Ensure you're in the project workspace
2. Check config file location for your agent
3. Explicitly mention pattern to follow

Next Steps

• Commands - Learn available npm scripts
• Best Practices - Development conventions
• Templates - Step-by-step task guides
• Patterns - Feature development patterns