20 KiB

Raw Permalink Blame History

Claude Code Sub-Agents - Efficiency & Cost Optimization Guide

Purpose: Effectively use Claude Code sub-agents for AI Dev Factory project development

🤖 Claude Code Sub-Agents Overview

What Are Sub-Agents?

Sub-agents are specialized AI agents within Claude Code that handle specific tasks:

File Editor - Create, edit, view, and analyze files
Bash Runner - Execute shell commands, manage services, run tests
Search Agent - Find files, code patterns, and search content
Explore Agent - Deep codebase exploration and analysis
Plan Agent - Create implementation plans and break down tasks
General-Purpose Agent - Complex multi-step tasks
Code Analyzer - Review code structure and architecture

Benefits for AI Dev Factory

✅ Targeted Actions - Each sub-agent optimized for specific tasks
✅ Cost Efficiency - Focused tasks = fewer tokens
✅ Faster Execution - Specialized agents work quicker
✅ Better Results - Right tool for the right job
✅ Parallel Execution - Run multiple sub-agents concurrently
✅ Error Prevention - Specialized checks catch issues early

🛠️ Claude Code Sub-Agents Reference

1. File Editor Agent

Purpose: Create, edit, view, and analyze files

Best For:

Creating documentation (MD files)
Writing configuration files
Editing code files
File comparison and analysis

Example Usage:

Task: "Create a Node.js package.json with Express and TypeScript dependencies"
→ Uses: File Editor agent
Result: Optimized package.json with correct dependencies

Cost-Saving Tips:

Be specific about file location and content
Specify exact dependencies instead of "latest versions"
Include version constraints to avoid unnecessary updates

2. Bash Runner Agent

Purpose: Execute shell commands and manage system operations

Best For:

Starting/stopping services (Docker, systemd)
Running tests and builds
Checking service status
Service management

Example Usage:

Task: "Check status of all Docker services: caddy, gitea, n8n, postgres"
→ Uses: Bash Runner agent
Result: Service status table with health indicators

Cost-Saving Tips:

Group related commands into single task
Use specific commands instead of "check everything"
Avoid verbose output unless needed

3. Search Agent (Grep)

Purpose: Find files, code patterns, and search content efficiently

Best For:

Finding specific code patterns
Locating configuration files
Searching for error messages
Finding function/class definitions

Example Usage:

Task: "Find all files containing 'workflow' in /home/bam/claude/mvp-factory/"
→ Uses: Search Agent
Result: List of files with line numbers and context

Cost-Saving Tips:

Use specific patterns instead of generic terms
Limit search scope to relevant directories
Use file type filters (*.md, *.js, *.py)

4. Explore Agent

Purpose: Deep codebase exploration and architecture analysis

Best For:

Understanding project structure
Analyzing architecture decisions
Finding related components
Comprehensive code review

Example Usage:

Task: "Analyze the n8n workflow structure in /home/bam/claude/mvp-factory/
Find patterns in node configurations and connections"
→ Uses: Explore agent
Result: Detailed architecture analysis with recommendations

Cost-Saving Tips:

Use for complex analysis only
Break large projects into smaller exploration tasks
Specify what you want to understand specifically

5. Plan Agent

Purpose: Create implementation plans and break down complex tasks

Best For:

Planning new features
Breaking down Phase 3 implementation
Task decomposition
Roadmap creation

Example Usage:

Task: "Create implementation plan for Phase 3 autonomous build test
Break down into actionable steps with time estimates"
→ Uses: Plan agent
Result: Detailed 11-step implementation plan

Cost-Saving Tips:

Use once per major feature
Reference existing plans instead of recreating
Focus on implementation details, not theory

6. General-Purpose Agent

Purpose: Handle complex multi-step tasks that require coordination

Best For:

Complex debugging scenarios
Multi-service integration tasks
End-to-end testing workflows
Complex system configuration

Example Usage:

Task: "Debug n8n workflow data preservation issue
Analyze SSH node behavior and suggest solutions"
→ Uses: General-Purpose agent
Result: Complete debugging report with working solution

Cost-Saving Tips:

Use only when other agents can't handle it
Break into smaller sub-tasks when possible
Be very specific about the problem

