Claude Code 项目目录结构详解

在使用 Claude Code 进行 AI 辅助开发时，合理的项目目录结构是高效协作的基础。Claude 在进入项目时会自动读取特定文件和目录，了解这些约定的组织结构，能帮助我们充分发挥智能编码助手的潜力。

一个典型的 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 进入项目时第一个读取的文件，相当于项目的"欢迎手册"。CLAUDE.md 放置在项目根目录，所有团队成员共享，它告诉 Claude 这个项目是什么、如何运行、以及有哪些约定。Claude 会自动递归读取父目录中的 CLAUDE.md，在 monorepo 中，子包内可再放一个 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.local.md

个人专属的覆盖层，叠加在 CLAUDE.md 之上。存放只与你本人相关的偏好或临时指令，不应共享给团队，因此会被 git 忽略。

典型内容：

# 我的本地覆盖

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

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

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

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

团队共享的配置文件，控制 Claude 允许或禁止执行哪些操作，作为团队安全基线。同时支持 settings.local.json 用于个人本地权限覆盖，临时放开或收紧某些权限，不影响团队其他成员。

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

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

该目录下每个 .md 文件自动映射为一条 /project:文件名 命令。这是团队将重复性任务标准化的核心机制。

review.md 示例：

# Code Review

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

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

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

Commands 还支持参数传递，使用 $ARGUMENTS 占位符接收调用时传入的参数。例如 /project:fix-issue 123 会将 "123" 传递给 fix-issue.md。

.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/api-conventions.md 示例：

# API Conventions

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

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

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

与 Commands 的核心区别：Commands 需要用户主动输入斜杠命令触发，属于"工具箱"；Skills 由 Claude 根据上下文自动判断是否调用，属于"智能本能"。

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

# Security Review Skill

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

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

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

.claude/agents/ — 子代理角色

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

agents/code-reviewer.md 示例：

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

# 代码审查员

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

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

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

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

速查表

最佳实践建议

从最小可行配置开始：

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

随着项目发展，再逐步引入更多配置：

1. commands/ — 当发现自己重复输入相同的指令时

2. rules/ — 当 CLAUDE.md 超过 100 行时，拆分模块

3. skills/ — 当有复杂的多步骤工作流需要标准化时

4. agents/ — 当任务复杂到需要多个专业视角并行时

核心原则："够用"胜过"完美"。不要一开始就构建复杂的多代理系统，在项目真正需要时再引入相应的配置层级。

作者：admin

TTF的家园-www.ttfde.top 个人博客以便写写东西，欢迎喜欢互联网的朋友一起交流!

TTF的家园 站点 QQ交谈