Claude Code Team Collaboration Guide: Handoffs, Reviews, and Permissions

Claude Code is useful for solo development, but team adoption exposes a different set of problems. The hard part is not only writing better prompts. It is knowing who approved which command, what context Claude saw, what it did not inspect, and whether an AI review was actually accepted by a human.

This guide shows a practical workflow for small and medium teams that want Claude Code to help with implementation, PR pre-review, onboarding, incident handoff, and shared development standards. A permission boundary means the files and commands Claude Code may read, edit, or run. A review receipt means a short PR record of how the team handled Claude Code’s suggestions.

flowchart LR
  A["Developer request"] --> B["CLAUDE.md and rules"]
  B --> C["Claude Code work"]
  C --> D["Tests and diff review"]
  D --> E["Review receipt"]
  E --> F["Human PR review"]

Four Shared Locations

Team workflows become stable when rules live in files, not in one person’s memory.

Location	Purpose	Commit it
CLAUDE.md	Project conventions, forbidden actions, test commands	Yes
.claude/settings.json	Shared permissions, deny rules, hooks	Yes
.claude/settings.local.json	Personal URLs, temporary sandbox settings	No
.claude/prompts/*.md	Handoff, review, investigation templates	Yes

The official docs explain how Claude Code memory, settings, permissions, and security fit together. For related local guides, see CLAUDE.md Best Practices, Claude Code Hooks Guide, and Advanced GitHub Actions.

Use Case 1: Developer-to-Reviewer Handoff

The most common failure is handing a PR to a reviewer with only “Claude fixed it.” Reviewers need to know what Claude inspected, what commands were approved, what tests failed, and which decisions still need human judgment.

Create .claude/prompts/handoff.md:

# Write a team handoff note

Read the current diff and write a handoff in this format.

## Goal
- Problem this change is meant to solve:

## Scope
- Files changed:
- Files not changed but likely affected:

## Verification
- Commands run:
- Passed/failed:
- Failure log summary:

## Reviewer focus
- Product decision:
- Security:
- Performance:
- Missing tests:

## Next owner
- Check first:
- Can wait:

Run it after preparing a diff:

claude -p "Read git diff and create a team handoff note using .claude/prompts/handoff.md"

Paste the result into the PR body. That one habit makes asynchronous review much easier because the reviewer starts from known risks instead of rediscovering the work.

Use Case 2: PR Pre-Review

Claude Code should not replace human approval. It is best used as a pre-review step that catches obvious bugs, missing tests, security risks, and inconsistent changes before a person spends attention on design decisions.

Create .claude/prompts/pr-review.md:

# PR pre-review

Review the diff with these checks:

1. Branches, null/undefined, and boundary values that may become bugs
2. Authorization, validation, and secret exposure
3. N+1 queries, extra rerenders, and heavy synchronous work
4. Violations of CLAUDE.md rules
5. Missing test cases

Output format:
- Severity: high / medium / low
- File:
- Line or function:
- Reason:
- Suggested fix:

Mark speculative findings as "needs confirmation".

Run it locally with GitHub CLI:

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

For GitHub Actions, keep the automation limited to a comment. The final merge decision remains human-owned.

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          Diff:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

The official common workflows page also covers review and testing workflows. In a team, write the rule clearly: AI comments are advisory; humans approve.

Use Case 3: Onboarding New Engineers

New engineers usually struggle less with syntax and more with “which command is safe?”, “where is the business rule?”, and “what should I read first?” Claude Code can generate the first onboarding map.

claude -p "
Explain this repository for a new teammate.
Include:
- Main directories and responsibilities
- Commands for local run, lint, test, and build
- First 3 files to read
- Business rules to check before changing code
- Common mistakes and how to avoid them
- A 30-minute practice task

Do not guess. List unknowns as needs confirmation.
"

Do not publish the output untouched. Ask a senior engineer to spend 30 minutes adding the parts Claude cannot know: production constraints, team history, and operational risks. For larger exploration, the subagent pattern guide helps separate research from summarization.

Use Case 4: Incident and Shift Handoff

During incidents, Claude Code is useful for summarizing logs and organizing hypotheses. The failure modes are serious: pasting secrets, sharing unverified guesses as facts, and losing what was already tried when the owner changes.

Store this as .claude/prompts/incident-handoff.md:

# Incident handoff

## Symptom
- Since when:
- Scope:
- User impact:

## Observed facts
- Logs:
- Metrics:
- Reproduction steps:

## Tried so far
- Commands:
- Result:
- Failed hypotheses:

## Remaining risk
- Data corruption:
- Security impact:
- Rollback status:

## Next owner
- First screen/log to inspect:
- Commands that must not be run:

Mask emails, access tokens, and customer IDs before giving logs to Claude Code. The official security docs describe permission prompts and prompt-injection risks; teams should treat logs as production data, not casual chat content.

CLAUDE.md Rules That Work

CLAUDE.md is for facts the team keeps repeating. Keep it short and concrete.

# Project instructions for Claude Code

## Before work
- Run `git status --short` before editing.
- Never revert existing user changes.
- If product behavior is unclear, write "needs confirmation" in the PR.

## Code rules
- Validate all API inputs.
- Make transaction boundaries explicit for database writes.
- Reuse existing translation keys before adding UI copy.

## Tests
- Add unit tests for logic changes.
- Add one regression test for each bug fix.
- If tests could not be run, explain why.

## PR
- Include summary, verification, and remaining risk.
- Only use Claude Code suggestions after human review.

If the repo already uses AGENTS.md, import it instead of duplicating rules.

@AGENTS.md

## Claude Code only
- Use plan mode for billing, auth, and deletion flows.
- Humans handle `git push`, production deploys, and migrations.

Lock Permission Boundaries

Claude Code is designed around explicit permission approval, but team projects still need shared boundaries. Start with a narrow allow list and a clear deny list.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

Hooks can run checks after edits or block risky commands. See the official hooks reference before rolling them out.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

This works only if your project has an npm run lint script. In a large monorepo, run file-scoped checks or move heavy verification to CI.

Add a Review Receipt

AI review becomes risky when nobody records which suggestions were accepted. Add this to your PR template:

## Claude Code review receipt

- Prompt used:
- Diff Claude Code reviewed:
- Suggestions accepted:
- Suggestions rejected and why:
- Extra human checks:
- Tests run:
- Remaining risk:

Final decision owner:

Use “not used” when Claude Code was not involved. The point is to keep AI-assisted work at least as transparent as normal work.

Pitfalls and Fixes

Failure	Impact	Fix
Stale CLAUDE.md	Old commands and deprecated APIs return	Review it monthly using real failures
Broad permissions	Secrets and production-like actions get too close	Write deny rules first, then minimal allow rules
AI-only approval	Product and ownership decisions disappear	Human approval is mandatory
Verbal handoff	The next day nobody can trace the reason	Paste handoff notes into PRs or issues
/clear removes context	Motivation for changes gets lost	Save a summary before compaction or reset
Heavy hooks	Developers start bypassing the workflow	Use file-scoped hooks or CI

Communication also fails when prompts are too vague. “Fix it nicely” asks Claude Code to guess the finish line. Prefer short boundaries: “only this function”, “do not touch schema”, “read the failing test log first”.

Minimum Team Checklist

• CLAUDE.md contains commands, forbidden actions, and PR rules
• .claude/settings.json separates allow, ask, and deny
• .claude/settings.local.json is gitignored
• Handoff, PR review, and incident prompts are shared
• The PR template includes a review receipt
• The final human decision owner is clear
• A 30-minute onboarding task exists

ClaudeCodeLab keeps refining templates like these for AI-assisted development teams. If you want a faster starting point for internal rollout, see ClaudeCodeLab products.

Conclusion

Team use of Claude Code is not about finding a magic prompt. It is about shared instructions, narrow permissions, durable handoffs, and review receipts that make AI work auditable.

For solo work, memorizing useful prompts may be enough. For teams, another person must be able to reproduce the workflow, trace failures, and separate Claude Code’s suggestions from human decisions.

After trying this setup in Masa’s small validation repository, the biggest immediate improvement came from adding handoff notes and review receipts to PRs. Reviewers asked fewer “what did you check?” questions. The worst setting was a full lint hook after every edit; it was too slow, so CI was a better place for that check. Start with CLAUDE.md, the PR pre-review prompt, and the review receipt.