@colin4k1024/tsp 2.4.0 → 2.4.2

package/docs/runbooks/project-claude-design-rationale.md

@@ -0,0 +1,188 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 项目级 CLAUDE 设计说明
+
+本文解释 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md) 这份主模板为什么这样设计，以及哪些部分应该按项目事实替换，哪些结构建议保留。
+
+这份文档适合两类人：
+
+- 第一次把 Team Skills Platform 接入项目的团队
+- 已经看过主模板，但还不理解每一段存在意义的人
+
+如果你的目标是直接复制一个可用模板，回到 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md)。
+
+## 如何使用这份说明
+
+推荐顺序：
+
+1. 先打开 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md)
+2. 再对照本文逐段理解为什么这样写
+3. 最后按 [project-onboarding.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/saas-nextjs-CLAUDE.md](../../examples/saas-nextjs-CLAUDE.md)
+- 后端主导项目：看 [../../examples/springboot-service-CLAUDE.md](../../examples/springboot-service-CLAUDE.md)
+
+如果你只是配置个人偏好，而不是配置项目，改看 [../../examples/user-CLAUDE.md](../../examples/user-CLAUDE.md)。
+
+## 下一步
+
+1. 先回到 [../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md) 复制主模板。
+2. 然后按 [project-onboarding.md](project-onboarding.md) 完成项目接入。
+3. 最后按 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md) 跑一次完整主链演练。

package/docs/runbooks/project-manager-daily-operations.md

@@ -0,0 +1,61 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Project Manager 日常操作手册
+
+本文面向项目经理，说明排期、依赖、里程碑和风险推进如何在 Team Skills Platform 下落地。
+
+如果你想先看当前公开命令和 specialist 入口，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。
+
+## 1. 你的默认职责
+
+- 把任务拆成可执行阶段和里程碑
+- 识别跨角色依赖与阻塞项
+- 跟踪风险状态和时间窗口
+- 把进度与风险同步给 tech-lead
+
+## 2. 进入 plan 前必须确认什么
+
+- 目标和范围外事项是否稳定
+- 谁负责关键交付物
+- 哪些依赖会影响排期
+- 是否存在必须升级给 tech-lead 的风险
+
+## 3. 排期时的固定检查
+
+- 依赖顺序是否清楚
+- 是否需要分阶段交付
+- 哪些事项必须作为阻塞项管理
+- QA、发布和观察窗口是否预留
+
+## 4. 应交付什么
+
+- 里程碑和依赖清单
+- 关键风险与缓解动作
+- 阻塞项与责任人
+- 建议的 handoff 节点
+
+如果需要成文化交付计划，直接按 [artifact-standards.md](../../rules/artifact-standards.md) 中的 Delivery Plan 最小字段组织：版本目标、工作拆解、风险与缓解、节点检查。
+
+## 5. 常用命令组合
+
+- `/team-intake`：确认目标和参与角色
+- `/team-plan`：形成阶段计划与依赖
+- `/tdd`：在高返工任务里把测试前置，降低阶段返工风险
+- `/handoff`：推动跨角色衔接
+- `/team-review`：收口风险和剩余问题
+- `/harness-audit`：平台刚新增入口或命令时，检查文档与命令面是否同步
+
+## 6. 常见错误
+
+- 只有时间点，没有依赖关系
+- 风险写得很泛，无法行动
+- 没有识别哪些任务应该先走 `/tdd`，导致计划上看似推进，实际上返工风险很高
+- 没有为 QA 和 release 预留明确窗口
+
+可结合这些文档一起看：[project-onboarding.md](project-onboarding.md)、[first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)、[project-manager-planning-conversation-example.md](project-manager-planning-conversation-example.md)

package/docs/runbooks/project-manager-planning-conversation-example.md

@@ -0,0 +1,82 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# Project Manager 计划推进对话样例
+
+本文给出一份偏 Project Manager 视角的成品对话样例，重点展示怎样把目标、依赖、里程碑和阻塞项整理成可执行的推进计划。
+
+## 1. 场景
+
+- 任务：审批记录查询需求已经完成 intake
+- 当前输入：目标、范围、参与角色已经明确
+- 目标：形成可执行的阶段计划和 handoff 节点
+
+## 2. 用户怎么说
+
+```text
+请以 project-manager 视角拆当前任务。
+输出：里程碑、关键依赖、角色协作顺序、风险、升级条件。
+如果存在并行开发，请说明哪些 handoff 必须提前约定。
+```
+
+## 3. 期望结果长什么样
+
+```text
+里程碑
+- M1：architect 确认接口契约与权限边界
+- M2：backend-engineer 完成接口实现与自测
+- M3：frontend-engineer 完成列表页与筛选交互
+- M4：qa-engineer 完成功能与权限回归
+
+关键依赖
+- 接口契约先于前后端联调
+- 权限边界先于 QA 用例冻结
+
+角色协作顺序
+- architect -> backend-engineer / frontend-engineer -> qa-engineer -> devops-engineer
+
+风险
+- 接口字段若晚变更，会影响联调和 QA 用例
+- 权限口径若晚确认，会导致回归重复执行
+
+升级条件
+- 若接口契约在开发开始后仍频繁变更，升级给 tech-lead
+- 若 QA 回归窗口不足，提前升级给 tech-lead 和 devops-engineer
+
+必须提前约定的 handoff
+- architect 到研发：接口契约、字段口径、权限边界
+- 研发到 QA：实现结果、自测证据、已知风险
+```
+
+## 4. 不合格结果通常长什么样
+
+```text
+这周先做开发，下周测一下。
+```
+
+这类结果的问题是：
+
+- 没有依赖顺序
+- 没有阻塞条件
+- 没有 handoff 节点
+
+## 5. Project Manager 在对话里最容易漏什么
+
+- QA 和 release 的时间窗口
+- 明确的升级条件
+- 对 handoff 的前置约束
+
+## 6. 继续推进时怎么说
+
+当阶段计划形成后，下一句通常是：
+
+```text
+请把上面的计划整理成可直接进入 /team-plan 的输出格式，包含角色职责、依赖、handoff 节点和风险。
+```
+
+与这些文档配合阅读：[project-manager-daily-operations.md](project-manager-daily-operations.md)、[parallel-development-coordination-walkthrough.md](parallel-development-coordination-walkthrough.md)、[role-prompt-recipes.md](role-prompt-recipes.md)