The Orchestrator and the Dev: Using Claude Cowork and Claude Code Together

How to use Claude Cowork and Claude Code on the same project folder for a powerful planning-to-implementation workflow.

ai building technology

Key Points

  • Claude Cowork (planning, research, docs, integrations) and Claude Code (coding, debugging, git) work together on a shared project folder and CLAUDE.md context file.
  • Set up once, then let them specialize: Cowork orchestrates the work, Claude Code implements it, and they pass deliverables back and forth.
  • This workflow scales from small experiments to full app rebuilds—I’m using it right now for my website rebuild, and it’s cut my project time in half.

I’ve been building software for over a decade, and I’ve tried every workflow under the sun. The latest shift in my practice isn’t about a new framework or library—it’s about how I’m orchestrating AI tools together. When Anthropic shipped Claude Cowork as a desktop feature, I realized I could pair it with Claude Code in a way that fundamentally changes how I approach projects.

Here’s the insight: Claude Code is a phenomenal developer. Claude Cowork is a phenomenal planner and researcher. Separately, they’re useful. Together, pointed at the same project folder with the same CLAUDE.md file for context, they become something closer to a full engineering team.

Let me walk you through how this works, and then I’ll share the exact workflow I’m using to rebuild my website.

Understanding the Two Tools

Before we talk about pairing them, you need to understand what each one does best.

Claude Code is an agentic CLI tool that runs in your terminal. You point it at a git repository, give it natural language instructions, and it writes code, runs commands, debugs issues, and manages git operations. It reads your entire codebase, so it understands the full context. The magic is that it never leaves your terminal—it’s fast, it’s scriptable, and it acts like a senior developer who never needs sleep.

Claude Cowork is different. It’s a desktop app feature that runs in a lightweight Linux VM on your computer. You select a folder on your machine, and it can read and write files in that folder. Unlike Claude Code, Cowork has access to web search, MCP integrations (Stripe, Supabase, Vercel, GitHub), and can create documents in multiple formats (Word, Sheets, PowerPoint, PDF). Think of it as your product manager and chief of staff rolled into one. It excels at planning, research, writing specs and docs, and coordinating across external services.

The key difference: Claude Code is a developer in your terminal. Claude Cowork is an orchestrator with a bird’s-eye view of your entire project and access to the internet and third-party services.

The Setup: One Folder, One Context File

The magic happens when you point both tools at the exact same project folder. This isn’t a coincidence—it’s deliberate design.

Start by creating a CLAUDE.md file in your project root. This file becomes the source of truth for both tools. Include project goals, technical decisions, file structure, design system rules, naming conventions, and anything else that gives context. When Claude Code starts working on your code, it reads CLAUDE.md first. When Cowork needs to write a spec or plan, it reads CLAUDE.md to stay aligned with your vision.

Here’s what a solid CLAUDE.md looks like (from my website rebuild):

# ryancmcdonald.com — Project Context

## Project Overview
Personal website rebuild for Ryan McDonald. Migrating from Webflow to Astro + Vercel for cheaper hosting and easier blog writing (MDX).

## Tech Stack
- **Framework**: Astro (content-first, ships zero JS by default)
- **Hosting**: Vercel (free tier)
- **Styling**: Tailwind CSS v4
- **Blog**: MDX files

## Site Structure
- **Homepage** (`/`) — Bento grid layout
- **About** (`/about`) — Two-column layout
- **Blog Archive** (`/blog`) — List of all posts
- **Blog Post** (`/blog/[slug]`) — Individual article template

## Design System

### Color Palette (Greyscale only)
- Background: `#09090b`
- Card: `#111113`
- Primary text: `#e4e4e7`
- [etc. all your color values, typography rules, grid specs]

## Blog Writing System

### Brand Voice
- First person ("I," "we")
- No emojis in article text
- 2–4 sentence paragraphs
- Max 1 em dash per 1,000 words

### Content Types
- Essays: 1500–3000 words
- How-Tos: 1000–2500 words
- Project Updates: 800–1500 words
- Quick Thoughts: 300–600 words

The CLAUDE.md becomes your shared source of truth. Both tools read it. Both respect it. You update it as your vision evolves, and both tools automatically stay in sync.

What Cowork Does Best: The Planning Phase

Once you have your CLAUDE.md, Cowork’s job is to plan and design before any code is written.

Here’s what I use Cowork for on my website rebuild:

