design-describe

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
• 用户提问提示表示要直接在 Codex 中询问用户。
• 遇到 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按照该技能所述协议执行。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 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 设计文字描述。

工作流：

1. 分析 — 使用视觉能力处理视觉输入（屏幕截图／视频）
2. 描述 — 详细描述布局、颜色、字体排版和交互

关键规则：

• 使用 ai-multimodal 技能分析图像／视频
• 聚焦设计元素：布局、间距、颜色、字体排版、交互

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

认真思考，基于此屏幕截图／视频描述设计： $ARGUMENTS

必需技能（优先级顺序）

1. ui-ux-pro-max - 设计智能数据库（务必首先启用）
2. frontend-design - 视觉分析

在确保高质量的同时提高令牌使用效率。

工作流：

1. 使用 ai-multimodal 技能，详细描述截图／视频，方便开发者轻松实现。
   • 具体描述设计风格、每个元素、元素的位置、每项交互、每个动画、每个过渡效果、每种颜色、每条边框、每个图标、每种字体样式、字号、字重、每处间距、内边距、外边距、尺寸、形状、纹理、材质、光线、阴影、反射、折射、模糊、发光、每张图片、背景透明度等。
   • 重要： 尝试推测截图中的字体名称（Google Fonts）和字号，不要只选用 Inter 或 Poppins。
2. 使用 ui-ux-designer 子 Agent，按照渐进式披露结构制定设计实现计划，使结果与截图／视频一致：
   • 按照 ## Naming 部分中的命名模式创建目录。
   • 将概览入口保存为 plan.md，内容保持通用、不超过 80 行，并列出每个阶段及其状态／进度和链接。
   • 为每个阶段创建 phase-XX-phase-name.md 文件，并包含以下部分：上下文链接、概览（含日期／优先级／状态）、关键见解、需求、架构、相关代码文件、实现步骤、待办事项、成功标准、风险评估、安全注意事项、后续步骤。
3. 向用户汇报计划摘要。

---

[IMPORTANT] 开始前，使用任务跟踪将所有工作拆分为小任务，包括每个待读取文件对应的任务。这有助于避免长文件造成上下文丢失。对于简单任务，AI 必须先询问用户是否要跳过。

技能变体： 设计技能的变体——根据截图或视频描述 UI。

AI 错误预防 — 每项任务都应避免以下失误：

删除前检查下游引用。 删除组件会导致文档和代码出现连锁过时问题。删除前，梳理所有引用该组件的文件。 对照实际代码验证 AI 生成的内容。 AI 可能会虚构 API、类名和方法签名。记录或引用之前，务必使用 grep 确认其存在。 编辑后追踪完整依赖链。 修改定义时，遗漏下游变量及其使用方会造成问题。务必追踪完整依赖链。 验证正确性时追踪所有代码路径。 确认代码存在不等于确认代码会执行。务必检查提前返回、错误分支和条件跳过，不要只验证正常路径。 调试时，先问“这是谁的职责？”再修复。 追踪问题究竟出在调用方（数据错误）还是被调用方（处理不当）。在责任所属的层级修复，切勿只修补表象。 假设现有值是有意设置的——修改前先问原因。 修改任何常量、限制、标志或模式之前，先阅读注释、查看 git blame，并检查周边代码。 验证所有受影响的输出，不要只检查第一个。 涉及多个技术栈的改动，必须验证每个输出。一个检查通过不代表全部通过。 先整体再局部地调试——避免注意力被最近的问题牵着走。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、依赖注入注册、数据前提），再逐一根据证据核实，然后再提出代码层面的假设。 精准修改——应用差异测试。 修复 Bug 时，每处改动都必须能直接对应到 Bug。不要顺带重设样式或改进相邻代码。增强任务：实施改进并明确告知用户。 编码前指出歧义——不要默默自行选择。 如果请求存在多种解读，列出每种解读及其工作量估算并询问用户。切勿自行假设采用全记录、基于文件或更复杂的方案。 批判性思维模式 — 运用批判性思维和顺序思维。每项声明都需要可追溯的证据，置信度 >80% 才能采取行动。 防止幻觉： 绝不把猜测当作事实陈述 — 为每项声明引用来源，坦诚承认不确定性，自查输出是否有误，独立交叉验证，并对自己的信心保持怀疑 — 毫无证据的确定性是所有幻觉的根源。

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

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

收尾提醒

• 强制、重要、务必注意：开始前使用任务跟踪，将工作拆分为小型待办任务
• 强制、重要、务必注意：创建新代码前，在代码库中搜索至少 3 个类似模式
• 强制、重要、务必注意：为每项声明引用 file:line 证据（置信度 >80% 才能采取行动）
• 强制、重要、务必注意：添加最终审核待办任务，以验证工作质量

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

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

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

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

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

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，并采用以下结构；除非用户明确调用了某个工作流/技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [BestMatch Workflow]（推荐）"
   • 选项 2："启用自定义工作流：[step1 → step2 → ...]"（附上一句话说明理由）
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] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。