这篇文章综合了我们团队的实战经验和网上最有价值的来源（Anthropic 官方、Builder.io、Harper Reed、Shrivu Shankar 等 12+ 个），从 AIDLC（AI Development Lifecycle）的角度做了一个系统性的梳理。从基础操作到多 Agent 协作，希望能帮你少走一些弯路。

核心理念：一切围绕 Context 管理

Claude Code 不是聊天机器人。它是一个自主编程 Agent —— 能读代码、改文件、跑命令、自动调试。但这种自主性有个关键约束：200k token 的 context window 会快速填满，性能随之下降。

几乎所有最佳实践都围绕一件事 —— 管理好 context。

AIDLC：AI 开发生命周期

传统 SDLC 是 需求→设计→编码→测试→部署。AI 编程时代，这个流程演化为 AIDLC：

关键理念：Planning before implementation is non-negotiable —— 规划先于实现，不可跳过。

基础操作：每天都在用的功能

/clear — 最重要的操作

/clear    # 每开始新任务就清空 context

不要等 context 满了才清理。经验法则：在 60k tokens 或 30% context 时就该 /clear 了。

关于 /compact，Shrivu Shankar 的评价是：”自动压缩是不透明的、容易出错的、没有优化好的。” 后面会介绍更好的替代方案（Document & Clear 模式）。

Plan Mode — 90% 时间该用

用 Shift+Tab 在模式间切换：Normal → Auto-accept → Plan。在 Plan Mode 下 Claude 只能读取和探索，不会编辑任何文件。

@ 提及 — 精准添加 context

@src/api/auth.ts     # 添加文件到 context
@src/components/     # 列出目录内容
@package.json        # 引用配置文件

思考深度控制

在 prompt 中加入关键词控制 Claude 的思考深度：

消息队列 — 批量提交任务

直接连续输入多条指令，Claude 会智能地按顺序处理。不需要等一个完成再发下一个。队列好一堆任务去忙别的，回来就看到一堆活干完了。

Background Tasks — Ctrl+B 后台化

当 Claude 正在执行长时间命令时，按 Ctrl+B 将其后台化，然后继续和 Claude 对话。这对测试套件、构建工具、dev server 特别有用 —— 不用干等。

Esc Esc — 回退检查点

搞砸了？连按两次 Esc 回到上一个检查点。可以选择只回退对话、只回退代码、或两者都回退。大胆尝试，随时回滚。

会话管理

claude --continue    # 继续上次对话（-c）
claude --resume      # 从历史会话列表中选择（-r）

CLAUDE.md — 项目记忆系统

这是 Claude Code 最重要的文件 —— 所有 12 个来源都强调了这一点。不配置 CLAUDE.md 等于让 Claude Code 没有项目记忆。

运行 /init 自动分析代码库，生成初始 CLAUDE.md。然后根据实际使用不断迭代。

该写什么，不该写什么

经验法则：对每一行问 “删掉这行会不会导致 Claude 犯错？” 如果不会，就删掉。控制在 200 行以内 —— 太长反而会被忽略。

CLAUDE.md 的常见反模式

Shrivu Shankar 在管理企业级 monorepo（13KB 的 CLAUDE.md）中总结的经验：

• 不要 @-引用大文件 —— 每次都嵌入整个文件，浪费 context。只给路径和条件：”遇到 FooBarError 时，参见 path/to/docs.md”
• 不要只说”永远不要” —— Agent 需要用时会卡住。要提供替代方案：”不要用 –foo-bar，改用 –baz”
• 不要写成百科全书 —— 只记录 Claude 做错的事情
• 把 CLAUDE.md 当作 forcing function —— 如果 CLI 命令很复杂，写个简单的 bash wrapper 而不是长段文档

层级结构

~/.claude/CLAUDE.md           # 全局个人偏好
项目根/CLAUDE.md              # 项目级规则（提交到 git）
项目根/src/api/CLAUDE.md      # 子目录级特定规则
项目根/.claude/settings.json  # 工具和权限配置

AIDLC 全流程实战

Phase 1: SPEC — 需求规格

Harper Reed 的工作流（经过数百人验证）：

1. 用 GPT-4o 或其他模型聊天打磨想法
2. 用最好的推理模型（o1-pro / o3 / Claude Opus）生成 spec.md
3. 用推理模型生成 prompt_plan.md —— 用 LLM 生成 prompt 是一个效果极好的技巧
4. 把两个文件放到项目根目录

Phase 2: PLAN — 架构规划

Anthropic 官方推荐的四步流程：

Step 1: EXPLORE — 进入 Plan Mode，让 Claude 只读取不修改

读 /src/auth 理解我们怎么处理 session 和登录
也看看我们怎么管理环境变量的

Step 2: PLAN — 仍然在 Plan Mode，让 Claude 制定方案