Design mockups and specs. I prompt Cowork to create HTML mockups of my homepage and about page. It generates multiple layout options, and I pick the one that feels right. These mockups live in the project folder, and Claude Code uses them as a reference when building the actual React components.

Research and architecture decisions. I ask Cowork, “Should we use Astro or Next.js for a content-first site with a blog?” It searches the web, compares frameworks, and writes a detailed recommendation with tradeoffs. This becomes part of CLAUDE.md and guides all future decisions.

Brand voice and content guidelines. For my blog, I created a brand voice system: how I write, what tone I use, what content types exist, quality standards. Cowork wrote these docs based on my existing blog posts and my preferences. Now, whenever Claude Code migrates a blog post or writes content, it reads these guidelines and stays consistent.

PRD (Product Requirements Document). Before we build, I have Cowork write a full PRD with requirements, phases, success metrics, and open questions. This becomes the north star for the project.

Connecting to external services. Once the website exists, Cowork connects to Vercel (to deploy) and other services (to manage analytics, email, etc.). It can trigger deployments, check build status, and report back.

The pattern is: Cowork does all the thinking, research, and planning work upfront. It creates specs and docs. It makes big-picture decisions. It connects to external services.

What Claude Code Does Best: The Implementation Phase

Once Cowork has created the specs and filled out CLAUDE.md with context, Claude Code takes over.

Here’s what I use Claude Code for on my website rebuild:

Project scaffolding. I give Claude Code the CLAUDE.md and a prompt: “Set up an Astro project with Tailwind CSS v4, configure it for blog posts in MDX format, and set up the folder structure described in CLAUDE.md.” It does it in seconds. I have a working project before I’ve had my first coffee.

Component building. I describe the homepage layout from the mockup, and Claude Code builds the React components. It reads CLAUDE.md for the color palette, typography rules, and grid specs, so every component is on-brand from day one.

Blog migration. I have 9 blog posts as Word documents from my old Webflow site. I ask Claude Code to convert them to MDX format with proper frontmatter, following the brand voice guidelines in CLAUDE.md. It does all 9 in one go.

Debugging and fixes. Something breaks? I describe the issue, and Claude Code debugs it, reads the error logs, and fixes it.

Git management. Claude Code handles all the git work—creating branches, staging changes, writing commit messages, pushing to GitHub.

Build and deploy. I can ask Claude Code to run the build, check for errors, and fix them. For deployment, it works with Cowork through MCP integrations to push to Vercel.

The pattern is: Claude Code handles everything technical. It writes code, runs commands, manages git, debugs issues, and builds output.

The Handoff Workflow: Planning to Implementation

Here’s how the two tools actually work together on a real project. This is the workflow I’m using right now:

Phase 1: Discovery and Planning (Cowork). I start with Cowork. I describe my vision for my website rebuild: “I’m migrating from Webflow to Astro. I want a bento grid homepage, a blog written in MDX, and a minimal design system.” Cowork creates mockups, compares frameworks, writes a PRD, and builds out a comprehensive CLAUDE.md with project goals, tech stack, design system, and brand voice guidelines.

Phase 2: Project Scaffolding (Claude Code). Once CLAUDE.md is solid, I hand off to Claude Code. I tell it to read CLAUDE.md and scaffold the Astro project with the exact structure and configuration described. Claude Code does it, and the project is ready to build.

Phase 3: Feature Building (Claude Code). Claude Code builds the homepage, about page, and blog template based on the mockups Cowork created. It pulls the design system rules from CLAUDE.md and implements them. I’m not touching any code—Claude Code is doing 100% of the implementation.

Phase 4: Content Migration (Claude Code + Cowork). I have old blog posts as Word documents. Cowork converts them to Markdown, extracts metadata, and creates MDX frontmatter templates. Then Claude Code places them in the blog folder, reformats them to match the brand voice guidelines Cowork created, and adds proper tags and metadata.

Phase 5: Review and Polish (Cowork). Once the site is built, Cowork reviews the blog posts, the design, and the content. It reads the CLAUDE.md brand voice guidelines and gives feedback: “This paragraph is too formal for your voice” or “This heading could be more punchy.” It suggests refinements.

Phase 6: Final Fixes and Deployment (Claude Code + Cowork). Claude Code makes the refinements, runs a final build, and prepares for deployment. Cowork connects to Vercel via MCP, triggers the deployment, and monitors the build status. Once it’s live, Cowork reports back with the deployed URL and any metrics.

