Claude Code 使用指南

项目结构与启动原则

问题场景：在做新需求时，AI 既会参考空间里的 A 项目，也会参考 B 项目，容易出错。

最佳实践：
- ✅ 每个完整项目都有自己的单独文件夹
- ✅ 在终端里进入到具体项目文件夹后启动 CC
- ✅ 确保参考的 codebase 只包含当前项目

模式选择

在 Claude Code 中有 3 种模式，通过 Shift+Tab 可以切换：

1️⃣ 普通模式

2️⃣ Plan 模式

3️⃣ 自动接受编辑模式

推荐工作流：
1. 一开始使用 Plan 模式（最佳）
2. 与 CC 讨论需求，让它不断调整方案和文档建议
3. 确定好后退出 Plan 模式
4. 切换到普通或自动接受模式执行

思考模式

思考层级

思考程度依次增强：

"think" < "think hard" < "think harder" < "ultrathink"

工作原理

通过调节 思考预算（即模型在内部推理阶段可用的资源/token 数），让模型在遇到复杂任务时"多花点时间思考"再出结果：
- ✅ 效果会更好
- ⚠️ 费用也会更多

示例用法：

think harder 分析这段代码的作用

Claude.md 创建

用途

可以记录：
- 🔹 个人习惯（特殊偏好、常用命令、代码风格等）
- 🔹 项目要求（项目背景、注意事项、测试说明等）
- 🔹 一切你想要 Claude 知悉的事项

Claude.md 的两个级别

创建方式

方式 1：使用 /init 命令

/init

会自动参考项目空间 codebase 生成文档。

方式 2：使用 # 添加 Memory

# 这里添加 memory 的实际内容

然后选择添加到用户级还是项目级。

查看 Claude.md

使用 /memory 命令查看记录内容（项目级和用户级都可查看）：

/memory

工作流管理

Spec 工作流

Spec 即 规范规格，用规格文档来驱动 AI 开发。可以理解为这个规格是 AI 要遵守的唯一契约，必须按照 spec 文档执行。

Spec 四部曲

1️⃣ 写需求文档

将模糊想法转化为结构化需求，让 AI 生成一个规范文档。

2️⃣ 写技术文档

把刚生成的规范文档以及你的技术偏好、项目约束发给 AI：
- 框架选择
- 编程语言
- 测试计划
- 其他技术约束

让它生成一个完整的技术文档。

3️⃣ 写 TODO 文档

把上面的两个文档再发给 AI，让它参考这两个文档：
- 将功能需求拆分成具体的、可执行的子任务
- 每个任务都可以独立实现和测试

4️⃣ 实现 (Implementation)

1. 让 AI 把上面的 3 个文档汇总成一个大的 spec.md
2. 发给你确认，有问题就修改
3. 确认无误后发给 AI，让它进行代码编写

Spec vs Claude.md

上下文问题的解决

解决方案：文档记录正好解决了这一问题，可以让 AI 看到完整的上下文背景信息。

个人工作流实践

我的工作流习惯：

1. 准备阶段：先自己写个大致文档需求
2. 讨论阶段：发给 AI 并基于这个文档讨论沟通，让它给建议
3. 确认阶段：让它把讨论过程中确认的信息完整复述，确保双方理解无误
4. 文档化阶段：确认无误后让它更新到之前的文档中
5. 包含 spec 完整环节（技术文档、任务拆分等）
6. 生成最终文档
7. 执行阶段：将最终文档发给它，让它开始执行
8. 测试阶段：测试需求效果

工具实战指南

场景 1：微服务拆分决策（高风险架构决策）

背景：单体应用用户量暴涨，考虑拆微服务，但怕拆坏了。

Step 1：深度思考 (sequential-thinking MCP)

分析我们这个单体应用，是否适合拆微服务？考虑：
- 团队规模（15人）
- 技术栈（Spring Boot 单体）
- QPS（5000）
- 业务复杂度
- 运维能力
- 迁移成本

输出：完整推理链，3 个方案对比（不拆/部分拆/全拆）

Step 2：查技术方案 (context7 MCP)

查 Spring Cloud Alibaba 的服务拆分最佳实践和 Seata 分布式事务方案

输出：官方文档相关章节，4 种事务方案对比

Step 3：记录决策 (memory MCP)

记住：我们的微服务拆分原则：
1. 按业务域拆，不按技术层拆
2. 优先拆读多写少的服务
...

Step 4：制定执行计划 (SubAgent: backend-architect)

基于上述决策，制定详细的微服务拆分计划：
1. 识别服务边界
2. 设计迁移方案（分阶段，可回滚）
...

输出：6 步完整迁移计划

场景 2：生产事故快速响应（争分夺秒）

自动触发 Skill：incident-response

阶段 1：并行排查（3 个 SubAgent 同时工作）

阶段 2：根因定位 (sequential-thinking MCP)

基于上述数据，分析根因：
- SQL 为何突然变慢？
- 为何今天才出问题？
...

输出：根因：订单表数据量突破 1000 万，某个未加索引的查询开始全表扫描

