Structuring Tasks for Cowork

Claude's cowork mode lets you delegate tasks to an autonomous agent that works in the background while you continue with other work. Unlike interactive sessions where you prompt and respond turn-by-turn, cowork mode takes a task description upfront, executes it independently — reading files, editing code, running commands — and presents the completed work for your review.

The quality of the output depends almost entirely on how well you structure the task description. A vague task produces vague results. A well-structured task with clear goals, sufficient context, and explicit success criteria produces work that needs minimal revision.

How Cowork Mode Differs from Interactive Mode

In a standard Claude Code session, you have a conversation. You ask Claude to do something, it does part of the work, you give feedback, it adjusts. This back-and-forth is valuable when you are exploring an approach or when the task requirements are unclear.

Cowork mode removes the back-and-forth. You write the task, Claude executes it autonomously, and you review the output when it is done. This means:

• Claude makes all decisions without checking in with you
• If the task description is ambiguous, Claude will make its best guess rather than asking for clarification
• If Claude encounters an unexpected situation (a test fails, a file is missing), it will attempt to resolve it on its own
• The entire execution happens in the background — you can work on other things

This makes cowork mode ideal for well-defined tasks where you know exactly what you want, and less ideal for exploratory work where the approach is uncertain.

When to Use Cowork vs Interactive Mode

Understanding when cowork is the right choice prevents frustration on both sides — yours and the agent's.

Use cowork when:

• The task has clear, stable requirements that will not change mid-execution
• The work is long-running and involves many files or steps
• You can define success criteria that Claude can verify on its own
• The task can be completed without your judgment at intermediate decision points
• You want to work on something else while the task runs

Use interactive mode when:

• You are exploring an approach and expect to refine direction as you go
• The task requires aesthetic judgment ("make it look good") or subjective decisions
• You need to approve intermediate steps before proceeding
• The requirements are still forming and may shift based on what Claude discovers
• The task is small enough that back-and-forth is not a significant overhead

A practical heuristic: if you would need to say "wait, actually do it differently" more than once during inline execution, cowork is probably not the right fit yet. Get the requirements stable through an interactive conversation first, then hand off the implementation to cowork.

Writing Clear Task Descriptions

A good cowork task description has five components. Each one reduces the probability that Claude will go in the wrong direction.

1. The Goal

State what you want to exist when the task is complete. Frame it in terms of observable outcomes, not implementation steps.

Good goal:

Add a dark mode toggle to the application header. When toggled, the
entire application should switch between light and dark themes. The
user's preference should persist across page reloads.

Weak goal:

Do dark mode.

The good goal tells Claude what the feature should do, where it should appear, and what behavior to preserve. The weak goal leaves everything to Claude's interpretation — and an autonomous agent with a broad mandate will interpret broadly.

2. Context

Provide information that Claude needs but cannot reliably infer from the codebase alone. This includes architectural decisions, relevant prior work, and constraints from external factors.

Context:
- The app uses Tailwind CSS with the dark: variant already configured
- There is an existing ThemeContext in src/contexts/ThemeContext.tsx that
  currently only provides the theme value but has no toggle function
- The header component is src/components/layout/Header.tsx
- All color values use Tailwind utility classes, so dark mode should work
  by adding a "dark" class to the <html> element
- The ThemeContext was created specifically to support this feature but
  was never fully wired up

Naming key files is especially important. It saves Claude from searching the entire codebase, reducing token usage and improving accuracy. Think of it as giving a new team member a map of the relevant code before they start working.

3. Constraints

Explicitly state what Claude should NOT do. Constraints prevent scope creep and unintended changes — the two most common issues with autonomous agents.

Constraints:
- Do not modify the color palette — only add the dark: variant equivalents
- Do not change the header layout or spacing
- Do not add any new npm dependencies
- Do not modify any test files — I will update tests separately
- Do not change src/components/ui/ — those components will be updated
  in a separate task

Constraints are critical in cowork mode because Claude cannot ask you "should I also update the footer?" — it will just do it if it seems logical. Every constraint you omit is a decision Claude makes on its own.

4. Success Criteria

Define how Claude should verify its own work. This gives the agent a stopping condition beyond "I think I am done."

Success criteria:
- npm run typecheck passes with no errors
- npm run lint passes with no errors
- Toggling the dark mode switch changes the theme immediately
- Refreshing the page preserves the last selected theme
- The toggle is visible and accessible on mobile viewports

Without success criteria, Claude might implement the feature but leave behind TypeScript errors, break an existing test, or produce something that technically works but does not meet your quality bar. Success criteria turn the task from "implement this" into "implement this and prove it works."

5. Scope Boundaries

For larger tasks, define what is in scope and what is explicitly out of scope. This is more granular than constraints — it tells Claude exactly where the edges of the task are.

