面向读者：日常写业务的开发者、负责工程效能/平台的技术负责人、对 Agent 工作流感兴趣的研究与实践者
目标：读完即可把 Claude Code 变成“懂你项目、能跑流程、可团队共享”的工程助手，而不只是“修报错/翻译代码”的对话模型。

---

引言：为什么你用 Claude Code “还行，但没到封神”？

不少人第一次用 Claude Code 的体验是：它能看懂仓库、能改多文件、还能跑命令，比传统 IDE 补全更像“同事”。Claude Code 的定位也明确：它是一个agentic coding tool，能读代码库、编辑文件、运行命令，并与开发工具集成。(Claude)

但“还行”和“封神”的差距，往往不在模型，而在工程化落地：

• 你每次开新会话都要重新解释：项目结构、规范、常用命令、上线流程、坑点。
• 团队成员各写各的，Claude 给出的建议也时而统一、时而分裂。
• 最耗时的不是写代码，是重复流程：跑测试、lint、生成变更说明、PR 自检、部署验证……

解决这些问题的关键，不是“更会提问”，而是把 Claude Code 变成项目工作流系统：让它在会话开始就带着正确上下文；让重复流程沉淀成可调用的技能；让复杂任务拆解成可并行的子代理；让团队把这些能力打包共享。

本文会按“工程化落地”的顺序，给出一套可直接复用的做法与模板。

---

1. 先把概念对齐：Claude Code 的“扩展层”是什么？

Claude Code 本体已经能做很多：改代码、跑命令、协助 Git、在 CI 里做自动化等。(Claude)
但真正让它“像开发环境”而不是“聊天框”的，是官方文档称为 extension layer 的那一层：你可以用它来定制知识、连接外部系统、自动化流程，并打包分发。(Claude)

从“常驻上下文”到“按需能力”再到“确定性自动化”，可以这样理解：

• CLAUDE.md：每次会话都加载的“项目宪法/工程规则”
• Skills：按需加载的“可复用知识 + 可调用工作流”（也承载 slash commands）(Claude)
• Subagents / Agent teams：把任务并行化、隔离上下文、引入专用角色(Claude)
• Hooks：在特定事件前后运行脚本，让自动化“确定且可审计”(Claude)
• MCP（Model Context Protocol）：把 Claude 接到外部数据源/系统（Drive、Jira、Slack、内部工具）(Claude)
• Plugins & marketplace：把以上能力打包分发，团队一键安装(Claude)

你会发现，这一套结构和“传统工程平台”的思路一致：规范（policy）→ 流程（workflow）→ 角色（agent）→ 自动化（automation）→ 集成（integration）→ 分发（distribution）。

---

2. 第一性原则：CLAUDE.md 不是 README，它是“会话入口的系统提示”

2.1 CLAUDE.md 的作用：让 Claude 每次开局就“站在正确的工程地基上”

官方定义非常直白：CLAUDE.md 是你放在项目里的 markdown 文件，Claude Code 会在每个 session 开始时读取它。(Claude)

它最适合放三类内容：

1. Claude 无法从代码推断出来的规则：比如团队约定、分支规范、部署策略、必须跑哪些检查。(Claude)
2. 风格与偏好：例如“只用 ES modules”“prefer pnpm”“接口返回统一 envelope”。(Claude)
3. 项目坑点/非显然约束：例如某模块测试需本地 Redis、某脚本必须在特定目录运行等。

一个很好用的判断标准：**“删掉这一行，会不会让 Claude 更容易犯错？”**如果不会，就删。官方也强调 CLAUDE.md 要保持简短，否则 Claude 会忽略你的真正指令。(Claude)

2.2 /init：用自动生成当起点，但一定要人工“去噪”

官方 best practices 推荐：运行 /init 来基于项目结构生成 starter CLAUDE.md，然后逐步迭代。(Claude)
注意：生成只是起点，你要对它进行“工程化裁剪”，把冗余描述删掉，把最关键的规则写得可执行。

2.3 CLAUDE.md 的加载与组织：可分层、可导入、可私有化

官方给了几个非常工程化的能力：

• CLAUDE.md 可放在多处：~/.claude/CLAUDE.md（全局）、项目根目录、父目录（适合 monorepo），子目录则按需加载。(Claude)
• 可用 @path/to/import 引入其它文件，把“常驻规则”与“详细文档”分离。(Claude)
• 还有 CLAUDE.local.md 这种不进仓库的私有偏好方案（适合个人习惯或本地环境差异）。(Claude)

2.4 一个可直接复用的 CLAUDE.md 模板（团队版）

把下面模板放在项目根目录 CLAUDE.md，按需改即可：

# Project: <一句话说明项目是做什么的>

# 1) Non-negotiables (必须遵守)
- Package manager: use pnpm, DO NOT use npm/yarn.
- Always run: pnpm test (or targeted tests) before finishing a change.
- No breaking API changes without updating docs + migration notes.

