Mastering Claude Code: Subagents, Agent Teams, Background Tasks, and Parallel Workflows

Overview

This course explores the advanced capabilities introduced in Anthropic’s Claude Code platform, focusing on subagents, agent teams, background tasks, and parallel workflows. Learners will understand how these features transform Claude Code from a simple single‑prompt chat interface into a powerful orchestration system for complex software engineering tasks. By the end of the course, you will be able to design, implement, and manage multi‑agent workflows that run concurrently, delegate work to specialized subagents, and automate long‑running processes without blocking your interactive session. The material is essential for developers, DevOps engineers, and AI‑augmented software teams who want to maximize productivity using Claude Code’s latest tooling.

Background & Context

Claude Code emerged as Anthropic’s answer to the growing demand for AI‑powered coding assistants that go beyond autocomplete and chat‑based suggestions. Early versions allowed users to ask natural‑language questions and receive code snippets, but real‑world software development often requires coordinated, multi‑step actions such as refactoring across dozens of files, running test suites, or generating documentation while continuing to write new code. Recognizing this gap, Anthropic introduced a suite of orchestration primitives—subagents to isolate responsibilities, agent teams to collaborate on shared goals, background tasks to run work off the main thread, and parallel workflows to execute independent steps simultaneously. These features align with broader trends in AI agent research, where modularity, concurrency, and fault tolerance are critical for scaling LLM‑based automation. The official 25‑minute video from Anthropic’s channel demonstrates these capabilities in a live coding session, showing how a developer can spawn a subagent to handle a linting fix while the main agent continues to implement a feature, all while background tasks run dependency updates and parallel workflows execute unit tests on multiple modules.

Core Concepts

Subagents

A subagent is a lightweight, child instance of Claude Code that inherits the parent’s context but operates with a narrowly defined scope. Think of it as a specialized worker that you can spawn to handle a discrete task—such as fixing a specific compiler warning, generating boilerplate for a new API endpoint, or running a static analysis tool—without interrupting the main agent’s conversation. Subagents receive their own token budget and can be configured with custom system prompts that constrain their behavior (e.g., “Only output Python code that adheres to PEP 8”). Because they run in isolation, any errors or side effects remain contained, making them ideal for risky or experimental changes. In practice, you invoke a subagent using the /agent spawn command, pass it a prompt, and optionally retrieve its output via a shared artifact store. For example:

/agent spawn --name lint-fixer --prompt "Run eslint --fix on src/**/*.js and report any remaining issues"

The subagent will execute the command, write any modified files to the workspace, and post a summary back to the parent thread. This pattern enables a divide‑and‑conquer strategy where complex refactors are broken into many small, verifiable steps.

Agent Teams

An agent team is a collection of subagents (or even full Claude Code instances) that collaborate toward a shared objective, communicating through a structured message bus. Unlike a loose group of independent subagents, a team defines roles, handoff protocols, and shared state. For instance, a team tasked with implementing a new microservice might consist of a “Designer” subagent that writes the OpenAPI spec, a “Coder” subagent that generates the server skeleton, a “Tester” subagent that creates unit and integration tests, and a “Reviewer” subagent that runs static analysis and security scans. The team coordinator—often the parent agent—can route messages based on content type: design artifacts go to the Designer, code snippets to the Coder, etc. This mirrors human software teams where specialization reduces cognitive load and increases throughput. Claude Code provides a /team create subcommand that accepts a YAML manifest describing each member’s name, role, and initial prompt:

name: microservice-team
members:
  - name: designer
    role: spec-writer
    prompt: "Write an OpenAPI 3.0 spec for a RESTful user‑management service."
  - name: coder
    role: implementation
    prompt: "Generate a Go server based on the spec provided by the designer."
  - name: tester
    role: validation
    prompt: "Create table‑driven unit tests for each handler in the generated code."
  - name: reviewer
    role: quality
    prompt: "Run golangci-lint and gosec on the codebase; report any high‑severity findings."

Once the team is instantiated, the parent can issue a high‑level goal (“Deliver a production‑ready user‑management microservice”) and watch the agents negotiate, iterate, and produce a cohesive output.

Background Tasks

Background tasks allow long‑running or periodic operations to execute without blocking the interactive chat session. They are launched with the /bg start command and run in a separate execution environment, returning control to the user immediately. Typical use cases include dependency updates (npm install, pip upgrade -r requirements.txt), continuous integration pipelines, log tailing, or watching file changes to trigger regeneration of documentation. Because they run asynchronously, you can monitor their progress via status commands (/bg list, /bg status <id>) and retrieve logs or artifacts when they finish. Crucially, background tasks can be chained: the completion of one task can trigger the start of another via event hooks. Example:

/bg start --name dep-update --command "pip install --upgrade -r requirements.txt" --on-success "/bg start --name test-suite --command \"pytest -q\""

This launches a dependency upgrade; if it succeeds, it automatically starts the test suite. Background tasks survive temporary disconnections, making them suitable for overnight builds or data‑processing jobs that may take hours.

Parallel Workflows

Parallel workflows enable the execution of independent steps concurrently, dramatically reducing wall‑clock time for tasks that can be decomposed into non‑dependent sub‑jobs. Claude Code implements this through the /workflow parallel construct, which accepts a list of commands or agent invocations and runs them in separate threads or processes, collecting results once all have finished. This is especially valuable for test suites that target different modules, code generation for multiple language bindings, or data‑processing pipelines where each chunk can be handled separately. A simple example:

/workflow parallel \
  --step "pytest tests/unit/test_auth.py -q" \
  --step "pytest tests/unit/test_payment.py -q" \
  --step "pytest tests/unit/test_email.py -q"

Each step runs in its own environment; the workflow completes when the slowest step finishes, and a consolidated report is returned. For more complex scenarios, you can combine parallel workflows with agent teams: each branch of the parallel workflow could spawn a subagent team responsible for a specific feature area, achieving both horizontal scaling (parallelism) and vertical specialization (teamwork).

How It Works / Step-by-Step

To leverage these features in a real project, follow this end‑to‑end workflow:

1. Initialize the workspace – Open Claude Code in your project root (claude-code .). Ensure you have the latest version (≥ 1.2) that includes the orchestration commands.
2. Define the overall goal – Articulate a high‑level objective in natural language, e.g., “Add OAuth 2.0 login to the web app and ensure all existing tests pass.”
3. Spawn specialist subagents – Break the goal into discrete work packages. For each, run /agent spawn with a tailored prompt. Example for the login feature:

```

/agent spawn --name oauth-login --prompt "Implement OAuth 2.0 authorization code flow using the existing User model; generate routes, middleware, and unit tests."

```

Wait for the subagent to finish and review its output via the artifact view.

1. Form an agent team for integration – If multiple subagents need to cooperate (e.g., one for frontend changes, one for backend API, one for test creation), create a team manifest and launch it with /team create. The team coordinator will manage message passing; you can observe the interaction log in the team pane.
2. Kick off background tasks for maintenance – While the team works, start background tasks that keep the environment healthy:

```

/bg start --name lint-watch --command "npm run lint -- --watch" --on-change "/agent spawn --name lint-fixer --prompt \"Fix any new lint errors reported by the watcher.\""

/bg start --name dep-audit --command "npm audit --production" --interval 1h

```

These run indefinitely, reporting results to the chat when they detect issues.

1. Execute parallel workflows for validation – Once the feature code is ready, run a parallel workflow to validate across multiple dimensions:

```

/workflow parallel \

--step "/agent spawn --name unit-tests --prompt \"Run jest unit tests on the new auth module.\"" \

--step "/agent spawn --name integration-tests --prompt \"Execute Cypress end‑to‑end flow for login/logout.\"" \

--step "/agent spawn --name security-scan --prompt \"Run OWASP ZAP baseline scan on the local dev server.\""

```

The workflow returns a combined success/failure status; any failing step triggers a notification.

1. Review and merge – Examine the aggregated logs, approve the changes via your version control system, and optionally trigger a CI/CD pipeline that mirrors the same parallel workflow in a staging environment.

Throughout this process, you can pause, inspect, or abort any subagent, team member, background task, or workflow step using the corresponding /cancel commands, giving you fine‑grained control over the automation lifecycle.

Real-World Examples & Use Cases

Example 1: Large‑Scale Refactor

A team needs to migrate a monolithic JavaScript application to TypeScript while preserving functionality. Using Claude Code, they create a subagent for each module (/agent spawn --name ts-convert-auth --prompt "Convert auth/*/.js to TypeScript, update imports, and run tsc --noEmit"). An agent team coordinates the conversion, ensuring shared types are defined first. Background tasks continuously run tsc --watch to catch early errors, and a parallel workflow executes the existing Jest test suite on each converted module in parallel, providing rapid feedback. The result is a migration completed in days rather than weeks, with minimal manual intervention.

Example 2: Automated Documentation Generation

