mcpField
F
fix-ci

fix-ci

github.com/duc01226云与 DevOps1239 次安装1 周前更新
代码仓库

关于 fix-ci

fix-ci 是用于分析 CI/CD 日志并修复构建或测试故障的工作流技能，面向处理流水线问题的开发者。它要求追溯根因、先向用户说明拟议修复并取得批准，再实施和验证。

主要功能

  1. 01获取配置平台的 CI 日志
  2. 02分析构建、测试与环境故障
  3. 03以证据追溯根因
  4. 04批准后实施针对性修复
  5. 05测试修复并运行 prove-fix

适用场景

  1. 01调查流水线构建失败
  2. 02定位 CI 中的测试错误
  3. 03排查环境变量或依赖问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/duc01226/easyplatform --skill fix-ci

安装后在 Claude Code 中输入/fix-ci确认已加载。

详细介绍

Codex 兼容性说明：

  • 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会重写旧版 Claude /skill-name 引用。
  • 任务跟踪要求：在执行任何工作流或技能步骤之前，先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
  • 用户问题提示表示要直接在 Codex 中询问用户。
  • 遇到 Claude 专属的模式切换说明时，请忽略。
  • 严格执行约定：用户明确调用技能时，按原样执行该技能协议。
  • 子 Agent 授权：当用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的启用即授权为该任务使用所需的 spawn_agent 子 Agent。
  • 除非用户事先明确批准偏离，否则不得跳过、调换顺序或合并协议步骤。
  • 对于工作流技能，明确执行每个列出的子技能步骤，并逐步报告证据。
  • 如果所需步骤／工具在此环境中无法运行，请停止并先询问用户，然后再调整。

Codex 项目参考文档加载（无 Hooks）

Codex 不会通过基于 Claude Hooks 的方式注入文档。 进行编码、规划、调试、测试或审查时，请按以下路由显式打开项目文档。