# 2) Code style (与默认不同的部分)
- TypeScript: prefer type over interface unless extending.
- React: functional components only; hooks start with `use`.
- Error handling: never swallow errors; use structured logs.

# 3) Workflow (可执行的命令/流程)
- Install: pnpm i
- Dev: pnpm dev
- Lint: pnpm lint
- Typecheck: pnpm typecheck
- Test: pnpm test --filter <module>

# 4) Repo etiquette
- Branch naming: feat/<ticket>-<short>
- Commit message: conventional commits
- PR checklist: tests, lint, changelog, risk notes

# 5) Project gotchas (最值钱的部分)
- API tests require local Redis on :6379
- When editing db migrations, also update schema snapshot
- The auth module has legacy code; refactor carefully

# 6) References
- See @README.md for high-level overview
- See @docs/architecture.md for architecture decisions

关键点：**不要写“教程”，要写“规则 + 命令 + 坑点”。**教程放在 docs 里，用 @import 引用即可。

---

3. 第二步：用 Skills 把重复劳动“产品化”，并沉淀成团队能力

3.1 Skills 是什么：可自动触发、也可 /slash-command 调用

官方定义：Skills 用一个 SKILL.md 来扩展 Claude 的能力；Claude 可以在合适时自动使用，或你用 /skill-name 直接调用。(Claude)

更关键的一点：自定义 slash commands 已经并入 skills——.claude/commands/review.md 和 .claude/skills/review/SKILL.md 都能生成 /review，并且旧的 .claude/commands/ 仍可工作。(Claude)
这意味着你可以把历史上分散的“命令脚本”逐步迁移到 skills，享受更强的配置能力（支持文件、frontmatter、权限控制等）。

3.2 Skills 放哪里：个人复用 vs 项目内共享

文档里给出典型路径：个人技能可放在 ~/.claude/skills/<skill>/SKILL.md，跨项目可用。(Claude)
而团队共享则更常见的做法是放在仓库内 .claude/skills/ 并提交版本控制（你可以结合 CLAUDE.md 提示团队统一安装/启用）。

3.3 SKILL.md 的结构：YAML frontmatter + Markdown 指令

官方明确：每个 skill 都需要 SKILL.md，包含两部分：YAML frontmatter（告诉 Claude 何时/如何用）+ markdown instructions（执行时要遵循的步骤）。其中 name 会变成 /slash-command，description 决定自动触发。(Claude)

下面给一个“团队 PR 审查清单”的技能示例，能把“重复、琐碎、但很关键”的工作标准化。

3.4 示例：/review-pr —— 把 PR 自检变成一键流程

目录结构：

.claude/
  skills/
    review-pr/
      SKILL.md
      checklist.md

SKILL.md：

---
name: review-pr
description: 对当前变更进行PR自检（测试、lint、风险点、API变更、文档）。当用户说“帮我review”“PR检查”“上线前检查”时使用。
---

# PR Review Skill

你是资深Reviewer。请对当前仓库的变更做一次可执行的PR自检，并输出“可直接贴到PR描述里”的结果。

# Step 0: 获取变更范围
- 读取 git diff / changed files 列表
- 总结本次变更的目的与影响面（模块、接口、数据结构）

# Step 1: 静态检查
- 检查是否有明显的安全问题（硬编码密钥、注入风险、越权）
- 检查是否违反项目规范（见 CLAUDE.md）

# Step 2: 建议的验证命令（按项目实际填写）
- 优先给出最小验证集（不要一上来跑全量）
- 若需要全量，明确原因

# Step 3: 风险评估与回滚
- 风险点列表（按严重度排序）
- 回滚策略（如 feature flag、db migration 风险等）

# Step 4: 输出格式
- 用以下标题输出：
  - Summary
  - Tests
  - Risks
  - Checklist
- Checklist 内容引用 @checklist.md

checklist.md：

- [ ] 关键路径有测试覆盖或手工验证说明
- [ ] 变更没有引入明显性能回退
- [ ] 文档/注释已更新（如有必要）
- [ ] API变更说明与兼容性评估已写清
- [ ] 迁移脚本可回滚/可重跑

为什么这个 skill 值得做？
因为它把“经验型活动”变成“流程型产物”：新人不会漏项，老手少耗脑，PR 质量更稳定。这类技能往往是团队效能提升最直接的一步。

---

4. 第三步：Subagents 把复杂任务并行化，让上下文更干净、结果更可靠

当你让 Claude “阅读大量文件 + 多轮推理 + 产出总结”时，主会话的上下文会被迅速塞满。解决办法之一是 Subagent：让它在隔离上下文中跑自己的 loop，最后只把摘要带回来。官方也把它列为 extension layer 的关键组成：Subagents 在隔离上下文中执行并返回总结。(Claude)

