Standardizing Claude Code Across Your Team: CLAUDE.md, Hooks, and Shared Skills

#claudecode #teamwork #productivity #devtools

Getting Claude Code working well for one developer is easy. Getting a whole team to use it consistently is a different challenge. Here's what works.

The Problem with Individual Setup

When every developer configures Claude Code differently:

Claude generates code following their conventions, not the team's
"Don't use any types" works for one person, breaks for another
Security rules are enforced inconsistently
New team members have to figure it all out from scratch

The solution: treat Claude Code configuration as code. Git it.

1. CLAUDE.md as Team Source of Truth

Create CLAUDE.md in your project root and commit it. Every team member gets the same configuration automatically.

# Project: payments-service

## Stack
- Node.js 20 LTS + TypeScript 5.x (strict)
- Express 4 + Prisma ORM + PostgreSQL 16
- Vitest for testing

## Commands
- Test: `npm test`
- Lint: `npm run lint` (ESLint + Prettier)
- Build: `npm run build`
- DB migration: `npx prisma migrate dev`

## Architecture (enforced)
- Layers: Router → Controller → Service → Repository
- No direct DB calls in Controllers or Routes
- No HTTP types (Request/Response) in Services
- Constructor injection for all dependencies

## Coding Rules
- No `any` type (add justification comment if unavoidable)
- No `console.log` in production code — use `src/lib/logger.ts`
- All async functions must have error handling
- Magic numbers → named constants in `src/constants/`

## Security
- All SQL through Prisma ORM (no raw string queries)
- All external input validated with Zod
- No PII in logs
- Secrets only via `process.env` (never hardcoded)

## Off Limits (do not modify without team discussion)
- `src/legacy/` — production-critical, being migrated
- `package.json` dependencies — requires review
- `.env` files — never read or write

## Key Files
- DB client: `src/lib/db.ts`
- Auth middleware: `src/middleware/auth.ts`
- Common types: `src/types/`
- Error classes: `src/errors/`

2. Team Hooks in Version Control

Put your hooks in .claude/hooks/ and commit them:

.claude/
├── settings.json          # Hook configuration (committed)
└── hooks/
    ├── README.md          # Explains each hook
    ├── ts_quality.py      # Auto-format + lint on write
    ├── guard_bash.py      # Block dangerous commands
    └── scan_secrets.py    # Detect leaked credentials

settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "python .claude/hooks/guard_bash.py"}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "python .claude/hooks/ts_quality.py", "timeout": 30},
          {"type": "command", "command": "python .claude/hooks/scan_secrets.py"}
        ]
      }
    ]
  }
}

Now every developer automatically gets auto-formatting and secret scanning when Claude Code writes files.

3. Team Skills in Version Control

Custom skills in .claude/skills/ are available to everyone who clones the repo:

.claude/
└── skills/
    ├── code-review.md
    ├── test-gen.md
    └── refactor-suggest.md

Example skill (code-review.md):

---
name: code-review
description: Run a structured code review
---

Review the specified file(s) for:

1. CLAUDE.md rule compliance (architecture, no-any, no-console.log)
2. Security issues (OWASP Top 10, secret exposure, injection risks)
3. Performance (N+1 queries, missing indexes, unnecessary loops)
4. Type safety (unsafe assertions, missing null checks)
5. Test coverage (untested branches, missing edge cases)

Format findings as:
- **[CRITICAL]** — must fix before merge
- **[HIGH]** — should fix in this PR
- **[MEDIUM]** — create ticket, fix later
- **[LOW]** — style/preference, optional

Team members use it with /code-review src/services/payment.ts before every PR.

4. Onboarding Checklist

Add this to your project README or onboarding docs:

## Claude Code Setup (5 minutes)

1. Install Claude Code
   npm install -g @anthropic-ai/claude-code

2. Authenticate
   claude auth login

3. Clone the repo (CLAUDE.md, hooks, and skills are already in it)

4. Verify it works
   Open claude and ask: "What's the tech stack for this project?"
   You should get a response based on CLAUDE.md.

5. Read .claude/hooks/README.md to understand what auto-runs

6. Try /code-review on a file you're working on

5. Maintaining CLAUDE.md

CLAUDE.md needs maintenance like any documentation:

## CLAUDE.md Update Rules (add to CONTRIBUTING.md)

1. Changes require a PR (no direct pushes to main)
2. PR description must explain why the rule is being added/changed
3. Test that Claude Code behaves correctly after the change before merging
4. Monthly team review: does CLAUDE.md still reflect reality?