FEATURE ARTICLE

Claude Code 最佳实践总览

Claude Code 最佳实践系列总览，覆盖目录结构、配置分层与团队协作建议。

2026-05-22 技术 工作流 / Claude Code

2.4 项目目录结构全景 🟢

一个完整的 Claude Code 项目配置结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
your-project/
├── CLAUDE.md                    # 📋 项目级指令（团队共享，提交到 Git）
├── CLAUDE.local.md              # 👤 个人项目偏好（自动 gitignore）
├── .claude/
│   ├── settings.json            # ⚙️ 项目设置（团队共享）
│   ├── settings.local.json      # 👤 个人项目设置（gitignore）
│   ├── CLAUDE.md                # 📋 等效于根目录 CLAUDE.md
│   ├── rules/                   # 📏 模块化规则文件
│   │   ├── code-style.md        #    代码风格
│   │   ├── testing.md           #    测试规范
│   │   └── security.md          #    安全要求
│   ├── agents/                  # 🤖 自定义子代理
│   │   ├── code-reviewer.md
│   │   └── debugger.md
│   ├── skills/                  # ⚡ 自定义技能
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── worktrees/               # 🌳 Git Worktree 目录（加入 .gitignore）
├── .mcp.json                    # 🔌 项目级 MCP 服务器配置
└── .github/
    └── workflows/
        └── claude.yml           # 🔄 Claude Code GitHub Actions

新手提示：刚开始只需要 CLAUDE.md 和 .claude/settings.json。其他配置随着需求逐步添加。

2.5 settings.json 分层配置 🟡

Claude Code 使用分层配置系统，优先级从高到低：

优先级 层级 位置 作用范围 是否共享
最高 🔴 托管策略 系统级路径（IT 部署） 组织内所有用户 是
↓ 命令行参数 CLI flags 当前会话 否
↓ 本地项目设置 .claude/settings.local.json 你在此项目 否
↓ 共享项目设置 .claude/settings.json 所有协作者 是（提交 Git）
最低 🟢 用户设置 ~/.claude/settings.json 你的所有项目 否

规则：高优先级覆盖低优先级。托管策略不可覆盖。

基础配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)"
    ]
  },
  "enabledPlugins": {
    "example-skills@anthropic-agent-skills": true,
    "context7@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true,
  "env": {
    "CLAUDE_CODE_EFFORT_LEVEL": "high"
  }
}

提示：添加 $schema 字段可以在 VS Code / Cursor 中获得自动补全。

2.7 快速验证配置 🟢

1
2
3
4
5
6
7
8
9
cd your-project
claude

# 在 Claude Code 中运行
> /init          # 自动生成 CLAUDE.md
> /config        # 查看/修改全局配置
> /permissions   # 查看/修改权限规则
> /cost          # 查看当前会话 token 用量
> /context       # 查看上下文消耗分布

4.7 实战：用规范驱动开发（SDD）做业务需求 🟡

4.1-4.6 介绍了通用的”探索→计划→编码→提交”流程。但面对较大的业务需求（新功能、新模块），直接在 Claude 的对话中口述需求往往不够——需求会散落在多轮对话中，Claude 的上下文窗口也可能装不下。

规范驱动开发（Spec-Driven Development, SDD） 提供了一种更结构化的做法：先把需求写成 Markdown 规范文件，再用 Claude Code 逐步实现。

三层产物

1
2
3
4
specs/001-feature-name/
├── spec.md      ← WHAT：功能需求（用户故事、验收标准、边界情况）
├── plan.md      ← HOW：技术方案（架构设计、数据结构、接口定义）
└── tasks.md     ← DO：原子任务（逐步执行指令，每个任务改一个文件）
产物 定位 核心内容 谁来写
spec.md 需求规范（WHAT/WHY） 用户故事、验收标准、边界情况、MVP 范围 你主导，Claude 辅助提问
plan.md 技术方案（HOW） 技术选型、目录结构、数据模型、接口设计、风险评估 Claude 主导，你审核决策
tasks.md 执行计划（DO） 原子化任务列表、依赖关系、TDD 顺序 Claude 生成，你审核完整性

在 Claude Code 中实操

第一步：协作编写 spec.md

1
2
3
> 我想构建 [功能描述]。用采访模式对我进行详细提问，
> 帮我生成一份 spec.md，包含：用户故事、验收标准、边界情况。
> 不要写任何技术实现细节。

第二步：生成 plan.md

1
2
3
4
> @specs/001-feature/spec.md
> 基于这份需求规范，生成技术方案 plan.md。
> 技术栈约束：[TypeScript / React / PostgreSQL]
> 包含：目录结构、核心数据模型、接口定义、实施阶段。

