Setting Up Claude Code for Team Projects

Claude Code is powerful solo. But the real leverage comes when your whole team uses it with shared conventions. Here's how we set it up across our projects.

Start with CLAUDE.md

Every project gets a CLAUDE.md in the root. This is the file Claude Code reads for project context. Treat it like onboarding docs for an AI teammate.

Ours typically includes:

• Build and dev commands
• Architecture overview (framework, routing, key patterns)
• Import conventions and path aliases
• Which directories are off-limits
• Testing approach and commands
• Key libraries and why we chose them

The goal isn't exhaustive documentation. It's the minimum context needed for Claude Code to make good decisions about your codebase.

The conventions that matter most

After setting up Claude Code across a dozen projects, these are the conventions that have the biggest impact on output quality:

Naming patterns. Tell it how you name components, hooks, utilities, and files. "Components use PascalCase, files use kebab-case, hooks start with use" — simple rules that prevent inconsistency.

State management approach. If you use server components by default and client components only when needed, say so explicitly. Otherwise Claude Code will add "use client" everywhere.

Error handling patterns. Describe how your app handles errors. Does it use error boundaries? Toast notifications? Centralized logging? Claude Code will match whatever pattern you describe.

Project structure template

We keep a template CLAUDE.md that we customize per project. The structure:

1. Commands section (copy-paste runnable)
2. Architecture section (stack, patterns, key decisions)
3. Conventions section (naming, imports, file organization)
4. Protected directories (things AI shouldn't modify)
5. Domain-specific context (business logic, terminology)

Section 5 is the one most teams skip, and it's the most valuable. If your app deals with property accounting, explain what a ledger entry is. Claude Code writes better domain code when it understands the domain.

Team workflow

Each developer runs Claude Code locally. Shared context comes from three places:

1. CLAUDE.md in the repo (committed, version controlled)
2. Code review standards that catch AI-generated anti-patterns
3. Shared prompting patterns for common tasks (we keep these in a team wiki)

We don't try to standardize prompts too tightly. Everyone thinks about tasks differently, and that's fine. The CLAUDE.md ensures consistent output regardless of how you ask for it.

Settings that matter

Keep the defaults mostly. The changes we make:

• Enable the project-level CLAUDE.md (it's on by default, just verify)
• Set up the allowed/denied tools list if you don't want it running certain commands
• Configure the model — we use Opus for complex refactors, Sonnet for routine work

Common mistakes to avoid

Don't over-specify. A CLAUDE.md that's 500 lines long gets ignored the same way humans ignore long docs. Keep it under 100 lines.

Don't describe what's obvious from the code. If your Next.js project uses the app router, Claude Code already knows that from reading your file structure. Focus on the things that aren't obvious.

Don't skip the domain context. "This is a property management app" tells Claude Code more about what your functions should do than any number of code conventions.

Keep it lean, keep it current, and let the team evolve it over time.