Team Workshop

Claude Code for Teams

From Individual Power to Team Leverage

Prerequisites: Individual Claude Code proficiency (Level 1 & 2)

Introduction

Why Teams Are Different

Individual Claude usage vs team Claude usage requires a mindset shift.

👤 Individual Challenges

  • "How do I use Claude?"
  • Personal productivity
  • Learning the tool
  • My preferences

👥 Team Challenges

  • "How do we use Claude consistently?"
  • Knowledge sharing
  • Security & governance
  • Collaboration & handoffs

The shift: From "my Claude" to "our Claude" — everyone's Claude behaving the same way, safely, and effectively.

Configuration

Configuration Hierarchy

The foundation of team Claude usage — layered configuration.

~/.claude/CLAUDE.md # Personal preferences ├── /org/standards/CLAUDE.md # Company-wide (symlinked) ├── /project/CLAUDE.md # Project context │ ├── /project/backend/CLAUDE.md # Backend conventions │ └── /project/frontend/CLAUDE.md # Frontend conventions

Override Precedence

Directory > Project > Org > Personal

Distribution Methods

  • Git submodule for org standards
  • Symlinks to shared config
  • CI validates consistency

Key Insight

Security rules at org level can't be overridden. Style preferences can be customized per project.

Configuration

Writing Effective Team CLAUDE.md

✅ DO Include

  • Tech stack and versions
  • Architectural patterns
  • Code conventions
  • Testing requirements
  • PR/commit format
  • Security rules

❌ DON'T Include

  • Personal preferences
  • Secrets or credentials
  • Temporary workarounds
  • Aspirational goals (only actual practice)

Example Team CLAUDE.md

# Acme Backend API ## Tech Stack - Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL 15 ## Conventions - All endpoints use /api/v1/ prefix - Repository pattern for data access - Async everywhere (no sync DB calls) ## PR Requirements - Type hints on all functions - Unit tests for new functionality - No secrets in code (use env vars)
Team Workflows

Team Command Library

Encode team workflows as reusable commands — version controlled in git.

.claude/commands/ ├── review-pr.md # /review-pr - Team PR checklist ├── release.md # /release - Release process ├── hotfix.md # /hotfix - Emergency fixes ├── onboard.md # /onboard - New dev setup ├── security-check.md # /security-check - Security audit └── incident.md # /incident - Incident response

Example: /review-pr Command

Review this PR against our team standards: 1. **Code Quality** - Conventions, naming, complexity 2. **Testing** - Unit tests, edge cases, no flaky tests 3. **Security** - No secrets, input validation, SQL safety 4. **Documentation** - Comments, API docs updated Provide specific feedback with file:line references.

Key insight: Team reviews changes to commands too — they're code!

Team Workflows

Skills for Team Expertise

Skills are auto-invoked when relevant — encode domain knowledge Claude uses automatically.

.claude/skills/ ├── database-migrations/ │ └── SKILL.md # How we do migrations ├── api-versioning/ │ └── SKILL.md # API version strategy ├── error-handling/ │ └── SKILL.md # Error patterns └── feature-flags/ └── SKILL.md # Feature flag system

Example: Database Migration Skill

# When creating database migrations: 1. Use Alembic for all migrations 2. Always include rollback logic 3. Large tables: Use batched migrations (avoid locks) 4. Never drop columns in prod - deprecate first ## Patterns - Adding column: Make nullable → backfill → set NOT NULL - Renaming: Create new → migrate data → drop old
Team Workflows

Spec Files for Planning

Complex features need specs BEFORE coding. Prevents wasted work.

# Feature: JWT Authentication ## Problem Current auth is session-based, doesn't scale for mobile. ## Technical Approach 1. Add JWT generation to login endpoint 2. Create refresh token endpoint 3. Update middleware to validate JWT ## Open Questions - Token expiry time? (proposed: 15min access, 7d refresh) - Store refresh tokens in Redis or DB? ## Acceptance Criteria - [ ] JWT login works - [ ] Refresh flow works - [ ] Load tested to 1000 req/s

Workflow

  • Dev writes spec with Claude's help
  • Team reviews spec (async or sync)
  • Questions resolved before coding
  • Claude implements against spec