第三步：分解 tasks.md

1
2
3
> @specs/001-feature/spec.md @specs/001-feature/plan.md
> 将技术方案分解为原子任务列表 tasks.md。
> 要求：每个任务只改一个文件，测试先行（奇数任务写测试，偶数任务写实现）。

第四步：逐步执行

1
2
> @specs/001-feature/tasks.md
> 执行任务 T001-T006。严格按 TDD 顺序：先写测试（必须失败），再写实现（使测试通过）。

6.1 编写有效的 CLAUDE.md 🟢

CLAUDE.md 是一个特殊文件，Claude 在每次会话开始时读取它。写入 Bash 命令、代码风格、工作流规则等Claude 无法从代码中推断的信息。

什么该写，什么不该写

该写 ✅ 不该写 ❌
Claude 猜不到的 Bash 命令 Claude 读代码就能知道的信息
与默认不同的代码风格规则 标准语言规范（Claude 已知）
测试指令和首选测试框架 详细的 API 文档（链接即可）
仓库约定（分支命名、PR 格式） 频繁变化的信息
项目特有的架构决策 长篇教程或解释
开发环境怪癖（必需的环境变量） 逐文件的代码库描述
常见陷阱和非显而易见的行为 “写干净的代码”之类的废话

格式自由但保持精炼，例如：

1
2
3
4
5
6
7
# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, not the whole test suite, for performance

分层加载机制 🟡

CLAUDE.md 文件可以放在多个位置，自动按层级加载：

优先级 层级 位置 管理者 加载时机
最高 🔴 企业托管策略 /Library/…/ClaudeCode/CLAUDE.md IT/DevOps 启动时，不可覆盖
↓ 项目级 ./CLAUDE.md 或 .claude/CLAUDE.md + .claude/rules/*.md 团队（Git） 启动时自动
↓ 项目级（个人） ./CLAUDE.local.md 个人（gitignore） 启动时自动
↓ 用户级 ~/.claude/CLAUDE.md + ~/.claude/rules/*.md 个人 启动时自动
最低 自动记忆 ~/.claude/projects//memory/MEMORY.md Claude 自动 前 200 行自动
按需 子目录 任意子目录的 CLAUDE.md 团队 Claude 访问该目录时

优先级规则：

  • 企业策略不可覆盖
  • 更具体的指令优先——项目级覆盖用户级
  • 所有层级累加贡献内容
  • 子目录 CLAUDE.md 按需加载（只在 Claude 访问该目录的文件时加载）

模块化 rules/ 目录 🟡

对大型项目，使用 .claude/rules/ 组织规则：

1
2
3
4
5
6
7
8
9
10
.claude/rules/
├── code-style.md        # 代码风格
├── testing.md           # 测试规范
├── security.md          # 安全要求
├── frontend/
│   ├── react.md         # React 特定规则
│   └── styles.md        # 样式规范
└── backend/
    ├── api.md           # API 设计
    └── database.md      # 数据库规范

规则文件支持通过 YAML frontmatter 限定作用路径：

1
2
3
4
5
6
7
8
9
10
---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
  - "src/**/*.{ts,tsx}"       # brace expansion：同时匹配 .ts 和 .tsx
---

# API 开发规范
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式

用户级 rules/：~/.claude/rules/ 下的规则应用于你所有项目，优先级低于项目级 .claude/rules/。适合存放个人编码偏好、通用工作流等。

Symlinks 共享规则：rules/ 目录支持符号链接，可跨项目复用规则文件：

1
2
3
4
5
# 链接共享规则目录
ln -s ~/shared-claude-rules .claude/rules/shared
​
# 链接单个规则文件
ln -s ~/company-standards/security.md .claude/rules/security.md

@ 导入语法 🟡

CLAUDE.md 支持通过 @ 语法导入其他文件：

1
2
3
4
# 项目概览见 @README.md，可用命令见 @package.json

# 额外指令
- Git 工作流：@docs/git-instructions.md

规则：

  • 支持相对路径和绝对路径
  • 导入可递归，最大深度 5 层
  • 代码块中的 @ 不会触发导入
    - 注意：@ 导入会把被引用文件的完整内容拉入上下文。避免导入大文件，改为让 Claude 按需读取

自动记忆（Auto Memory）🟡

除了手动编写的 CLAUDE.md，Claude 还有自动记忆系统：

