@colin4k1024/tsp 2.4.5 → 2.4.6

package/docs/runbooks/claude-quick-start.md

@@ -1,227 +0,0 @@
----
-version: "2.3.0"
-status: draft
-created: 2026-03-28
-updated: 2026-04-18
-owner: 工程团队
-doc_tier: entry
-last_verified: 2026-04-18
-source_of_truth:
-  - ../../README.md
-  - ../../AGENTS.md
-  - ./team-skills-usage.md
----
-
-# Claude 快速上手
-
-本文面向第一次把 Team Skills Platform 安装到 Claude 的使用者，目标是在 5 到 10 分钟内跑通第一个可工作的主链示例，并知道新增的 specialist 与 runtime 能力该从哪里开始体验。
-
-## 1. 安装
-
-```bash
-node scripts/build-platform-artifacts.js
-CLAUDE_HOME_DIR="$HOME/.claude" ./scripts/install-claude.sh
-```
-
-安装脚本会做两件事：
-
-- 把完整插件目录复制到 `~/.claude/plugins/team-skills-platform/`
-- 把 `skills/`、`agents/`、`commands/`、`rules/`、`templates/`、`examples/` 等同步到 `~/.claude/` 下的对应目录
-
-## 2. 校验安装是否成功
-
-至少确认以下文件存在：
-
-- `~/.claude/commands/team-help.md`
-- `~/.claude/agents/roles/tech-lead.md`
-- `~/.claude/examples/project-CLAUDE.md`
-- `~/.claude/marketplace.json`
-
-如果这些文件不存在，优先回查：
-
-- 是否先执行了构建脚本
-- `CLAUDE_HOME_DIR` 是否指向了预期目录
-- 是否误把历史导入源当成正式安装入口
-
-如果还没有定位到问题，继续看 [troubleshooting.md](troubleshooting.md)。
-
-### 2.1 可选能力检查：Graphify / GitNexus
-
-如果你准备在 brownfield 项目中启用代码图谱能力，安装后可以先做预检查：
-
-```bash
-npm run graphify:doctor
-npm run gitnexus:doctor
-```
-
-预检查仅验证环境，不会自动安装依赖。Graphify 适合轻量结构证据，GitNexus 适合 MCP 查询、impact 和 detect_changes；若失败，按 [troubleshooting.md](troubleshooting.md) 的对应章节处理。
-
-## 3. 长期使用建议：准备项目级 CLAUDE.md
-
-如果你只是先试一条命令，这一步可以放到第一次试跑之后再做；如果你准备把平台长期接入某个项目，这一步应尽快完成。
-
-用户级 `CLAUDE.md` 适合放默认偏好，项目级 `CLAUDE.md` 适合放技术栈、命令流和门禁要求。建议从以下样例开始：
-
-- 通用项目样例：[../../examples/project-CLAUDE.md](../../examples/project-CLAUDE.md)
-- Next.js SaaS 样例：[../../examples/saas-nextjs-CLAUDE.md](../../examples/saas-nextjs-CLAUDE.md)
-- Spring Boot 服务样例：[../../examples/springboot-service-CLAUDE.md](../../examples/springboot-service-CLAUDE.md)
-- 流程型企业项目样例：[../../examples/workflow-enterprise-CLAUDE.md](../../examples/workflow-enterprise-CLAUDE.md)
-- 平台治理仓库样例：[../../examples/platform-governance-CLAUDE.md](../../examples/platform-governance-CLAUDE.md)
-- 数据看板项目样例：[../../examples/data-analytics-dashboard-CLAUDE.md](../../examples/data-analytics-dashboard-CLAUDE.md)
-- GitHub Actions / 供应链治理仓库样例：[../../examples/github-actions-supply-chain-CLAUDE.md](../../examples/github-actions-supply-chain-CLAUDE.md)
-- AI / Eval 平台样例：[../../examples/ai-eval-platform-CLAUDE.md](../../examples/ai-eval-platform-CLAUDE.md)
-- 移动端 / 小程序项目样例：[../../examples/mobile-miniapp-CLAUDE.md](../../examples/mobile-miniapp-CLAUDE.md)
-- IaC / Kubernetes 平台仓库样例：[../../examples/iac-kubernetes-platform-CLAUDE.md](../../examples/iac-kubernetes-platform-CLAUDE.md)
-- 插件 / 扩展仓库样例：[../../examples/plugin-extension-platform-CLAUDE.md](../../examples/plugin-extension-platform-CLAUDE.md)
-- 数据 / ML pipeline 仓库样例：[../../examples/data-ml-pipeline-CLAUDE.md](../../examples/data-ml-pipeline-CLAUDE.md)
-- 安全 / 合规平台仓库样例：[../../examples/security-compliance-platform-CLAUDE.md](../../examples/security-compliance-platform-CLAUDE.md)
-- 内部开发者平台样例：[../../examples/internal-developer-platform-CLAUDE.md](../../examples/internal-developer-platform-CLAUDE.md)
-- 数据可观测性 / 质量平台样例：[../../examples/data-observability-quality-CLAUDE.md](../../examples/data-observability-quality-CLAUDE.md)
-
-如果你想按 vertical 场景成熟度决定先看模板还是先看 demo，先看 [../presentation/vertical-scenario-route-map.md](../presentation/vertical-scenario-route-map.md)。
-如果你想按表格确认每个 vertical 已补齐哪些材料，再看 [vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)。
-
-## 4. 第一个最小闭环
-
-第一次不要一口气跑完整条链路，先用一个最小闭环确认平台工作正常。
-
-主链入口统一从 `/team-help` 开始。真正进入正式任务后，PRD、delivery-plan、execute-log、handoff 等内容都要按命令说明通过 `npm run artifact:persist -- ...` 回写到项目仓库，而不是只停留在对话里。
-
-### 4.1 新功能示例
-
-```text
-/team-help
-目标：判断当前任务入口
-现状：是否已有 brownfield 文档、project-context、handoff 证据
-输出：推荐下一条主链命令和缺失前置条件
-```
-
-拿到入口建议后继续：
-
-```text
-/team-intake
-目标：为订单服务新增审批 API
-范围：接口、权限校验、测试计划
-不做：前端页面、发布脚本重构
-约束：必须评估是否启用 私有流程与权限集成
-输出：参与角色、风险、下一步命令建议
-```
-
-拿到 intake 结果后继续：
-
-```text
-/team-plan
-基于上一步结果拆解 architect、backend-engineer、qa-engineer 的任务。
-要求给出依赖关系、custom overlay 是否启用、每次 handoff 的最小交付物。
-```
-
-### 4.2 前端问题修复示例
-
-```text
-/team-help
-目标：判断当前任务入口
-现状：是否已有 brownfield 文档、project-context、handoff 证据
-输出：推荐下一条主链命令和缺失前置条件
-```
-
-再进入需求锁边界：
-
-```text
-/team-intake
-目标：修复订阅页在 iPad 下的布局溢出
-范围：页面布局、响应式验证、UI 自测证据
-不做：接口改造
-约束：必须附带 ui-review-checklist
-```
-
-如果问题足够小，可以走短链路：`/code-review` -> `/handoff` -> `/team-review`，但不要跳过验证证据。
-
-## 5. 安装后另外三条最短体验路径
-
-### 5.1 想体验测试先行
-
-```text
-/team-plan
-基于当前需求结果拆解实现任务，并给出可进入 /tdd 的最小上下文。
-```
-
-```text
-/tdd
-目标：新增订单审批记录查询能力
-现有缺口：还没有测试和契约验证路径
-成功标准：先给出 red-green-refactor 步骤，并整理成可直接进入 /team-execute 的动作清单
-```
-
-### 5.2 想体验平台能力自检
-
-```text
-/harness-audit
-目标：检查当前平台的命令、skills、hooks、rules、文档和集成深度。
-输出：Overall Score、Dimension Scores、Top Actions、Recommendations。
-```
-
-适合在你刚补了一批命令、skills 或文档之后，快速看还有哪些入口没同步。
-
-### 5.3 想先理解后台运行时增强
-
-如果你不想马上跑命令，而是先想知道 memory、observe、cost、budget、compact、instinct 这些新增能力怎么影响会话行为，直接看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md) 和 [ecc-harness-usage.md](ecc-harness-usage.md)。
-
-## 6. 什么时候用 specialist
-
-Claude 里建议把 specialist 当成“专项分析器”，不是最终裁决者。
-
-- 用 `/plan` 做深度规划
-- 用 `/tdd` 做测试先行
-- 用 `/code-review` 做风险审查
-- 用 `/build-fix` 处理构建故障
-- 用 `/verify` 做验证回环
-- 用 `/harness-audit` 做平台能力体检
-
-这些输出都要回到 `/handoff` 或 `/team-*`。如果不回收，平台就会退化成多个平行结论，失去 `tech-lead` 编排的价值。
-
-## 7. 常用对话模板
-
-如果你只想快速复制命令骨架，不想先读完整示例，先看 [team-commands-quick-prompts.md](team-commands-quick-prompts.md)；如果你想看更贴近日常对话的整句提示，直接看 [claude-conversation-prompt-recipes.md](claude-conversation-prompt-recipes.md)；如果你想看最短的两条上手路径，再看 [first-team-command-60-seconds.md](first-team-command-60-seconds.md)。
-
-如果你想直接看一份从 intake 到 review 的成品对话，继续看 [claude-end-to-end-conversation-example.md](claude-end-to-end-conversation-example.md)。
-
-### 6.1 进入主链
-
-```text
-请按 Team Skills Platform 工作模型处理当前任务。
-先以 tech-lead 视角执行 /team-intake，输出目标、范围外事项、风险和建议参与角色。
-```
-
-### 6.2 进入专项分析
-
-```text
-基于当前 intake 结果，调用 /code-review 或 /plan 做专项分析。
-请把结论整理成可直接进入 /handoff 的格式。
-```
-
-### 6.3 明确是否需要 custom overlay
-
-```text
-如果任务依赖私有流程、权限、发布或设计资产，请先判断是否需要启用 enterprise overlay。
-如果不需要，也请明确说明原因。
-```
-
-## 8. 常见误区
-
-- 不要把 specialist 的结论直接当最终决定
-- 不要默认所有任务都需要 custom overlay
-- 不要在用户级 `CLAUDE.md` 里堆满项目专属约束
-- 不要只给代码 diff，不补 handoff 和验证证据
-
-下一步建议：
-
-- 想按任务场景继续展开：看 [claude-usage-scenarios.md](claude-usage-scenarios.md)
-- 想先看所有命令和能力怎么映射：看 [command-and-capability-matrix.md](command-and-capability-matrix.md)
-- 想单独看 runtime hooks 与后台机制：看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)
-- 想直接复制 Claude 的常用说法：看 [claude-conversation-prompt-recipes.md](claude-conversation-prompt-recipes.md)
-- 想直接看 Claude 的完整对话示例：看 [claude-end-to-end-conversation-example.md](claude-end-to-end-conversation-example.md)
-- 想把平台正式接入项目：看 [project-onboarding.md](project-onboarding.md)
-- 想直接走一遍完整主链：看 [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-- 想查完整命令和输出规范：看 [team-skills-usage.md](team-skills-usage.md)
-
-完整说明见 [team-skills-usage.md](team-skills-usage.md)。

package/docs/runbooks/claude-usage-scenarios.md

@@ -1,176 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Claude 使用场景总览
-
-本文把 Claude 端的使用文档按“上手、接入、日常开发、专项协作、问题排查”五类组织起来，方便团队按场景阅读，而不是靠猜文件名。
-
-## 1. 首次使用
-
-- 安装与首个闭环：[claude-quick-start.md](claude-quick-start.md)
-- 新项目接入：[project-onboarding.md](project-onboarding.md)
-- 项目级 CLAUDE 设计说明：[project-claude-design-rationale.md](project-claude-design-rationale.md)
-- 按项目类型直接复制起手句：[../../examples/project-type-starter-playbook.md](../../examples/project-type-starter-playbook.md)
-- 按更垂直项目类型复制连续脚本：[../../examples/vertical-project-conversation-scripts.md](../../examples/vertical-project-conversation-scripts.md)
-- GitHub Actions / AI Eval / 移动端 / 合规 / 内部平台 / 数据质量 demo script：[github-actions-supply-chain-demo-script.md](github-actions-supply-chain-demo-script.md)、[ai-eval-platform-demo-script.md](ai-eval-platform-demo-script.md)、[mobile-miniapp-demo-script.md](mobile-miniapp-demo-script.md)、[security-compliance-platform-demo-script.md](security-compliance-platform-demo-script.md)、[internal-developer-platform-demo-script.md](internal-developer-platform-demo-script.md)、[data-observability-quality-demo-script.md](data-observability-quality-demo-script.md)
-- 按材料成熟度选择 vertical 场景：[../presentation/vertical-scenario-route-map.md](../presentation/vertical-scenario-route-map.md)
-- 按表格查看 vertical 材料覆盖：[vertical-scenario-capability-matrix.md](vertical-scenario-capability-matrix.md)
-- 完整主链演练：[first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-
-## 2. 日常开发
-
-- 新功能全流程：[claude-feature-development-guide.md](claude-feature-development-guide.md)
-- 测试先行与 red-green-refactor：先看 [specialist-commands-playbook.md](specialist-commands-playbook.md)
-- 代码评审工作流：[claude-code-review-workflow.md](claude-code-review-workflow.md)
-- 前端工程师日常操作：[frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)
-- 后端工程师日常操作：[backend-engineer-daily-operations.md](backend-engineer-daily-operations.md)
-- QA 工程师日常操作：[qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
-- DevOps 工程师日常操作：[devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)
-- 项目经理日常操作：[project-manager-daily-operations.md](project-manager-daily-operations.md)
-- Tech Lead 日常操作：[tech-lead-daily-operations.md](tech-lead-daily-operations.md)
-- 产品经理日常操作：[product-manager-daily-operations.md](product-manager-daily-operations.md)
-- 架构师日常操作：[architect-daily-operations.md](architect-daily-operations.md)
-
-## 3. Specialist 与交接
-
-- Specialist 命令工作簿：[specialist-commands-playbook.md](specialist-commands-playbook.md)
-- Claude 场景化示例集：[../../examples/claude-scenario-playbook.md](../../examples/claude-scenario-playbook.md)
-- Handoff 填充指南：[handoff-filling-guide-with-examples.md](handoff-filling-guide-with-examples.md)
-- Team Intake 完整示例：[team-intake-example.md](team-intake-example.md)
-- Team Plan 完整示例：[team-plan-example.md](team-plan-example.md)
-- Team Execute 完整示例：[team-execute-example.md](team-execute-example.md)
-- Team Handoff 完整示例：[team-handoff-example.md](team-handoff-example.md)
-- Team Review 完整示例：[team-review-example.md](team-review-example.md)
-- Team Release 完整示例：[team-release-example.md](team-release-example.md)
-- API Mock 策略与生命周期手册：[api-mocking-strategy-and-lifecycle-guide.md](api-mocking-strategy-and-lifecycle-guide.md)
-- 前后端联调与验收清单：[frontend-backend-integration-acceptance-checklist.md](frontend-backend-integration-acceptance-checklist.md)
-- Consumer-Driven Contract 与 Mock 对齐指南：[consumer-driven-contract-testing-with-mock-alignment.md](consumer-driven-contract-testing-with-mock-alignment.md)
-- Team 命令快速提示：[team-commands-quick-prompts.md](team-commands-quick-prompts.md)
-- Claude 对话提示模板：[claude-conversation-prompt-recipes.md](claude-conversation-prompt-recipes.md)
-- 角色高频提示模板：[role-prompt-recipes.md](role-prompt-recipes.md)
-- Claude 完整对话样例：[claude-end-to-end-conversation-example.md](claude-end-to-end-conversation-example.md)
-- QA 放行对话样例：[qa-review-conversation-example.md](qa-review-conversation-example.md)
-- DevOps 发布对话样例：[devops-release-conversation-example.md](devops-release-conversation-example.md)
-- Tech Lead 收口对话样例：[tech-lead-closure-conversation-example.md](tech-lead-closure-conversation-example.md)
-- Product Manager 需求澄清对话样例：[product-manager-clarification-conversation-example.md](product-manager-clarification-conversation-example.md)
-- Project Manager 计划推进对话样例：[project-manager-planning-conversation-example.md](project-manager-planning-conversation-example.md)
-- Architect 方案设计对话样例：[architect-design-conversation-example.md](architect-design-conversation-example.md)
-- 60 秒跑通第一个 Team 命令：[first-team-command-60-seconds.md](first-team-command-60-seconds.md)
-
-## 4. 共享 walkthrough
-
-- Bug 修复全流程：[bug-fix-complete-walkthrough.md](bug-fix-complete-walkthrough.md)
-- Code Review 协作演练：[code-review-collaboration-walkthrough.md](code-review-collaboration-walkthrough.md)
-- 多服务后端集成演练：[multi-service-backend-integration-walkthrough.md](multi-service-backend-integration-walkthrough.md)
-- 紧急修复发布演练：[hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)
-- 前端重构演练：[frontend-refactor-walkthrough.md](frontend-refactor-walkthrough.md)
-- API 设计与演进演练：[api-design-evolution-walkthrough.md](api-design-evolution-walkthrough.md)
-- 文档更新协作演练：[documentation-update-walkthrough.md](documentation-update-walkthrough.md)
-- 构建失败处理演练：[build-failure-recovery-walkthrough.md](build-failure-recovery-walkthrough.md)
-- 需求澄清与范围管理演练：[requirement-clarity-and-scope-walkthrough.md](requirement-clarity-and-scope-walkthrough.md)
-- 系统架构设计与 ADR 演练：[system-architecture-design-walkthrough.md](system-architecture-design-walkthrough.md)
-- 金丝雀灰度发布演练：[canary-staging-release-walkthrough.md](canary-staging-release-walkthrough.md)
-- 生产事故应急响应演练：[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)
-- 发布后回滚与恢复演练：[release-rollback-recovery-walkthrough.md](release-rollback-recovery-walkthrough.md)
-- 前后端并行开发与联调演练：[frontend-backend-parallel-integration-walkthrough.md](frontend-backend-parallel-integration-walkthrough.md)
-- 并行研发协调演练：[parallel-development-coordination-walkthrough.md](parallel-development-coordination-walkthrough.md)
-- 跨角色问题分诊演练：[cross-role-issue-triage-walkthrough.md](cross-role-issue-triage-walkthrough.md)
-- GitHub Actions 与供应链治理演练：[github-actions-supply-chain-walkthrough.md](github-actions-supply-chain-walkthrough.md)
-- AI Eval 平台演练：[ai-eval-platform-walkthrough.md](ai-eval-platform-walkthrough.md)
-- 移动端与小程序交付演练：[mobile-miniapp-delivery-walkthrough.md](mobile-miniapp-delivery-walkthrough.md)
-- IaC 与 Kubernetes 平台演练：[iac-kubernetes-platform-walkthrough.md](iac-kubernetes-platform-walkthrough.md)
-- 插件与扩展平台演练：[plugin-extension-platform-walkthrough.md](plugin-extension-platform-walkthrough.md)
-- 数据与 ML Pipeline 演练：[data-ml-pipeline-walkthrough.md](data-ml-pipeline-walkthrough.md)
-- 安全与合规平台演练：[security-compliance-platform-walkthrough.md](security-compliance-platform-walkthrough.md)
-- 内部开发者平台演练：[internal-developer-platform-walkthrough.md](internal-developer-platform-walkthrough.md)
-- 数据可观测性与质量平台演练：[data-observability-quality-walkthrough.md](data-observability-quality-walkthrough.md)
-
-## 5. 一页速查
-
-- 前端缺陷修复一页速查：[frontend-bugfix-one-page.md](frontend-bugfix-one-page.md)
-- 发布收口一页速查：[release-closure-one-page.md](release-closure-one-page.md)
-- 事故分诊一页速查：[incident-triage-one-page.md](incident-triage-one-page.md)
-- 管理层价值速查一页：[executive-value-one-page.md](executive-value-one-page.md)
-
-## 6. 受众阅读路径
-
-- 实施接入阅读路径：[implementation-onboarding-reading-path.md](implementation-onboarding-reading-path.md)
-- 团队培训阅读路径：[team-training-reading-path.md](team-training-reading-path.md)
-
-## 7. 排障与完整规范
-
-- 安装与使用排障：[troubleshooting.md](troubleshooting.md)
-- 命令与能力矩阵：[command-and-capability-matrix.md](command-and-capability-matrix.md)
-- runtime 能力总览：[runtime-capabilities-overview.md](runtime-capabilities-overview.md)
-- 完整使用手册：[team-skills-usage.md](team-skills-usage.md)
-- 命令输出合同：[team-command-output-contracts.md](team-command-output-contracts.md)
-- 发布治理阅读路径：[release-governance-reading-path.md](release-governance-reading-path.md)
-- 示例总索引：[../../examples/INDEX.md](../../examples/INDEX.md)
-
-## 8. 企业扩展与发布收口
-
-- 自定义 overlay 扩展：[custom-overlay.md](custom-overlay.md)
-- 自定义 overlay 创建入口：[custom-overlay.md](custom-overlay.md)
-- Langfuse 追踪与可观测性集成指南：[langfuse-and-observability-integration-guide.md](langfuse-and-observability-integration-guide.md)
-- 发布治理阅读路径：[release-governance-reading-path.md](release-governance-reading-path.md)
-
-## 9. 推荐阅读路径
-
-### 8.1 第一次用 Claude
-
-1. [claude-quick-start.md](claude-quick-start.md)
-2. [project-onboarding.md](project-onboarding.md)
-3. [first-team-workflow-walkthrough.md](first-team-workflow-walkthrough.md)
-4. [../../examples/claude-scenario-playbook.md](../../examples/claude-scenario-playbook.md)
-
-### 8.2 已经接入，准备日常使用
-
-1. [claude-feature-development-guide.md](claude-feature-development-guide.md)
-2. [claude-code-review-workflow.md](claude-code-review-workflow.md)
-3. [specialist-commands-playbook.md](specialist-commands-playbook.md)
-
-### 8.3 想体验新增能力
-
-1. 想先看命令、skills、runtime 全景：看 [command-and-capability-matrix.md](command-and-capability-matrix.md)
-2. 想体验 `/tdd` 或 `/harness-audit`：看 [claude-quick-start.md](claude-quick-start.md) 和 [../../examples/claude-scenario-playbook.md](../../examples/claude-scenario-playbook.md)
-3. 想理解 observation、cost、budget、compact、instinct：看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)
-
-### 8.4 前端或后端专项
-
-1. 前端看 [frontend-engineer-daily-operations.md](frontend-engineer-daily-operations.md)
-2. 后端看 [backend-engineer-daily-operations.md](backend-engineer-daily-operations.md)
-3. 遇到跨角色交接时补看 [handoff-filling-guide-with-examples.md](handoff-filling-guide-with-examples.md)
-
-### 8.5 联调与跨角色协作
-
-1. 并行联调看 [frontend-backend-parallel-integration-walkthrough.md](frontend-backend-parallel-integration-walkthrough.md)
-2. 多角色推进看 [parallel-development-coordination-walkthrough.md](parallel-development-coordination-walkthrough.md)
-3. 问题归因不清时看 [cross-role-issue-triage-walkthrough.md](cross-role-issue-triage-walkthrough.md)
-
-### 8.6 质量、发布或编排专项
-
-1. QA 看 [qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
-2. 发布看 [devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)
-3. 编排和收口看 [tech-lead-daily-operations.md](tech-lead-daily-operations.md)
-
-### 8.7 需求、架构与发布专项
-
-1. 需求澄清看 [product-manager-daily-operations.md](product-manager-daily-operations.md) 和 [requirement-clarity-and-scope-walkthrough.md](requirement-clarity-and-scope-walkthrough.md)
-2. 架构设计看 [architect-daily-operations.md](architect-daily-operations.md) 和 [system-architecture-design-walkthrough.md](system-architecture-design-walkthrough.md)
-3. 发布治理看 [canary-staging-release-walkthrough.md](canary-staging-release-walkthrough.md)、[production-incident-response-walkthrough.md](production-incident-response-walkthrough.md)、[release-rollback-recovery-walkthrough.md](release-rollback-recovery-walkthrough.md)
-
-### 8.8 自定义 overlay 扩展场景
-
-1. 想创建自定义 overlay，看 [custom-overlay.md](custom-overlay.md)
-2. 
-
-### 8.9 按受众快速进入
-
-1. 管理层先看 [executive-value-one-page.md](executive-value-one-page.md)
-2. 实施接入先看 [implementation-onboarding-reading-path.md](implementation-onboarding-reading-path.md)
-3. 团队培训先看 [team-training-reading-path.md](team-training-reading-path.md)

package/docs/runbooks/code-review-collaboration-walkthrough.md

@@ -1,65 +0,0 @@
----
-version: "0.1.0"
-status: draft
-created: 2026-03-28
-updated: 2026-03-28
-owner: 工程团队
----
-
-# Code Review 协作演练
-
-本文演示一轮完整的 code review 协作：发起评审、处理问题、回收结论、再次确认。
-
-## 1. 场景
-
-- 功能已基本完成
-- 希望在 QA 前先暴露工程质量问题
-- 需要把 review 结论结构化回收到主链
-
-## 2. 推荐链路
-
-1. `/code-review`
-2. `/team-execute` 或直接修复
-3. `/code-review` 二次确认
-4. `/handoff`
-5. `/team-review`
-
-## 3. 第一轮 review 输入示例
-
-```text
-/code-review
-目标：评审审批记录查询接口与前端列表页改动
-重点关注：权限校验、错误处理、空态与响应式
-```
-
-## 4. 第一轮输出如何处理
-
-- Critical：立即修
-- High：通常不应带入 QA
-- Medium：能修则修，至少记录
-- Low：作为后续优化
-
-## 5. 二次确认示例
-
-```text
-/code-review
-基于上一轮评审意见，已修复权限校验和空态问题。
-请确认当前是否还存在阻塞 QA 的问题。
-```
-
-## 6. 最终回落到 handoff
-
-handoff 中至少要写：
-
-- review 发现了什么
-- 已修复什么
-- 还剩什么已知问题
-- QA 需要重点验证什么
-
-## 7. 常见错误
-
-- review 结果没有进入 handoff
-- 第二轮 review 只是重复跑，没有说明修了什么
-- 把 review 当成 QA 的替代
-
-与通用说明配合阅读：[claude-code-review-workflow.md](claude-code-review-workflow.md)

package/docs/runbooks/codeql-pr-security-gates.md

@@ -1,64 +0,0 @@
-# CodeQL PR 安全门禁手册
-
-本手册承接 `github/codeql-action` 的工程实践，用于把语义安全扫描接入 PR 与 code scanning 流程。它是安全 review 的补充证据来源，不替代人工威胁建模、依赖门禁或运行时验证。
-
-## 适用场景
-
-- 仓库托管在 GitHub，且具备使用 CodeQL 的前置条件。
-- 团队希望在 PR 或默认分支上提前发现代码级安全问题，而不是只靠人工 review。
-- 需要把安全扫描结果沉淀成可追踪、可分级、可回写的门禁输入。
-
-## 不适用场景
-
-- 仓库不在 GitHub，或当前环境不满足 CodeQL 使用条件。
-- 团队尚未建立基本的安全 review 责任链，却指望扫描器代替人工判断。
-- 期望把 CodeQL 结果当成唯一安全结论，而忽略鉴权设计、依赖风险和运行时暴露面。
-
-## 推荐落地方式
-
-1. 先确认使用边界：仓库托管方式、GitHub Advanced Security 条件、支持语言和扫描触发时机。
-2. 第一阶段先启用默认查询集，观察噪音、误报和 triage 成本，不要一开始就堆大量自定义查询。
-3. 将 CodeQL 与现有安全链分层：
-   - `dependency-review-gates` 负责依赖和许可证风险
-   - CodeQL 负责代码级语义问题
-   - 安全评审角色 / reviewer 负责最终风险判断与阻塞决策
-4. 若要把扫描结果用于 PR 门禁，先定义哪些严重级别或问题类型会阻塞，哪些只做观察。
-5. 结果必须回写到 `/code-review`、`/team-review` 或发布前检查，不让 code scanning 结果只停留在 GitHub 安全面板里。
-
-## 最小门禁模型
-
-- `scan layer`：CodeQL 在 PR 或默认分支上执行语义分析
-- `triage layer`：确认哪些结果是真问题、哪些是误报或暂不处理
-- `decision layer`：安全评审角色、`code-reviewer`、`tech-lead` 决定是否阻塞
-
-工具负责发现候选问题，团队负责做业务语义判断。
-
-## 重点检查项
-
-- 用户输入到 SQL、模板、文件、命令或反序列化边界的危险流向
-- 鉴权、授权、敏感数据处理和错误暴露相关问题
-- 语言与框架特定的常见安全陷阱
-- 代码结构层面人工 review 不易稳定发现的语义漏洞
-
-## 反模式
-
-- 还没定义 triage 规则，就把所有 CodeQL 告警直接当阻塞项。
-- 只看告警数量，不分析哪些会真正影响当前仓库的风险面。
-- 让 CodeQL 替代人工安全 review，以为“没报警就绝对安全”。
-- 扫描结果长期无人处理，最后大家默认忽略整套安全门禁。
-
-## 输出回落
-
-- PR 阶段：把高优先级扫描结果和 triage 结论写入 review 结论或风险摘要。
-- 团队协作：在 `/team-review` 中明确哪些问题来自 CodeQL、哪些已经人工确认或降级处理。
-- 发布阶段：若仍有未关闭的高风险扫描结果，必须回写到 `/team-release` 的放行结论或观察项。
-
-## 许可证与使用边界
-
-- `github/codeql-action` 本身是 MIT，但底层 CodeQL CLI 另有 GitHub 使用条件。
-- 深度接入前必须确认仓库托管方式、组织能力和 GitHub 安全产品边界，不要默认所有仓库都能直接启用。
-
-## 参考来源
-
-- [github/codeql-action](https://github.com/github/codeql-action)
-- [dependency-review-gates.md](dependency-review-gates.md)