项目级 CLAUDE 设计说明
本文解释 ../../examples/project-CLAUDE.md 这份主模板为什么这样设计，以及哪些部分应该按项目事实替换，哪些结构建议保留。
这份文档适合两类人：
- 第一次把 Team Skills Platform 接入项目的团队
- 已经看过主模板，但还不理解每一段存在意义的人
如果你的目标是直接复制一个可用模板，回到 ../../examples/project-CLAUDE.md。
如何使用这份说明
推荐顺序：
- 先打开 ../../examples/project-CLAUDE.md
- 再对照本文逐段理解为什么这样写
- 最后按 project-onboarding.md 把项目事实替换进去
本文只解释设计意图，不提供第二份可复制模板，避免 examples 目录里出现两份长期漂移的近似文件。
1. 标题和第一句
模板用 AI Working Agreement 这类标题，是为了把它定位成“项目级默认工作约定”，而不是普通背景说明文档。
建议保留：
- 项目名或产品名
- “默认采用 Team Skills Platform 工作模式”这类总开关句子
建议替换：
- 具体项目名称
- 如果你的团队不是所有任务都按这套模式执行，可以把“默认采用”改成“复杂任务默认采用”
2. 项目背景
这一段的目标不是重写 PRD，而是给模型最少但关键的项目事实，让它知道：
- 你是什么类型的系统
- 前后端和数据边界在哪里
- 哪些外部依赖经常构成约束
- 哪些文档应该优先被读取
为什么必须写：
- 写技术栈，可以减少模型凭空猜框架
- 写架构边界，可以减少角色越界和错误改动范围
- 写关键文档，可以让后续规划优先回到仓库已有事实源
不要在这里堆太细的目录或模块清单。项目背景应该短，但要能定边界。
3. 默认角色链路
这一段决定了任务默认由谁发起、谁拆解、谁实现、谁验收、谁收口。对混合项目来说，这一段尤其重要，因为没有角色约束时，模型很容易退化成“一个角色什么都做”。
为什么主模板这样排：
tech-lead放在最前面，确保主链有明确收口点product-manager单列，避免需求澄清被隐式吞掉frontend-engineer和backend-engineer分开，减少跨端责任混淆qa-engineer和devops-engineer保留在链路里，避免测试和发布被遗漏
如果项目很小，可以删掉少数角色，但不要省掉最终收口角色。
4. 默认命令流
这一段是主链骨架。它告诉模型：什么时候先 intake，什么时候应该交接，什么时候进入 review 和 release。
为什么主模板保留完整主链：
/team-intake负责锁定目标和边界/team-plan负责拆任务和责任/team-execute负责真正实施/handoff负责把多角色结果整理成结构化交接/team-review和/team-release负责质量与上线收口
如果这里不写清楚，模型更容易直接跳到实现或 review，导致上下文断层。
5. specialist 使用规则
这段不是在鼓励多用 specialist，而是在给 specialist 设边界。
为什么要单列：
- 先写使用时机，再写回落要求，能同时约束效率和责任
- 把
/code-review放在联调前，是为了尽早暴露问题 - 把
/verify留给最终验证，是为了避免在早期滥用它代替规划或评审 - 最后一条“必须回落到主链”是整段最重要的规则
团队第一次接入时，最常见的错误就是 specialist 输出很多，但没有人负责最终决定。
6. 项目约束
这一段应该只写“不能省”的门禁，而不是把所有最佳实践都塞进来。
为什么主模板这么收敛：
- 构建和校验脚本是这个仓库自己的事实约束，必须明确
- 前端质量门禁单列，是因为混合项目里前端最容易被压缩成只改页面
- 接口和数据库约束单列，是因为后端变更的破坏半径最大
- custom overlay 启用规则单列，是为了避免默认污染所有任务
如果你发现这一段越来越长，说明你把操作细节写进了项目约束。那部分应该放到 runbook，而不是项目级 CLAUDE.md。
7. 默认技能装配
这一段的作用是告诉模型“默认带哪些工具箱”，不是列出所有存在的 skills。
为什么主模板这样配：
- shared skills 作为默认底座，覆盖需求、方案、合同和测试
- 前端技能只在混合项目里作为常见默认，而不是所有项目都启用
- 安全评审、验证收口和发布治理属于高频专项能力，但更适合直接通过命令与 runbook 触发，而不是继续保留薄 skill 名称
- custom overlay 默认关闭，是为了保持上下文干净
项目首次接入时，技能装配宁可偏少，也不要一上来全开。
8. 默认交付物
这一段经常被忽略，但实际很有价值。它会直接影响模型输出的结构质量。
为什么要写：
- 它把“每一步应该产出什么”说清楚了
- 它让
/handoff和/team-review不会只收到模糊总结 - 它能显著减少“做了很多，但没有结构化结果”的情况
如果团队经常抱怨 AI 输出不稳定，先看是不是没有把交付物结构写清楚。
9. 首次调用模板
这里不是为了罗列所有命令，而是为了降低第一次正式使用时的摩擦。
为什么主模板保留这三段：
- 第一条
/team-intake模板必须写目标、范围、不做、约束和输出，这五项能显著提高结果质量 - 第二条
/team-plan模板说明了要拆哪些角色，防止 plan 只有一层任务列表 - 第三条
/handoff模板明确交接字段，防止交付阶段只剩一句“已完成”
如果你的团队刚接入，建议保留这三段，不要急着删掉。
哪些内容应该替换
必须替换：
- 项目名和产品类型
- 技术栈与架构边界
- 项目约束中的真实门禁
- 首次调用模板中的业务示例
按场景替换：
- 默认角色链路
- 默认技能装配
- 默认命令流中是否保留
/team-release
尽量保留结构：
- 项目背景
- 默认角色链路
- 默认命令流
- specialist 使用规则
- 项目约束
- 默认交付物
什么时候不该用主模板
下面两类项目更适合直接看差异指南：
如果你只是配置个人偏好，而不是配置项目，改看 ../../examples/user-CLAUDE.md。
下一步
- 先回到 ../../examples/project-CLAUDE.md 复制主模板。
- 然后按 project-onboarding.md 完成项目接入。
- 最后按 first-team-workflow-walkthrough.md 跑一次完整主链演练。