1
2
3
4
~/.claude/projects/<project>/memory/
├── MEMORY.md              # 索引文件（前 200 行自动加载）
├── debugging.md           # 调试模式笔记
└── api-conventions.md     # API 设计决策

project 由 git 仓库根路径决定——同一 repo 的子目录共享同一个 memory 目录；非 git 项目按工作目录区分。

  • Claude 在会话中自动记录有用信息
  • MEMORY.md 的前 200 行在每次会话启动时注入系统提示；其余 topic 文件（如 debugging.md）不自动加载，Claude 按需读取
  • 使用 /memory 命令可在编辑器中直接编辑
  • 你可以主动让 Claude 记住信息："记住我们使用 pnpm 而不是 npm"
  • Worktree 隔离：Git worktrees 各自拥有独立的 memory 目录，互不影响（与 9.5 Worktree 并行开发配合使用）

关闭 Auto Memory（默认开启）：

方式 配置 作用范围
/memory 菜单 交互式开关 当前用户
用户设置 ~/.claude/settings.json 中 “autoMemoryEnabled”: false 所有项目
项目设置 .claude/settings.json 中 “autoMemoryEnabled”: false 当前项目
环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 优先级最高，覆盖以上所有

CI/CD 环境建议用环境变量关闭，避免自动记忆污染 runner。

三大记忆系统对比

Claude Code 有三套独立的记忆机制，各有适用场景：

维度 CLAUDE.md Auto Memory Session Memory
存储位置 项目根目录 / ~/.claude/ ~/.claude/projects//memory/ 会话内存（不持久化）
谁来写 人工编写，提交到 Git Claude 自动记录 Claude 会话中自动管理
作用范围 团队共享（项目级）或个人全局 个人 + 项目级 仅当前会话
加载方式 每次会话自动注入系统提示 MEMORY.md 前 200 行自动注入；其余文件按需读取 始终在上下文中
典型内容 编码规范、项目架构、团队约定 调试经验、个人偏好、项目特有模式 当前任务的中间状态
适合存放 “团队所有人都该知道的” “我个人反复遇到的” “这次任务需要的”

选择原则：团队规范 → CLAUDE.md；个人经验 → Auto Memory；临时上下文 → 自然语言告诉 Claude。

6.2 配置权限 🟡

默认情况下，Claude Code 对可能修改系统的操作请求权限。这很安全但频繁打断你。

权限允许列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git commit *)",
      "Bash(git push *)"
    ],
    "ask": [
      "Bash(git push --force *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)",
      "Bash(rm -rf *)"
    ]
  }
}

deny 优先 → 然后 ask → 然后 allow → 首次匹配生效。

6.4 配置 MCP 服务器 🟡

MCP（Model Context Protocol）让 Claude 连接外部数据源——Notion、Figma、数据库等。

MCP 架构速览

MCP 基于三个角色协作：

角色 位置 职责 示例
Host（宿主） 中心编排器 管理连接、路由请求 Claude Code
Client（客户端） 连接器 1:1 会话管理、协议翻译、安全边界 每个 Server 一个内部实例
Server（服务器） 能力提供方 暴露 Tools / Resources / Prompts GitHub Server, Notion Server

MCP Server 提供三种能力：

能力类型 说明 示例
Tools（行动能力） AI 可执行的操作 create_issue、query_database
Resources（参考数据） AI 可引用的数据 @github:issue://123
Prompts（工作流模板） 封装好的提示词 /mcp__github__list_prs

安全模型：AI 模型永远不接触 API Key/Token。凭证由 Host 在运行时通过环境变量注入。

添加服务器

1
claude mcp add <server-name> -- <command>

配置文件

1
2
3
4
5
6
7
8
9
10
11
12
// .mcp.json（项目级）
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
位置 作用域
.mcp.json（项目根目录） 项目级，所有协作者
~/.claude.json 用户级，所有项目

内置技能：/simplify 与 /batch 🟡

除了自定义 Skills，Claude Code 还内置了两个强大的技能（v2.1.63+），覆盖代码审查和大规模迁移两大高频场景。

/simplify —— 自动化代码审查

/simplify 是一个并行代码审查技能，会同时启动 3 个专项审查代理（subagent），从不同维度分析你最近的代码变更：

审查代理 关注点 典型发现
code reuse 重复代码、可提取的公共逻辑 “这三个文件有相似的错误处理，可提取为 handleApiError() 工具函数”
code quality 代码规范、可读性、潜在 bug “变量命名不一致：userId vs user_id；缺少边界检查”
efficiency 性能问题、不必要的计算 “循环内重复查询数据库，可移到循环外批量获取”

/batch —— 大规模并行迁移

