Setting Up Multi-Agent Workflows

The Orchestrator Pattern

In multi-agent workflows, you need a primary orchestrator. Claude Code excels in this role because:

• Full filesystem access for context gathering
• MCP integrations for external tools
• Subagent spawning capability
• Persistent memory across sessions

Environment Setup

Step 1: Configure Claude Code as Orchestrator

Create a project-level configuration:

# Create .claude directory
mkdir -p .claude

# Create project settings
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Read",
      "Write",
      "Edit"
    ]
  },
  "context": {
    "include": ["src/**", "tests/**", "docs/**"],
    "exclude": ["node_modules/**", "dist/**"]
  }
}
EOF

Step 2: Define Agent Roles

Create a .claude/agents.md file to document agent responsibilities:

# Agent Roles

## Claude Code (Orchestrator)
- Codebase analysis and architecture decisions
- Complex refactoring operations
- Git operations and branch management
- Task delegation and progress tracking
- Final review and integration

## Cursor (Real-time Developer)
- Active coding in IDE
- Quick iterations and fixes
- Real-time autocomplete assistance
- File-specific implementations

## Devin (Autonomous Worker)
- End-to-end feature implementation
- Research tasks requiring web access
- Prototype development
- Documentation generation

Step 3: Set Up Cursor Integration

Configure Cursor to work alongside Claude Code:

// .cursor/settings.json
{
  "ai.model": "claude-sonnet-4-20250514",
  "ai.contextFiles": [
    ".claude/agents.md",
    "ARCHITECTURE.md"
  ],
  "ai.excludeFiles": [
    "node_modules/**",
    ".git/**"
  ]
}

Workflow Configuration

Create a Handoff Protocol

<!-- .claude/handoff-protocol.md -->

# Agent Handoff Protocol

## Context Transfer Format
When handing off to another agent, include:

1. **Current State**: What has been completed
2. **Next Steps**: What needs to be done
3. **Relevant Files**: Files the agent should read
4. **Constraints**: Any limitations or requirements
5. **Success Criteria**: How to know when done

## Example Handoff

### From Claude Code to Cursor:
"I've created the API route structure in `src/api/`.
Please implement the handler in `src/api/users/route.ts`:
- Use the existing auth middleware
- Follow the pattern in `src/api/posts/route.ts`
- Return proper error responses
Success: All TypeScript types pass, tests green"

Practical Multi-Agent Session

Scenario: Building a Dashboard Feature

Phase 1: Claude Code Analysis

# Claude Code analyzes and plans
claude "Analyze the codebase and create a plan for adding
a user analytics dashboard. Identify:
1. Existing data sources
2. Component patterns to follow
3. API routes needed
4. Files to create/modify"

Phase 2: Cursor Implementation

With Claude Code's plan, switch to Cursor:

In Cursor: "Following the plan in .claude/dashboard-plan.md,
implement the DashboardPage component. Use the existing
Card and Chart components from our design system."

Phase 3: Claude Code Review

# Return to Claude Code for review
claude "Review the dashboard implementation in
src/components/Dashboard/. Check for:
- Consistency with existing patterns
- Performance issues
- Missing error handling
- Test coverage"

Synchronization Strategies

Git-Based Sync

# Claude Code creates feature branch
git checkout -b feature/dashboard

# Work in Cursor (auto-saves)
# Claude Code can track changes
git status
git diff

# Claude Code commits logical units
git add -p  # Interactive staging
git commit -m "feat: add dashboard component structure"

File-Based Communication

# Claude Code writes instructions
echo "## Current Task
Implement the chart component in src/components/Chart.tsx
See reference: src/components/Graph.tsx" > .claude/current-task.md

# Cursor reads and executes
# Claude Code monitors progress
watch -n 5 'stat -f "%m" src/components/Chart.tsx'

Conflict Resolution

When agents produce conflicting changes:

1. Prefer the orchestrator's decision (Claude Code)
2. Use git diff to identify conflicts
3. Have Claude Code merge intelligently

claude "There are conflicting changes in src/api/handler.ts.
Cursor added validation but it conflicts with the error
handling I added. Merge these changes, keeping both
features while maintaining consistency."

Best Practices

1. Single Active Writer: Only one agent modifies a file at a time
2. Frequent Commits: Commit before switching agents
3. Clear Handoffs: Document what was done and what's next
4. Shared Context: Keep .claude/ directory updated
5. Regular Sync Points: Pause to verify all agents are aligned

Next Steps

In the next lesson, we'll explore advanced orchestration with Devin and autonomous agent chains for complex feature development. :::