Claude Code 项目目录结构

一个典型的 Claude Code 项目目录结构如下：

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 -- 项目核心指令

CLAUDE.md　

这是 Claude 进入项目时第一个读取的文件，相当于项目欢迎手册。

CLAUDE.md 放置在项目根目录，所有团队成员共享，它告诉 Claude：这个项目是什么、如何运行、有什么约定。

典型内容：

# 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/     # 数据模型层

💡 提示： Claude 会自动递归读取父目录中的 CLAUDE.md。在 monorepo 中，子包内可再放一个 CLAUDE.md，Claude 会将两层指令合并理解。

CLAUDE.local.md

个人专属的覆盖层，叠加在 CLAUDE.md 之上。

CLAUDE.local.md 存放只与你本人相关的偏好或临时指令，不应共享给团队。

典型内容：

# 我的本地覆盖

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

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

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

---

.claude/settings.json -- 权限与配置中心

settings.json

团队共享的配置文件，控制 Claude 允许或禁止执行哪些操作，作为团队安全基线。

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

settings.local.json

个人本地权限覆盖，临时放开或收紧某些权限，不影响团队其他成员。

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

---

.claude/commands/ -- 自定义斜杠命令

目录下每个 .md 文件自动映射为一条 /project:文件名 命令。

.claude/commands/ 是团队将重复性任务标准化的核心机制。

文件名	对应命令
review.md	/project:review
fix-issue.md	/project:fix-issue
deploy.md	/project:deploy

示例：commands/review.md

# Code Review

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

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

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

示例：commands/fix-issue.md（带参数）

# Fix GitHub Issue

给定 Issue 编号 $ARGUMENTS，请：

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

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

💡 参数传递： 命令文件中可使用 $ARGUMENTS 占位符接收调用时传入的参数。

---

.claude/rules/ -- 模块化行为规则

将 CLAUDE.md 中的规则拆分模块化存放，Claude 在整个会话中始终遵守。适合存放长期稳定执行的行为约定，避免 CLAUDE.md 过于臃肿。

示例：rules/code-style.md

# Code Style Rules

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

示例：rules/testing.md

# Code Style Rules

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

示例：rules/api-conventions.md

# API Conventions

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

---

.claude/skills/ -- 自动调用的工作流

Skills 是更高级的复合工作流。当 Claude 判断某个任务适合某个 skill 时，会自动读取并执行对应的 SKILL.md，无需手动调用。

每个 skill 是一个子目录，目录内包含 SKILL.md。

示例：skills/security-review/SKILL.md

# Security Review Skill

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

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

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

⚡ Skills vs Commands 的区别：

• Commands 需要用户主动输入斜杠命令触发，是"工具箱"
• Skills 由 Claude 根据上下文自动判断是否调用，是"智能本能"

---

.claude/agents/ -- 子代理角色

定义可被主 Claude 实例派遣的专业子代理。在复杂任务中，主代理将子任务委派给对应专家角色，实现多代理协作。子代理在隔离上下文中运行，拥有独立的权限范围。

示例：agents/code-reviewer.md

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

# 代码审查员

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

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

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

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

示例：agents/security-auditor.md

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

# 安全审计员

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

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

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

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

---

速查表

文件 / 目录	提交 Git	触发方式	核心用途
CLAUDE.md	✅ 是	自动（启动时）	项目基础指令与约定
CLAUDE.local.md	❌ 否	自动（启动时）	个人覆盖、临时指令
.claude/settings.json	✅ 是	自动（启动时）	团队权限基线
.claude/settings.local.json	❌ 否	自动（启动时）	个人权限覆盖
.claude/commands/*.md	✅ 是	手动（/project:xxx）	可复用的标准化流程
.claude/rules/*.md	✅ 是	自动（全局生效）	模块化行为规范
.claude/skills/*/SKILL.md	✅ 是	自动（Claude 判断）	智能复合工作流
.claude/agents/*.md	✅ 是	自动（主代理派遣）	专业子代理角色定义

---

最佳实践建议

从最小可行配置开始：

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

随着项目发展，再逐步引入：

1. commands/ — 当你发现自己重复输入相同的指令时
2. rules/ — 当 CLAUDE.md 超过 100 行时，拆分模块
3. skills/ — 当有复杂的多步骤工作流需要标准化时
4. agents/ — 当任务复杂到需要多个专业视角并行时

原则： "够用"胜过"完美"。不要一开始就构建复杂的多代理系统，在真正需要时再引入。