fix-ui

Codex 兼容性说明：

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

Codex 项目参考资料加载（无钩子）

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

始终阅读：

• 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 开始，然后只打开与任务相关的文件。

快速摘要

**目标：**诊断并修复 UI/UX 问题，包括布局、样式、响应式表现和视觉缺陷。

工作流：

1. 识别 — 找到导致视觉问题的组件／模板
2. 诊断 — 跟踪 CSS／HTML／组件逻辑，找出根本原因
3. 修复 — 应用有针对性的修复（SCSS、模板、组件逻辑）
4. 验证 — 检查响应式行为和跨浏览器渲染

关键规则：

• 调试思维：每项断言都需要 file:line 证据
• 始终在模板元素上使用 BEM 类
• 修复布局问题时检查响应式断点

**预先阅读（设计系统）：**从 docs/project-config.json 加载 designSystem.canonicalDoc 和 tokenFiles，确保修复使用真实的令牌名称（--brand-*、$brand-*）和规范的组件类，而不是自行编造的值。

调试思维（不可妥协）

保持审慎。运用批判性思维和顺序思维。每项断言都必须有可追溯的证据，并附上置信度百分比（Idea 应高于 80%）。

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

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

强制重要要求，务必注意： 每项声明都必须标注 Confidence: X%，并附上证据列表和 file:line 证明。 95%+ 可自由推荐 | 80–94% 需注明注意事项 | 60–79% 列出未知事项 | <60% 停止——收集更多证据。

必备技能（按优先级排序）

1. ui-ux-pro-max - 设计智能数据库
2. web-design-guidelines - 设计原则
3. frontend-design - 实现模式

⚠️ 修复前先验证（不可妥协）： 找到 UI 根因后，必须注意通过直接提问向用户说明发现的问题和拟议的修复方案，并在进行任何代码更改前获得明确批准。不得擅自修复。

使用 ui-ux-designer 子代理阅读并分析 ./docs/design-guidelines.md，然后修复以下问题： $ARGUMENTS

工作流

首先：运行 ui-ux-pro-max 搜索，以了解背景和常见问题：

python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<product-type>" --domain product
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<style-keywords>" --domain style
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "z-index animation" --domain ux

如果用户提供了截图或视频，请使用 ai-multimodal 技能尽可能详细地描述问题，确保开发人员能根据描述轻松推断根因。

1. 使用 ui-ux-designer 子代理逐步实施修复。
2. 使用截图工具和 ai-multimodal 技能，截取已实施修复的截图（精确截取父容器，不要截取整个页面），并使用适当的 Gemini 分析技能（ai-multimodal、video-analysis 或 document-extraction）分析这些输出，以确保结果符合设计指南并解决所有问题。

• 如果问题仍未解决，重复此流程，直到所有问题都解决。

3. 使用 chrome-devtools 技能分析已实施的修复，并确保其符合设计指南。
4. 使用 tester Agent 测试修复并编译代码，确保其正常运行，然后向主 Agent 汇报。

• 如果存在问题或测试失败，请让主 Agent 修复所有问题，并重复此流程，直到所有测试通过。

5. 项目管理与文档： 如果用户批准更改： 并行使用 project-manager 和 docs-manager 子代理，更新项目进度和文档：
   • 使用 project-manager 子代理，在指定的计划文件中更新项目进度和任务状态。
   • 使用 docs-manager 子代理，根据需要更新 ./docs 目录中的文档。
   • 使用 project-manager 子代理，在 ./docs/project-roadmap.md 文件中创建项目路线图。
   • 重要： 为了简洁，写作时可牺牲语法规范。 如果用户拒绝更改： 请用户说明问题，并让主 Agent 修复所有问题，然后重复此流程。
6. 最终报告：

• 向用户汇报更改摘要，并简要说明所有内容、指导用户开始使用，并建议后续步骤。
• 询问用户是否要提交并推送到 Git 仓库；如果是，使用 git-manager 子代理提交并推送到 Git 仓库。
• 重要： 撰写报告时可牺牲语法规范，以求简洁。
• 重要： 如有未解决的问题，请在末尾列出。

请记住：

• 你可以随时使用 ai-multimodal 技能按需生成图像素材。

• 始终使用 ai-multimodal 技能分析并验证生成的素材是否符合要求。

