Claude Code for Teams: Best Practices for Shared Projects (2026)

Q: How do I prevent Claude Code from accessing sensitive files?

Create a .claudeignore file (similar to .gitignore) listing files Claude should not read. Alternatively, set file permission restrictions. The main protection is not committing secrets to the repo in the first place.

Q: How do we handle CLAUDE.md for a monorepo?

Root CLAUDE.md for global conventions. Package-specific CLAUDE.md for package-level patterns. Claude Code reads both hierarchically when you're in a package subdirectory.

The single most important step for Claude Code team adoption is committing a well-maintained CLAUDE.md to your repo — it becomes living onboarding documentation that every developer's Claude instance reads automatically, ensuring AI-generated code follows team conventions instead of Claude's defaults. This guide covers the full team setup: shared context, API key management, cost allocation, and the workflow patterns that prevent the biggest team AI problem: inconsistent code quality across developers.

The Team AI Problem

When Claude Code is used inconsistently across a team:

Developer A has a detailed CLAUDE.md → Claude generates convention-following code
Developer B uses Claude Code cold → Claude generates generic code
Developer C prompts carelessly → Claude makes architectural choices inconsistently

The result: an AI-assisted codebase that's harder to maintain than a human-only one, because the AI made different implicit decisions for each developer.

The solution is centralized context management.

Step 1: The Shared CLAUDE.md

Every team member's Claude Code instance reads CLAUDE.md at session start. A well-crafted team CLAUDE.md means every developer gets the same "briefed" Claude.

What to include in a team CLAUDE.md

# [Project Name] — Claude Code Guide

