在 DDAD 里，CLAUDE.md 负责协议，Commands 负责复用，Hooks 负责约束

今天是一个超长文，关于我最近对于文档驱动AI开发的思考，无论是vibecoding 还是agentic coding 大家目所能及的文章内容都是讲OPC，讲如何变成一个超级个体，很少人讲在10甚至是100+人的团队如何使用AI进行团队协作编程，今天这一篇从Claude Code项目内的第一个文档来看如何在团队里更好的使用AI CODING。好了废话说完了，下面是正文开始😊

很多团队开始使用 Claude Code 之后，第一反应都是先写一个 CLAUDE.md。

这一步没错。

错的是，后面很多人会不自觉地把它写成一个“万能文件”——既想让它承担提示词功能，又想让它装下全部项目背景，还想顺手把团队规范、操作流程、风险提醒、模块说明、排查经验统统塞进去。

结果就是：

文件越来越长

重点越来越散

AI 不一定更稳定

团队成员也越来越难维护

所以问题并不是“要不要写 CLAUDE.md”，而是：

在团队级 Agentic 开发里，CLAUDE.md 到底该承担什么，不该承担什么？

在 DDAD（Document-Driven AI Development，文档驱动 AI 开发）里，这个问题的答案其实很明确：

CLAUDE.md 负责协议层。

Commands / Skills 负责复用层。

Hooks 负责约束层。

Docs 负责事实层。

如果这一层分不清，团队最后得到的不是一个稳定的 AI 协作系统，而只是一个不断膨胀、越来越难维护的大 prompt。

一、为什么很多团队会把 CLAUDE.md 用错？

因为大多数人一开始接触 Claude Code，还是沿着“提示词工程”的惯性在思考。

他们会觉得：

AI 理解偏了，那就多补一点说明

AI 忘了规范，那就把规范加进去

AI 动错了目录，那就再加几条提醒

AI 这次没按流程来，那就补一段工作步骤

这样做短期看似有效，但长期一定会出问题。

因为你解决问题的方式，始终是：

往一个文件里继续加。

而团队协作真正需要的，从来不是一个越来越长的入口文件，而是一套清晰的知识分层。

这就是 DDAD 和普通 prompt engineering 的根本区别。

Prompt engineering 想解决的是：

这次怎么让模型表现更好？

DDAD 想解决的是：

这个团队怎样为 AI 构建一个长期稳定的协作环境？

这两个问题不是一个层级。

所以把 CLAUDE.md 当成一个“大一统入口”，本质上是把团队协作问题，降维成了单次提示问题。

这就是误区的根源。

二、在 DDAD 里，CLAUDE.md 应该是什么？

如果用一句话定义，我会这样说：

CLAUDE.md 不是 prompt file，而是仓库级协作协议入口。

也就是说，它不是用来装下一切的，而是用来告诉 Claude Code：

这个项目是什么

这个仓库怎么走

默认怎么协作

哪些流程要调用什么 command

哪些地方不能乱动

真正的知识和事实在哪里

这意味着，CLAUDE.md 应该保留的是高密度、低歧义、长期稳定的信息，而不是所有历史背景和所有细节说明。

按你这个 DDAD 口径，我认为一个团队项目中的 CLAUDE.md，至少应该包含下面这些内容。

1. 项目目的（Purpose）

Claude 进入仓库时，首先要知道的是：

这个系统是干什么的

解决什么问题

主要服务谁

哪些目标比局部优化更优先

因为一旦没有目的层，AI 很容易变成“局部最优主义者”：

代码也许改对了，但方向不一定对。

2. 仓库地图（Repo Map）

AI 不怕代码多，怕的是没有地图。

这里应该让它快速知道：

核心业务目录在哪

基础设施目录在哪

测试目录在哪

配置入口在哪

构建部署入口在哪

哪些目录是高风险区域

团队成员和 AI 一样，都需要这张地图。

3. 关键文档入口（Key Doc Entrypoints）