• 如需移除背景、调整或裁剪图像，请酌情使用 media-processing 技能。

• 重要： 分析技能目录，并在执行过程中启用所需技能。

• 修复后，必须注意运行 $prove-fix——为每项更改构建代码证明轨迹并给出置信度评分。绝不可跳过。

[IMPORTANT] 开始前，使用任务跟踪将所有工作拆分为小任务——包括为每个待读取的文件创建任务。这可以防止长文件导致上下文丢失。对于简单任务，AI 必须主动询问用户是否跳过此步骤。

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

技能变体： $fix 的变体——UI／UX 视觉问题诊断与修复。

从结果到起点的调试追踪 — 对于非简单 Bug、验证失败、回归修复、会改变行为的代码，或代码流不明确的情况，先从观察到的最终状态开始，向后追踪，再提出修复方案。

1. 第 0 帧：观察到的最终状态 — 指明确切的用户可见输出、失败的断言、日志行、持久化值、API 响应、渲染出的 UI 或聚合分桶。记录生成该结果的读取器／查询／渲染器，并提供 文件:行号 证据。
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	最大预计天数
单个字段/配置标记/样式修复	1	0.5d
在现有模型中添加属性并绑定到现有 UI	2	1d
新增端点 + 轻量 UI 控件（按钮/菜单/列），复用测试夹具	3	2-3d
新增端点 + 新 UI 界面，或增量式多层变更 + 新领域规则 + 2 个以上测试文件	5	3-5d
新模型/聚合，或迁移，或跨模块契约，或复杂测试（>1.5d），或新 UI + 非简单后端	8	5-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 与后端的差异、影响范围和风险因素？→ 缺少则补充

• 必须重要务必注意：修改前搜索至少 3 个现有模式并阅读代码。如果 graph.db 存在，则运行图追踪。

• 必须重要务必注意：每项陈述都要引用 file:line 证据。置信度 >80% 才可采取行动，<60% = 不要提出建议。

• 必须务必注意：估算：自底向上的阶段工时决定 man_days_traditional（Σh/6 × productivity_factor）；SP 为推导值。UI 成本通常占主导——如果新增 UI 界面（页面／复杂表单／仪表板），将 SP 提高一个档位。Frontmatter 必须包含 story_points、complexity、man_days_traditional、man_days_ai、estimate_scope_included、estimate_scope_excluded、estimate_reasoning（说明 UI 与后端的成本驱动因素）。对于基于现有模型和现有 UI 的增量改动，SP 上限为 3，除非测试范围 >1.5 天。SP 为 13 时应拆分，SP 为 21 时必须拆分。

务必注意：运用批判性思维——每项陈述都需要可追溯的证据，置信度 >80% 才可采取行动。防止幻觉：绝不要把猜测当作事实。

务必注意：运用 AI 错误预防措施——先进行整体性调试，在负责的层级修复，在编码前明确歧义，压缩上下文后重新阅读文件。

• 必须在处理目标工作前初始化任务跟踪；一次只转换一个任务的状态。

• 必须逐步将计划／审查结果保存到 plans/reports/，并基于磁盘上的内容综合整理。

• 必须在任务跟踪初始化后、目标／源代码工作开始前，阅读必需的项目参考文档，并注明 Reference docs read: ...。

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

务必注意调试器追踪关卡：对于非简单的 bug／修复／调查／审查工作，从观察到的最终输出开始，沿链路向后追踪：reader → storage/projection → writer → consumer/job → producer/trigger。列出所有供给路径和假设，然后再修复。在以下内容齐备前不得继续：追踪结果、假设矩阵、负责的修复层，以及前向收敛证明。

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

收尾提醒

• 必须重要务必注意：开始前使用任务跟踪将工作拆分为小型待办任务
• 必须重要务必注意：编写新代码前，在代码库中搜索至少 3 个相似模式
• 必须重要务必注意：每项陈述都要引用 file:line 证据（置信度 >80% 才可采取行动）
• 必须重要务必注意：添加最终审查待办任务，以验证工作质量
• 必须重要务必注意：修复尝试失败 3 次后停止——报告结果，并在第 4 次尝试前询问用户 必须重要务必注意：开始前阅读以下文件：

[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] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。