/batch 是一个大规模代码库迁移技能，自动将一个高层指令分解为多个独立任务并行执行，每个任务生成独立的 PR。

/simplify vs /batch 速览

维度 /simplify /batch
目的 代码审查——发现并修复质量问题 大规模迁移——批量变更代码库
输入 自动检测近期变更（或指定范围） 一条高层迁移指令
并行方式 3 个审查代理同时分析同一段代码 N 个执行代理各自处理不同文件/模块
输出 问题列表 + 自动修复建议 每个任务一个独立 PR
适合频率 每次 PR 前 每次大规模迁移时
难度 🟡 🔴

6.5 配置 Hooks 🟡

Hooks 在 Claude 工作流的特定节点自动执行脚本。与 CLAUDE.md 中的建议性指令不同，Hooks 是确定性的，保证操作一定发生。

Hooks vs CLAUDE.md 规则

维度 CLAUDE.md 规则 Hooks
驱动模型 建议性（AI 可能忽略） 事件驱动，确定性执行
类比 团队规范文档 自动化传感器
执行保证 不保证 退出码 0 = 继续，退出码 2 = 阻止（限可阻止事件）
适用场景 代码风格、架构决策 格式化、保护文件、通知、验证
经验法则 “Claude 应该做” “必须发生”

核心事件类型

事件 触发时机 典型用途
SessionStart 会话开始或恢复 注入上下文、初始化环境
UserPromptSubmit 提交提示词后 预处理或验证输入
PreToolUse 工具调用前 阻止危险操作
PostToolUse 工具调用后 自动格式化、运行 lint
Notification 需要注意时 桌面通知
Stop Claude 完成响应 验证任务完成度
PreCompact 压缩前 注入必须保留的上下文

Hook 退出码

退出码 行为
0 操作继续。stdout 可注入上下文（仅 exit 0 时解析 JSON 输出）
2 阻止操作（仅限可阻止事件：PreToolUse、UserPromptSubmit、Stop 等）。stderr 作为反馈发送给 Claude。对于不可阻止事件（PostToolUse、Notification 等），exit 2 仅显示 stderr
其他 操作继续。stderr 记入日志

注意：exit 2 的具体行为取决于事件类型。例如 PreToolUse 中 exit 2 阻止工具调用，Stop 中 exit 2 阻止 Claude 停止（强制继续），PostToolUse 中 exit 2 仅将 stderr 显示给 Claude（工具已执行，无法阻止）。

Boris Pro Tip B7：Boris 配置了 PostToolUse Hook 在每次文件编辑后自动运行 Prettier 格式化。这保证了所有 Claude 写的代码都自动符合项目格式规范，无需在 CLAUDE.md 中写格式化规则。

实用 Hook 示例

文件编辑后自动格式化：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Claude 也可以帮你写 Hooks：

1
2
写一个 Hook，在每次文件编辑后运行 eslint
写一个 Hook，阻止对 migrations 目录的写入

运行 /hooks 可以交互式配置，或直接编辑 .claude/settings.json。

6.6 创建 Skills 🟡

Skills 是存放在 .claude/skills/ 下的可重用工作流或领域知识。与 CLAUDE.md 的全量常驻不同，Skills 采用两级加载：description 常驻（占上下文预算约 2%，用于 AI 自动发现），完整内容仅在调用时加载。设置 disable-model-invocation: true 的 Skill，description 也不会常驻。

指令 vs 技能：范式转换

注意：当前版本中，自定义 Slash Commands 已并入 Skills 体系（.claude/commands/ 作为兼容方式保留）。下表用于理解两种思维模型的区别，而非两套独立机制。

维度 Slash Commands（指令） Skills（技能）
本质 命令式：”去做这件事” 声明式：”我是一种能力”
发起者 用户主动调用 AI 自发现匹配任务
示例 /gen-test myfile.go “我是一个 Go 代码审查技能”
发现机制 用户记住命令名 AI 扫描技能库自动匹配
核心价值 执行效率 渐进式知识加载

关键洞察：Skills 解决的核心问题是”如何在保持上下文窗口轻量的同时提供大量专业知识”——答案是 AI 按需加载，只在需要时才读取。

SKILL.md 结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---
分析并修复 GitHub Issue: $ARGUMENTS。

1. 使用 `gh issue view` 获取 Issue 详情
2. 理解问题描述
3. 搜索代码库找到相关文件
4. 实现必要的修改
5. 编写并运行测试验证修复
6. 确保代码通过 lint 和类型检查
7. 创建描述性的提交消息
8. 推送并创建 PR

