project-setup

Project Setup

Set up projects to work optimally with Claude Code with proper configuration, permissions, and team sharing.

Quick Reference

Quick Setup Checklist

For new projects:

• Create .claude/ directory structure
• Add CLAUDE.md with project knowledge
• Configure .claude/settings.json with permissions
• Add .claude/settings.local.json to .gitignore
• Set up MCP servers in .mcp.json if needed
• Create project-specific slash commands
• Run /init to verify setup

Directory Structure

Minimal Setup

project/
├── .claude/
│   └── settings.json          # Basic permissions
└── CLAUDE.md                  # Project knowledge

Standard Setup

project/
├── .claude/
│   ├── settings.json          # Shared project settings
│   ├── settings.local.json    # Personal overrides (gitignored)
│   ├── commands/              # Project slash commands
│   │   └── deploy.md
│   └── skills/                # Project-specific skills
│       └── domain-model/
│           └── SKILL.md
├── .mcp.json                  # Shared MCP servers
├── CLAUDE.md                  # Project knowledge (root)
└── src/
    └── CLAUDE.md              # Subdirectory knowledge (optional)

Full Setup (with hooks)

project/
├── .claude/
│   ├── settings.json          # Settings with hooks
│   ├── settings.local.json    # Personal overrides
│   ├── commands/              # Slash commands
│   │   ├── deploy.md
│   │   └── test.md
│   ├── skills/                # Project skills
│   │   └── domain-model/
│   │       └── SKILL.md
│   └── hooks/                 # Hook scripts
│       ├── format.sh
│       └── validate.py
├── .mcp.json                  # Shared MCP servers
└── CLAUDE.md                  # Project knowledge

CLAUDE.md

The most important file for Claude Code. Place in project root.

Template

# CLAUDE.md

## Project Overview
[Brief description of what this project does]

## Tech Stack
- [Framework/language]
- [Database]
- [Key dependencies]

## Commands
- `bun install` - Install dependencies
- `bun dev` - Start development server
- `bun test` - Run tests
- `bun build` - Build for production

## Architecture
[Key directories and their purposes]

## Code Style
- [Linting rules]
- [Naming conventions]
- [Patterns to follow]

## Important Notes
- [Gotchas and things Claude should know]

Location Precedence

Claude reads CLAUDE.md files in this order (all are included):

1. ~/.claude/CLAUDE.md - Personal global instructions
2. ~/CLAUDE.md - Home directory instructions
3. ./CLAUDE.md - Project root
4. ./src/CLAUDE.md - Subdirectory (and any other CLAUDE.md files)

Tip: Use subdirectory CLAUDE.md files for module-specific guidance.

Settings Files

.claude/settings.json

Project settings committed to version control.

{
  "permissions": {
    "allow": [
      "Bash(bun:*)",
      "Bash(git:*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {}
}

.claude/settings.local.json

Personal overrides (add to .gitignore).

{
  "permissions": {
    "allow": [
      "Bash(docker:*)"
    ]
  },
  "env": {
    "DEBUG": "true"
  }
}

~/.claude/settings.json

User-level settings (applies to all projects).

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": []
  },
  "env": {}
}

Permission Setup

Permission Patterns

Recommended Permissions by Project Type

Node.js/Bun:

{
  "permissions": {
    "allow": [
      "Bash(bun:*)", "Bash(npm:*)", "Bash(npx:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

Python:

{
  "permissions": {
    "allow": [
      "Bash(python:*)", "Bash(pip:*)", "Bash(uv:*)",
      "Bash(pytest:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

Rust:

{
  "permissions": {
    "allow": [
      "Bash(cargo:*)", "Bash(rustc:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

MCP Server Configuration

.mcp.json (Shared)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Adding Servers

# Add to project (creates .mcp.json)
claude mcp add --scope project memory -- npx -y @modelcontextprotocol/server-memory

# Add to user (all projects)
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github

# Add remote server
claude mcp add --transport http context7 https://mcp.context7.com/v1/mcp

Hooks Setup

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Project: $(basename $CLAUDE_PROJECT_DIR)\""
          }
        ]
      }
    ]
  }
}

Team Considerations

What to Commit

.gitignore Additions

# Claude Code personal settings
.claude/settings.local.json
.claude/*.local.json

# MCP server data (if any)
.mcp-data/

Team Onboarding

1. Clone repository
2. Run /init to verify Claude Code setup
3. Create personal .claude/settings.local.json for overrides
4. Set required environment variables
5. Run /project-status (if command exists) to verify

Validation Commands

# Check Claude Code settings
claude config list

# Verify MCP servers
claude mcp list

# Check permissions
/permissions

# View hooks
/hooks

Common Issues

Reference Files