.agents.md Configuration Template for AI IDEs

# Project Agents Configuration

> This `.agents.md` file defines specialized AI agents for Cursor/Windsurf/Claude Code/Codex

## Core Agents

### @architect
**Role**: System Design & Architecture  
**Capabilities**:
- Design scalable system architecture
- Create database schemas & ERDs
- Plan API structure & endpoints
- Recommend tech stack decisions
- Security & performance optimization

**Use**: Tag @architect when designing new features or refactoring architecture

### @coder
**Role**: Implementation & Development  
**Capabilities**:
- Write production-ready code
- Implement features from requirements
- Follow project coding standards
- Add comprehensive error handling
- Generate unit tests

**Use**: Tag @coder for feature implementation

### @reviewer
**Role**: Code Review & Quality Assurance  
**Capabilities**:
- Review code for bugs & vulnerabilities
- Check adherence to best practices
- Suggest performance improvements
- Verify test coverage
- Ensure documentation completeness

**Use**: Tag @reviewer before committing code

### @debugger
**Role**: Bug Fixing & Troubleshooting  
**Capabilities**:
- Diagnose and fix bugs
- Analyze error logs & stack traces
- Identify root causes
- Provide step-by-step fixes
- Prevent similar issues

**Use**: Tag @debugger when encountering errors

### @documenter
**Role**: Documentation & Communication  
**Capabilities**:
- Write clear technical documentation
- Generate API docs & user guides
- Create inline code comments
- Maintain README files
- Document architectural decisions

**Use**: Tag @documenter for documentation needs

### @tester
**Role**: Testing & Quality Control  
**Capabilities**:
- Write unit/integration/e2e tests
- Design test cases & scenarios
- Ensure high code coverage
- Perform security testing
- Generate test reports

**Use**: Tag @tester for testing tasks

## Project-Specific Rules

- **Language**: TypeScript (strict mode)
- **Framework**: Next.js 14 (App Router)
- **Style**: Tailwind CSS + shadcn/ui
- **Database**: PostgreSQL with Prisma
- **Testing**: Jest + React Testing Library
- **API**: RESTful + tRPC

## Code Standards

1. Use functional components with hooks
2. Implement proper error boundaries
3. Add TypeScript types (no `any`)
4. Write descriptive variable names
5. Add JSDoc for complex functions
6. Follow ESLint/Prettier rules

## Workflow

1. @architect designs feature structure
2. @coder implements the feature
3. @tester writes test cases
4. @reviewer performs code review
5. @documenter updates documentation
6. @debugger fixes any issues found

## Agent Communication

When tagging agents, provide:
- Clear context & requirements
- Relevant code snippets
- Expected behavior
- Any constraints/limitations

**Example:**
```
@architect I need to design a user authentication system with:
- Email/password login
- OAuth (Google, GitHub)
- JWT tokens
- Role-based access control
- Rate limiting
```

## Custom Project Agents

### @api-builder
**Specialty**: REST API & GraphQL development
- Endpoint design
- Request/response validation
- Authentication middleware
- Rate limiting
- API documentation

### @db-expert
**Specialty**: Database optimization
- Query optimization
- Index strategy
- Migration scripts
- Data modeling
- Performance tuning

### @ui-designer
**Specialty**: Frontend & UX
- Component architecture
- Responsive design
- Accessibility (a11y)
- Animation & transitions
- Design system consistency

## Agent Activation

To activate agents in your IDE:
1. Create this `.agents.md` file in project root
2. IDE will auto-detect agents
3. Tag agents in comments or chat: `@architect`
4. Provide context for better responses

## Best Practices

- **Be Specific**: Provide clear requirements and context
- **One Agent at a Time**: Focus requests to avoid confusion
- **Iterate**: Use feedback from agents to refine approach
- **Combine Agents**: Chain agents for complex workflows
- **Document Decisions**: Use @documenter to capture rationale