团队实用 Skill/Command 创意

来自 Claude Code 团队的真实用法：

  • /techdebt：每次会话结束时运行，自动发现和清理重复代码
  • 上下文聚合 Skill：同步过去 7 天的 Slack、GDrive、Asana、GitHub 到一个上下文中，快速获取项目全貌
  • 数据分析 Skill：封装 BigQuery / bq CLI 查询能力，团队成员直接在 Claude Code 中跑分析（Boris 说他 6 个月没写过一行 SQL）
  • analytics-engineer 代理：编写 dbt 模型、审查代码、在 dev 环境测试变更

经验法则：如果一个操作你每天做超过一次，就该把它变成 Skill 或 Slash Command。

调用方式：

1
/fix-issue 1234

frontmatter 参数

参数 说明
name 技能名称（调用时用 /name）
description 描述（默认常驻加载到上下文用于 AI 自动发现，保持简短；设 disable-model-invocation: true 时不常驻）
disable-model-invocation 设为 true 表示需要手动调用（有副作用的工作流）
$ARGUMENTS 占位符，接收 /skill-name 后的参数

6.7 创建自定义子代理 🔴

子代理运行在独立的上下文窗口中，有自己的系统提示、工具访问和权限。

为什么需要子代理？

可以把主 Claude 会话想象成 CTO，子代理是各部门总监：

角色 类比 特点
主会话 CTO 全局视野，协调任务
安全子代理 安全总监 专注安全审计，有自己的知识和工具
测试子代理 QA 总监 专注测试覆盖，独立上下文
调试子代理 故障专家 专注根因分析，不受其他任务干扰

子代理的三个核心特质：

特质 解决的问题 机制
独立上下文窗口 上下文污染 独立内存空间，不读/不污染主会话
自定义系统提示 指令冲突 每个子代理有专属人格和领域知识
细粒度工具权限 权限过宽 最小权限原则（审查者只读、DevOps 可执行）

子代理配置文件

在 .claude/agents/ 下创建 Markdown 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 审查代码安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---

你是一名高级安全工程师。审查代码的：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 代码中的密钥或凭证
- 不安全的数据处理

提供具体行号引用和修复建议。

关键配置项

1
2
3
4
5
6
7
8
9
10
11
---
name: db-reader
description: 执行只读数据库查询
tools: Bash                        # 可用工具
model: haiku                       # 控制成本
permissionMode: dontAsk            # 自动拒绝未允许的工具
maxTurns: 10                       # 限制最大轮次
memory: user                       # 启用跨会话持久记忆
background: true                   # 在后台运行
isolation: worktree                # 在独立 worktree 中工作
---

使用子代理的技巧

  • 在任何请求后追加 “use subagents”，让 Claude 投入更多算力并行处理
  • 将独立子任务分配给子代理，保持主会话上下文窗口干净聚焦
  • 可以通过 Hook 将权限请求路由到 Opus 审批（详见 Hooks 文档）
  • 使用 /agents 可交互式管理子代理（创建、编辑、删除），无需手动编辑文件

内置子代理

子代理 模型 用途
Explore Haiku（快速） 只读代码搜索和分析
Plan 继承 Plan Mode 下的代码库研究
general-purpose 继承 复杂多步骤任务
Bash 继承 独立上下文中执行命令

9.2 Headless 模式 🟡

概念：AI 即可编程函数

Headless 模式的本质是把 Claude 变成一个可编程函数：f(输入) → 输出。通过 claude -p，你可以在任何无交互环境中调用 Claude——CI 管道、pre-commit hooks、自动化脚本、定时任务。

官方已将编程接口统一归入 Agent SDK（含 CLI / Python SDK / TypeScript SDK 三种接入方式）。本节聚焦 CLI 的 -p 用法，其语法保持不变。

核心参数速查

参数 作用 示例
-p “prompt” 以 Headless 模式运行 claude -p “解释这个项目”
–output-format 输出格式（text/json/stream-json） –output-format json
–allowedTools 免确认执行的工具列表 –allowedTools “Bash(git *)”
–json-schema 强制 AI 返回你定义的 JSON 结构 –json-schema ‘{“type”:”object”,…}’
–continue 继续当前目录最近一次会话 claude -p “继续分析” –continue
–resume 恢复指定 session –resume “$session_id”
–append-system-prompt 追加系统提示词 –append-system-prompt “只用中文回复”
–verbose 显示调试信息（常配合 stream-json） –output-format stream-json –verbose
-include-partial-messages token 级增量流式事件（需配合 -p + stream-json） -p –output-format stream-json –include-partial-messages