Configuring Claude Code for a Team Workflow

Project CLAUDE.md hierarchies, path-scoped rules, an isolated forked skill, and multi-server MCP config with credential expansion — the pieces that make Claude Code behave consistently across a whole team instead of just one laptop.

Try It

Which rule fires for this file?

Two rules are configured, each scoped to a glob. Pick a file below and see which one — if any — would actually load into context.

Editing src/api/users.ts —

.claude/rules/api-conventions.md (paths: ["src/api/**/*"])

Validate input early, return typed results, no business logic in handlers.

How It Layers

CLAUDE.md hierarchy, broadest to narrowest

~/.claude/CLAUDE.md

Global — every project

→

project/CLAUDE.md

This repo — every teammate

→

.claude/rules/*.md

Path-scoped — only matching files

→

.claude/skills/*

Invoked on demand, optionally forked

Concepts

The five pieces, explained

Claude Code reads CLAUDE.md at multiple levels — global (~/.claude/CLAUDE.md), project root, and any nested directory CLAUDE.md files above the file you're working on. All applicable levels get combined into context; more specific (closer to the file) instructions take precedence when they conflict with broader ones. This is what makes a single project CLAUDE.md apply consistently to every teammate who opens `claude` there — it's not personal config, it's committed to the repo.

Test Yourself

Quick knowledge check

Five questions, no scoring pressure — pick an answer to see if it lands.

1. What determines whether a .claude/rules/*.md file gets loaded for a given edit?

2. A skill's frontmatter has `context: fork`. What does that actually change?

3. `.mcp.json` has `"DATABASE_URL": "${DATABASE_URL}"` inside a server's `env` block. What does that accomplish?

4. Your project has a .mcp.json AND your personal ~/.claude.json both define MCP servers. What happens when you open Claude Code here?

5. For which of these would plan mode most likely add real value over direct execution?

Hands-On

Plan mode vs. direct execution — three tasks

Run each of these twice in your own sandbox — once in plan mode, once with direct execution — and compare what actually differed.

Task 1 — Single-file bug fix

A handler checks `!id` to reject empty ids, but a whitespace-only id like " " slips through and produces a bogus record. Fix the validation.

Plan mode and direct execution should converge on nearly the same fix — a baseline for what "no meaningful difference" looks like.

Task 2 — Multi-file migration

Extract a type shared by one handler into its own module, then update the original file to import it from there — previewing what happens once more files need the same shape.

Touches two files and a signature — enough ambiguity (naming, exact location) that plan mode should visibly surface those decisions before editing.

Task 3 — New feature

Add a new handler following the same pattern as an existing one, plus a co-located test file, with two different path-scoped rules both in play at once.

The biggest task — this is where plan mode should differ most from direct execution: it has to ask or state assumptions instead of guessing at edge cases.

Rolling out Claude Code across a team?

Happy to talk through CLAUDE.md hierarchies, rules, skills, and MCP config for your setup.

Get in touch