Claude Code Project Structure

A comprehensive guide to structuring your Claude Code projects for maximum productivity and team collaboration.

🎯 What is This Repository?

This repository demonstrates the optimal file and folder structure for projects using Claude Code — Anthropic's official CLI, desktop app, and IDE extension for AI-powered development.

Whether you're working solo or on a team, proper project structure helps Claude Code:

• Understand your codebase faster
• Follow your coding standards automatically
• Remember team conventions across sessions
• Execute custom workflows with slash commands
• Use specialized skills and agents for specific tasks

🚀 Why Project Structure Matters

Claude Code loads configuration files at the start of each session. A well-structured project means:

✅ Consistent behavior - Claude follows the same rules every time
✅ Faster onboarding - New team members get instant context
✅ Reusable workflows - Create slash commands for common tasks
✅ Specialized agents - Deploy focused agents for review, security, testing
✅ Personal flexibility - Local overrides for individual preferences
✅ Better results - Claude understands your architecture, conventions, and rules

📁 Complete Folder Structure

claude-code-project-structure/
├── README.md                              # This file
├── CLAUDE.md                              # Shared project documentation (committed)
├── CLAUDE.local.example.md                # Example personal preferences (not committed)
├── .mcp.example.json                      # Example MCP server configuration
│
├── .claude/                               # Claude Code configuration directory
│   ├── settings.json                      # Shared project settings (committed)
│   ├── settings.local.example.json        # Example local settings (not committed)
│   │
│   ├── commands/                          # Reusable slash commands
│   │   ├── review.md                      # /review - Code review workflow
│   │   ├── deploy.md                      # /deploy - Deployment checklist
│   │   └── fix-issue.md                   # /fix-issue - Bug fix workflow
│   │
│   ├── skills/                            # Specialized knowledge modules
│   │   └── testing-patterns/
│   │       └── SKILL.md                   # Testing best practices
│   │
│   └── agents/                            # Specialized sub-agents
│       ├── code-reviewer.md               # Code quality agent
│       └── security-auditor.md            # Security scanning agent
│
└── .gitignore                             # Protects secrets and local files

🔧 How Each File Works

Core Documentation Files

CLAUDE.md

Purpose: Onboarding documentation loaded in every Claude Code session.

What to include:

• Project overview and goals
• Tech stack and architecture
• Coding conventions and standards
• Testing requirements
• Git workflow rules
• Security guidelines
• Documentation standards

When Claude uses it: Automatically loaded at session start to understand project context.

CLAUDE.local.md

Purpose: Personal preferences and workflow notes (not committed to git).

What to include:

• Your preferred terminal commands
• Local environment setup
• Personal formatting preferences
• Custom shortcuts or reminders
• Notes specific to your development setup

When Claude uses it: Loaded alongside CLAUDE.md but overrides take precedence for your local workflow.

.mcp.example.json

Purpose: Example configuration for MCP (Model Context Protocol) servers.

What it enables:

• Connect Claude Code to GitHub, Jira, Slack, databases
• Access external tools and services
• Extend Claude's capabilities beyond the filesystem

How to use:

1. Copy .mcp.example.json to .mcp.json
2. Add your real credentials and endpoints
3. Never commit the real .mcp.json file

Settings Files

.claude/settings.json

Purpose: Project-wide settings shared with the team.

What to configure:

• Tool permissions (which commands are auto-allowed)
• Hooks (commands that run before/after Claude actions)
• PreToolUse/PostToolUse validations
• Git workflow enforcement
• Linting and formatting checks

Example use cases:

• Auto-run tests before commits
• Enforce branch naming conventions
• Validate no secrets in code
• Run linters on file changes

.claude/settings.local.json

Purpose: Personal overrides (not committed).

What to override:

• Additional tool permissions
• Local-only hooks
• Development shortcuts
• Personal automation preferences

Commands (Slash Commands)

Slash commands are reusable workflows stored in .claude/commands/.

How to use: Type /command-name in Claude Code to invoke.

/review - Code Review Workflow

Analyzes changed files for code quality, security issues, test coverage, and improvement suggestions.

Usage: /review
Usage: /review --strict

/deploy - Deployment Preparation

Validates environment config, runs tests, checks deployment risks, creates deployment checklist.

Usage: /deploy
Usage: /deploy production

/fix-issue - Bug Fix Workflow

Structured approach to understanding, fixing, and testing bugs with minimal changes.

Usage: /fix-issue "User login fails on mobile"