## Project Context
[2-3 sentences: what the product does, who uses it, what stack we're on]

## Development Commands
```bash
# Required before every PR
npm run typecheck        # Zero type errors expected
npm run test             # All tests must pass
npm run lint             # Zero lint errors
npm run build            # Build must succeed

Architecture Rules

All DB queries go through lib/db/queries/ — no inline SQL or Prisma calls in routes
All server mutations go through Server Actions in app/actions/ — no direct DB access from components
Every API route validates the session: see middleware.ts for the pattern
All monetary values stored as integers (cents) — never floats

File Organization

New feature? Follow the structure in src/features/[existing-feature]/
New API route? Follow the pattern in app/api/[existing-route]/route.ts
New component? Check components/ui/ — don't recreate what's already there

Code Style Rules

TypeScript strict mode — no any, no as unknown as
Functional components only — no class components
Error handling: use our AppError class from lib/errors.ts, not raw Error
Logging: use lib/logger.ts, not console.log

Anti-patterns (These Cause Production Issues)

NEVER filter by userId alone — always include organizationId (multi-tenant security)
NEVER commit .env files or hardcoded API keys
NEVER use Date.now() for timestamps — use server-side new Date() in DB inserts
NEVER skip migrations — if you change schema.ts, always run npm run db:migrate

When You're Unsure

Ask before implementing. Use the convention in the most recently modified similar file. If no precedent exists, propose in a PR comment rather than picking arbitrarily.


### What NOT to put in team CLAUDE.md

- General programming advice Claude already knows
- Technology descriptions (e.g., "React is a UI library")
- Things obvious from the code (e.g., "we use TypeScript" — Claude can see that)
- Personal preferences that aren't team conventions

**Target length**: 300-600 tokens. Short enough that every line carries weight.

---

## Step 2: API Key and Account Setup

### Option A: Individual Claude.ai Pro subscriptions (small teams)

Best for teams of 2-5 where each developer uses Claude Code independently:
- Each developer has their own Claude.ai Pro at $20/month
- Claude Code is included in the Pro plan
- No shared API key, no cost allocation needed
- Simple to set up, easy to onboard

**Limitation**: No centralized usage visibility.

### Option B: Shared API key with usage tracking (larger teams)

For teams where you need cost control and visibility:

1. Create a team workspace in [Anthropic Console](https://console.anthropic.com)
2. Create a shared API key (or per-developer keys under the workspace)
3. Set spending limits per key

```bash
# Team members configure the API key:
export ANTHROPIC_API_KEY=sk-ant-api03-[team-key]

# Or add to ~/.zshrc / ~/.bashrc:
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-[team-key]' >> ~/.zshrc

Option C: Per-developer API keys (auditability)

Create individual API keys for each team member under the same workspace. Benefits:

Per-developer usage tracking in the Console
Easy to revoke a specific developer's access
Spending limits per developer

# Onboarding script for new developers
echo "Setting up Claude Code for [name]..."
echo "1. Go to console.anthropic.com/settings/keys"
echo "2. Create a key named 'dev-[your-name]-[project]'"
echo "3. Add to your shell: export ANTHROPIC_API_KEY=sk-ant-..."

Step 3: Setting Spending Limits

Uncontrolled Claude Code usage can surprise you on the monthly bill. Set limits in the Anthropic Console:

Per-key monthly limit: Cap each developer at $X/month
Workspace-level limit: Hard cap on total team spending
Alert threshold: Email notification at 80% of limit

Typical team usage:

Usage pattern	Monthly cost per developer
Light (1-2 hours/day)	$10-30
Medium (4-6 hours/day)	$40-80
Heavy (full-day AI-assisted development)	$100-200

Step 4: Onboarding New Developers

Onboarding checklist

## Claude Code Onboarding Checklist

### Setup (Day 1)
- [ ] Install Claude Code: `npm install -g @anthropic-ai/claude-code`
- [ ] Add ANTHROPIC_API_KEY to shell config
- [ ] Run `claude` in project directory to verify it works
- [ ] Read CLAUDE.md — it's your Claude briefing document

### First session orientation (Day 1)
Run this at the start of your first session:

"Read CLAUDE.md and give me a summary of:
1. The project and what it does
2. The most important architectural rules
3. The anti-patterns I should never do"

If Claude's answer is accurate, you're set up correctly.

### Learn the task patterns (Day 2-3)
- [ ] Read 3 examples of good Claude prompts in PROMPTS.md (add this file)
- [ ] Practice with a small non-critical task
- [ ] Review what Claude generated vs. existing code conventions

### Team workflow (ongoing)
- [ ] Update CLAUDE.md when you establish a new convention
- [ ] Add to PROMPTS.md when you write a particularly effective prompt
- [ ] Escalate to team lead if Claude is consistently getting something wrong

PROMPTS.md — team prompt library

Maintain a PROMPTS.md (or .claude/prompts/) with effective prompts your team has developed:

# Team Prompt Patterns

## Adding a new API endpoint
"Add a [HTTP method] /api/[resource]/[action] endpoint.
It should [what it does].
Follow the pattern in app/api/[existing-endpoint]/route.ts exactly.
Include: session validation, input validation with zod, error handling with AppError,
and the organizationId filter on any DB queries."

## Adding a DB query
"Add a function [functionName] to lib/db/queries/[entity].ts.
It should [what it returns].
Follow the cursor pagination pattern in lib/db/queries/users.ts.
Always filter by organizationId."

## Debugging a type error
"[paste error]
File: [filepath]
I am [what I was trying to do].
Find the root cause. Do not change the type definition — fix the usage site."

Step 5: Code Review for AI-Generated Code

AI-generated code needs code review — sometimes more carefully than human-written code because AI can be confidently wrong.

Review checklist for Claude-generated code

## AI Code Review Checklist

Security:
- [ ] Multi-tenant: does every DB query filter by organizationId?
- [ ] Auth: is the session validated before any data access?
- [ ] Input validation: are all external inputs validated before use?
- [ ] No hardcoded credentials or API keys

Correctness:
- [ ] Does the logic match the stated requirement?
- [ ] Are edge cases handled (empty arrays, null values, 0)?
- [ ] Is error handling using our AppError pattern?

Consistency:
- [ ] Does it follow the file structure in CLAUDE.md?
- [ ] Are naming conventions consistent with existing code?
- [ ] Is the complexity appropriate — not over-engineered?

Tests:
- [ ] Were tests generated and do they pass?
- [ ] Do tests cover the edge cases?

Common Team Failure Modes

"Claude generated different patterns in different files"

Cause: CLAUDE.md too vague, or developers running Claude without loading project context.

Fix: Add explicit "follow the pattern in [file]" to CLAUDE.md. Require developers to reference specific files before implementing similar functionality.

"Claude changed something it shouldn't have"

Cause: Prompt too broad ("update the user service") without scope limits.

Fix: Add to team prompt patterns: always specify what should NOT change. Example: "Add X to the UserService. Do not change existing method signatures or tests."

"We can't tell what code was AI-generated"

Cause: No convention for marking AI-generated code in PRs.

Fix: Optional policy: PR description notes "AI-assisted" or specific sections were AI-generated. Useful for audit trails in regulated industries.

"The AI keeps making the same mistake"

Cause: Common mistake not documented in CLAUDE.md.

Fix: Add the specific anti-pattern to CLAUDE.md as soon as you catch it. Example: "NEVER use Date.now() — we caught this causing timezone bugs in production."

Frequently Asked Questions

How do I prevent Claude Code from accessing sensitive files? Create a .claudeignore file (similar to .gitignore) listing files Claude should not read. Alternatively, set file permission restrictions. The main protection is not committing secrets to the repo in the first place.

Should CLAUDE.md be in git? Yes, always. CLAUDE.md is team documentation that everyone should read and update. Track it in git, review changes in PRs, and treat updates to it as important as code changes.

How do we handle CLAUDE.md for a monorepo? Root CLAUDE.md for global conventions. Package-specific CLAUDE.md for package-level patterns. Claude Code reads both hierarchically when you're in a package subdirectory.

What's the right team size for Option A (individual Pro) vs Option B (shared API)? Option A (individual Pro at $20/user) is simpler and cost-competitive up to about 5-6 developers. Option B (shared API key) makes more sense for larger teams where centralized cost visibility and per-developer spending controls matter.

How do we keep CLAUDE.md from getting stale? Assign ownership to one team member. Review CLAUDE.md in quarterly retrospectives. Add a step to your PR template: "Did this PR reveal any new conventions that should be in CLAUDE.md?"

Related Guides

Context Engineering for Claude — Deep dive on CLAUDE.md design
Claude Code Complete Guide — All Claude Code features
Claude Code Git Workflows — AI-assisted PR and branching

Go Deeper

Power Prompts 300 — $29 — Includes team CLAUDE.md templates for 5 common project types (Next.js SaaS, Python API, mobile, data pipeline, CLI tool) plus 50+ reviewed team prompt patterns ready to drop into PROMPTS.md.

→ Get Power Prompts 300 — $29

30-day money-back guarantee. Instant download.