Mastering Claude Code: Subagents, Custom Workflows, and Sandboxed Execution in Professional Pipelines

Claude Code can investigate a codebase, edit files and run development tools. For a team workflow, separate three decisions: which task to delegate, where a worker may write, and which actions it may execute. Subagents, Git worktrees and permission settings address different parts of that problem; none makes an unchecked change safe to merge.

1. The Multi-Agent Hierarchy: Planner vs. Worker Subagents

Use a subagent when its investigation is self-contained and the main conversation needs a short finding rather than the entire search output. Anthropic documents separate context and configurable tools for subagents. There is no universal repository size or turn count at which delegation becomes necessary. A small fix may be quicker to complete in the main conversation. See the official subagent guide.

The following is a suggested division of responsibilities, not a fixed product hierarchy. Start with the permissions each task needs rather than giving every worker full access.

2. Managing Concurrency with Git Worktrees

A worktree provides another checkout of the same repository. Give independent workers separate branches and clear file ownership. This reduces direct interference with a checkout, but does not prevent incompatible edits, shared-service changes or merge conflicts. Git documents the behavior and restrictions in its worktree reference.

1. From the main repository, check git status and choose a task-specific branch and unused directory.
2. Create the worker checkout: git worktree add -b ai/parser-fix ../ai-parser-fix HEAD.
3. Have the worker make the scoped change and run the relevant checks inside that checkout. Inspect the diff before committing.
4. Review the branch through your normal integration process. After integration and confirmation that no uncommitted work remains, remove the extra checkout with git worktree remove ../ai-parser-fix.

Adapt both names to your repository. Do not run several workers against the same test database, deployment environment or other shared state without coordination. A separate directory does not isolate those dependencies.

3. Configuring Custom Skills and CLAUDE.md Rules

Put the project’s build commands, architectural conventions and review requirements where agents and humans can find them. A CLAUDE.md instruction describes intended behavior; it does not enforce access restrictions. Anthropic distinguishes instructions from the permission system, where allowed and denied tool actions are configured.

• Build and test commands: specify the commands that actually exist in this project and when each is needed.
• File ownership: state which module a worker may change and who owns related files.
• Acceptance criteria: describe the observable behavior, relevant regression checks and conditions requiring a human decision.
• Handoff format: request the changed files, result of each check, remaining uncertainty and any action still pending.

Check permissions and sandboxing before execution

Use /permissions to inspect the active rules. Permission modes can change when actions run automatically or require approval. Check the mode selected in your environment instead of inferring it from a tutorial.

For supported environments, Anthropic documents a sandboxed Bash tool with filesystem and network boundaries. Review its configuration and any exclusions. These boundaries apply to the configured tool execution; they should not be treated as a blanket guarantee for every connector, remote system or approved action.

The separate --restricted CLI option is intended for evaluation harnesses: it removes certain built-in execution and web-fetch tools and confines built-in file tools. It is not another name for the Bash sandbox. Check the CLI reference before using this option.

A practical worker handoff

Use this example as a task brief, then adapt the paths and checks. It is an editorial workflow recommendation, not a claim that an agent will obey it without enforced permissions and review.

Task: fix the parser's handling of an empty input.
Scope: src/parser/ and the related parser tests only.
Acceptance: the empty input returns the documented result;
existing valid-input behavior is preserved.
Validation: run the parser test command documented by this project.
Stop and report: the fix requires another module, a new dependency,
credentials, or a change to an external service.
Handoff: explain the diff, report test results, and list what is unverified.

Before integration, inspect the diff for unrelated edits, confirm the checks exercise the reported failure, and review external actions separately. Passing tests is evidence about the tested cases, not proof that all behavior is correct.

Frequently Asked Questions (FAQ)

How does Claude Code handle sensitive API keys and secrets?

A .env file or environment variable is not automatically a safe boundary. Restrict secret access and network destinations through the controls appropriate to your environment, and inspect what enabled tools and integrations can access. Do not paste credentials into prompts or include them in a worker’s report.

Can Claude Code execute long-running tasks autonomously?

Capabilities depend on the interface, configuration and available tools. Give a long task a bounded objective, a checkpoint and a stop condition. Do not use an open-ended “run until everything passes” instruction as a substitute for reviewing failing tests, cost, external actions and the resulting diff.

Method and update: This guide was revised on 6 September 2026 using Anthropic’s and Git’s official documentation, with AI assistance for research and editing. The workflow and handoff example are editorial recommendations. They are not a product benchmark, a penetration test or evidence of a particular team’s results. Recheck the linked documentation against the version and environment you use.