DEV Community

Carlos Oliva Pascual
Carlos Oliva Pascual

Posted on • Originally published at stacknotice.com

Claude Code for Teams: Shared CLAUDE.md, Hooks, and Preventing AI Drift (2026)

#ai #programming #webdev #claude

Every tutorial about Claude Code assumes one developer. That's not how most software gets built.

When your entire team starts using Claude Code, a quiet problem surfaces: AI drift. Two developers ask Claude to add error handling to the same module and get incompatible implementations. One developer's Claude follows the Zod-everywhere convention, another's doesn't know about it. The junior developer's Claude makes architectural decisions that contradict what the senior dev established last week.

This is the problem no solo-dev tutorial addresses. Here's how to solve it.

Full guide at stacknotice.com/blog/claude-code-for-teams-2026

The Root Cause: Claude's Context is Per-Session

Claude Code doesn't share memory between developers. When your colleague opens a new session, their Claude knows nothing about the architectural decisions you made last Tuesday, the convention the team adopted last month, or the patterns you agreed to avoid.

The fix: make the shared context explicit and version-controlled.

The Team CLAUDE.md

Claude Code reads CLAUDE.md from multiple locations. For teams, the project-level CLAUDE.md (committed to the repo) is the key:

# Project: TaskApp — AI Conventions

## Architecture decisions (do not deviate without team discussion)
- State management: Zustand only. No Redux, no Context for global state.
- Data fetching: TanStack Query client-side, Next.js fetch for RSC.
- Validation: Zod everywhere — forms, API responses, environment variables.
- Database: Drizzle ORM with Neon. Never write raw SQL outside Drizzle.
- Auth: Clerk. Do not implement custom auth logic.

## Patterns we explicitly avoid
- No `any` types, not even temporary ones.
- No `console.log` in production — use the structured logger in src/lib/logger.ts.
- No inline styles — Tailwind only.
- No direct database access in route handlers — always go through the service layer.

## Before creating a new file, check
- Does a similar utility already exist in src/lib/?
- If adding a new dependency, confirm with the team first.
Enter fullscreen mode Exit fullscreen mode

This isn't a style guide for humans — it's the instruction set every Claude session on this project reads automatically. Treat it with the same care as eslint.config.ts.

Module-Level CLAUDE.md for Critical Paths

Add CLAUDE.md in directories with high stakes:

# src/payments/CLAUDE.md

## CRITICAL — Read before touching any file here

This handles Stripe webhooks and subscription state. Mistakes cause billing failures.

## Invariants that must ALWAYS hold
- Every webhook handler MUST verify the Stripe signature before processing.
- idempotency_key is REQUIRED on every Stripe API call.
- Subscription state in DB is source of truth — never derive it from Stripe directly.
Enter fullscreen mode Exit fullscreen mode

Shared PostToolUse Hook: TypeScript Check on Every Edit

Commit this to .claude/settings.json in the repo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Every file edit triggers a TypeScript check. Claude sees the errors immediately and fixes them in the same response. Across the team, no one can merge code that breaks the type system — even if Claude generated it.

The Two-Claude Review Pattern

Most developers use Claude to write code. Teams that also use it to review catch a different class of bugs.

# Terminal 1 — Writer Claude
claude "Implement the subscription upgrade flow per docs/upgrade-flow.md.
Write tests as you go."

# Terminal 2 — Reviewer Claude (after Writer is done)
claude "A colleague just implemented the subscription upgrade flow:
$(git diff main...HEAD)

Review for correctness, security, and CLAUDE.md conventions.
Be critical. Find problems, don't approve."
Enter fullscreen mode Exit fullscreen mode

The Reviewer Claude has no attachment to the Writer Claude's decisions. It reviews objectively. In practice, this catches 2-3 real issues per feature that the Writer Claude missed.

Keeping CLAUDE.md Current

Add a section Claude can update itself:

## Recent decisions (Claude may update this section)
- 2026-06-10: Switched email from Sendgrid to Resend
- 2026-06-05: Adopted Zod for all environment variables
- 2026-05-28: Drizzle transactions for all multi-table writes

## Refactors in progress
- [ ] Migrating Context to Zustand — 60% done (src/store/)
- [ ] Moving validation to Zod — 80% done
Enter fullscreen mode Exit fullscreen mode

At the end of significant sessions: "Update CLAUDE.md with what we decided today." Over months, it becomes a living architecture decision record every new session inherits automatically.

The Rule: Decisions vs Preferences

Decisions (team CLAUDE.md — version controlled):

  • Which ORM to use
  • Error handling patterns
  • File naming conventions
  • Sensitive modules requiring extra care

Preferences (personal ~/.claude/CLAUDE.md):

  • How verbose you want explanations
  • Your preferred response format
  • Personal coding style within conventions

When everything goes into the team file, Claude starts following conflicting instructions. Keep the boundary clean.

The shift from "everyone uses Claude individually" to "the team uses Claude together" is about making implicit conventions explicit. Once the decisions live in CLAUDE.md, every developer's AI session starts from the same baseline — and AI drift stops.

Full guide with onboarding workflow, subagent parallelization, and team checklist at stacknotice.com/blog/claude-code-for-teams-2026.

Top comments (0)