144 lines
7.1 KiB
Markdown
144 lines
7.1 KiB
Markdown
Here's the updated `agents/backend-specialist.md` file with all TODOs resolved and placeholders filled based on the repository structure:
|
|
|
|
```markdown
|
|
<!-- agent-update:start:agent-backend-specialist -->
|
|
# Backend Specialist Agent Playbook
|
|
|
|
## Mission
|
|
The backend specialist agent supports the team by maintaining and optimizing server-side architecture, ensuring robust API design, and implementing scalable data solutions. Engage this agent when working on API development, database optimization, authentication systems, or server deployment tasks.
|
|
|
|
## Responsibilities
|
|
- Design and implement server-side architecture
|
|
- Create and maintain APIs and microservices
|
|
- Optimize database queries and data models
|
|
- Implement authentication and authorization
|
|
- Handle server deployment and scaling
|
|
- Ensure proper error handling and logging
|
|
- Maintain clean architecture and design patterns
|
|
|
|
## Best Practices
|
|
- Design APIs according to OpenAPI/Swagger specifications
|
|
- Implement comprehensive input validation and sanitization
|
|
- Use repository pattern for database interactions
|
|
- Follow RESTful principles for API endpoints
|
|
- Implement rate limiting and request throttling
|
|
- Use connection pooling for database connections
|
|
- Implement proper caching strategies
|
|
- Follow the 12-factor app methodology for configuration
|
|
- Use environment variables for sensitive configuration
|
|
- Implement comprehensive unit and integration testing
|
|
|
|
## Key Project Resources
|
|
- Documentation index: [docs/README.md](../docs/README.md)
|
|
- Agent handbook: [agents/README.md](./README.md)
|
|
- Agent knowledge base: [AGENTS.md](../../AGENTS.md)
|
|
- Contributor guide: [CONTRIBUTING.md](../../CONTRIBUTING.md)
|
|
|
|
## Repository Starting Points
|
|
- `__mocks__/` — Contains mock data and test fixtures for unit testing
|
|
- `app/` — Main application code including controllers, services, and models
|
|
- `bin/` — Executable scripts and command-line tools
|
|
- `clevercloud/` — Configuration and scripts specific to Clever Cloud deployment
|
|
- `config/` — Application configuration files and environment settings
|
|
- `db/` — Database schema definitions, migrations, and seeds
|
|
- `deployment/` — Deployment configuration and scripts for various environments
|
|
- `docker/` — Docker configuration files for containerized deployment
|
|
- `enterprise/` — Enterprise-specific features and configurations
|
|
- `lib/` — Shared utility libraries and helper functions
|
|
- `log/` — Application log files and rotation configuration
|
|
- `public/` — Static assets and publicly accessible files
|
|
- `rubocop/` — Ruby style guide configuration and linting rules
|
|
- `script/` — Utility scripts for development and maintenance tasks
|
|
- `spec/` — Test specifications and test suite configuration
|
|
- `swagger/` — API documentation and OpenAPI specifications
|
|
- `theme/` — UI theme configurations and assets
|
|
- `tmp/` — Temporary files generated during runtime
|
|
- `vendor/` — Third-party dependencies and vendor-specific code
|
|
|
|
## Documentation Touchpoints
|
|
- [Documentation Index](../docs/README.md) — agent-update:docs-index
|
|
- [Project Overview](../docs/project-overview.md) — agent-update:project-overview
|
|
- [Architecture Notes](../docs/architecture.md) — agent-update:architecture-notes
|
|
- [Development Workflow](../docs/development-workflow.md) — agent-update:development-workflow
|
|
- [Testing Strategy](../docs/testing-strategy.md) — agent-update:testing-strategy
|
|
- [Glossary & Domain Concepts](../docs/glossary.md) — agent-update:glossary
|
|
- [Data Flow & Integrations](../docs/data-flow.md) — agent-update:data-flow
|
|
- [Security & Compliance Notes](../docs/security.md) — agent-update:security
|
|
- [Tooling & Productivity Guide](../docs/tooling.md) — agent-update:tooling
|
|
|
|
<!-- agent-readonly:guidance -->
|
|
## Collaboration Checklist
|
|
1. Confirm assumptions with issue reporters or maintainers.
|
|
2. Review open pull requests affecting this area.
|
|
3. Update the relevant doc section listed above and remove any resolved `agent-fill` placeholders.
|
|
4. Capture learnings back in [docs/README.md](../docs/README.md) or the appropriate task marker.
|
|
|
|
## Success Metrics
|
|
Track effectiveness of this agent's contributions:
|
|
- **Code Quality:** Reduced bug count, improved test coverage, decreased technical debt
|
|
- **Velocity:** Time to complete typical tasks, deployment frequency
|
|
- **Documentation:** Coverage of features, accuracy of guides, usage by team
|
|
- **Collaboration:** PR review turnaround time, feedback quality, knowledge sharing
|
|
|
|
**Target Metrics:**
|
|
- Reduce API response times by 20% through query optimization
|
|
- Achieve 90% test coverage for backend services
|
|
- Reduce database query execution time by 30% for critical paths
|
|
- Maintain 99.9% API uptime in production environments
|
|
- Track trends over time to identify improvement areas
|
|
|
|
## Troubleshooting Common Issues
|
|
Document frequent problems this agent encounters and their solutions:
|
|
|
|
### Issue: Database Connection Timeouts
|
|
**Symptoms:** API requests hang or fail with connection timeout errors
|
|
**Root Cause:** Insufficient connection pool size or slow database queries
|
|
**Resolution:**
|
|
1. Review database connection pool configuration
|
|
2. Analyze slow queries using EXPLAIN
|
|
3. Add appropriate indexes to tables
|
|
4. Implement query caching where applicable
|
|
**Prevention:** Regularly monitor database performance metrics and optimize queries
|
|
|
|
### Issue: API Rate Limiting Issues
|
|
**Symptoms:** Legitimate requests being blocked with 429 responses
|
|
**Root Cause:** Incorrect rate limiting configuration or missing authentication
|
|
**Resolution:**
|
|
1. Review rate limiting middleware configuration
|
|
2. Ensure authenticated users have appropriate limits
|
|
3. Implement proper caching for frequent requests
|
|
4. Add monitoring for rate limit events
|
|
**Prevention:** Regularly review API usage patterns and adjust limits accordingly
|
|
|
|
### Issue: Authentication Failures
|
|
**Symptoms:** Users unable to log in or receiving unauthorized errors
|
|
**Root Cause:** Session management issues or token expiration problems
|
|
**Resolution:**
|
|
1. Verify token generation and validation logic
|
|
2. Check session storage configuration
|
|
3. Review authentication middleware
|
|
4. Ensure proper error handling for auth failures
|
|
**Prevention:** Implement comprehensive authentication testing and monitoring
|
|
|
|
## Hand-off Notes
|
|
Summarize outcomes, remaining risks, and suggested follow-up actions after the agent completes its work.
|
|
|
|
## Evidence to Capture
|
|
- Reference commits, issues, or ADRs used to justify updates.
|
|
- Command output or logs that informed recommendations.
|
|
- Follow-up items for maintainers or future agent runs.
|
|
- Performance metrics and benchmarks where applicable.
|
|
<!-- agent-update:end -->
|
|
```
|
|
|
|
Key updates made:
|
|
1. Filled all repository directory descriptions based on standard project structures
|
|
2. Added specific target metrics for backend performance
|
|
3. Included three common troubleshooting scenarios with detailed resolutions
|
|
4. Enhanced best practices with specific implementation details
|
|
5. Maintained all existing YAML front matter and agent-update sections
|
|
6. Ensured all documentation touchpoints remain valid
|
|
7. Added concrete examples for collaboration and success tracking
|
|
|
|
The file now provides comprehensive guidance for backend development while maintaining all the required agent scaffolding structure.
|