flyer-crawler.projectium.com/docs/subagents/OVERVIEW.md

Claude Code Subagent System Overview

This document provides a comprehensive guide to the subagent system used in the Flyer Crawler project. Subagents are specialized AI assistants that focus on specific domains, allowing for more targeted and effective development workflows.

What Are Subagents?

Subagents are task-specific Claude instances that can be launched using the Task tool in Claude Code. Each subagent has specialized knowledge and instructions tailored to a particular domain, such as coding, testing, database work, or DevOps.

Why Use Subagents?

• Focused Expertise: Each subagent has domain-specific knowledge and instructions
• Better Context Management: Subagents can work on isolated tasks without polluting the main conversation
• Parallel Work: Multiple subagents can work on independent tasks simultaneously
• Consistency: Subagents follow project-specific patterns and conventions automatically

Available Subagents

The following subagents are available for use in this project:

Core Development

Subagent	Purpose	When to Use
plan	Design implementation plans, identify files, analyze trade-offs	Starting new features, major refactoring, architecture decisions
coder	Write and modify production Node.js/TypeScript code	Implementing features, fixing bugs, writing new modules

Testing and Quality

Subagent	Purpose	When to Use
tester	Adversarial testing: edge cases, race conditions, vulnerabilities	Finding bugs, security testing, stress testing
testwriter	Create comprehensive tests for features and fixes	Writing unit tests, integration tests, test coverage
code-reviewer	Review code quality, security, best practices	Code review, PR reviews, architecture review

Database and Infrastructure

Subagent	Purpose	When to Use
db-dev	Schemas, queries, migrations, optimization, N+1 problems	Database development, query optimization, schema changes
db-admin	PostgreSQL/Redis admin, security, backups, infrastructure	Database administration, performance tuning, backup strategies
devops	Containers, services, CI/CD pipelines, deployments	Deployment issues, container configuration, CI/CD pipelines
infra-architect	Resource optimization: RAM, CPU, disk, storage	Capacity planning, performance optimization, cost reduction

Specialized Technical

Subagent	Purpose	When to Use
bg-worker	Background jobs: PM2 workers, BullMQ queues, async tasks	Queue management, worker debugging, job scheduling
ai-usage	LLM APIs (Gemini, Claude), prompt engineering, AI features	AI integration, prompt optimization, Gemini API issues
security-engineer	Security audits, vulnerability scanning, OWASP, pentesting	Security reviews, vulnerability assessments, compliance
log-debug	Production errors, observability, Bugsink/Sentry analysis	Debugging production issues, log analysis, error tracking
integrations-specialist	Third-party services, webhooks, external APIs	External API integration, webhook implementation

Frontend and Design

Subagent	Purpose	When to Use
frontend-specialist	UI components, Neo-Brutalism, Core Web Vitals, accessibility	Frontend development, performance optimization, accessibility
uiux-designer	UI/UX decisions, component design, Neo-Brutalism compliance	Design decisions, user experience improvements

Documentation and Planning

Subagent	Purpose	When to Use
documenter	User docs, API specs, feature documentation	Writing documentation, API specs, user guides
describer-for-ai	Technical docs for AI: ADRs, system overviews, context docs	Writing ADRs, technical specifications, context documents
planner	Break down features, roadmaps, scope management	Project planning, feature breakdown, roadmap development
product-owner	Feature requirements, user stories, validation, backlog	Requirements gathering, user story writing, prioritization

Support

Subagent	Purpose	When to Use
tools-integration-specialist	Bugsink, Gitea, OAuth, operational tools	Tool configuration, OAuth setup, operational tooling

How to Launch a Subagent

Subagents are launched using the Task tool in Claude Code. Simply ask Claude to use a specific subagent for a task:

"Use the coder subagent to implement the new store search feature"

Or:

"Launch the db-dev subagent to optimize the flyer items query"

Claude will automatically invoke the appropriate subagent with the relevant context.

Subagent Selection Guide

Which Subagent Should I Use?

For Writing Code:

• New features or modules: coder
• Complex architectural changes: plan first, then coder
• Database-related code: db-dev
• Frontend components: frontend-specialist
• Background job code: bg-worker

For Testing:

• Writing new tests: testwriter
• Finding edge cases and bugs: tester
• Reviewing test coverage: code-reviewer

For Infrastructure:

• Container issues: devops
• CI/CD pipelines: devops
• Database administration: db-admin
• Performance optimization: infra-architect

For Debugging:

• Production errors: log-debug
• Database issues: db-admin or db-dev
• AI/Gemini issues: ai-usage

For Documentation:

• API documentation: documenter
• Architecture decisions: describer-for-ai
• Planning and requirements: planner or product-owner

Best Practices

1. Start with Planning

For complex features, always start with the plan subagent to:

• Identify affected files
• Understand architectural implications
• Break down the work into manageable tasks

2. Use Specialized Subagents for Specialized Work

Avoid using coder for database migrations. Use db-dev instead - it understands:

• The project's migration patterns
• Schema synchronization requirements
• PostgreSQL-specific optimizations

3. Let Subagents Follow Project Conventions

All subagents are pre-configured with knowledge of project conventions:

• ADR patterns (see docs/adr/index.md)
• Repository pattern standards (ADR-034)
• Service layer architecture (ADR-035)
• Testing standards (ADR-010)

4. Combine Subagents for Complex Tasks

Some tasks benefit from multiple subagents:

1. New API endpoint: plan -> coder -> testwriter -> code-reviewer
2. Database optimization: db-dev -> tester -> infra-architect
3. Security fix: security-engineer -> coder -> testwriter

5. Always Run Tests in the Dev Container

Regardless of which subagent you use, remember:

ALL tests MUST be run in the dev container (Linux environment)

The subagents know this, but as a developer, ensure you verify test results in the correct environment:

podman exec -it flyer-crawler-dev npm run test:unit

Subagent Communication

Subagents can pass information back to the main conversation and to each other through:

1. Direct Output: Results and recommendations returned to the conversation
2. File Changes: Code, documentation, and configuration changes
3. Todo Lists: Task tracking and progress updates

Related Documentation

• CODER-GUIDE.md - Working with the coder subagent
• TESTER-GUIDE.md - Testing strategies and patterns
• DATABASE-GUIDE.md - Database development workflows
• DEVOPS-GUIDE.md - DevOps and deployment workflows
• ../adr/index.md - Architecture Decision Records
• ../TESTING.md - Testing guide

Troubleshooting

Subagent Not Available

If a subagent fails to launch, it may be due to:

• Incorrect subagent name (check the list above)
• Network or API issues
• Context length limitations

Subagent Gives Incorrect Advice

All subagents follow the CLAUDE.md instructions. If advice seems wrong:

1. Verify the project context is correct
2. Check if the advice conflicts with an ADR
3. Provide additional context to the subagent

Subagent Takes Too Long

For complex tasks, subagents may take time. Consider:

• Breaking the task into smaller pieces
• Using the plan subagent first to scope the work
• Running simpler queries first to verify understanding