A documentation maintainer wants to keep API reference pages in sync with code changes. They spawn a background task that watches the src/ directory for changes to JSDoc comments. Upon detection, it triggers a subagent that runs typedoc --out docs/api and then opens a pull request with the updated files. Simultaneously, an agent team runs a parallel workflow that checks for broken links (markdown-link-check) and validates code snippets (dotenv-cli node snippets/test.js). This creates a self‑healing documentation system that requires virtually no human oversight after initial setup.

Example 3: Multi‑Language Library Release

An open‑source maintainer must publish a new version of a library that provides bindings for Python, Rust, and Go. They create an agent team with three members: one updates the Python setup.py and runs twine upload, another updates the Rust Cargo.toml and publishes to crates.io, and the third updates the Go go.mod and pushes to GitHub releases. A parallel workflow executes the test suites for each language binding concurrently, ensuring that a failure in one language does not block the others. Background tasks monitor the registries for any post‑publish issues and notify the maintainer via email.

Key Insights & Takeaways

• Subagents let you delegate isolated, well‑scoped tasks to specialized AI workers without losing the main conversational thread.
• Agent teams enable structured collaboration among multiple AI workers, mimicking human software teams with defined roles and communication protocols.
• Background tasks free up your interactive session by running long‑running or periodic operations asynchronously, with support for chaining and event‑based triggers.
• Parallel workflows dramatically reduce latency for independent validation, testing, or code‑generation steps by executing them concurrently.
• Combining these primitives—subagents inside teams, teams launched via background tasks, and workflows run in parallel—creates a hierarchical automation system capable of handling enterprise‑scale software engineering.
• Proper scoping of prompts is critical: overly broad prompts cause subagents to drift, while overly narrow ones may require excessive manual intervention.
• Monitoring and logging are built‑in; use /agent list, /team list, /bg list, and /workflow status to inspect live executions and diagnose failures.
• Error isolation means a failing subagent or background task does not corrupt the workspace state of other concurrent operations.
• The orchestration commands are version‑controlled; always verify you are running the latest Claude Code release to access all features.
• These capabilities shift the user role from prompt engineer to workflow designer, focusing on defining goals, constraints, and integration points rather than writing every line of code manually.

Common Pitfalls / What to Watch Out For

One frequent mistake is launching too many subagents simultaneously without considering token or resource limits, which can lead to throttling or degraded performance. Always start with a modest concurrency level and scale up only after observing stable behavior. Another pitfall is neglecting to define clear handoff criteria in agent teams; without explicit message schemas, agents may talk past each other, resulting in duplicated work or stalled progress. Users sometimes forget to monitor background tasks, assuming they will run forever; long‑running tasks can accumulate log files or leave stray processes if not periodically checked with /bg status. When using parallel workflows, it is essential to ensure that the steps truly have no shared mutable state; concurrent writes to the same file or database can cause race conditions and corrupt outputs. Finally, over‑reliance on automation can erode manual code‑review habits; always allocate time to inspect the artifacts produced by subagents and teams before merging to main branches.

Review Questions

1. Explain how a subagent differs from a standard Claude Code chat session in terms of scope, state, and typical use cases.
2. Describe the steps required to create an agent team that coordinates a frontend subagent, a backend subagent, and a testing subagent, including the manifest format and communication mechanism.
3. Given a scenario where you need to run a linter, a test suite, and a security scan concurrently while also keeping a dependency watcher alive in the background, outline the exact sequence of Claude Code commands you would issue, and explain how you would verify that each component completed successfully.

Further Learning

• Study the official Claude Code documentation on orchestration commands (/agent, /team, /bg, /workflow) for advanced flags and environment variables.
• Explore patterns for fault‑tolerant agent teams, such as checkpointing and replay mechanisms, drawing from research on multi‑agent reinforcement learning.
• Investigate integrating Claude Code workflows with external CI/CD systems (GitHub Actions, GitLab CI) to trigger background tasks from push events.
• Read about concurrent programming models (actors, futures, promises) to better design parallel workflows that avoid shared‑state hazards.
• Experiment with building domain‑specific language (DSL) wrappers around the Claude Code CLI to simplify repetitive workflow definitions for your team or organization.

<!-- auto-diagram -->

flowchart LR
    A[Complex Software Task] --> B{Orchestration Layer};
    B --> C[Subagents/Teams];
    C --> D[Delegated Work];
    D --> E{Parallel Workflows};
    E --> F[Background Tasks];
    F --> G[Concurrent Execution];
    G --> H[Completed Solution];