我想加 Google OAuth。哪些文件需要改？
session 流程是什么？做个计划。
ultrathink - 给我 2-3 个备选方案，带优缺点分析

Step 3: IMPLEMENT — 切回 Normal Mode 执行

Step 4: COMMIT — 让 Claude 用描述性的 commit message 提交，开 PR

什么时候跳过 Plan？ 当你能一句话描述 diff 的时候。

Phase 3: CODE — Harper Reed 的自动化模式

1. 打开 @prompt_plan.md，找到所有未完成的 prompt
2. 对每个未完成的 prompt：
   - 确认它真的没完成（不确定就问）
   - 按描述实现
   - 确保测试通过，程序能构建/运行
   - 提交更改，写清晰的 commit message
   - 更新 @prompt_plan.md 标记为已完成
3. 每完成一个 prompt 后暂停，等待用户审查
4. 根据用户指示继续下一个

Phase 4: VERIFY — TDD 是 AI 最爱的工作方式

和人类程序员不同，AI 的最佳工作方式是先写测试再实现。先写测试和 mock → 下一个 prompt 把 mock 变成真实实现。TDD 是对抗幻觉和 LLM 跑偏最有效的方法。

Hooks — 自动化质量门禁

{
  "hooks": [
    {
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "prettier --write \"$CLAUDE_FILE_PATHS\""
      }]
    }
  ]
}

关键经验：在 commit 时阻断（测试没过不让提交），而不是在 write 时阻断 —— 打断 Agent 的执行计划会让它”困惑”。让它先完成工作，在最终提交时检查。

多层 Code Review

• Layer 1: Claude 自审 —— 用 subagent 或新 context 审查自己的代码
• Layer 2: 人工审查 —— 验证行为和测试覆盖率
• Layer 3: 多 Claude 实例交叉审查 —— 一个写，另一个审

Phase 5: SHIP — Git 集成

直接让 Claude 处理 Git 和 GitHub CLI 任务。推荐用 draft PR 模式：让 Claude 创建 draft PR，审查完再标记 ready for review。风险低，流程清晰。

🌟 Skills — 可能比 MCP 更重要的划时代功能

如果这篇文章你只记住一件事，那就是 Skills。Simon Willison（SQLite 创始人、Django 联合创始人）直言：“Claude Skills are awesome, maybe a bigger deal than MCP.”

为什么这么说？因为 Skills 从根本上改变了 Claude Code 的定位 —— 它不再只是一个编码工具，而是一个通用 Agent 平台。

什么是 Skills

Skills 是一种极其简单但极其强大的机制：一个包含 SKILL.md 文件的文件夹，里面可以有指令、脚本和资源文件。Claude 在会话开始时只加载每个 Skill 的名称和描述（几十个 token），只在需要时才读取完整内容。

my-skill/
├── SKILL.md           # 主指令文件（必须）
├── template.md        # Claude 填写的模板
├── examples/
│   └── sample.md      # 示例输出
└── scripts/
    └── validate.sh    # Claude 可执行的脚本

Anthropic 把这个设计称为 Progressive Disclosure（渐进式展开）：

• 第一层：名称和描述 → 几十个 token，预加载到系统提示
• 第二层：SKILL.md 完整内容 → 仅在 Claude 判断相关时加载
• 第三层：额外文件（reference.md、scripts/）→ 仅在特定场景需要时加载

这解决了 MCP 最大的问题 —— token 浪费。GitHub 的 MCP server 光是存在就要消耗数万 token。而 Skills 只在需要时才占用 context。

为什么说是划时代的

关键洞察：

• Skills 让人人都能”教”AI —— 不需要写代码，不需要搭服务器，只需要写 Markdown 描述你的专业知识
• Skills 遵循 Agent Skills 开放标准 —— 跨平台可移植，不只是 Claude 专属
• Skills 可以自我演化 —— 让 Claude 把成功的做法和常见错误捕获到 Skill 中，实现 Agent 的自我改进
• Skills 是 Claude 文件创建能力的底层实现 —— Claude.ai 上的 .pdf、.docx、.xlsx、.pptx 生成能力，全部是用 Skills 实现的

三类 Skills

1. 内置 Skills（Bundled Skills）

Claude Code 自带，每个会话都可用：

• /simplify — 审查最近修改的文件，找代码复用/质量/效率问题，自动修复。内部派生三个并行审查 agent
• /batch <instruction> — 大规模并行变更。分析代码库 → 拆解为 5-30 个独立工作单元 → 每个单元一个 agent 在独立 worktree 中执行 → 开 PR
• /debug — 读取会话 debug 日志，排查问题

2. Anthropic 官方 Skills + 社区 Skills

通过 Plugin Marketplace 安装：

# 添加 Anthropic 官方 Skills 仓库
/plugin marketplace add anthropics/skills