CLAUDE.md 不应该重复所有文档内容，但必须告诉 AI：

架构文档在哪

业务规则在哪

ADR 在哪

runbook 在哪

API 约定在哪

spec 模板在哪

这一步非常关键。

因为 DDAD 不是“把所有东西都喂给 AI”，而是让 AI 明确知道：

真相存放在哪里。

4. 上下游关联项目的路径和概要

这是很多文章不会写，但你这个方法论特别应该写进去的一层。

很多团队问题不是出在单仓库内部，而是出在：

它依赖哪个上游项目

它会影响哪个下游系统

本地有哪些 sibling repo / monorepo package / gateway service / shared sdk

哪些仓库之间有接口约束、数据契约或发布顺序

如果 AI 不知道这些上下游关系，它就只能在当前目录内做局部推理。

而团队级 Agentic 开发要的是：

它知道自己改的不是一块孤立代码，而是一个系统中的节点。

所以 CLAUDE.md 里应该有一节专门写：

相关仓库路径

每个关联项目的用途

调用方向

变更影响面

需要联动阅读的文档入口

5. 全局协作协议（Global Collaboration Protocol）

这部分定义的不是项目知识，而是协作原则。

例如：

默认先读文档，再动代码

重大改动先出方案

高风险模块最小改动优先

不擅自扩大任务边界

不在未确认时修改关键目录

这部分决定的是 Claude Code 在这个仓库里的“行为风格”。

6. 默认流程（Default Workflow）

也就是：如果没有额外说明，Claude 应该怎么推进工作。

比如：

读 CLAUDE.md

读相关 docs/spec

总结上下文和风险

输出计划

再实施

改完运行检查

输出变更说明

这部分是工作节奏，而不是知识说明。

7. Command 路由（Workflow Routing）

这是你刚才提得很准的一点，也是这版文章最重要的改动。

CLAUDE.md 不应该承担所有具体流程本身，而应该规定：

什么场景调用哪个 command

什么类型的任务必须先走哪个 skill

什么动作需要执行哪个检查流程

例如：

新功能开发先走 /write-spec

重构前先走 /impact-check

提交前必须执行 /review-pr

生产故障排查优先走 /incident-debug

这就是“协议层”该做的事：

规定路由，不承载所有执行细节。

8. 边界与禁区（Boundaries & No-go Zones）

最后是明确边界。

例如：

哪些目录不可直接改

哪些模块必须人工确认

哪些变更必须附带测试

哪些操作必须经过 hooks 或审查

这部分必须明确，不要写成模糊建议。

因为模糊建议在团队协作里等于没有约束。

三、既然 CLAUDE.md 要保留这些内容，那什么不该继续塞进去？

答案也很简单：

凡是会重复执行、可模板化、可复用的规范，不该继续堆在 CLAUDE.md 里。

这些东西更适合做成 commands / skills。

为什么？

因为这类内容的本质，不是“仓库记忆”，而是“执行流程”。

例如这些东西：

PR review 流程

重构流程

发布流程

调试流程

spec 编写流程

风险评估流程

模块接手流程

如果每次都靠 CLAUDE.md 中的一大段说明去重复触发，那它很快就会变成一个低效的大总表。

所以在 DDAD 里，我们更应该把它们做成：

.claude/commands/

.claude/skills/

也就是说：

协议层规范放在 CLAUDE.md。

执行层规范做成 Commands / Skills。

这就是团队知识复用的正确分层。

四、为什么 Commands / Skills 更适合承载团队规范复用？

因为 command / skill 天生具备几个 CLAUDE.md 不擅长的特点。

1. 它可显式调用

AI 不需要从一大段背景里猜“现在该走哪套流程”，而是可以直接进入特定模式。

比如：

/write-spec

/review-pr

/refactor-module

/release-check

这让协作更像“进入某种工作模式”，而不是“再读一遍总说明文件”。

2. 它适合复用

一套 command 可以：

跨会话复用

跨成员复用

跨项目复用

