Shared CLAUDE.md and hooks prevent AI drift in team codebases

Carlos Oliva Pascual's article addresses a gap in most Claude Code tutorials: they assume a single developer, but teams face "AI drift" — the problem where two developers asking Claude to implement the same feature get incompatible results because each session starts from scratch with no shared context. The proposed fix is making implicit conventions explicit and version-controlled. A project-level `CLAUDE.md` committed to the repo serves as the instruction set every Claude session reads automatically, encoding decisions such as using Zustand for state management, TanStack Query for client-side data fetching, Zod for all validation, Drizzle ORM with no raw SQL, and Clerk for auth. High-stakes directories get their own nested `CLAUDE.md` files — the article's example covers a payments directory where every webhook handler must verify the Stripe signature and every Stripe API call must include an `idempotency_key`.

Finally, the article recommends a dedicated section in `CLAUDE.md` that Claude itself can update at the end of significant sessions, turning the file into a living architecture decision record.

A shared `.claude/settings.json` committed to the repo configures a `PostToolUse` hook that runs `npx tsc --noEmit 2>&1 | head -20` after every write or edit, surfacing TypeScript errors inline so Claude can fix them in the same response. The article also describes a dual-Claude review workflow: one terminal runs a "Writer Claude" that implements a feature, while a second "Reviewer Claude" is given the resulting diff and instructed to review for correctness, security, and `CLAUDE.md` convention compliance without any attachment to the Writer's choices. Finally, the article recommends a dedicated section in `CLAUDE.md` that Claude itself can update at the end of significant sessions, turning the file into a living architecture decision record. The article draws a clear boundary between team-level decisions (version-controlled `CLAUDE.md`) and personal preferences (a developer's local `~/.claude/CLAUDE.md`), warning that mixing the two causes conflicting instructions.

Key facts

1. 01The article identifies 'AI drift' as the core team problem: each Claude Code session starts with no memory of prior architectural decisions made by other developers.
2. 02A project-level `CLAUDE.md` committed to the repo acts as the shared instruction set every Claude session reads automatically.
3. 03Nested `CLAUDE.md` files in high-stakes directories (e.g., `src/payments/`) can encode critical invariants like required Stripe signature verification.
4. 04A shared `.claude/settings.json` hook runs `npx tsc --noEmit 2>&1 | head -20` after every file write or edit, surfacing TypeScript errors immediately.
5. 05A dual-terminal Writer/Reviewer pattern uses a second Claude instance to review the first's diff; the article states this catches 2-3 real issues per feature.
6. 06A dedicated section in `CLAUDE.md` lets Claude update the file itself at session end, creating a living architecture decision record.
7. 07The article distinguishes team decisions (version-controlled `CLAUDE.md`) from personal preferences (local `~/.claude/CLAUDE.md`) to avoid conflicting instructions.

Topics