The Claude Code Project Structure is a well-organized framework designed to streamline development workflows, ensure clarity in team collaboration, and maintain consistency across coding standards. It includes essential files, modular configurations, and automation hooks to optimize project management.
CLAUDE.mdLoaded every single session. Contains project overview, tech stack, coding conventions, architecture notes, hard rules, and safety boundaries. Under 200 lines for clarity.
CLAUDE.local.mdPersonal overrides. Never committed. Stores machine-specific paths, personal preferences, and experimental rules. Stacks on top of CLAUDE.md.
AGENTS.mdThe team roster. Who does what. Defines subagent roles, capabilities, and handoff protocols. Prevents overlap and ensures multi-agent sessions stay coordinated.
mcp.jsonMCP server integrations. Shared via git. Connects Claude to external services like GitHub, Notion, Slack, Gmail, PostgreSQL, and more.
settings.jsonPermissions, tools, and hooks config. Defines what Claude can read, write, and execute. Includes allow/deny lists and hook events. Personal overrides go in settings.local.json.
rules/*.mdModular rule files. Loaded on demand. Each .md file is a focused rule module (e.g., coding style, API conventions, testing standards). Keeps CLAUDE.md lean by externalizing details.
commands/*.mdCustom slash commands for your project. Each .md becomes a /project:command-name. Perfect for PR reviews, deploys, and scaffolding.
skills/<name>/SKILL.mdAuto-triggered by task context. Not a single file—organized by skill type. Loads only when Claude recognizes the task. Keeps runtime lightweight.
agents/*.mdSpecialized subagents with isolated context. Includes system prompts, own tools, and sandboxed execution windows for tasks like security reviews and research.
hooks/*.shEvent-driven scripts. 100% enforcement. Automates Claude’s operations with deterministic shell commands. Includes pre/post hooks for validation and formatting.
memory/*.mdPersistent memory across all sessions. Tracks project context, architectural decisions, and progress. Compensates for context resets.
workflows/*.mdMulti-step task blueprints. Defines repeatable workflows for feature builds, bug fixes, and code reviews. Combines skills, subagents, and hooks in sequence.
Imagine Sarah, a software engineer, working on a collaborative project using Claude Code.
CLAUDE.md, which provides her with an overview of the tech stack, coding conventions, and architecture notes. She reviews the hard rules to ensure compliance.CLAUDE.local.md, customizing paths and preferences for her setup.AGENTS.md to confirm her role and responsibilities. She sees that her teammate Alex is handling security reviews, while she focuses on feature development.mcp.json file integrates Claude with GitHub and Slack, allowing Sarah to push updates and communicate seamlessly./project:deploy from commands/deploy.md to deploy the latest build. Claude automatically triggers relevant skills from skills/deploy/SKILL.md.hooks/validate-code.sh ensure her changes meet coding standards.memory/progress.md with notes on completed tasks, ensuring the team stays aligned.workflows/feature-build.md, Sarah follows a multi-step blueprint to finalize the feature, combining subagents, hooks, and skills.By the end of the day, Sarah has completed her tasks efficiently, leveraging the structured framework of Claude Code.