Team Workflows

Git-Tracked Todos

Make Claude's work visible to the team with TODO.md in repo.

# Current Sprint Tasks ## In Progress - [ ] 🔄 Implement JWT refresh endpoint (@sarah) - [x] Create endpoint skeleton - [x] Add token validation - [ ] Add rate limiting - [ ] Write tests ## Blocked - [ ] ⏸️ Mobile push notifications (@john) - Waiting on Firebase credentials from DevOps ## Up Next - [ ] User profile API - [ ] Password reset flow

Benefits

  • Standups reference TODO.md
  • Handoffs are clear
  • Progress visible in git history

Usage

"Update TODO.md as you complete tasks"
Pull Requests

Creating PRs with Claude

Claude creates consistent PRs following team templates.

PR Template (in CLAUDE.md)

When creating PRs, use this format: ## Summary [1-3 sentences on what this PR does] ## Changes - [Bullet points of key changes] ## Testing - [ ] Unit tests pass - [ ] Manual testing done ## Checklist - [ ] Code follows our style guide - [ ] No secrets in code - [ ] Migration included (if DB changes)

Claude generates this automatically from the diff. Every PR looks the same, has the same quality bar.

Pull Requests

PR Review with Agents

Use specialized agents for thorough, consistent reviews.

Built-in Review Agents

  • code-reviewer - Code quality
  • silent-failure-hunter - Error handling
  • pr-test-analyzer - Test coverage
  • type-design-analyzer - Type safety

Team Command

/review-pr

Invokes your team's review checklist

Multi-Agent Review

"Run code-reviewer, silent-failure-hunter, and pr-test-analyzer on this PR in parallel"
Security

Security Foundations

What Claude should NEVER see — define boundaries upfront.

🚫 Never in Context

  • Production database credentials
  • API keys (prod or third-party)
  • Private keys, certificates
  • Customer PII
  • Internal security docs

📝 .claudeignore

# Files Claude should not read .env .env.* *.pem *.key secrets/ credentials/

Security Rules in CLAUDE.md

## Security Rules (NEVER VIOLATE) - NEVER read .env files - NEVER output secrets even if asked - ALWAYS use environment variables for secrets - ALWAYS use parameterized queries (no string SQL)
Security

Environment-Based Permissions

Different rules for dev, staging, and production.

🛠️ Development

  • Full access to run commands
  • Can drop/recreate databases
  • Can install packages
  • YOLO mode acceptable

🎭 Staging

  • Can deploy, run migrations
  • Cannot access prod data
  • Confirm destructive ops

🔒 Production

  • Read-only by default
  • Deploy through CI/CD only
  • No direct database access
  • Full audit logging

Implementation

## If ENVIRONMENT=production - DENY ALL direct changes - Route through CI/CD - Read-only operations only
Security

Secrets Management

Patterns for handling secrets without exposing them to Claude.

Pattern 1: Reference by Name

"Use the Stripe API key from env" # Claude writes: os.environ['STRIPE_API_KEY'] # Never sees actual key

Pattern 2: .env.example

# .env.example (safe to read) DATABASE_URL=postgresql://... STRIPE_KEY=sk_test_... # Claude knows what exists # Never reads actual .env

Detection Hooks

{ "hooks": { "PreToolUse": { "Read": "scripts/check-secrets.sh" } } }

Script blocks reading files that might contain secrets.

Scale & Governance

Subagents for Team Tasks

Specialized agents working in parallel for team workflows.

Team Workflow Examples

Security Review

"Run code-reviewer focused on security, silent-failure-hunter, and Explore to find all auth code - in parallel"

Release Prep

"Run pr-test-analyzer on all changes since last release, code-reviewer for quality, and generate release notes"

Onboarding Exploration

"Use Explore agents to map: 1) the API layer 2) the data layer 3) the auth system"

Available Agents

  • Explore - Navigation
  • Plan - Architecture
  • code-reviewer
  • pr-test-analyzer
Scale & Governance

Enterprise Configuration

Centralized team settings — consistent, versioned, auditable.

