Claude Code Projects

How to use Claude Code's Projects feature to organize sessions, share context across conversations, and manage team context for different codebases.

Claude Code organizes context around directories: each directory with a CLAUDE.md is effectively a project. Here's how to structure projects for solo and team use.

Project setup

# A "project" in Claude Code = a directory + CLAUDE.md + .claude/settings.json

my-api/
├── CLAUDE.md            # project context (committed to git)
├── .claude/
│   ├── settings.json   # permissions, hooks, MCP (committed to git)
│   └── commands/       # custom slash commands (committed to git)
│       ├── deploy-check.md
│       └── generate-migration.md
├── src/
└── tests/

# Start Claude Code in the project:
cd my-api
claude

# Claude reads CLAUDE.md automatically — no setup needed.

Multi-project workflow

# Working across multiple repos:

# Each repo is its own project with its own CLAUDE.md:
~/projects/
├── api-service/
│   ├── CLAUDE.md        # "Python FastAPI service, PostgreSQL, ..."
│   └── .claude/
├── mobile-app/
│   ├── CLAUDE.md        # "React Native app, iOS/Android, ..."
│   └── .claude/
└── data-pipeline/
    ├── CLAUDE.md        # "Apache Airflow, BigQuery, ..."
    └── .claude/

# Switch context by cd-ing:
cd ~/projects/api-service && claude   # API context loaded
cd ~/projects/mobile-app && claude    # Mobile context loaded — different CLAUDE.md

Global vs project context

# ~/.claude/CLAUDE.md — applies everywhere:
## Global preferences
- Use type hints in all Python functions
- Prefer functional style over classes for utilities
- Always show the command before running it

# ./CLAUDE.md — project specific:
## My API Service
### Stack: Python 3.12, FastAPI, PostgreSQL 15
### Commands: pytest tests/ -x -q
### Architecture: ...

# Both files are merged — global provides baseline,
# project CLAUDE.md adds/overrides for this codebase.

Custom commands per project

# .claude/commands/generate-migration.md
Generate an Alembic migration for the following schema change:

$ARGUMENTS

Requirements:
- Migration file name: alembic/versions/YYYYMMDD_HHMMSS_description.py
- Include both upgrade() and downgrade() methods
- Use op.batch_alter_table() for SQLite compatibility
- Add a comment at the top explaining what this migration does

After generating, run: alembic check to verify no pending migrations conflict.

# Use it:
/generate-migration "add email_verified boolean column to users table"

Team onboarding via CLAUDE.md

# New teammate onboards to Claude Code in 2 minutes:
git clone https://github.com/myorg/my-api
cd my-api
claude  # CLAUDE.md auto-loaded — Claude knows the stack, commands, conventions

# Teammate asks:
"How do I run the tests?"
# Claude reads CLAUDE.md and answers from the Commands section — no guessing.

# Teammate asks:
"What's the architecture of the auth system?"
# Claude reads CLAUDE.md architecture section + src/auth/ for details.

Keep CLAUDE.md current

# Open CLAUDE.md for editing:
/memory

# Or edit directly and commit:
# Common update triggers:
# - New service added to the stack
# - Build command changed (package.json scripts, Makefile target renamed)
# - Active WIP context changed (new branch, different feature focus)
# - New convention adopted by the team

# Treat CLAUDE.md like a living document — update it when things change.
# An outdated CLAUDE.md is worse than none (gives Claude wrong context).

For a complete guide to CLAUDE.md structure and memory layers, see Claude Code memory guide. For configuring project permissions and hooks, see Claude Code settings.json reference.

Frequently asked questions

Free tools

More examples