# 浏览并安装
/plugin
→ Browse and install plugins
→ 选择 document-skills 或 example-skills
→ Install now

# 或直接安装
/plugin install document-skills@anthropic-agent-skills

官方高价值 Skills 举例：

3. 自定义 Skills — 把你的专业知识封装给 AI

这是 Skills 最大的价值所在。Anthropic 官方建议：”构建 Skill 就像给新员工写入职指南”。

---
name: security-review
description: Automated security scan findings remediation. 
  Use when fixing security scan results or SAST/DAST findings.
---

When processing security scan findings:

1. Read the scan report file
2. For each finding:
   - Understand the vulnerability type and severity
   - Locate the affected code
   - Apply the appropriate fix pattern
   - Verify the fix doesn't break functionality
3. Re-run the scanner to confirm fixes
4. Generate a summary report

## Fix patterns by category
### SQL Injection → Use parameterized queries
### XSS → Sanitize output with appropriate encoding
### Hardcoded Secrets → Move to environment variables
...

这个例子来自真实使用：安全扫描工具吐出数百条 findings，手动修复极其枯燥。封装成 Skill 后，整个流程自动化 —— 以前要几天的工作大幅缩短。

Anthropic 的 Skill 开发最佳实践：

1. 从评估开始 — 先跑 Agent 看它在哪些任务上挣扎，然后针对性地构建 Skill
2. 结构化扩展 — 当 SKILL.md 变得太大时，拆分成独立文件并引用。代码既是可执行工具也是文档
3. 从 Claude 的视角思考 — 特别注意 name 和 description，Claude 用它们决定是否触发 Skill
4. 和 Claude 一起迭代 — 让 Claude 把成功做法和常见错误捕获到 Skill 中

Skills 存储位置与优先级

优先级：企业 > 个人 > 项目。Plugin Skills 使用命名空间（plugin-name:skill-name），不会冲突。

Superpowers 框架 — Skills 生态的先驱

Superpowers 是 Jesse Vincent 构建的 Skills 框架，在 Anthropic 官方发布 Skills 之前就已经存在。它现在已经拥抱官方 Skills 系统，提供：

• 结构化开发工作流 — 从头脑风暴到细化设计 → 创建详细计划 → 通过 subagents 执行
• 强制 TDD 循环 — RED-GREEN-REFACTOR
• 系统化调试和 code review 工作流
• Git worktree 隔离
• 跨平台兼容 — 也支持 Gemini CLI 和 Codex

Skills vs MCP：什么时候用哪个

高级效率技巧

Context 管理进阶：Document & Clear 模式

复杂任务的黄金模式 —— 比 /compact 好得多：

1. 让 Claude 把当前计划和进度写到 .md 文件：

把剩余计划写入 HANDOFF.md。解释你尝试了什么、
什么有效、什么无效，让下一个有新鲜 context 的 
agent 只需要加载这个文件就能继续。

2. /clear 清空 context
3. 新对话只给文件路径：@HANDOFF.md

三文件模式（大型任务）

~/dev/active/[task-name]/
├── [task-name]-plan.md      # 已确认的计划
├── [task-name]-context.md   # 关键文件、决策记录
└── [task-name]-tasks.md     # 工作检查清单

Git Worktrees — 并行开发的利器

运行 3-4 个 Claude 会话并行处理不同 feature，感觉像有了一个小开发团队：

# Terminal 1
claude --worktree feature-auth

# Terminal 2
claude --worktree bugfix-123

# Terminal 3
claude --worktree refactor-logging

每个会话有自己的目录和分支。变更物理上不可能冲突。完成后 Claude 会问你保留还是丢弃。

MCP Servers — 值得花时间配置

如果经常用外部服务，通过 MCP 连接可以省掉大量上下文切换：

• GitHub/GitLab MCP —— 浏览 PR、读 issue、检查 CI pipeline、跨 repo 搜索、创建 PR
• Slack / Figma / Atlassian MCP —— 直接在 Claude Code 内操作

浏览器集成与 Headless 模式

# 浏览器集成
claude --chrome

# Headless 模式 — 用于脚本和 CI/CD
claude -p "修复 lint 错误"
git diff | claude -p "解释这些变更"
cat error.log | claude -p "诊断这个错误"

多 Agent 协作

Claude 可以派生并行子 Agent，每个有独立的 200k context window。

速查表

快捷键

常用命令

CLI 参数

反模式避坑指南

参考来源

• Best Practices for Claude Code — Anthropic 官方文档
• How I use Claude Code — Steve Sewell, Builder.io
• Basic Claude Code — Harper Reed
• How I Use Every Claude Code Feature — Shrivu Shankar
• Advent of Claude (31 Tips) — Ado, Anthropic DevRel
• 32 Claude Code Tips — YK
• Claude Code Best Practices 综合分析 — 12 源综合
• Superpowers — 社区 Skills 框架