Skills

Skills are specialized knowledge modules loaded when relevant.

testing-patterns/

Provides testing best practices, patterns for unit/integration tests, mocking strategies, and edge case handling.

When Claude uses it: When writing or reviewing tests, or when you explicitly invoke testing-related tasks.

Agents

Agents are specialized sub-agents with focused roles.

code-reviewer

Focused on code quality, maintainability, performance, and best practices.

When to use: Spawn with Agent tool for independent code reviews.

security-auditor

Specialized in security scanning, secrets detection, vulnerability analysis, and security best practices.

When to use: Spawn with Agent tool for security reviews before merging.

🎓 How to Use This Repository

For Learning

1. Clone this repository:

   git clone https://github.com/yourusername/claude-code-project-structure.git
   cd claude-code-project-structure

2. Open it in Claude Code (CLI, desktop app, or IDE extension)

3. Explore each file to understand its purpose

4. Try the slash commands: /review, /deploy, /fix-issue

For Your Own Projects

1. Copy the structure:

   # Copy .claude/ folder to your project
   cp -r .claude/ /path/to/your/project/
   
   # Copy CLAUDE.md and customize it
   cp CLAUDE.md /path/to/your/project/

2. Customize for your project:

   • Edit CLAUDE.md with your tech stack, conventions, and rules
   • Modify .claude/settings.json for your team's workflow
   • Create custom commands in .claude/commands/
   • Add project-specific skills in .claude/skills/

3. Set up local overrides:

   # Create your personal local files (not committed)
   cp CLAUDE.local.example.md CLAUDE.local.md
   cp .claude/settings.local.example.json .claude/settings.local.json
   cp .mcp.example.json .mcp.json

4. Commit team files, ignore personal files:

   git add CLAUDE.md .claude/
   git add .gitignore
   git commit -m "Add Claude Code project structure"

For Teams

Share with the team (committed):

• CLAUDE.md - Project knowledge
• .claude/settings.json - Shared workflows
• .claude/commands/ - Team slash commands
• .claude/skills/ - Shared knowledge modules
• .claude/agents/ - Specialized agents

Keep personal (not committed):

• CLAUDE.local.md - Personal notes
• .claude/settings.local.json - Personal preferences
• .mcp.json - Your credentials

Result: Everyone gets consistent Claude behavior while maintaining personal flexibility.

📝 Best Practices

1. Start with CLAUDE.md

Every project should have a CLAUDE.md that explains:

• What the project does
• How it's structured
• What the conventions are
• What Claude should know

2. Create Commands for Repeated Tasks

If you do something more than twice, make it a slash command:

• Code reviews
• Deployment prep
• Migration scripts
• Testing workflows
• Documentation generation

3. Use Skills for Domain Knowledge

When Claude needs specialized knowledge (testing patterns, security rules, API conventions), create a skill module.

4. Deploy Agents for Focused Work

Use specialized agents for:

• Independent code reviews
• Security audits
• Performance analysis
• Documentation review

5. Protect Secrets

Always use .example files for templates and never commit:

• .mcp.json
• CLAUDE.local.md
• .claude/settings.local.json
• Any files with real credentials

6. Document Your Conventions

The better documented your project is, the better Claude performs. Include:

• Architecture decisions
• Coding standards
• Testing requirements
• Security rules
• Git workflow

7. Iterate and Improve

Your Claude Code structure will evolve. Update files as you discover what works best for your team.

🔒 Security Considerations

Never commit:

• Real API keys or credentials
• Database connection strings
• Environment-specific secrets
• Personal access tokens

Always commit:

• Example configuration files (.example suffix)
• Documentation explaining what goes where
• Team-shared workflows and conventions

Use .gitignore: This repository includes a .gitignore that protects local files. Review it and adapt for your stack.

🤝 Contributing

If you have suggestions for improving this structure:

1. Open an issue with your idea
2. Submit a pull request with improvements
3. Share your own best practices

📚 Additional Resources

• Claude Code Documentation
• Claude API Documentation
• Model Context Protocol (MCP)

📄 License

MIT License - feel free to use this structure in your projects.

🙌 Acknowledgments

Created to help developers get the most out of Claude Code. Share this repository with anyone who wants to improve their AI-assisted development workflow.

---

Ready to supercharge your development workflow?

⭐ Star this repository if you find it helpful
🔗 Share on LinkedIn to help other developers
💬 Open an issue if you have questions

Happy coding with Claude! 🚀