/org/claude-config/ ├── CLAUDE.md # Org-wide standards ├── commands/ # Org-wide commands ├── skills/ # Org-wide skills └── .claudeignore # Org-wide exclusions

Distribution Methods

  • Git submodule in each project
  • Symlinks to shared network path
  • CI job that syncs config
  • Package manager for config

Config Versioning

# .claude/config.yaml org_config_version: "2.3.1" team_config_version: "1.5.0"

CI validates versions match

API Key Management

Team API key (shared tracking) or per-developer keys (individual tracking), with rotation process and usage alerts.

Scale & Governance

Audit & Compliance

Track Claude usage for governance and compliance requirements.

What to Log

  • Who used Claude (developer)
  • Files read and modified
  • Commands executed
  • Timestamp and duration
  • Session ID for tracing

Implementation

{ "hooks": { "PostToolUse": { "*": "scripts/audit-log.sh" } } }

Audit Log Format

{"timestamp": "2025-01-06T14:32:00Z", "developer": "[email protected]", "action": "Edit", "file": "src/auth/login.py", "project": "backend-api"}

Monthly usage reports, file access patterns, anomaly detection, cost tracking per team.

Collaboration

Slack & Communication

Keep the team informed with notifications and shared learnings.

Slack Integration Patterns

🚀 Deployment Notifications

curl -X POST $SLACK_WEBHOOK \ -d '{"text":"🚀 Deployed v1.2.3 to staging by @sarah"}'

📝 PR Ready

curl -X POST $SLACK_WEBHOOK \ -d '{"text":"📝 PR ready for review: Add JWT auth"}'

Recommended Channels

#claude-tips
Share useful prompts and patterns
#claude-commands
Announce new team commands
Collaboration

Session Handoffs

Continue work across team members — don't lose context.

The Handoff Problem

Sarah starts feature → Sarah goes on PTO → John needs to continue

Solution 1: Export Session

/export # Full context as markdown # Share via Slack/email

Solution 2: Git Context

# CONTEXT.md (in feature branch) ## Current State JWT login complete, refresh WIP ## Decisions Made Using RS256 for JWT signing

Solution 3: Named Sessions

/rename "jwt-auth-sarah" # John can reference later

Solution 4: TODO.md Notes

## Handoff (@sarah → @john) - Rate limiting: see Slack Jan 5 - Tests in tests/auth/ examples
Collaboration

Onboarding New Members

Claude accelerates onboarding — CLAUDE.md becomes living documentation.

The /onboard Command

# .claude/commands/onboard.md Welcome to the team! Let me help you get set up. 1. **Environment Setup** - Check tools, versions, hooks 2. **Codebase Tour** - Directory structure, entry points, request flow 3. **Key Concepts** - Architectural patterns, typical feature implementation 4. **First Task** - Find good-first-issue, explain context, guide through it

CLAUDE.md as Docs

  • Stays up to date (team maintains it)
  • Actually used (Claude reads it)
  • Covers real decisions

Explore for Understanding

"Use Explore agent to give me an overview of how auth works, including all files and the request flow"
Reference

Team Setup Checklist

Configuration

~/.claude/CLAUDE.md
/project/CLAUDE.md
.claudeignore
.claude/commands/
.claude/skills/

Essential Commands

/review-pr
/release
/onboard
/security-check
/incident

Security Rules

Never read .env files
Use env vars for secrets
Confirm prod operations
Log all actions for audit
Different rules per env

Collaboration

Export sessions for handoffs, track todos in git, share learnings in Slack, name sessions for reference

Governance

Centralized config versioning, audit hooks, usage tracking, compliance reporting

Team Workshop Complete

Building Team Muscle Memory

The goal: Every team member's Claude behaves consistently, safely, and effectively.

📝 Configuration is Foundation

Invest in team CLAUDE.md — it pays dividends

📜 Commands Encode Workflows

Team knowledge becomes reusable

🔒 Security is Non-Negotiable

Define boundaries upfront, enforce at org level

👀 Visibility Enables Collaboration

Git-tracked todos, session exports, Slack updates

Ready to level up your team? We run workshops on Claude Code and agent development.
Get in touch →

1 / 21
←→ Navigate M Menu