团队共享维护

这才叫组织级能力，而不是个人 prompt 收藏夹。

3. 它更容易演进

流程经常会变。

如果所有流程都写死在 CLAUDE.md 里，每次修改都要碰全局入口；

但如果拆成 commands / skills，就可以局部演进、版本化维护。

4. 它更符合 DDAD 的“知识即代码”

在 DDAD 里，知识不是说明性的附件，而是可执行的团队记忆。

而 command / skill 正是这种“可执行知识”的最佳承载体之一。

所以真正的问题不是：

团队知识规范要不要写？

而是：

哪些该留在协议层，哪些该沉淀成可执行复用单元？

五、Hooks 为什么必须单独分层？

还有一层特别重要，不能混进 CLAUDE.md，也不能只交给 commands，那就是 Hooks。

因为有些规则不是“希望 AI 记住”，而是“必须保证发生”。

比如：

编辑后自动跑 formatter

改核心模块自动跑测试

修改高风险目录自动拦截

没通过检查禁止继续提交

这些事情如果只写在文档里，本质上仍然是软约束。

而软约束在高风险场景下是不够的。

所以在 DDAD 里：

文档负责表达

command 负责执行流程

hook 负责确定性约束

你可以把它理解成三层：

CLAUDE.md：告诉 AI 规则是什么

command / skill：告诉 AI 这类任务怎么做

hook：确保关键规则一定被执行

这才是完整系统，而不是单文件信仰。

六、Docs 的作用不是“补充阅读”，而是事实来源

最后再说一层容易被忽略的：docs/。

在很多团队里，docs 常常是最容易被边缘化的部分。

但在 DDAD 里，它恰恰是最重要的“事实层”。

docs/ 的作用不是为了让人“有空再看”，而是为了让 Claude Code 和团队成员都知道：

真实架构长什么样

历史决策是什么

业务规则怎么定义

运维流程怎么走

某些模块为什么不能那样改

所以 docs 不是补充材料，而是：

协作中的事实来源。

也正因为如此，CLAUDE.md 里才必须保留关键文档入口，而不是把所有文档内容复制粘贴进去。

入口层负责导航，事实层负责支撑。

七、DDAD 视角下的正确分层应该是什么？

如果把上面所有内容压缩成一套团队级结构，我会给出这样一个结论：

CLAUDE.md

负责：

项目目的

仓库地图

关键文档入口

上下游关联项目路径和概要

全局协作协议

默认流程

Command 路由

边界与禁区

.claude/commands/ / .claude/skills/

负责：

可复用工作流

标准化执行步骤

输出模板

团队共享的操作模式

.claude/hooks/

负责：

自动检查

风险拦截

强制约束

不依赖模型记忆的确定性行为

docs/

负责：

架构事实

ADR

runbook

业务规则

深层背景知识

这四层一分清，很多原本混乱的问题都会自动变简单：

入口文件不会无限膨胀

流程可以复用

风险可以约束

知识可以定位

团队协作可以稳定下来

这才是 DDAD 想要的东西。

八、结论：别再让 CLAUDE.md 承担一切

如果用一句话总结这篇文章，我会这样说：

在团队 Agentic 开发里，CLAUDE.md 不该承担一切。它应该只负责协议入口，而不是试图装下整个系统。

真正成熟的做法，不是继续往 CLAUDE.md 里塞更多内容，而是完成分层：

协议放在 CLAUDE.md

复用放在 Commands / Skills

约束放在 Hooks

事实放在 Docs

这样做的价值，不只是让 Claude Code 更稳定。

更重要的是，它让团队从“提示词试错”走向“协作系统设计”。

而这，正是 DDAD 的核心立场：

文档不是附属物，而是人机协作的接口。

知识不是背景材料，而是可执行的团队记忆。

协作不是临时互动，而是可编排、可约束、可复用的工程系统。

当你这样设计项目时，Claude Code 才更有可能不像一个偶尔聪明、偶尔失忆的聊天机器人