Claude Code Setup Guide for Team Projects: Shared CLAUDE.md, Git Hooks, Permissions & Slash Commands
Claude Code Setup Guide for Team Projects
Claude Code is Anthropic’s agentic coding tool that lives in your terminal, understands your codebase, and accelerates development workflows. Setting it up properly for a team ensures consistent AI-assisted development across all contributors. This guide walks through configuring shared conventions, git hook integration, permission modes, and custom slash commands.
Step 1: Install Claude Code
Claude Code requires Node.js 18+ and runs on macOS, Linux, and Windows (via WSL or Git Bash).
# Install globally via npm
npm install -g @anthropic-ai/claude-code
Verify installation
claude —version
Authenticate with your Anthropic account
claude auth login
Each team member needs their own Anthropic API key or an organization-managed account. Set it as an environment variable or authenticate interactively.
# Option A: Environment variable
export ANTHROPIC_API_KEY=YOUR_API_KEY
Option B: Interactive login (opens browser)
claude auth login
Step 2: Create a Shared CLAUDE.md Convention File
The CLAUDE.md file is how your team encodes project-specific instructions that Claude Code follows in every session. Place it at the project root and commit it to version control.
# Create the project-level CLAUDE.md
touch CLAUDE.md
Here is a practical template for team projects:
# Project: Acme Web Platform
Tech Stack
- Backend: Python 3.12, FastAPI, SQLAlchemy
- Frontend: React 18, TypeScript, Tailwind CSS
- Database: PostgreSQL 16
- Testing: pytest (backend), Vitest (frontend)
Code Conventions
- Use snake_case for Python, camelCase for TypeScript
- All API endpoints must include OpenAPI docstrings
- Never use print() for logging — use structlog
- Prefer composition over inheritance
Testing Rules
- All new functions require unit tests
- Integration tests must hit a real database, never mocks
- Run
make test before suggesting a task is complete
Security
- Never hardcode secrets or API keys
- Use parameterized queries only — no string interpolation for SQL
- Validate all user input at API boundaries
Git Workflow
- Branch naming: feature/, bugfix/, hotfix/
- Commit messages follow Conventional Commits
Always rebase onto main before opening a PRClaude Code supports a hierarchy of instruction files:
| File Location | Scope | Use Case |
|---|---|---|
~/.claude/CLAUDE.md | Global (all projects) | Personal preferences, auth info |
PROJECT_ROOT/CLAUDE.md | Project-wide | Team conventions, committed to git |
any_subdirectory/CLAUDE.md | Directory-scoped | Module-specific rules |
# .claude/settings.json — project-level settings
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit.*)",
"hook": "bash -c 'npm run lint && npm run test:unit'"
}
],
"PostToolUse": [
{
"matcher": "Edit",
"hook": "bash -c 'echo Reminder: run tests after edits'"
}
]
}
}You can also use standard git hooks that Claude Code respects:
# .git/hooks/pre-commit
#!/bin/sh
npx lint-staged
python -m pytest tests/unit -q --tb=short
Claude Code will not bypass --no-verify by default. If a hook blocks a commit, it investigates the root cause rather than skipping it.
Step 4: Set Up Permission Modes
Permission modes control what Claude Code can do without asking. Choose the right mode for your team’s risk tolerance.
| Mode | Behavior | Best For |
|---|---|---|
| **default** | Prompts before risky actions (file writes, shell commands) | Most teams |
| **plan** | Read-only analysis, no file modifications | Code review, exploration |
| **trust** | Auto-approves most local actions | Solo work, CI environments |
# Start Claude Code in plan mode (read-only)
claude --mode plan
Start in default mode (recommended for teams)
claude —mode default
Configure allowed tools in settings
.claude/settings.json
{
“permissions”: {
“allow”: [
“Read”,
“Glob”,
“Grep”,
“Edit”
],
“deny”: [
“Bash(rm -rf*)”,
“Bash(git push —force*)”
]
}
}
Commit the .claude/settings.json file to your repository so all team members share the same permission boundaries.
Step 5: Create Custom Slash Commands
Slash commands let your team define reusable prompts for common workflows. Store them in the .claude/commands/ directory.
# Create the commands directory
mkdir -p .claude/commands
Create a command file for each workflow:
# .claude/commands/review.md
Review the current git diff for:
- Security vulnerabilities (OWASP Top 10)
- Performance issues
- Missing error handling
Test coverage gaps Provide actionable feedback with file:line references.# .claude/commands/fix-tests.md Run the test suite withmake test. For each failing test:- Read the test and the code under test
- Identify the root cause
- Fix the code (not the test) unless the test is wrong
Re-run to confirm the fix# .claude/commands/document.md For each public function in $ARGUMENTS:- Add a docstring following project conventions
- Include parameter types, return types, and examples
Do not modify any logic or formattingUse these commands in any Claude Code session:
# Run the review command /review
Run fix-tests
/fix-tests
Document a specific file
/document src/api/handlers.py
Pro Tips for Power Users
- Use
/compactregularly — In long sessions, run/compactto summarize context and free up the context window without losing important state.- Chain commands in CI — Runclaude -p “run all tests and fix failures” —mode trustin your CI pipeline for automated fix-and-retry loops.- Scope CLAUDE.md per module — Place aCLAUDE.mdin subdirectories likeservices/auth/CLAUDE.mdto give module-specific instructions that only activate when working in that directory.- Use the memory system — Ask Claude to/memoryto store team decisions, architectural choices, or recurring feedback that persists across sessions.- Parallel tool calls — Claude Code makes independent tool calls in parallel. Structure your requests to enable this by asking for multiple independent tasks at once.
Troubleshooting Common Issues
| Problem | Cause | Solution |
|---|---|---|
| CLAUDE.md not picked up | File not in project root or not named exactly | Ensure the file is CLAUDE.md (case-sensitive) at repository root |
| Permission denied on tool use | Permission mode too restrictive | Check .claude/settings.json allow/deny lists and adjust |
| Slash command not found | File not in .claude/commands/ | Verify path is .claude/commands/command-name.md |
| Hook blocks every commit | Linter or tests failing | Fix underlying issues; Claude Code won't skip hooks by design |
| Context window exhausted | Long session with many files | Run /compact or start a new session with focused scope |
Can multiple team members use different CLAUDE.md settings?
Yes. The global ~/.claude/CLAUDE.md file is personal to each developer and is never committed to the repository. The project-level CLAUDE.md at the repo root is shared by all team members via version control. Personal preferences go in the global file, while team conventions go in the project file. When both exist, instructions from both are combined, with project-level instructions taking precedence for project-specific rules.
How do I prevent Claude Code from running destructive commands?
Use the .claude/settings.json file to explicitly deny dangerous patterns. Add entries like Bash(rm -rf*), Bash(git push —force*), and Bash(DROP TABLE*) to the deny list. Commit this file to your repository so the restrictions apply to every team member. Additionally, use —mode plan for read-only sessions where no modifications should occur.
Do custom slash commands support arguments and variables?
Yes. Use the $ARGUMENTS placeholder in your command markdown files. When a team member runs /your-command some arguments here, the text after the command name replaces $ARGUMENTS in the template. This lets you build reusable, parameterized workflows like /document src/models/user.py or /review —focus security.