Claude Code Team Collaboration Guide

1

The Core Principle

Shared config via git, personal state stays local. Everything in .claude/ (without "local" in the name) is your team contract. Everything with "local" or under ~/.claude/ is personal.

2

Shared vs. Personal

Artifact	Location	Committed?	Purpose
`CLAUDE.md`	Project root	Shared	Team instructions, standards, build commands
`.claude/settings.json`	Project `.claude/`	Shared	Permissions, hooks, MCP servers
`.claude/rules/`	Project `.claude/`	Shared	Scoped rules by topic or file path
`.claude/skills/`	Project `.claude/`	Shared	Project-specific skills and commands
`.claude/agents/`	Project `.claude/`	Shared	Custom subagent definitions
`CLAUDE.local.md`	Project root	Personal	Your personal project preferences
`.claude/settings.local.json`	Project `.claude/`	Personal	Your permission overrides
`~/.claude/`	Home directory	Personal	Global config, rules, skills
Auto memory	`~/.claude/projects/`	Personal	Each dev accumulates their own learnings

3

Best Practices

1

CLAUDE.md is your team's constitution Put coding standards, architecture decisions, build commands, and constraints here. Both developers' Claude instances read this on every session. It walks up the directory tree, so monorepo sub-projects can have their own.
2

Use .claude/rules/ for scoped team rules testing.md, api-conventions.md, security.md — shared via git. Personal preferences go in ~/.claude/rules/ (not shared).
3

Shared hooks enforce consistency Commit formatting hooks, lint-on-save, or file protection rules in .claude/settings.json. Personal hooks go in .claude/settings.local.json.
4

Memory is NOT shared — and that's by design Each developer accumulates their own learnings in ~/.claude/projects/. For team knowledge, promote it into CLAUDE.md or .claude/rules/ instead.
5

Coordinate branches, not sessions Use standard git branching. Each dev works on their own branch. Claude Code respects git state; both devs can work in parallel without conflicts.
6

PR changes to shared Claude config Treat changes to CLAUDE.md, .claude/settings.json, rules, and skills like code changes — review them in pull requests.

4

Required .gitignore Entries

      # Claude Code personal files — do NOT commit

      CLAUDE.local.md

      .claude/settings.local.json

      # These SHOULD be committed (team shared):

      # ✓ CLAUDE.md

      # ✓ .claude/settings.json

      # ✓ .claude/rules/

      # ✓ .claude/skills/

      # ✓ .claude/agents/

Auto memory lives in ~/.claude/projects/ (outside your repo) — no gitignore needed for it.

5

Flavor-Specific Collaboration Patterns

Shared State

STATE.md tracks active feature, tier, gate, and branch
docs/builds/ holds build logs per feature
docs/build-layers.md tracks layer progress

How to Split Work

Assign different features or layers to each developer
The gate system (design → plan → build → review) serializes decisions while parallelizing execution
Each dev should be on a different feature branch when using /build-feature

Tip: Standard git workflow. Lowest coordination overhead. If both devs are on different features, there's almost zero friction.

Built-in Collaboration Docs

docs/stakeholders.md — who's involved, roles, contact channels
docs/operating-model.md — roles, responsibilities, handoffs
docs/automation-inventory.md — scheduled tasks with owners
docs/playbooks/ — SOPs for repeatable tasks
docs/cadence.md — recurring cycles with next-run dates

How to Split Work

Assign cycle ownership explicitly — Dev A owns recurring cycles, Dev B owns initiatives
Session logs in docs/sessions/ enable async handoff between devs
Playbook-driven workflow makes delegation safe

Tip: Ops has the richest collaboration vocabulary. Use stakeholders.md and operating-model.md to make role assignment explicit. This is the flavor where collaboration matters most — and is best supported.

Shared State

sources/manifest.md tracks ingested sources
wiki/index.md is the topic map
Sources are immutable — never edited, only superseded

How to Split Work

Split by topic domain — Dev A curates domain X, Dev B handles domain Y
Wiki pages are mostly independent files = lowest merge-conflict risk
The wiki index is the only contention point — keep entries one-line

Tip: Immutable sources + independent wiki pages make this the safest flavor for parallel work. The only coordination needed is the wiki index and avoiding duplicate source ingestion.

6

What to Watch Out For

!

STATE.md conflicts Only one dev should advance a given work unit at a time. Assign work units clearly to avoid merge conflicts.

!

Skill evolution If one dev modifies a shared skill in .claude/skills/, the other gets the change on next git pull. Treat skill changes like code — PR them.

!

Hook divergence A hook added to .claude/settings.json affects both devs. Discuss hooks before committing them.

!

Memory divergence Over time, each dev's Claude "knows" different things. Project-critical knowledge belongs in CLAUDE.md, not memory.

!

Agent Teams ≠ two humans Agent Teams is for one developer orchestrating multiple Claude sessions. Two humans each running Claude Code is a different pattern — you coordinate through git.

7

Onboarding Checklist

Steps to get your colleague up and running on a shared project:

Ensure CLAUDE.md, .claude/settings.json, .claude/rules/, and .claude/skills/ are committed
Add CLAUDE.local.md and .claude/settings.local.json to .gitignore
Have your colleague clone the repo and run claude — it picks up all shared config automatically
Agree on work unit ownership (who works on which feature / cycle / wiki domain)
Use PRs for changes to shared Claude config, just like code
Each dev creates their own CLAUDE.local.md for personal preferences