Cowork-Claude Code Workflow

Parallel execution model for building systems using Cowork (specification and planning) and Claude Code (implementation). Framework for managing two concurrent development agents.

Model Overview

Cowork is the brain. Claude Code agents are the hands.

Cowork writes specifications, plans architecture, and coordinates decisions. Claude Code agents execute in parallel, with coordination flowing through Cowork via a shared context file (CLAUDE.md) rather than agent-to-agent communication.

Parallel Execution Fundamentals

Running Two Claude Code Agents

Setup: Two terminal windows, each running a separate Claude Code session.

Coordination:

• No direct agent-to-agent communication
• All decisions and status updates flow through Cowork
• Cowork updates a shared CLAUDE.md file in the repository
• Each agent reads CLAUDE.md at session start; updates it before session end

Never let agents coordinate directly — this causes merge conflicts, duplicate work, and decision inconsistency.

Never let idle terminals sit — start the next task immediately when one finishes; keep both terminals busy.

Never skip CLAUDE.md updates — stale context creates wrong assumptions and rework.

Never re-litigate decisions — once a decision is captured in CLAUDE.md, it’s settled unless explicitly reopened through Cowork.

Good Parallel Pairs (No File Overlap)

These tasks can run in parallel without conflict:

• Schema + UI shell: Database schema design and frontend component structure use different files
• API endpoint A + API endpoint B: Different route files, no shared dependencies
• Feature UI page 1 + Feature UI page 2: Different page files, independent functionality
• Tests + docs: Different file types, no code dependencies
• Database migrations + email system: Different systems, no file overlap
• UI component A + component B (different features): Separate files, clear boundaries

Bad Parallel Pairs (Will Conflict)

These tasks should NOT run in parallel:

• API + UI that consumes it: UI depends on API interface; sequential work prevents breaking changes
• Two issues touching same files: Merge conflicts guaranteed
• Shared utility + feature using that utility: Feature depends on utility interface; must build utility first
• Database schema + API routes that query schema: Routes depend on schema; sequential work prevents breaking changes
• Common style system + multiple components using it: Components depend on system design; setup first, then parallelize components

CLAUDE.md File Structure

Purpose: Shared context document updated by Cowork and read by agents.

Format: Markdown with structured sections.

Minimal example:

# Project Status
 
## Current Decisions
- Next.js 16 + Supabase + Railway (locked)
- Event P&L calculation via Square + Xero mapping (locked)
 
## In Flight
- Agent A (Terminal 1): Building Square API client, ETA 2 hours
- Agent B (Terminal 2): Schema for events table + RLS policies, ETA 1.5 hours
 
## Blockers
- Xero data cleanup (scheduled for bookkeeper, not agent-owned)
 
## Notes for Agents
- Always use Prisma for database queries
- Environment variables in .env.local, never committed
- Test on Railway staging before production deploy

Agent Handoff Process

When a Claude Code agent session ends:

1. Summarise work completed: What code was written? What succeeded? What failed?
2. Update CLAUDE.md: Current status, decisions, blockers, next steps
3. Commit and push: All work to git
4. Notify Cowork: (via chat) Session complete; ready for next task

When starting a new session:

1. Read CLAUDE.md: Understand current state and decisions
2. Read recent git log: Understand what previous agents built
3. Identify next task: What’s unblocked and highest priority?
4. Execute: Build the feature/fix
5. Repeat handoff: Summarise, update CLAUDE.md, commit, notify

Key Principles

Decision Immutability

Once Cowork captures a decision in CLAUDE.md, it’s binding. If an agent disagrees with a decision, they:

1. Complete their assigned task as specified
2. Document the concern in CLAUDE.md
3. Notify Cowork in chat
4. Cowork decides whether to reopen the decision

Never let agents unilaterally overturn decisions. Consistency across parallel work depends on this.

Task Clarity

Cowork provides clear, specific PRD (Product Requirements Document) before each agent session:

• What feature/fix to build
• What files to change
• What tests to write
• What success looks like
• Any blocking dependencies

Bad PRD: “Add user authentication”
Good PRD: “Add Google OAuth login to /app/auth/login page using Supabase built-in provider; store user.email in database; test with @prideofourfootscray.bar email only; success = user can sign in and see /app/dashboard”

Failure Handling

If an agent gets stuck:

1. Document the blocker in CLAUDE.md
2. Commit partial work to git
3. Notify Cowork in chat
4. Cowork unblocks, assigns new task, or escalates

Do not let the agent spend 3+ hours on a blocker alone.

Tools and Context Size

Cowork context window: 200k tokens (current) Claude Code context window: 200k tokens each (two agents)

Total capacity: ~600k tokens across all three sessions.

Management:

• Cowork focuses on high-level specifications and decisions
• Claude Code agents focus on code (detailed implementation)
• Avoid duplicating large code blocks in Cowork; link to CLAUDE.md instead
• Archive old decisions in CLAUDE.md after they’re implemented (move to “Completed” section)

Example Workflow

Scenario: Build event P&L reporting feature.

Day 1, Cowork:

• Specification PRD: Schema for events, line items, costs; P&L calculation logic; API endpoint
• Parallel pairs identified: Schema + API routes (separate files)
• CLAUDE.md updated with decisions

Day 1, Agent A (Terminal 1):

• Task: Build Prisma schema (events, line_items, event_costs tables with RLS)
• Time: 1 hour
• Result: Commit schema; update CLAUDE.md; notify Cowork

Day 1, Agent B (Terminal 2):

• Task: Build API route for event P&L calculation (/api/events/[eventId]/pnl)
• Blocker: Schema not yet in database; cannot test
• Decision: Build route with mocked schema; Agent A will run migration
• Time: 1.5 hours
• Result: Commit route; document mock schema in CLAUDE.md; notify Cowork

Day 2, Cowork:

• Review both agents’ work
• Identify: Schema deployed; route can now be tested against real schema
• CLAUDE.md updated: Next task is test + documentation

Day 2, Agent A (Terminal 1):

• Task: Write integration tests for P&L route (test event creation → P&L calculation)
• Time: 1 hour
• Result: All tests passing; commit; update CLAUDE.md

Day 2, Agent B (Terminal 2):

• Task: Write API documentation (endpoint spec, example requests/responses)
• Time: 45 minutes
• Result: Docs committed; feature complete

Related Pages

• Tech Stack — technology choices enabling this workflow
• Automation Opportunities — automation projects using this workflow
• Humphrey Intelligence App — dashboard built using this workflow