In scope:
- Adding the toggle component to the header
- Updating ThemeContext to support toggling
- Adding dark: variant classes to the main layout components
  (Header, Sidebar, Footer, PageContainer)

Out of scope:
- Updating individual page components for dark mode (separate task)
- Adding animation or transition effects to the theme switch
- Supporting system-preference-based auto-detection (future enhancement)
- Writing tests for the new functionality (separate task)

Breaking Large Tasks into Subtasks

Cowork mode works best with focused, well-scoped tasks. If a task is too large, Claude may lose coherence, make inconsistent decisions across files, or miss edge cases in later steps because its context is consumed by earlier work.

When to break up a task:

• The task touches more than 10-15 files
• The task involves multiple independent concerns (UI + API + database)
• Different parts of the task require different approaches or expertise
• You want to review intermediate output before proceeding

How to break up a task effectively:

Instead of one monolithic task:

Build a complete user profile page with avatar upload, bio editing,
notification preferences, and connected accounts management.

Break it into focused subtasks:

Subtask 1: Create the profile page layout
- Add a new page at /profile with the standard app layout
- Create a ProfileHeader component showing avatar placeholder and name
- Create a ProfileSection component for grouping related settings
- Use static placeholder content — real data integration comes later
- Key files: src/app/profile/page.tsx, src/components/profile/
- Success: page renders at /profile, typecheck passes, lint passes

Subtask 2: Add avatar upload functionality
- Add file upload to the ProfileHeader component from Subtask 1
- Upload to the existing /api/upload endpoint (already implemented)
- Show a loading spinner during upload, error state on failure
- Update the avatar URL in the user profile after successful upload
- Key files: src/components/profile/ProfileHeader.tsx, src/lib/upload.ts
- Success: can upload an image, it displays immediately, persists after reload

Subtask 3: Add bio editing with auto-save
- Add an editable bio field in a ProfileSection
- Use the existing TextArea component from src/components/ui/TextArea.tsx
- Auto-save after 500ms of no typing (debounced)
- Show a subtle "Saved" indicator that fades after 2 seconds
- Key files: src/components/profile/BioEditor.tsx (create), src/hooks/
- Success: can edit bio, it auto-saves, persists after reload, typecheck passes

Each subtask is independently reviewable and testable. If Subtask 2 has issues, you can fix them without affecting Subtask 1 or Subtask 3. And because the subtasks are sequenced logically, each builds on the output of the previous one.

Providing Sufficient Context

The difference between a good cowork result and a mediocre one often comes down to how much relevant context you provided upfront. Claude reads the codebase, but it makes better decisions when you point it in the right direction.

Name key files explicitly:

Key files:
- src/components/layout/Header.tsx — the header component to modify
- src/contexts/ThemeContext.tsx — existing theme context to extend
- src/app/layout.tsx — root layout where ThemeProvider wraps the app
- src/styles/globals.css — global styles, Tailwind base layer

This saves Claude from searching the entire codebase and reduces the risk of it finding and modifying the wrong file.

Explain conventions Claude should follow:

Conventions to follow:
- Components use function declarations: export function MyComponent() {}
- State management uses React context, not external libraries
- All components in src/components/ui/ have tests in __tests__/
- CSS uses Tailwind utility classes exclusively — no custom CSS files
- Hooks go in src/hooks/ with a use prefix: useThemeToggle.ts

Explain the "why" behind existing decisions:

Background:
- We chose Tailwind's dark: variant over CSS custom properties because
  our design system is built around Tailwind utilities
- The ThemeContext was added in preparation for this dark mode feature
  but only reads from localStorage — it does not apply the class to <html>
- The header already has a slot for action buttons on the right side

This background prevents Claude from "improving" your architecture when it should be working within it.

Reviewing Agent Output

When a cowork task completes, efficient review is essential. Here is a practical review process:

Step 1: Read the summary. Claude provides a summary of what it changed. Check that the scope matches your expectations before looking at any code.

Step 2: Check the diff. Use git diff to see exactly what changed. This is faster than reading entire files and immediately reveals unintended modifications.

Step 3: Run the success criteria. If you specified "npm run typecheck passes," run it. If you specified "the toggle persists across reloads," test it. Your success criteria should serve as a checklist.

Step 4: Look for scope creep. Did Claude modify files you did not mention? Did it add dependencies you did not request? Did it refactor something unrelated "while it was in there"? These are common with autonomous agents.

Step 5: Test edge cases. Autonomous agents handle the happy path well but may miss edge cases. What happens on first visit when no preference exists? What if localStorage is unavailable? What about server-side rendering where window does not exist?

Using Background Agents Effectively

Background agents let you run cowork tasks while continuing to work on other things. This is powerful for parallelizing independent work streams.

Effective parallel patterns:

# Agent 1: Working on the API layer
"Add a new /api/notifications endpoint that returns the user's
unread notifications. Use the existing notification_events table.
Include cursor-based pagination. Run typecheck when done.
Key files: src/app/api/, src/lib/db/notifications.ts"