始终阅读：

  • docs/project-config.json（项目专属路径、命令、模块以及工作流／测试设置）
  • docs/project-reference/docs-index-reference.md（指向完整的 docs/project-reference/* 目录）
  • docs/project-reference/lessons.md（始终适用的防护规则与反模式）

按情况阅读的文档：

  • 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
  • 前端／UI／样式／设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
  • 规格／测试用例规划或 TC 映射：feature-docs-reference.md
  • 集成测试实现／审查：integration-test-reference.md
  • E2E 测试实现／审查：e2e-test-reference.md
  • 代码审查／审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要不加区分地阅读所有文档。请从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

快速摘要

目标： 分析 CI/CD 流水线日志，找出并修复已配置流水线平台中的构建／测试失败。

工作流：

  1. 获取 — 从已配置的流水线平台下载 CI 日志
  2. 分析 — 根据日志输出识别根本原因（构建错误、测试失败、环境问题）
  3. 修复 — 根据追踪到的根本原因实施针对性修复

关键规则：

  • 基础设施上下文： 阅读 docs/project-config.json → infrastructure.cicd.tool，以识别 CI 平台（例如 "azure-devops"、"github-actions"、"gitlab-ci"）。针对该平台的正确流水线配置文件进行操作。
  • 调试思维：每项断言都必须有 file:line 证据
  • 专注于 CI 特有问题（环境变量、Docker、依赖项、构建顺序）
  • 验证修复不会破坏本地开发

调试思维（不可妥协）

保持怀疑。运用批判性思维和顺序思维。每项断言都必须有可追溯的证据和置信度百分比（观点应高于 80%）。

  • 采取行动前，必须通过实际代码追踪验证每个假设——切勿假定第一个假设正确——原因：第一个猜测通常只是最容易注意到的问题，并非真正原因
  • 每项根本原因断言都必须包含 file:line 证据
  • 如果无法通过代码追踪证明根本原因，请注明“假设，尚未确认”
  • 质疑假设：“这真的是原因吗？”→ 追踪实际执行路径
  • 检查是否完整：“还有其他促成因素吗？”→ 检查相关代码路径
  • 不要在没有证据的情况下声称“应该能修复”——请验证修复确实解决了追踪到的根本原因

⚠️ 强制要求：置信度与证据门槛

强制要求、重要、务必注意： 对每项声明，都必须附上 Confidence: X%、证据列表和 file:line 证明。 95% 及以上可直接推荐 | **80–94%**需附带注意事项 | **60–79%**列出未知项 | 低于 60%：停止 — 收集更多证据。

CI 日志 URL

$ARGUMENTS

⚠️ 修复前先验证（不可妥协）： 分析 CI 日志并确定根本原因后，必须通过直接提问向用户呈现调查结果和建议的修复方案，并获得明确批准后，才能更改任何代码。不得悄悄修复。

工作流

  1. 使用 debugger 子 Agent，通过 docs/project-config.json 中配置的平台工具/API 读取 CI 日志，从最后一条失败日志/错误向前追溯至根本原因，并向主 Agent 汇报。 1.5. 将分析结果写入 .ai/workspace/analysis/{ci-issue}.analysis.md。实施修复前重新阅读。
  2. 🛑 呈现根本原因和建议的修复方案 → 直接向用户提问 → 等待用户批准。
  3. 根据报告和解决方案开始实施修复。
  4. 使用 tester Agent 测试修复并确保其有效，然后向主 Agent 汇报。
  5. 如果存在问题或测试失败，从第 2 步重新开始。
  6. 完成后，向用户总结所做的更改并简要说明，指导用户开始使用，并建议后续步骤。

备注

  • 使用为已配置的 CI 平台提供的 CLI/API。如果配置的平台是 GitHub Actions，且无法使用 gh，请先指导用户安装并授权 GitHub CLI。

  • 修复后，必须运行 $prove-fix — 为每项更改构建代码证明追踪，并提供置信度评分。绝不能跳过。

[IMPORTANT] 开始前，使用任务跟踪将所有工作拆分成小任务 — 包括为每个文件读取操作创建任务。这样可以避免长文件导致上下文丢失。对于简单任务，AI 必须询问用户是否要跳过。

  • docs/project-reference/domain-entities-reference.md — 领域实体目录、关系和跨服务同步（任务涉及业务实体/模型时阅读）（相关时直接阅读；不要依赖钩子注入的对话文本）

技能变体： $fix 的变体 — 专用于 CI/CD 流水线日志分析。 从终点到起点的调试追踪 — 对于复杂 Bug、验证失败、回归修复、行为变更代码或代码流向不明确的情况，请从观察到的最终状态出发，反向追踪后再提出修复方案。

  1. 帧 0：观察到的最终状态 — 指明确切的用户可见输出、失败断言、日志行、持久化值、API 响应、渲染的 UI 或聚合分桶。记录生成该结果的读取器／查询／渲染器，并提供 file:line 证据。
  2. 每次向后追溯一跳 — 追踪最终读取器 -> 投影／缓存／存储 -> 写入器 -> 消费者／处理器／作业 -> 生产者／调用方 -> 原始触发。在每一跳记录：输入、转换、输出、负责人和证据。
  3. 列出所有输入路径 — 找出所有可能写入最终路径的上游生产者／调用方／事件／作业，包括重试、异步、缓存、后台任务以及其他 UI／API 路径。将每条路径标记为已验证、已排除或仍未知。
  4. 建立假设矩阵 — 对每个合理原因，列出支持证据、反对证据、复现／验证方法、影响范围和状态（primary、contributing、ruled out、latent）。在明确排除或限定其他竞争原因之前，不要修复。
  5. 选择负责修复的层级 — 找出不变量的责任方，以及能够保护所有下游消费者的最低共享层。除非症状出现的层级负责该不变量，否则不得在症状出现处修复。
  6. 正向证明收敛 — 选定修复方案后，再次从起点追踪到终点，说明修正后的状态如何到达观察到的最终输出。将每个根本原因对应到一项修复，并将每项修复对应到一个测试／证明。

满足以下条件前不得继续： 已指明最终状态 · 已撰写反向追踪 · 已列出所有输入路径 · 已完成假设矩阵 · 已论证负责修复的层级 · 已将正向收敛证明对应到测试。

切勿： 从第一个可疑代码路径开始。将多个生产者合并为一条“流程”。未经证明读取模型就把重复症状视为重复记录。跳过已排除的假设。

源代码／测试偏移检查。 对于编码、修复、调试、调查、测试或审查工作：当源代码行为发生变化时，检查受影响的单元／集成／E2E 测试，并依据证据判断测试应调整以符合预期行为，还是源代码变更本身是需要修复的意外 Bug。不要为迁移代码编写测试；架构／数据迁移是一次性执行路径，而非核心应用逻辑。 防止 AI 出错 — 每项任务都要避免以下失败模式：

删除前检查下游引用。 删除组件会导致文档和代码连锁过时。移除前，先梳理所有引用该组件的文件。 根据实际代码验证 AI 生成的内容。 AI 会臆造 API、类名和方法签名。记录或引用前，务必使用 grep 确认其确实存在。 编辑后追踪完整依赖链。 修改定义时，可能会遗漏由其派生的下游变量和使用方。务必追踪完整依赖链。 验证正确性时追踪所有代码路径。 确认代码存在，不等于确认它会执行。务必追踪提前退出、错误分支和条件跳过，而不只是正常路径。 调试时，先问“这是谁的责任？”，再修复。 追踪问题出在调用方（数据错误）还是被调用方（处理错误）。在负有责任的层修复，绝不要只修补症状出现的位置。 假设现有值是有意设置的——修改前先问为什么。 修改任何常量、限制值、标志或模式前：阅读注释、检查 git blame，并查看周边代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，需要验证每一项输出。一个检查通过，不代表所有检查都通过。 整体优先的调试方式——抵制注意力被最近线索牵走的陷阱。 调查任何故障时，先列出每项前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据验证，然后才能提出任何代码层面的假设。 精确修改——应用差异测试。 修复错误时，每一行更改都必须能直接追溯到该错误。不要顺手调整相邻代码的风格或进行改进。处理增强任务时，既要实现改进，也要明确说明。 编写代码前先指出歧义——不要默默自行选择。 如果请求有多种解释，请逐一列出并估算所需工作量，然后询问。不要擅自假定要处理所有记录、采用基于文件的方案或选择更复杂的路径。

根因调试 — 采用系统化方法，绝不靠猜测和反复试错。

  1. 复现 — 提供证据（错误消息、堆栈跟踪、屏幕截图），确认问题确实存在
  2. 隔离 — 使用二分搜索和图追踪，将范围缩小到具体文件、函数或行
  3. 追踪 — 沿数据流从输入追踪到故障点。阅读实际代码，不要推断。
  4. 提出假设 — 提出理论并注明置信度百分比。说明有哪些证据支持或反驳它
  5. 验证 — 使用有针对性的 grep 和阅读代码来检验假设。一次只检查一个变量。
  6. 修复 — 解决根因，而不是症状。通过图中的 connections 验证修复不会破坏调用方

绝不： 在没有证据时猜测。只修症状，不解决根因。跳过复现步骤。

嵌套任务扩展约定 — 对于工作流步骤调用，[Workflow] ... 行只是父级容器；子技能仍会创建可见的阶段任务。

  1. 先获取当前任务列表。如果存在匹配的活动父级工作流行，则设置 nested=true 并记录 parentTaskId；否则独立运行。
  2. 在阶段工作开始前，为声明的每个阶段创建一个任务。嵌套时，任务主题前缀设为 [N.M] $skill-name — phase。
  3. 嵌套时，使用 TaskUpdate(parentTaskId, addBlockedBy: [childIds]) 将父任务与子任务关联。
  4. 协调者必须在调用子技能或子 Agent 前，预先展开该子技能的阶段列表，并关联工作流行。
  5. 开始工作前，恰好将一个子任务标记为 in_progress；证据记录完成后，立即将其标记为 completed。
  6. 只有所有子任务都已完成，或已明确取消并说明原因，才能完成父任务。

阻塞条件： 当前任务列表已完成、子阶段已创建、嵌套时父任务已关联、首个子任务已标记为 in_progress。 项目参考文档门禁 — 在完成任务跟踪初始化后、读取目标文件或源文件、进行 grep、编辑或分析之前运行。项目文档优先于通用框架假设。

  1. 确定范围：文件类型、领域和操作。
  2. 根据触发条件确定必需文档：始终阅读 docs/project-reference/lessons.md；查找文档时阅读 docs-index-reference.md；评审时阅读 code-review-rules.md；后端/CQRS/API 相关时阅读 backend-patterns-reference.md；领域/实体相关时阅读 domain-entities-reference.md；前端/UI 相关时阅读 frontend-patterns-reference.md；样式/设计相关时阅读 scss-styling-guide.md + design-system/design-system-canonical.md；集成测试时阅读 integration-test-reference.md；E2E 测试时阅读 e2e-test-reference.md；功能文档/规范相关时阅读 feature-docs-reference.md；架构/新领域相关时阅读 project-structure-reference.md。
  3. 阅读所有存在的必需文档；不存在的文档视为不适用并跳过。不要将对话文本（例如 [Injected: <path>]）当作当前上下文中包含该文档的证明。
  4. 开始目标工作前，说明：已阅读参考文档：... | 缺失/不适用：...。

**开始工作前必须完成：**评估范围、检查/阅读必需文档、确认 lessons.md，并给出引用。

任务跟踪与外部报告持久化 — 执行前完成初始化；随后在处理目标/源文件前预读取项目参考文档。

  1. 在读取目标文件、grep、编辑或分析之前，创建一份简短的任务分解。上下文丢失时，先检查当前任务列表。
  2. 开始工作前将一项任务标记为 in_progress，并在取得证据后立即标记为 completed；不得批量切换状态。
  3. 对计划/评审工作，在发现首条问题前创建 plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md。
  4. 每处理完一个文件/章节或作出一项决策后，追加记录发现；最后根据报告文件综合整理。
  5. 最终输出引用：完整报告：plans/reports/{filename}。

**开始工作前必须完成：**已创建任务分解；计划/评审工作已声明报告路径；已持久化首条发现，之后才能记录下一条发现。

批判性思维 — 运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度须高于 80% 才能采取行动。 **防止幻觉：**绝不将猜测当作事实——每项主张都要引用来源，坦然承认不确定性，自查输出错误，独立交叉验证，对自己的判断保持怀疑——没有证据支撑的确定性是所有幻觉的根源。

先理解代码 — 严格门禁：阅读现有代码之前，不得编写、规划或修复。

  1. 搜索 3 种以上相似模式（grep/glob）——引用 file:line 证据
  2. 阅读目标区域的现有文件——理解其结构、基类和惯例
  3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
  4. 通过 connections 或 callers_of 映射依赖关系——了解哪些内容依赖目标
  5. 对于非简单任务（涉及 3 个以上文件），将调查结果写入 .ai/workspace/analysis/
  6. 实施前重新阅读分析文件——绝不能只凭记忆工作。— 原因：上下文过长时，记忆会偏离文件；文件才是事实依据
  7. 如果现有模式可行，绝不另创模式——严格遵循，或说明偏离原因。— 原因：不一致的模式会割裂代码库，并拖慢后续读者的工作

开始工作前必须完成：- [ ] 已阅读目标文件 - [ ] 已 grep 3 种以上模式 - [ ] 已追踪图谱（如果 graph.db 存在）- [ ] 已通过证据验证假设 基于证据的推理 — 禁止推测。每项主张都必须有证据。

  1. 每项主张都要引用 file:line、grep 结果或框架文档
  2. 声明置信度：>80% 可直接行动，60-80% 先验证，<60% 不得建议
  3. 架构变更必须进行跨服务验证
  4. “证据不足”是有效且预期的输出

满足以下条件前禁止继续： - [ ] 证据文件路径（file:line）- [ ] 已执行 grep 搜索 - [ ] 已找到 3 个以上相似模式 - [ ] 已声明置信度

未经证实不得使用：“显然”“我认为”“应该是”“可能是”“这是因为” 如果信息不完整 → 输出："证据不足。已验证：[...]。未验证：[...]。" 估算框架 — 优先自下而上；故事点（SP）为推导值；预计用时可能 ≥3d 时，输出最小值至最大值范围。与技术栈无关。基准：3-5 年经验的开发者，每天 6 个有效工作小时。AI 估算假设使用 Claude Code + 项目上下文。

方法：

  1. 影响范围检查（见下文）——决定代码和测试成本
  2. 分解阶段 → 每阶段小时数 → bottom_up_hours = Σ phase_hours
  3. likely_days = ceil(bottom_up_hours / 6) × productivity_factor
  4. 累加风险余量（基础值 + 附加值）→ max_days = likely_days × (1 + margin)
  5. min_days = likely_days × 0.9
  6. 当 likely_days ≥3 时输出范围；<3 时可用单点值（仍须记录余量）
  7. man_days_ai = 相同范围 × AI 加速比
  8. story_points 根据 likely_days 通过 SP-Days 推导——绝不作为估算驱动因素。偏差 >50% → 以自下而上估算为准

效率系数： 0.8 脚手架、代码生成和 AI 钩子完善 · 1.0 成熟默认值 · 1.2 模式薄弱 · 1.5 从零开始

成本驱动因素启发式规则（在选择工作类型行之前应用）：

  • UI 占主导：CRUD/业务应用中通常如此——成本为后端的 1.5-3 倍（状态、验证、响应式、无障碍、打磨）
  • 仅以下情况由后端占主导： 多聚合不变量、跨服务契约、架构迁移、复杂查询/性能、新事件流

复用与创建轴（首要杠杆，按层计算）：

UI 层级成本
复用现有屏幕上的组件0.1-0.3d
在现有屏幕上添加控件/列0.3-0.8d
将组件组合成新屏幕1-2d
新屏幕，含自定义布局/状态/验证2-4d
新建共享/通用组件（含主题、测试）3-6d+
后端层级成本
在新位置复用查询/处理程序0.1-0.3d
小幅更新现有处理程序/实体0.3-0.8d
在现有仓库/模型上新增查询0.5-1d
在现有聚合上新增命令/处理程序（增量式）1-2d
新建聚合/实体（仓库、验证、事件）2-4d
新建跨服务契约或架构迁移各 2-4d
多聚合不变量/复杂领域规则3-5d

规则： 将 UI、后端和测试各层级成本相加，再应用效率系数。复用可直接跳过对应层级——请注明。

测试范围驱动因素（明确计算 test_count——用“+测试”含糊带过是首要失败原因）：

驱动因素数量
顺利路径用户旅程每个用户故事/验收标准主流程 1 项
状态机转换可达转换数 × 允许的操作者数
多实体状态组合state(A) × state(B)——仅计算可达组合，不计算笛卡尔积
授权矩阵（所有者、非所有者、较高权限、未认证）× 每种变更操作
验证规则每个必填字段/边界/格式/跨字段规则 1 项
UI 状态（每个新屏幕/对话框）顺利、加载中、空状态、错误、部分状态——仅计算实际存在的状态
负向路径/不变量每条可违反的业务规则 1 项
测试层级（传统方式，含设置、断言和偶发失败处理）成本
1-5 个用例，复用测试夹具0.3-0.5d
6-12 个用例，新增 1 个测试夹具0.5-1d
13-25 个用例，多实体设置1-2d
26-50 个用例，或新增状态机覆盖2-3d
>50 个用例，或完整端到端旅程3-5d

测试乘数： 新增测试夹具/种子数据框架 +0.5d · 每个跨服务/总线断言 +0.3d · UI 端到端测试 ×1.5 · 每新增一个角色 +1-2 个用例

影响范围（强制预检查——影响代码和测试）：

  1. 直接修改的文件/组件——计数
  2. 其中的“复杂”项（>500 LOC、多处理程序、核心、频繁修改）——计数
  3. 下游使用方（调用方、事件订阅者、跨服务）——列出
  4. 是否改动共享/通用代码（影响多个应用）——是/否
  5. 回归范围——需要重新测试的区域

规则： 改动复杂项 → 添加 risk_factors。每个下游使用方 → +1-3 个回归用例。影响范围 >5 个区域或 >2 个复杂项 → 估算前重新评估是否应拆分。

风险余量（决定最大值上限）：

预计天数基础余量
<1d 微小+10%
1-2d 小型增量+20%
3-4d 实际功能+35%
5-7d 大型+50%
8-10d 特大型+75%
>10d+100% 并标记为应拆分

风险因素附加值（累加——在 risk_factors 中逐项列出）：

因素+余量
touches-complex-existing-feature（>500 LOC、多处理程序、核心）+20%
cross-service-contract 变更+25%
schema-migration-on-populated-data+25%
new-tech-or-unfamiliar-pattern+30%
regression-fan-out（≥3 个下游区域需重新测试）+20%
performance-or-latency-critical+20%
concurrency-race-event-ordering+25%
shared-common-code（多个使用方/多个应用）+25%
unclear-requirements-or-design+30%

合并规则： 总余量 >100% → 停止并拆分（缓冲超过 2 倍就是不诚实）。likely_days ≥5 时余量 <15% → 估算偏低，应扩大范围。

工作类型上限（likely_days 的硬性上限）：

工作类型最大 SP最大预计天数
单个字段/配置标记/样式修复10.5d
在现有模型中添加属性并绑定到现有 UI21d
新增端点 + 轻量 UI 控件（按钮/菜单/列），复用测试夹具32-3d
新增端点 + 新 UI 界面，或增量式多层变更 + 新领域规则 + 2 个以上测试文件53-5d
新模型/聚合，或迁移，或跨模块契约，或复杂测试（>1.5d），或新 UI + 非简单后端85-7d
新 UI 界面 +（新聚合或迁移或跨服务契约）13应拆分
跨服务契约 + 迁移组合13应拆分
超出以上范围21必须拆分

SP→天数（仅用于验证）： 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d（传统/AI 预计天数） AI 加速比： SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x。AI 成本 = (code_gen × 1.3) + (test_gen × 1.3)（30% 审查开销）。

强制前置元数据：

story_points: <n>
complexity: low | medium | high | critical
man_days_traditional: '<min>-<max>d' # likely ≥3d 时用范围；<3d 时用 '<N>d'
man_days_ai: '<min>-<max>d'
risk_margin_pct: <n> # 基础值 + 附加值
risk_factors: [touches-complex-existing-feature, regression-fan-out] # 来自附加值的封闭列表；没有则为 []
blast_radius:
    touched_areas: <n>
    complex_touched: <n>
    downstream_consumers: [列表或数量]
    shared_common_code: yes | no
estimate_scope_included: [代码，集成测试，前端，i18n，文档]
estimate_scope_excluded: [单元测试，端到端测试，性能测试，部署，代码审查轮次]
estimate_reasoning: |
    用 5-7 行说明：
    (a) UI 层级——应用的行
    (b) 后端层级——应用的行
    (c) 测试范围——按驱动因素拆分用例数、文件数、测试夹具、层级行
    (d) 成本驱动因素——占主导的层级及原因
    (e) 影响范围——改动项、复杂项、回归范围
    (f) 风险因素——导致余量的因素；说明为何余量不更大/更小
    示例："UI：组合 Form/Table/Dialog → 新屏幕（约 1.5d）。后端：在现有聚合上新增命令，
    复用验证和仓库（约 1d）。测试：4 个转换 × 2 个操作者 + 3 个验证规则 + 2 个 UI 状态 = 13 个用例，
    新增 1 个测试夹具 → 13-25 个用例层级，约 1.5d。驱动因素：UI 组合 + 新状态。影响范围：4 个区域，1 个复杂项。
    风险：基础值 35% + 复杂项改动 20% = 55% → 最大值 3.9d → 范围 2.5-4d。"

合理性自检：

  • likely_days ≥3d 却给出单点值？→ 拒绝，必须给出范围
  • likely_days ≥5d 时余量 <15%？→ 估算偏低，应扩大范围
  • 余量 >100%？→ 停止，改为拆分，而不是增加缓冲
  • 改动了现有复杂功能，但 (c) 中没有回归预算？→ 拒绝
  • 影响范围 >5 个区域或 >2 个复杂项，却没有讨论拆分？→ 拒绝
  • 仅在现有模型和现有 UI 上做增量修改？→ SP 上限为 3，除非测试 >1.5d
  • 新 UI 界面（页面/复杂表单/仪表板）？→ 即使后端只有一个端点，SP 也至少为 5
  • 后端涉及跨服务/迁移/多聚合？→ 无论 UI 如何，SP 至少为 8
  • bottom_up_hours / 6 与 SP-Days 的偏差 >50%？→ 以自下而上估算为准，调低 SP
  • 去掉测试后，SP 是否至少下降一个档位？→ 测试占主导；请明确说明
  • 推理是否说明了 UI 与后端的差异、影响范围和风险因素？→ 缺少则补充
  • MANDATORY MUST ATTENTION 估算：自下而上的阶段工时决定 man_days_traditional（Σh/6 × productivity_factor）；SP 为推导值。UI 成本通常占主导——如果新增 UI 界面（页面/复杂表单/仪表板），则将 SP 提高一个档位。Frontmatter MUST 包含 story_points、complexity、man_days_traditional、man_days_ai、estimate_scope_included、estimate_scope_excluded、estimate_reasoning（说明 UI 与后端的成本驱动因素）。除非测试范围超过 1.5d，否则基于现有模型和现有 UI 的增量工作，SP 上限为 3。SP 为 13 时 SHOULD 拆分，为 21 时 MUST 拆分。

IMPORTANT MUST ATTENTION 修改前，搜索 3+ 个现有模式并阅读代码。如果 graph.db 存在，则运行图追踪。

IMPORTANT MUST ATTENTION 每项声明都要引用 file:line 证据。置信度 >80% 才采取行动，<60% 时 = 不要提出建议。

MUST ATTENTION 运用批判性思维——每项声明都需要经过追踪的证据，置信度 >80% 才采取行动。防止幻觉：绝不要将猜测当作事实。

MUST ATTENTION 采取 AI 错误预防措施——先从整体入手进行调试，在责任层修复，在编码前明确歧义，并在压缩后重新阅读文件。

  • MANDATORY 在开始目标工作前，先初始化任务跟踪；每次只转换一个任务的状态。

  • MANDATORY 逐步将计划/审查发现保存到 plans/reports/，并基于磁盘中的内容综合整理。

  • MANDATORY 在完成任务跟踪初始化后、开始目标/源代码工作前，阅读必需的项目参考文档，并引用 Reference docs read: ...。

  • MANDATORY 始终包含 lessons.md；项目约定优先于通用默认规则。

IMPORTANT MUST ATTENTION 调试器追踪门槛：对于非简单的 Bug/修复/调查/审查工作，从观察到的最终输出开始，沿链路向上追踪：读取器 -> 存储/投影 -> 写入器 -> 消费者/作业 -> 生产者/触发器。列出所有供给路径和假设后再修复。在追踪、假设矩阵、责任修复层和前向收敛证明完成之前，禁止继续。

  • MANDATORY 父工作流行不能代替子阶段跟踪；存在嵌套时，展开各阶段并关联父项。
  • MANDATORY 编排器必须在调用前预先展开子技能阶段；使用 [N.M] $skill-name — phase 前缀，并遵守一次仅有一个 in_progress 任务的规则。

收尾提醒

IMPORTANT MUST ATTENTION 开始前，使用任务跟踪将工作拆分成较小的待办任务 IMPORTANT MUST ATTENTION 编写新代码前，在代码库中搜索 3+ 个相似模式 IMPORTANT MUST ATTENTION 为每项声明引用 file:line 证据（置信度 >80% 才采取行动） IMPORTANT MUST ATTENTION 添加最终审查待办任务，以验证工作质量 IMPORTANT MUST ATTENTION 修复尝试失败 3 次后停止——报告结果，并在进行第 4 次尝试前询问用户 MANDATORY IMPORTANT MUST ATTENTION 开始前，阅读以下文件：

[TASK-PLANNING] 行动前，分析任务范围，并使用任务跟踪系统地将任务拆分为较小的待办任务和子任务。

无 Hook 提示协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

  1. 检测： 将提示词与工作流目录进行匹配
  2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
  3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
    • 问题："你想启用哪个工作流？"
    • 选项 1："启用 [最佳匹配工作流]（推荐）"
    • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
  4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
  5. 创建任务： 跟踪工作流的所有步骤
  6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

  1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
  2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
  3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
  4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
  5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
  6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
  7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。

评论

支持 Markdown