4.1 什么时候该用 Subagent？

典型场景：

• 安全审查：需要扫描大量文件，但你只想要最终风险点清单
• 性能排查：需要跨模块跟踪调用链，但主会话只要结论与修复建议
• 文档生成：需要读取多处实现细节，但最终只输出结构化文档

4.2 Subagent 文件长什么样？

官方示例显示 Subagent 文件同样是 YAML frontmatter + prompt，并且如果你手工添加，需要重启 session 或用 /agents 立即加载。(Claude)

你可以做一个 “security-reviewer” 子代理：

---
name: security-reviewer
description: 扫描当前变更的安全风险并给出修复建议
tools: Read, Glob, Grep
model: sonnet
---

你是应用安全工程师。请基于当前仓库与变更，输出：
1) 风险点（按严重度排序）
2) 证据（文件路径/片段摘要）
3) 修复建议（可落地）
4) 若无法确定，给出需要补充的信息

工程化提示：把“角色定义 + 输出结构”写清楚，效果会比“帮我看看有没有安全问题”稳定得多。

---

5. 第四步：Hooks 与 MCP —— 让自动化更确定，让集成更深入

5.1 Hooks：让“必须发生”的动作变成确定性脚本

Hooks 的价值在于：它不是 LLM 生成的建议，而是在事件前后运行的脚本，更可预测、可审计。官方文档也提示：如果你要在每次会话启动注入上下文，用 CLAUDE.md；而 hooks 更适合事件型自动化。(Claude)

你可以用 hooks 做的事情包括（举例）：

• 每次 Claude 编辑文件后自动格式化（prettier/black）
• 每次准备 commit 前自动跑 lint / typecheck
• 每次生成补丁后自动运行关键用例

5.2 MCP：把 Claude 接到你的“真实世界数据与系统”

Claude Code 支持 MCP（Model Context Protocol），官方描述它是连接外部数据源的开放标准：可以读 Drive 文档、更新 Jira、拉 Slack 数据，或接入你自己的工具链。(Claude)

如果你在做平台/效能工程，MCP 往往意味着更高的上限：把“编码助手”升级为“工程协作中枢”。

---

6. 最后一公里：Plugins 与团队分发——把能力打包，让“好用”可复制

当你在一个项目里把 CLAUDE.md、skills、subagents、hooks、MCP 配好后，下一步一定是：怎么让团队也一键拥有？
官方在 extension layer 中明确指出：Plugins 与 marketplace 用于打包与分发这些能力。(Claude)

工程上建议你按“层级”打包：

• 最低层：CLAUDE.md（项目规范）
• 中间层：skills（流程与知识）
• 高阶层：subagents（并行角色）
• 自动化层：hooks（确定性动作）
• 集成层：MCP 配置（连接外部系统）

做成 “team-toolkit” 之后，新人入职或新项目启动就不再是“口口相传”，而是“安装即得”。

---

7. 现实问题：成本、时效与实践策略

7.1 成本与计划：别把“工具费”当成隐藏成本

Claude Code 通常需要 Claude 订阅或 Anthropic Console 账户（取决于使用环境与提供商）。(Claude)
至于具体订阅与价格档位，建议以 Claude 官方 pricing 为准，并结合团队使用量评估。(Claude)

7.2 时效性：把规则当代码维护

CLAUDE.md、skills、subagents 本质上都是“可执行知识”，它们会随着架构演进而过期。最好的做法是：

• 把它们当成代码一样 PR、review、版本化
• 观察 Claude 行为：如果它开始反复问已写明的问题，说明规则不清或被淹没
• 定期“瘦身”：删掉无效规则，保留最具约束力的部分（官方也强调 CLAUDE.md 过长会适得其反）。(Claude)

7.3 推荐落地路线图（从 0 到 1 再到规模化）

1. 先落 CLAUDE.md：把常用命令、硬约束、坑点写进去（1 天内完成）
2. 做 2~3 个最有 ROI 的 Skills：比如 /review-pr、/deploy-staging、/write-tests（一周内可见收益）
3. 引入 Subagents：安全/性能/文档三类最常见（把复杂任务并行化）
4. 加 Hooks：把“必须发生”的检查变成确定性自动化
5. 上 MCP：当你需要接 Jira/Slack/内部平台，或者要做“AI 工程中枢”时再上
6. 插件化分发：团队规模化的关键一步

---

结语：真正的“封神”来自工程化，而不是更会聊天

Claude Code 的差异化在于它不仅能“生成代码”，还能读仓库、改多文件、跑命令、接入工具链，并通过扩展层把能力沉淀为流程与产品。(Claude)

如果你只把它当“更聪明的 Copilot”，你得到的是“更快写代码”；
如果你把它当“工作流系统”，你得到的是“更快交付 + 更稳质量 + 更可复制的工程能力”。