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 该项目的基本信息、运行方式和约定。

# 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 之上，存放只与你个人相关的偏好或临时指令，不应共享给团队。典型内容包括本地数据库地址、调试偏好以及当前任务的临时专注范围。

# 我的本地覆盖

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

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

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

.claude/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:文件名 命令。这是团队将重复性任务标准化的核心机制。

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

# API Conventions

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

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

Skills 是更高级的复合工作流。当 Claude 判断某个任务适合某个 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 查询、不必要的循环等）

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

示例：agents/security-auditor.md

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

# 安全审计员

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

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

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

速查表

最佳实践建议

建议从最小可行配置开始：

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交谈