Claude Code Project Directory Structure

A typical Claude Code project directory structure is as follows:

your-project/
├── CLAUDE.md                    ← 团队共享指令，提交到 git
├── CLAUDE.local.md              ← 个人覆盖，被 git 忽略
└── .claude/
    ├── settings.json            ← 权限 + 配置，提交到 git
    ├── settings.local.json      ← 个人权限，被 git 忽略
    ├── commands/                ← 自定义斜杠命令
    │   ├── review.md            →  /project:review
    │   ├── fix-issue.md         →  /project:fix-issue
    │   └── deploy.md            →  /project:deploy
    ├── rules/                   ← 模块化指令文件（全局生效）
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/                  ← 自动调用的工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    └── agents/                  ← 子代理角色定义
        ├── code-reviewer.md
        └── security-auditor.md

---

CLAUDE.md -- Project Core Instructions

CLAUDE.md　

This is when Claude enters the projectthe first readfile, equivalent to the project welcome manual.

CLAUDE.md is placed in the project root directory and shared by all team members. It tells Claude: what this project is, how to run it, and what conventions exist.

Typical content:

# My Project

一句话描述项目用途。

## Tech Stack
- Backend: Python / FastAPI
- Frontend: React + TypeScript
- Database: PostgreSQL

## Common Commands
\`npm run dev\`    # 启动开发服务器
\`pytest tests/\`  # 运行测试
\`npm run build\`  # 构建生产版本

## Code Conventions
- 使用 snake_case 命名变量
- 所有 API 需要写单元测试
- PR 合并前必须通过 CI

## Architecture Overview
src/
├── api/        # FastAPI 路由层
├── services/   # 业务逻辑层
└── models/     # 数据模型层

💡 Tip:Claude will automatically recursively read CLAUDE.md in parent directories. In a monorepo, you can place another CLAUDE.md inside a subpackage, and Claude will merge and understand both levels of instructions.

CLAUDE.local.md

Personal exclusive override layer, layered on top of CLAUDE.md.

CLAUDE.local.md stores preferences or temporary instructions that are only relevant to you and should not be shared with the team.

Typical content:

# 我的本地覆盖

本地数据库地址：localhost:5433（非默认端口）

调试时请优先输出详细日志。

## 临时规则（本次任务用）
目前专注于重构 auth/ 模块，其他模块暂时不要改动。

---

.claude/settings.json-- Permissions and Configuration Center

settings.json

Team-shared configuration file that controls Claudeallow or forbidwhich operations to execute, serving as the team's security baseline.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pytest:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)"
    ]
  }
}

settings.local.json

Personal local permission override, temporarily loosening or tightening certain permissions without affecting other team members.

{
  "permissions": {
    "allow": [
      "Bash(rm ./tmp/*)"
    ]
  }
}

---

.claude/commands/-- Custom Slash Commands

Each in the directory.mdfile is automatically mapped to a/project:文件名command.

.claude/commands/is the team's approach to turning repetitive tasksinto standardizedcore mechanism.

File name	corresponding command
review.md	/project:review
fix-issue.md	/project:fix-issue
deploy.md	/project:deploy

Example:commands/review.md

# Code Review

请对当前修改执行完整的代码审查：

1. 检查是否有安全漏洞（SQL 注入、XSS 等）
2. 验证错误处理是否完整
3. 确认测试覆盖率是否达标
4. 检查是否符合代码风格规范
5. 评估性能影响

用中文输出结构化审查报告，按严重程度排列问题。

Example:commands/fix-issue.md(with parameters)

# Fix GitHub Issue

给定 Issue 编号 $ARGUMENTS，请：

1. 读取并理解 Issue 描述
2. 定位相关代码文件
3. 实现最小化修复方案
4. 编写对应的单元测试
5. 更新 CHANGELOG.md

调用方式：/project:fix-issue 123

💡 Parameter passing:In the command file, you can use$ARGUMENTSplaceholders to receive parameters passed when invoked.

---

.claude/rules/-- Modular Behavioral Rules

Split the rules in CLAUDE.mdinto modularstorage. Claude always complies throughout the entire session. Suitable for storing long-term stable behavioral conventions, avoiding overly bloated CLAUDE.md.

Example:rules/code-style.md

# Code Style Rules

- TypeScript 严格模式，禁用 any 类型
- 函数长度不超过 40 行，超出则拆分
- 优先使用 const，避免使用 let
- 导入顺序：标准库 → 三方包 → 本地模块
- 所有 export 的函数/类型需要 JSDoc 注释
- 禁止使用 console.log，使用项目 logger

Example:rules/testing.md

# Code Style Rules

- TypeScript 严格模式，禁用 any 类型
- 函数长度不超过 40 行，超出则拆分
- 优先使用 const，避免使用 let
- 导入顺序：标准库 → 三方包 → 本地模块
- 所有 export 的函数/类型需要 JSDoc 注释
- 禁止使用 console.log，使用项目 logger

Example:rules/api-conventions.md

# API Conventions

- RESTful 风格，资源名使用复数形式
- 统一响应格式：{ data, error, meta }
- 错误码遵循 HTTP 标准语义
- 所有接口需要在 OpenAPI 文档中声明
- 分页参数统一使用 page / page_size

---

.claude/skills/-- Automatically Invoked Workflows

Skills are more advancedcomposite workflows. When Claude determines that a task is suitable for a skill, it automatically reads and executes the corresponding SKILL.md,no manual invocation needed。

Each skill is a subdirectory, containingSKILL.md。

Example:skills/security-review/SKILL.md

# Security Review Skill

## 触发条件
当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。

## 执行步骤
1. 扫描 SQL 注入风险（检查所有数据库查询）
2. 检查 XSS 防护（验证输出转义）
3. 审计权限边界（确认最小权限原则）
4. 检查敏感数据处理（日志、错误信息中是否泄露）
5. 输出 OWASP Top 10 对照检查表

## 输出格式
按 CVSS 评分排列，高危问题优先展示。

⚡ Difference between Skills and Commands:

• CommandsRequires the user to actively input a slash command to trigger; it is a "toolbox"
• SkillsClaude automatically determines whether to invoke based on context; it is "intelligent instinct"

---

.claude/agents/-- Subagent Roles

Defines that can be dispatched by the main Claude instanceDispatched professional subagents. In complex tasks, the main agent delegates subtasks to corresponding expert roles, achievingmulti-agent collaboration. Subagents run in isolated contexts and have independent permission scopes.

Example:agents/code-reviewer.md

---
name: code-reviewer
description: 资深代码审查员，专注代码质量与可维护性
---

# 代码审查员

## 角色定位
你是一名拥有 10 年经验的资深工程师，专注于代码可读性、性能优化和最佳实践。

## 审查重点
- 命名是否清晰表达意图
- 函数/类的单一职责原则
- 边界条件和错误处理
- 性能瓶颈（N+1 查询、不必要的循环等）

## 权限
只读访问，不直接修改文件。

## 输出格式
使用 Markdown 表格输出，包含：问题位置、严重程度、建议方案。

Example:agents/security-auditor.md

---
name: security-auditor
description: 安全审计专家，专注漏洞扫描与合规审计
---

# 安全审计员

## 角色定位
你是一名安全工程师，熟悉 OWASP、CVE 数据库和常见攻击向量。

## 审计范围
- 认证与授权逻辑
- 输入验证与输出转义
- 依赖包已知漏洞（结合 npm audit / pip audit）
- 敏感信息泄露风险

## 权限
只读访问 + 可运行安全扫描工具。

## 输出格式
按 CVSS 3.1 评分排列，包含：漏洞描述、影响范围、修复建议、参考链接。

---

Cheat Sheet

File / Directory	Commit to Git	Trigger method	Core purpose
CLAUDE.md	✅ Yes	Automatic (on startup)	Project basic instructions and conventions
CLAUDE.local.md	❌ No	Automatic (on startup)	Personal overrides, temporary instructions
.claude/settings.json	✅ Yes	Automatic (on startup)	Team permission baseline
.claude/settings.local.json	❌ No	Automatic (on startup)	Personal permission overrides
.claude/commands/*.md	✅ Yes	Manual (/project:xxx）	Reusable standardized workflows
.claude/rules/*.md	✅ Yes	Automatic (globally effective)	Modular behavioral guidelines
.claude/skills/*/SKILL.md	✅ Yes	Automatic (judged by Claude)	Intelligent composite workflows
.claude/agents/*.md	✅ Yes	Automatic (dispatched by main agent)	Professional sub-agent role definitions

---

Best Practice Recommendations

Start with a minimal viable configuration:

your-project/
├── CLAUDE.md        # 先从这里开始
└── .claude/
    └── settings.json    # 配置基本权限

As the project grows, gradually introduce:

1. commands/— When you find yourself repeatedly entering the same instructions
2. rules/— When CLAUDE.md exceeds 100 lines, split it into modules
3. skills/— When there are complex multi-step workflows that need standardization
4. agents/— When tasks are complex enough to require multiple professional perspectives in parallel

Principle:"Good enough" beats "perfect." Don't build a complex multi-agent system from the start; introduce it only when truly needed.

Other extensions