# Agent 2: Working on the UI layer (independent of Agent 1)
"Create a NotificationBell component for the header that shows
an unread count badge. Use a placeholder data shape for now:
{ unread_count: number, notifications: Array<{id, title, date}> }.
Match the existing header icon styling. Run typecheck when done.
Key files: src/components/layout/Header.tsx, src/components/ui/"

# After both complete: You wire them together manually

This pattern gets both the API and UI built simultaneously. You then integrate them yourself with full understanding of both sides.

Anti-patterns to avoid:

• Running two agents that edit the same file — this creates merge conflicts that are tedious to resolve
• Running a dependent task before the prerequisite completes — Subtask 2 needs Subtask 1's output
• Launching too many agents simultaneously — reviewing five completed tasks at once is harder than reviewing them sequentially
• Giving an agent a task requiring your aesthetic judgment mid-execution — "build the UI and pick colors that look good" will rarely match your taste

Task Templates for Common Workflows

New Feature

Goal: [What the feature does, observable by users]

Context:
- Key files: [list 3-5 relevant files with their roles]
- Related features: [existing features this interacts with]
- Design constraints: [any UI/UX requirements or mockups]

Constraints:
- Do not modify: [files or modules to leave alone]
- Do not add: [no new dependencies, no new architectural patterns]
- Do not change: [existing APIs, function signatures, test files]

Implementation notes:
- [Specific technical approach to follow]
- [Existing patterns to match]
- [Naming conventions for new files]

Success criteria:
- npm run typecheck passes
- npm run lint passes
- npm test passes (existing tests not broken)
- [Feature-specific verification steps]

Bug Fix

Goal: Fix [specific bug description]

Observed behavior: [what happens now, including reproduction steps]
Expected behavior: [what should happen instead]

Context:
- Start with: [file path where the bug likely originates]
- Related files: [other files in the affected flow]
- Recent changes: [what changed before the bug appeared, if known]

Constraints:
- Fix the root cause, not just the symptom
- Do not change public API or function signatures
- Preserve all existing test behavior

Success criteria:
- [The specific scenario works correctly after the fix]
- npm test passes (no regressions)
- npm run typecheck passes

Refactor

Goal: Refactor [what] to [improve readability / reduce duplication / etc.]

Context:
- Files to refactor: [explicit list]
- Current pattern: [describe what exists now]
- Target pattern: [describe what you want after refactoring]

Constraints:
- Behavior must remain identical — this is a pure refactor
- All existing tests must pass without modification
- Do not refactor beyond the listed files
- Do not change any public interfaces or exported types

Success criteria:
- npm test passes with no modifications to test files
- npm run typecheck passes
- npm run lint passes
- [Structural goals: "no file exceeds 200 lines", "no function exceeds 30 lines"]

Common Mistakes in Task Descriptions

Too vague: "Improve the auth system." Improve how? Faster? More secure? Different UX? Claude will pick an interpretation, and it will probably not match yours.

Too prescriptive: "Open Header.tsx, go to line 47, add a div with className 'flex items-center gap-2', insert a button with onClick that calls toggleTheme..." If you are specifying every line of code, you do not need an autonomous agent.

Missing constraints: "Add user search." Without constraints, Claude might add a search API endpoint, a search UI with autocomplete, full-text indexing via a new dependency, and a search history feature — when you just wanted a simple filter on the existing list.

No verification step: "Add the notification bell." Claude implements it, but does it typecheck? Do existing tests still pass? Without a verification step, you inherit all validation work.

Conflicting instructions: "Use the existing Button component from the design system. Also, the button should have rounded corners and a gradient background." If the existing Button component does not support gradients, which instruction wins? Be explicit about priorities.

Assuming Claude knows your preferences: "Make it look like the rest of the app." This works if the app has a consistent, obvious style. It fails if the app has multiple visual patterns and Claude picks the wrong one. Be specific about which pattern to match.

Key Takeaways

• Cowork mode works best for well-defined tasks with clear goals — it is not ideal for exploratory or ambiguous work where direction may shift
• Every task description should include five components: goal, context, constraints, success criteria, and scope boundaries
• Constraints are critical because autonomous agents cannot ask clarifying questions mid-execution — state what NOT to do explicitly
• Break large tasks into focused subtasks of 10-15 files or fewer, each independently reviewable and testable
• Front-load context by naming key files and explaining conventions — this reduces wasted search time and improves accuracy
• Include verification steps (typecheck, lint, test) as success criteria so Claude confirms its own work before presenting it
• Use background agents for independent parallel work, but never have multiple agents edit the same files
• Review output efficiently: check the summary, review the diff, run success criteria, look for scope creep
• The most common mistake is insufficient constraints — an autonomous agent with a broad mandate will consistently do more than you expect