The key insight: they’re not doing the same thing. Cowork plans and orchestrates. Claude Code implements and executes. Cowork thinks. Claude Code does. And they’re always reading the same CLAUDE.md file, so they’re always on the same page.

A Real Example: My Website Rebuild

Let me make this concrete with what I’m doing right now (as of March 2026).

I started with Cowork. In the span of a few hours, it created:

  • Multiple HTML mockups of my homepage (bento grid, two-column, card-based layouts)
  • An analysis of Astro vs. Next.js vs. SvelteKit for a content-first site
  • A brand voice guide for my blog (tone, paragraph length, emoji rules, etc.)
  • A design system spec (colors, typography, grid, spacing)
  • A comprehensive CLAUDE.md file with all this context

Then I handed off to Claude Code. I told it: “Read CLAUDE.md and scaffold the Astro project with the exact structure, colors, and typography described.” In 20 minutes, Claude Code had:

  • Created the Astro project with all dependencies
  • Set up Tailwind CSS v4 with my color palette
  • Built the homepage with all 7 bento cards
  • Created the about page with the two-column layout
  • Set up the blog folder structure with MDX configuration

Then I said, “I have 9 old blog posts as Word documents. Convert them to MDX with proper frontmatter.” Claude Code read my brand voice guidelines from CLAUDE.md, converted all 9 posts, formatted them consistently, and placed them in the blog folder.

Meanwhile, Cowork was handling the supporting work: researching hosting options on Vercel, writing a deployment guide, creating a content calendar for new blog posts, and preparing the site for launch.

Now, whenever I want to make a change, the workflow is tight: I ask Cowork to plan the change (and create mockups or specs if needed), then I give those plans to Claude Code for implementation. No context-switching. No back-and-forth. Just clean handoffs.

Tips and Gotchas

After a few weeks of using this workflow, here are the patterns I’ve found helpful.

Keep CLAUDE.md updated. This is your single source of truth. Whenever your vision changes or you make a technical decision, update CLAUDE.md immediately. Both tools read it, and it keeps you all aligned. I update mine weekly.

Use Cowork for big-picture thinking. Don’t ask Claude Code to decide if you should use Astro or Next.js. Ask Cowork. Don’t ask Claude Code to write your brand voice guidelines. Ask Cowork. Claude Code is a dev—let it code.

Give Claude Code the specs, not the vision. When you want a feature built, don’t say “I want a nice homepage.” Say “Build a bento grid homepage with 7 cards: Hero (span-2, row-2), Projects (span-2), About (span-2), Contact (span-1), Social (span-1), Now (span-2), Writing (span-4). Each card has a 16px border radius, 24px padding, and uses the color palette from CLAUDE.md.” The more specific you are, the better Claude Code executes.

Use Cowork’s web search for research. If you’re making a decision that requires current information (best practices, pricing comparisons, market trends), ask Cowork. It has web search. Claude Code doesn’t.

Don’t overlap their work. Don’t ask Claude Code to write your brand voice guidelines, and don’t ask Cowork to debug your code. You’ll get mediocre results. Each tool has a zone of genius—play to that.

Version your CLAUDE.md. If you’re working on multiple major features or branches, keep track of your CLAUDE.md versions. I commit mine to git every time I make a significant change. It’s easier to revert context than to figure out what broke.

Use MCP integrations sparingly, but strategically. Cowork can connect to Vercel, Supabase, Stripe, GitHub, and other services via MCP. This is powerful for the final 10% of work (deployments, database migrations, payment integrations). Don’t try to do this with Claude Code alone.

The Result

I’ve been using this workflow for about a month now, and it’s genuinely changed how I approach projects. The separation of concerns is clean: Cowork thinks, plans, and researches. Claude Code executes. And the shared CLAUDE.md keeps them in perfect sync.

What used to take me two weeks (design, build, refactor, deploy) now takes me four days. I’m not writing any code—I’m directing two AI systems to work together. It’s less about “AI writing your code” and more about “AI doing your work while you stay in the strategy layer.”

If you’re building anything—a website, an app, a landing page, a content project—I’d recommend trying this workflow. Point Cowork and Claude Code at the same folder. Write a solid CLAUDE.md. Let them specialize. You’ll be surprised how much faster you move.

The orchestrator and the dev. They work better together.

← All posts