💰 Cost Optimization Strategies

1. Token Budget Management

Strategy: Progressive Token Allocation

Initial Task: 500 tokens
Retry with Context: +250 tokens (750 total)
Detailed Debugging: +250 tokens (1000 total)
Complex Analysis: +500 tokens (1500 total)

Implementation:

Start with minimal context
Add context only when needed
Avoid unnecessary explanation in prompts
Use "compact mode" for routine tasks

Example:

# Instead of:
"Please analyze the entire codebase structure and provide detailed recommendations"

# Use:
"Find all workflow files in /home/bam/claude/mvp-factory/ and list their purposes"

2. Efficient Task Formulation

❌ High-Cost Approach:

Task: "Analyze the entire AI Dev Factory project, understand all components,
review documentation, check for issues, and provide recommendations"

✅ Low-Cost Approach:

Task: "Find all .md files in /home/bam/claude/mvp-factory/ and list their topics"
Task: "Check if all Phase 2 documentation is complete"
Task: "Review Phase 3 implementation checklist"

Why: Smaller, specific tasks = fewer tokens = lower cost

3. Use Structured Commands

✅ Instead of:

"Please look at my code and see if there are any issues"

✅ Use:

Task: "Search for TODO comments in /home/bam/claude/mvp-factory/"
Task: "Find all files modified after Phase 2 completion"
Task: "Check if all API keys are documented"

4. Leverage File Editor for Batch Operations

Efficient Pattern:

Task: "Create package.json for n8n workflow testing"
Task: "Create workflow configuration file"
Task: "Update CLAUDE.md with new reference"

Instead of One Large Task:

Task: "Create test infrastructure, update docs, and configure workflow"

5. Cache & Reuse Context

Strategy:

Keep files organized for easy access
Reference existing files instead of recreating
Use consistent file locations
Document decisions for future reference

Example:

# Reference existing plan instead of creating new
Task: "Update phase3.md with progress from Step 1"
Task: "Mark Step 2 as completed in todo list"

⏱️ Time Reduction Techniques

1. Parallel Sub-Agent Execution

OpenHands Can Run Multiple Sub-Agents Concurrently:

Task: [
  "Check Docker services status",
  "Find all workflow documentation",
  "List n8n workflows via API"
]
→ Runs in parallel = 3x faster

When to Use Parallel:

Independent tasks
Checking multiple services
Searching different directories
Verifying multiple configurations

When NOT to Use Parallel:

Dependent tasks (B needs A's output)
Complex analysis requiring sequential steps
Tasks that modify the same files

2. Incremental Analysis

Instead of Full Analysis:

Task: "Analyze entire codebase structure"

Use Incremental:

Task: "Check if any files changed since last review"
Task: "Find new files added to project"
Task: "Review modified documentation only"

3. Smart Command Grouping

Group Related Commands:

# Instead of 3 separate tasks:
Task: "Check n8n status"
Task: "Check Gitea status"
Task: "Check Caddy status"

# Use one task:
Task: "Check status of all Docker services: n8n, gitea, caddy, postgres
Report which are running and which have issues"

4. Pre-configured Task Templates

Common Tasks Template:

# Service Status Check
Task: "Check status of Docker services in /home/bam/services/services-stack/
List running, stopped, and unhealthy services"

# Documentation Check
Task: "Check if all Phase 3 documentation is present:
phase3.md, implementation steps, success criteria"

# API Health Check
Task: "Verify n8n API is accessible: curl https://n8n.oky.sh/api/v1/workflows"

🎯 Best Practices for AI Dev Factory Project

1. Documentation Tasks

Efficient Pattern:

Task: "Create implementation plan for Step X of Phase 3
Include: prerequisites, commands, verification, troubleshooting"

Task: "Update todo list with completed tasks
Mark Step X as completed, add next steps"

Task: "Create checklist for testing Phase 3 workflow
Include: success criteria, test scenarios, verification steps"

2. Code Review Tasks

Use Targeted Reviews:

Task: "Review n8n workflow configuration for data preservation issues
Check if $node pattern is used correctly"

Task: "Verify all API keys are documented with proper locations
Check .env, .n8n_api_key, SSH keys"

Task: "Review Phase 3 implementation for missing components
Check if all 11 workflow nodes are defined"

3. Testing Tasks

Systematic Testing:

Task: "Test SDK wrapper: sh /home/bam/openhands-sdk-wrapper-sh.sh 'Create test file'
Verify output format and exit codes"

Task: "Test n8n webhook: curl -X POST https://n8n.oky.sh/webhook/openhands-fixed-test
Check if workflow executes and returns success"

Task: "Verify data preservation: Check if repo data is preserved after SSH node
Review node configuration and output"

4. Debugging Tasks

Efficient Debugging:

# Step 1: Identify the problem
Task: "Check n8n execution logs for recent workflow runs
Find any failed nodes or error messages"

# Step 2: Analyze the issue
Task: "Review SSH node configuration in workflow ID: j1MmXaRhDjvkRSLa
Check if passThrough is set correctly"

# Step 3: Implement fix
Task: "Update node configuration to use $node pattern for data preservation
Verify the fix works with test execution"

🔧 Error Prevention Strategies

1. Validation Before Execution

Always Validate First:

Task: "Check if prerequisites are met before starting Phase 3
Verify: Gitea accessible, n8n running, OpenHands configured"

Task: "Validate file permissions for API keys
Check: /home/bam/.n8n_api_key, /home/bam/openhands/.env, /home/bam/.ssh/n8n_key"

Task: "Verify workflow exists before trying to update it
Check: workflow ID j1MmXaRhDjvkRSLa is active"

2. Incremental Changes

Avoid Large Changes:

# Instead of:
Task: "Update all documentation files with new Phase 3 info"

# Use:
Task: "Update CLAUDE.md with Phase 3 overview"
Task: "Update phase3.md with Step 1 completion"
Task: "Update todo list with progress"

3. Verification After Changes

Always Verify:

Task: "After creating new workflow, verify it's active
Check: curl https://n8n.oky.sh/api/v1/workflows"

Task: "After updating documentation, check for broken links
Verify all referenced files exist"

Task: "After modifying configs, test if services still start
Run: docker compose -f /home/bam/services/services-stack/docker-compose.yml ps"

4. Use Dry-Run Mode

For Destructive Operations:

Task: "Review git status before making changes
List: modified files, untracked files, staged changes"

Task: "Show what would be deleted before deleting files
Preview: which files will be removed, their sizes"

Task: "Check if workflow update would succeed
Verify: API token is valid, workflow ID exists"

📊 Claude Code Task Optimization Templates

1. Service Management

Template:

Task: "Manage service: [service-name]
Actions: [start/stop/restart/status]
Location: /home/bam/services/services-stack/
Verify: Check if service is healthy after operation"

Example:

Task: "Restart n8n service
Location: /home/bam/services/services-stack/
Verify: Check if n8n API is accessible after restart
Report: Service status and any errors"

2. Documentation Updates

Template:

Task: "Update [file-name].md with [specific change]
Location: /home/bam/claude/mvp-factory/
Changes: [list specific changes]
Verify: Check file exists and changes are correct"

Example:

Task: "Update phase3.md with Step 1 completion
Location: /home/bam/claude/mvp-factory/
Changes: Mark 'Setup Test Repository' as completed
Verify: Check checkbox is updated and timestamp added"

3. Code Analysis

Template:

Task: "Analyze [component] for [specific issue]
Scope: [file or directory]
Focus: [specific aspects to check]
Report: [what to report back]"

Example:

Task: "Analyze n8n workflow for data preservation
Scope: workflow ID j1MmXaRhDjvkRSLa
Focus: Check if $node pattern is used after SSH nodes
Report: Which nodes need fixing and how"

4. Testing Tasks

Template:

Task: "Test [component] [action]
Setup: [prerequisites]
Execute: [specific commands]
Verify: [expected results]
Cleanup: [if needed]"

Example:

Task: "Test n8n workflow execution
Setup: Workflow ID j1MmXaRhDjvkRSLa is active
Execute: POST to webhook with test data
Verify: HTTP 200 response, workflow completes
Report: Success/failure, execution time, any errors"

🚀 Phase 3 Implementation Strategy

Efficient Task Breakdown

Step 1: Setup Test Repository (20 min)

Task: "Create test repository in Gitea
Name: autonomous-build-test
Description: Test repo for Phase 3 autonomous build testing
Verify: Repository is created and accessible"

Step 2: Configure Webhook (15 min)

Task: "Configure Gitea webhook for test repository
URL: https://n8n.oky.sh/webhook/autonomous-build-test
Events: Push events
Verify: Test webhook delivery succeeds"

Step 3: Build Workflow (60 min)

# Task 3a: Design workflow structure
Task: "Design 11-node workflow structure for autonomous build test
Document: Node types, connections, data flow"

# Task 3b: Create workflow nodes
Task: "Create workflow nodes in n8n
Nodes: Webhook, Extract Repo, Initialize Retry, OpenHands Build, Wait, Check Results, Decision, Update Gitea, Format Error, Check Retry, Retry Loop"

# Task 3c: Configure connections
Task: "Connect workflow nodes according to flow design
Verify: All connections are correct"

Step 4: Test Success Path (30 min)

Task: "Test workflow with valid code
Setup: Push working code to test repo
Execute: Trigger webhook
Verify: Build succeeds, Gitea status updated to success
Report: Execution details and any issues"

Step 5: Test Failure Path (45 min)

Task: "Test workflow with intentional errors
Setup: Push code with build errors
Execute: Trigger webhook
Verify: Errors detected, retry counter increments
Report: Error messages and retry behavior"

Step 6: Test Max Retries (30 min)

Task: "Test workflow with persistent errors
Setup: Push code that fails 3 times
Execute: Let workflow retry 3 times
Verify: Stops after 3 attempts, final failure notification
Report: Retry count and final status"

📈 Success Metrics

Performance Targets

Efficiency Metrics:

Documentation Task Time: < 5 minutes (instead of 30+ minutes)
Code Review Time: < 10 minutes (instead of 60+ minutes)
Error Detection: < 2 minutes (instead of manual debugging)
Test Execution: < 3 minutes (instead of 30+ minutes)

Cost Metrics:

Token Usage: < 3000 tokens per task
Retry Rate: < 20% (tasks completed on first attempt)
Error Rate: < 5% (successful task completion)
Documentation Updates: < 500 tokens each

Quality Metrics:

Task Accuracy: 95%+ (correct implementation)
Documentation Coverage: 100% (all changes documented)
Test Coverage: 100% (all paths tested)
Error Prevention: 90%+ (issues caught before deployment)

🔍 Troubleshooting Common Issues

Issue: High Token Usage

Symptoms: Task uses 5000+ tokens

Solutions:

Break task into smaller subtasks
Be more specific in task descriptions
Use targeted searches instead of general analysis
Reference existing files instead of recreating

Example Fix:

# Before: "Analyze entire project"
Task: "Count lines in phase3.md"

# After: More specific
Task: "Find TODO items in phase3.md"

Issue: Tasks Taking Too Long

Symptoms: Task execution > 10 minutes

Solutions:

Use parallel execution for independent tasks
Specify exact files/directories to work with
Use incremental analysis
Avoid unnecessary verification steps

Example Fix:

# Before: "Check everything"
Task: "Verify all services are running"

# After: Specific
Task: "Check if n8n container is running: docker ps | grep n8n"

Issue: Incorrect Results

Symptoms: Task completes but output is wrong

Solutions:

Be more specific about expected output
Include examples in task description
Verify prerequisites before execution
Use validation tasks

Example Fix:

# Before: Vague
Task: "Update documentation"

# After: Specific
Task: "Add checkbox [ ] for Step 1 in phase3.md and mark it as completed"

Issue: Sub-Agent Not Working

Symptoms: Task doesn't use expected sub-agent

Solutions:

Use task keywords that trigger the right agent
Search → Use "find", "search", "grep"
Explore → Use "analyze", "explore", "understand"
Plan → Use "plan", "break down", "design"
Bash → Use "run", "execute", "check status"

Example Fix:

# To trigger Search Agent:
Task: "Find all workflow files containing 'SSH'"

# To trigger Explore Agent:
Task: "Analyze the architecture of the n8n workflow"

# To trigger Bash Runner:
Task: "Check Docker service status"

📚 Quick Reference Commands

Common Tasks

Check All Services:

Task: "Check status of all Docker services
Command: cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
Report: Running/Stopped/Unhealthy services"

Verify Documentation:

Task: "Check if all Phase 3 files exist
Files: phase3.md, claude-code-subagents-doc.md, openhands-subagents-doc.md
Report: Missing files and file sizes"

Test n8n Workflow:

Task: "Test n8n workflow execution
Workflow ID: j1MmXaRhDjvkRSLa
Test: POST to webhook with sample data
Verify: HTTP 200 and success response"

Update Phase Progress:

Task: "Mark Step X as completed in phase3.md
Action: Change [ ] to [X] for specific step
Add: Completion timestamp and notes
Verify: Change is saved correctly"

Efficiency Tips

Use specific file paths instead of "the project directory"
Include expected output format in task description
Reference existing files instead of recreating
Break complex tasks into smaller steps
Use validation tasks before making changes
Group related commands into single tasks
Avoid unnecessary explanation in prompts
Use consistent naming for files and tasks

🎓 Advanced Strategies

1. Task Chaining

Pattern:

Task 1: "Create plan for Phase 3 Step 1"
Task 2: "Execute Step 1 according to plan"
Task 3: "Mark Step 1 as completed"
Task 4: "Create plan for Step 2"
...

2. Context Preservation

Pattern:

# Reference previous tasks
Task: "Based on previous analysis of n8n workflow,
implement the suggested data preservation fix"

Task: "Continue from where we left off in Phase 3
Next step is: Configure Gitea webhook"

3. Iterative Refinement

Pattern:

# First pass: Basic implementation
Task: "Create basic workflow structure"

# Second pass: Add details
Task: "Add error handling to workflow"

# Third pass: Optimize
Task: "Optimize workflow for faster execution"

4. Verification Loop

Pattern:

Task: "Make changes to [file]"
Task: "Verify changes are correct"
Task: "If errors found, fix them"
Task: "Verify again until perfect"

Claude Code Sub-Agents Guide - Last Updated: 2025-12-02 Optimized for AI Dev Factory Project

20 KiB Raw Permalink Blame History

Claude Code Sub-Agents - Efficiency & Cost Optimization Guide

🤖 Claude Code Sub-Agents Overview

What Are Sub-Agents?

Benefits for AI Dev Factory

🛠️ Claude Code Sub-Agents Reference

1. File Editor Agent

2. Bash Runner Agent

3. Search Agent (Grep)

4. Explore Agent

5. Plan Agent

6. General-Purpose Agent

💰 Cost Optimization Strategies

1. Token Budget Management

2. Efficient Task Formulation

3. Use Structured Commands

4. Leverage File Editor for Batch Operations

5. Cache & Reuse Context

⏱️ Time Reduction Techniques

1. Parallel Sub-Agent Execution

2. Incremental Analysis

3. Smart Command Grouping

4. Pre-configured Task Templates

🎯 Best Practices for AI Dev Factory Project

1. Documentation Tasks

2. Code Review Tasks

3. Testing Tasks

4. Debugging Tasks

🔧 Error Prevention Strategies

1. Validation Before Execution

2. Incremental Changes

3. Verification After Changes

4. Use Dry-Run Mode

📊 Claude Code Task Optimization Templates

1. Service Management

2. Documentation Updates

3. Code Analysis

4. Testing Tasks

🚀 Phase 3 Implementation Strategy

Efficient Task Breakdown

📈 Success Metrics

Performance Targets

🔍 Troubleshooting Common Issues

Issue: High Token Usage

Issue: Tasks Taking Too Long

Issue: Incorrect Results

Issue: Sub-Agent Not Working

📚 Quick Reference Commands

Common Tasks

Efficiency Tips

🎓 Advanced Strategies

1. Task Chaining

2. Context Preservation

3. Iterative Refinement

4. Verification Loop

20 KiB

Raw Permalink Blame History