Enterprise Patterns and Team Workflows

Claude Code scales from solo developers to large engineering teams. But team usage introduces challenges: how do you maintain consistency when ten developers each have their own Claude habits? How do you enforce security policies? How do you make code reviews efficient when both humans and AI are contributing? This lesson covers the patterns that make Claude Code work at team and enterprise scale.

What You Will Learn

• Shared CLAUDE.md conventions for team alignment
• Automated code review workflows
• PR creation and management patterns
• Monorepo strategies for multi-app organizations
• Security best practices for team environments

---

Team Alignment with Shared CLAUDE.md

The most important step for team adoption is a well-crafted, shared CLAUDE.md checked into the repository. This file ensures every developer's Claude Code sessions follow the same conventions.

What to Include

# CLAUDE.md

## Build Commands
npm run dev          # Start dev server on port 3000
npm run build        # Production build
npm test             # Run Jest tests
npm run lint         # ESLint check
npm run typecheck    # TypeScript strict check

## Architecture
- Next.js 16 App Router with TypeScript strict mode
- Supabase for database (PostgreSQL) and auth
- Tailwind CSS for all styling (no CSS modules)
- React 19 with Server Components by default

## Code Conventions
- Functional components only, no class components
- Named exports only, no default exports
- Use path alias @/* for imports from src/
- Error boundaries required for all page-level components
- All API routes return \{ data, error \} shape
- Use Zod for runtime validation at API boundaries

## Git Conventions
- Branch naming: feature/*, fix/*, chore/*
- Commit messages: Conventional Commits format
- All PRs require at least one approval
- Squash merge to main

## Testing
- Test files live next to source: Component.test.tsx
- Minimum 80% branch coverage for new code
- E2E tests required for user-facing flows
- Mock external services, never hit real APIs in tests

## Security
- Never commit .env files or secrets
- Use environment variables for all configuration
- Validate all user input with Zod schemas
- Use parameterized queries, never string interpolation for SQL

Directory-Specific Instructions

For large teams, add CLAUDE.md files to key directories:

src/
├── api/
│   └── CLAUDE.md     # API conventions, auth patterns, rate limiting
├── components/
│   └── CLAUDE.md     # Component patterns, prop types, accessibility
├── lib/
│   └── CLAUDE.md     # Utility function standards, error handling
└── tests/
    └── CLAUDE.md     # Testing patterns, mock strategies, fixtures

Code Review Automation

Claude Code can automate the first pass of code reviews, catching issues before human reviewers spend time on them.

Automated PR Review with GitHub Actions

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: $\{\{ secrets.ANTHROPIC_API_KEY \}\}
          claude_args: "--max-turns 15 --model claude-sonnet-4-5"
          prompt: |
            Review this PR. Check for:
            1. Security vulnerabilities (SQL injection, XSS, exposed secrets)
            2. Performance issues (N+1 queries, missing indexes, memory leaks)
            3. Error handling gaps (unhandled promises, missing try/catch)
            4. Type safety issues (any types, missing null checks)
            5. Test coverage (new code should have tests)

            Format as inline PR comments on specific lines.
            End with a summary comment rating the PR: Approve / Request Changes / Needs Discussion.

Custom Review Agent

For more control, create a dedicated review agent:

---
# .claude/agents/code-reviewer.md
description: "Performs thorough code review following team standards"
model: claude-sonnet-4-5
tools:
  - Read
  - Grep
  - Glob
  - Bash
disallowedTools:
  - Edit
  - Write
maxTurns: 20
color: yellow
---

You are a senior code reviewer. Your job is to review code changes
without modifying any files.

## Review Checklist
1. Security: injection attacks, auth bypass, secret exposure
2. Performance: query patterns, caching, bundle size impact
3. Correctness: edge cases, null handling, race conditions
4. Maintainability: naming, complexity, documentation
5. Testing: coverage, edge cases, mocking strategy
6. Accessibility: ARIA labels, keyboard navigation, color contrast

## Output Format
Provide findings as a structured review with severity levels:
- CRITICAL: Must fix before merge
- WARNING: Should fix, but not blocking
- SUGGESTION: Nice to have improvements
- PRAISE: Highlight good patterns worth noting

PR Creation and Management

Claude Code can streamline PR workflows from creation through merge:

Automated PR Creation

> "Create a PR for the current branch. Include:
>  - A clear title following Conventional Commits format
>  - Summary of what changed and why
>  - Testing instructions
>  - Screenshots if any UI changed (use Playwright to capture them)
>  - Link to the related issue"

PR Template Integration

Create a .github/PULL_REQUEST_TEMPLATE.md that Claude follows:

## Summary
<!-- What does this PR do? -->

## Changes
<!-- List of changes -->

## Testing
<!-- How was this tested? -->

## Checklist
- [ ] Tests added/updated
- [ ] Types are correct
- [ ] No console.log statements
- [ ] Accessibility checked
- [ ] Mobile responsive

Then instruct Claude in your CLAUDE.md:

## PR Conventions
When creating PRs, always fill out the PR template completely.
Link to related issues with "Closes #NNN" or "Relates to #NNN".
Add appropriate labels: feature, bugfix, chore, docs.

Batch PR Management

> "Review all open PRs on this repo. For each:
>  1. Check if CI is passing
>  2. Check if it has required approvals
>  3. Check if it has merge conflicts
>  Report a summary table with PR number, title, status, and action needed."

Monorepo Strategies

Monorepos with multiple apps need careful Claude Code configuration:

Layered Settings

monorepo/
├── CLAUDE.md                    # Shared conventions
├── .claude/
│   └── settings.json            # Shared hooks and permissions
├── apps/
│   ├── web/
│   │   ├── CLAUDE.md            # Web-specific instructions
│   │   └── .claude/
│   │       └── settings.json    # Web-specific hooks
│   ├── api/
│   │   ├── CLAUDE.md            # API-specific instructions
│   │   └── .claude/
│   │       └── settings.json    # API-specific hooks
│   └── mobile/
│       └── CLAUDE.md            # Mobile-specific instructions
└── packages/
    └── shared/
        └── CLAUDE.md            # Shared package conventions

Turborepo-Aware Instructions

# CLAUDE.md (monorepo root)

## Monorepo Commands
npx turbo dev --filter=@company/web     # Start web app only
npx turbo build --filter=@company/api   # Build API only
npx turbo test                          # Test all packages
npx turbo lint                          # Lint all packages

## Cross-Package Changes
When modifying shared packages, always:
1. Run tests in ALL consuming apps: npx turbo test
2. Check for type errors across the monorepo: npx turbo typecheck
3. Verify no circular dependencies were introduced

## Package Dependencies
- @company/web depends on @company/shared, @company/ui
- @company/api depends on @company/shared, @company/db
- Never import from app packages into shared packages

Scoped Agent Work

When working in a monorepo, scope Claude's work to specific packages:

> "Working only in apps/web/, add form validation to the signup page.
>  Do not modify any files outside apps/web/.
>  Run: npx turbo test --filter=@company/web to verify."

Security Best Practices

Secret Management

# CLAUDE.md Security Section

## Secrets Policy
- NEVER commit .env files, API keys, or credentials
- NEVER include secrets in CLAUDE.md or memory files
- Use environment variables for all sensitive configuration
- When you need a secret value, ask the developer to provide it
- If you see a secret in code during review, flag it as CRITICAL

Permission Policies for Teams

Create a shared .claude/settings.json that enforces team security:

\{
  "permissions": \{
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(git:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npx turbo:*)"
    ],
    "deny": [
      "Bash(curl -X POST:*)",
      "Bash(wget:*)",
      "Bash(rm -rf:*)",
      "Bash(docker rm:*)",
      "Bash(ssh:*)",
      "Bash(scp:*)"
    ]
  \}
\}

Audit Trail

For regulated environments, log all Claude Code actions:

\{
  "hooks": \{
    "PostToolUse": [
      \{
        "command": "node .claude/hooks/audit-log.js",
        "timeout": 5000
      \}
    ]
  \}
\}

// .claude/hooks/audit-log.js
const fs = require('fs');
const log = \{
  timestamp: new Date().toISOString(),
  tool: process.env.TOOL_NAME,
  input: process.env.TOOL_INPUT,
  session: process.env.SESSION_ID,
  user: process.env.USER
\};
fs.appendFileSync(
  '.claude/audit.jsonl',
  JSON.stringify(log) + '\\n'
);

Onboarding New Team Members

Claude Code accelerates onboarding when properly configured:

Onboarding Slash Command

<!-- .claude/commands/onboard.md -->
Help me get started with this project:

1. Explain the high-level architecture (read CLAUDE.md and key files)
2. Show me how to run the development environment
3. Walk me through the directory structure
4. Explain the testing strategy
5. List the most important files I should read first
6. Show me a typical development workflow (branch, code, test, PR)

New developers type /onboard on their first day and get a comprehensive project tour from Claude.

---

Key Takeaways

• A well-crafted shared CLAUDE.md is the foundation of team Claude Code usage
• Automate first-pass code reviews with GitHub Actions and a read-only review agent
• Create PR templates and conventions that Claude follows consistently
• In monorepos, layer CLAUDE.md and settings.json at root and per-app levels
• Enforce security through shared deny lists, secret policies, and audit logging hooks
• Use onboarding slash commands to accelerate new team member ramp-up
• Always route AI-generated changes through the same PR review process as human changes