阶段 3：生成止损方案 (Skill 内部逻辑)

输出：3 个方案对比（快速/中期/根治）

阶段 4：执行（一键复制命令）

输出：可执行命令

kubectl scale...
ALTER TABLE...

最后：记录到 memory (memory MCP)

记住：订单表到 1000 万行会有性能问题，需提前分库分表

场景 3：接手遗留项目（快速上手）

背景：接手一个 2 年没人维护的老项目，代码无文档。

Step 1：项目全貌扫描 (SubAgent: Explore)

探索这个项目：
1. 识别技术栈和依赖
2. 找到核心模块和入口
...

输出（10 分钟）：项目架构图、核心模块清单、风险清单

Step 2：关键逻辑理解（并行调用 3 个 SubAgent）

Step 3：技术债评估 (Skill: tech-debt-manager)

输出：
- 高优先级技术债（5 个）
- 建议优先偿还的 3 个

Step 4：依赖升级计划 (Skill: dependency-upgrade-check)

检测到：
- 3 个依赖有已知 CVE 漏洞
- 生成分阶段升级计划

Step 5：知识沉淀 (memory MCP)

把这个项目的关键信息记住：
- 核心模块和职责
- 数据库表和字段含义
...

场景 4：新功能完整开发流程（端到端）

Phase 1：需求分析 (sequential-thinking MCP)

分析积分系统需求：
- 核心功能：赚积分、花积分...
- 风险：超发、作弊、性能

输出：功能拆解、技术方案选型（Redis+MySQL 双写）

Phase 2：查技术方案 (context7 MCP)

查 Redis 分布式锁的最佳实践和积分系统的反作弊方案

输出：Redisson 分布式锁示例、防御手段

Phase 3：数据库设计 (SubAgent: database-optimizer)

设计积分系统的数据库表结构...

输出：完整 DDL、索引设计

Phase 4：开发（写代码）

正常开发过程

Phase 5：Code Review (Skill: smart-code-review)

自动触发：检查并发安全、SQL 性能、异常处理...

Phase 6：提交前检查（斜杠命令：/commit）

自动执行：
- 运行单测
- 检查代码规范
- 生成 commit message

Phase 7：记录 (memory MCP)

记住积分系统的实现：
- 用 Redis 计数器 + MySQL 持久化
...

场景 5：技术栈升级（高风险迁移）

背景：Vue 2 升级到 Vue 3，涉及 200+ 组件。

Step 1：影响面评估 (SubAgent: frontend-developer)

分析这个 Vue 2 项目升级到 Vue 3 的影响：
- 哪些 API 发生了 breaking change
...

输出：
- 需要改动的文件清单（185 个）
- 不兼容的库（3 个）
- 估算工作量：15 人天

Step 2：查迁移指南 (context7 MCP)

查 Vue 3 官方迁移指南和常见坑

输出：官方 migration guide、社区常见问题合集

Step 3：制定迁移计划 (sequential-thinking MCP)

制定分阶段、可回滚的 Vue 3 迁移计划...

输出：5 个阶段的迁移计划，每阶段的回滚方案

Step 4：自动化迁移 (Skill: migration-script)

执行：用 ast-grep 批量替换：this.$xxx → Composition API

Step 5：逐批验证 (Skill: migration-validator)

每迁移一批：
- ✅ 运行单测
- ✅ 运行 E2E 测试
- ✅ 检查 bundle size

Step 6：记录 (memory MCP)

记住 Vue 2→3 迁移的坑：
- Element UI 要换成 Element Plus
...

综合实战

验收标准（做到这 5 点算成功）

• [ ] 说 "查 React 19 最新文档"，能调用 context7 返回结果
• [ ] 说 "分析该不该用微服务"，能用 sequential-thinking 深度推理
• [ ] 说 "记住我们用 PostgreSQL"，下次相关问题能自动调用 memory
• [ ] 说 "准备提交代码"，能自动触发 pre-commit-check (Skill)
• [ ] 输入 /release，能执行完整发布流程（用上面自己定义的 slash command 实现）

最佳实践

1️⃣ 不要贪多，先用三件套起步

MCP（必装 3 件套）：
- memory - 记忆管理
- context7 - 文档查询
- sequential-thinking - 深度推理

Skills（先写 3 个）：
- 代码检查
- 文档同步
- 依赖评估

SubAgents：
- 遇到复杂问题再调度
- 不用提前学

其他的，等这 3 个用顺了再说。

2️⃣ 设计自己团队的工作流剧本

把团队最烦的 3 件事自动化：

1. 代码提交流程（自动检查 + commit）
2. 生产事故响应（并行排查 + 生成方案）
3. 新人入职流程（自动化环境 + 知识导入）

3️⃣ 让知识沉淀，而不只是用一次

用 memory MCP 记录：
- 团队踩过的坑
- 重要的架构决策
- 经常用的配置和规范

相关资源

• Claude Code 配置
• MCP 服务器配置
• Skill 开发指南
• SubAgent 使用手册

claude-code/guide #productivity/ai-tools #development/workflow