frontend-design

Codex 兼容性说明：

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

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

Codex 使用静态项目参考资料加载，而不是运行时注入项目文档。 进行编码、规划、调试、测试或审查时，请按照此路由显式打开项目文档。

始终阅读：

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

缺失或过时的上下文路由： 如果 docs/project-config.json、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任何任务所需的参考文档缺失或过时，请在常规项目工作前自动运行 $project-init 或范围更窄的设置路由（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）。如果 Codex 镜像或 AGENTS.md 缺失或过时，请要求用户运行 $sync-codex；不要自动运行它。

按情况查阅文档：

• 后端/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
• 编写规范、docs/specs/ 路径或 TC 格式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 行为/公共契约变更或规范-测试-代码同步：workflow-spec-test-code-cycle-reference.md 以及上述规范文档
• 派生规范索引/ERD/重新实现指南：spec-system-reference.md 和 docs/specs/ 下的源 Feature Specs
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件查阅的领域文档

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

[BLOCKING] 按声明的顺序执行技能步骤。未经用户明确批准，绝不跳过、重排或合并步骤。 [BLOCKING] 在每个步骤或子技能调用之前，更新任务跟踪：步骤开始时设为 in_progress，结束时设为 completed。 [BLOCKING] 每个已完成或已跳过的步骤都必须附上简要证据或明确的跳过原因。 [BLOCKING] 如果无法使用 Task 工具，请创建并维护具有相同状态转换的等效逐步计划跟踪器。

快速摘要

目标： 打造独具特色、达到生产级水准且设计品质出众的前端界面，避免千篇一律的 AI 风格。

工作流：

1. 检测输入类型 — 用户提供了截图/图像，还是需要从头构建
2. 提取设计指南 — 对于截图：使用视觉分析工具分析颜色、字体、间距和布局
3. 设计思考 — 选择大胆的美学方向（基调、差异化、约束条件）
4. 编写代码 — 编写达到生产级水准、视觉出众且风格统一的代码
5. 验证质量 — 将实现与原始设计/构想进行对比

关键规则：

前端/UI 上下文（如适用）

当任务涉及前端或 UI 改动时，

• 组件模式：docs/project-reference/frontend-patterns-reference.md
• 样式/BEM 指南：docs/project-reference/scss-styling-guide.md
• 设计系统令牌：docs/project-reference/design-system/README.md

SCSS/BEM 规则（规范）： 所有模板元素都必须使用 BEM 类名（block__element--modifier）。禁止使用魔法数字 — 使用变量/设计令牌。嵌套层级最多为 3 层。

• 对于截图输入，先提取设计指南，再编写代码
• 选择独具特色、富有个性的字体和大胆统一的配色 — 切勿使用通用字体（Inter、Roboto、Arial）或陈词滥调的配色方案
• 让实现的复杂度与美学构想相匹配（极繁主义 = 精心设计，极简主义 = 精准克制）

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

此技能旨在指导创建独具特色、达到生产级水准的前端界面，避免千篇一律的“AI 垃圾”风格。编写真正可用的代码，并对美学细节和创意选择给予格外关注。

用户会提供前端需求：需要构建的组件、页面、应用或界面。他们可能会补充相关背景，例如用途、受众或技术约束。

前置条件

⚠️ 必须仔细阅读 references/design-extraction-overview.md，然后再执行基于截图的工作流 — 其中包含设计指南提取流程、分析提示词，以及截图/图像输入工作流所需的视觉验证方法。对于素材生成工作流，还必须阅读 references/asset-generation.md。

输入类型与工作流

用户提供截图/图像/设计参考时

截图/图像/设计输入的强制工作流：

1. 提取设计指南，使用 ./references/design-extraction-overview.md：

   • 使用视觉分析工具分析截图/图像
   • 提取：颜色（十六进制代码）、字体（字体、字号、字重）、间距比例、布局模式、视觉层级
   • 将发现记录在项目的 docs/design-guidelines/extracted-design.md 中
   • 完整分析提示词参见 ./references/extraction-prompts.md

2. 编写代码，遵循提取的指南：

   • 使用提取结果中的精确颜色（十六进制代码）
   • 匹配字体规范（字体、字号、字重、行高）
   • 复现布局结构和间距系统
   • 保持视觉层级和组件模式
   • 保留美学方向和氛围

3. 验证质量，使用 ./references/visual-analysis-overview.md：

   • 将实现与原始截图进行对比
   • 检查颜色准确度、间距一致性和字体匹配度
   • 确保保留所有设计元素

重要： 不要直接开始实现。必须先提取设计指南，再编写代码。

从头构建时（未提供截图）

按照下文的“设计思考”流程创建原创设计。

设计思维

开始编码前，先了解背景，并确立一个大胆的美学方向：

• 目的：这个界面要解决什么问题？谁会使用它？
• 基调：选择一种极致风格：极简到极致、极繁主义的混乱、复古未来主义、有机／自然、奢华／精致、俏皮／玩具感、编辑／杂志风、粗野／原始、装饰艺术／几何、柔和／粉彩、工业／实用主义等。可选风格非常多。可以从中汲取灵感，但最终设计要忠于所选的美学方向。
• 约束：技术要求（框架、性能、无障碍）。
• 差异化：什么能让人难以忘怀？人们会记住的亮点是什么？

至关重要：选择明确的概念方向，并精准地贯彻到底。大胆的极繁主义与精致的极简主义都行得通——关键在于有意识地设计，而不是追求强烈。

然后实现可运行的代码（HTML/CSS/JS、React、Vue 等），要求：

• 达到生产级品质且功能完善
• 视觉出众、令人印象深刻
• 风格统一，审美观点清晰
• 每个细节都经过精心打磨

前端美学指南

重点关注：

• 字体排印：选择优美、独特、有趣的字体。避免使用 Arial 和 Inter 等通用字体，转而选择能提升前端美感的鲜明字体；尝试出人意料、富有个性的字体搭配。将独特的展示字体与精致的正文字体配对。
• 色彩与主题：坚持统一的美学风格。使用 CSS 变量保持一致。主色鲜明、点缀色突出，胜过犹豫不决、均匀分布的配色方案。
• 动效：使用动画呈现效果与微交互。对于 HTML，优先采用纯 CSS 方案。React 可用时使用 Motion 库（使用 anime.js 实现动画：./references/animejs.md）。聚焦于影响力大的时刻：一次精心编排、带有错落显现效果（animation-delay）的页面加载，比零散的微交互更能带来惊喜。加入滚动触发效果和出人意料的悬停状态。
• 空间构图：尝试出人意料的布局、不对称、重叠、对角流动、打破网格的元素，以及宽裕的留白或受控的密集布局。
• 背景与视觉细节：营造氛围和层次感，而不是默认使用纯色。添加符合整体风格的环境效果与纹理。运用富有创意的形式，例如渐变网格、噪点纹理、几何图案、分层透明效果、戏剧性阴影、装饰边框、自定义光标和颗粒叠加效果。
• 视觉素材：使用 visual analysis tooling 技能生成素材；如有需要，使用媒体处理工具去除生成素材的背景

使用视觉素材

快速入门：./references/visual-tooling-overview.md

生成新的视觉素材

生成符合设计美学的全新主视觉图、背景、纹理或装饰元素时，请使用 visual analysis tooling 技能。这样可以确保生成的素材符合设计思维和美学指南，而不是产出千篇一律的图像。

分析提供的截图／图像／设计稿

当用户提供截图、照片或设计参考供分析或复刻时，请在实现之前使用 ./references/design-extraction-overview.md 提取设计指南。对于截图输入，此步骤为必做项（参见上文“输入类型与工作流”）。

工作流：

• ./references/asset-generation.md - 生成与设计风格一致的视觉素材
• ./references/visual-analysis-overview.md - 分析并验证素材质量（模块化）
• ./references/design-extraction-overview.md - 从灵感参考中提取指南（模块化）
• ./references/technical-overview.md - 优化与最佳实践（模块化）

每份概述都引用了详细的子模块，以便逐步展开内容。

绝不要使用泛泛的 AI 生成审美，例如过度使用的字体系列（Inter、Roboto、Arial、system fonts）、陈词滥调的配色方案（尤其是白色背景上的紫色渐变）、可预见的布局和组件模式，以及缺乏情境特色的千篇一律的设计。

发挥创意，做出出人意料、又真正贴合情境的选择。每个设计都应该与众不同。在浅色和深色主题、不同字体及不同美学风格之间灵活变化。绝不要在不同生成结果中趋同于常见选择（例如 Space Grotesk）。

重要：让实现的复杂度与美学构想相匹配。极繁主义设计需要精巧的代码，并配以丰富的动画和效果。极简或精致的设计则需要克制、精准，并仔细关注间距、排版和细微之处。优雅源于对构想的出色呈现。

请记住：Claude 能够完成非凡的创意作品。不要有所保留，尽情展现跳出框架思考并全力打造鲜明独特构想时，真正能够创造出的成果。

相关内容

• interface-design — 产品 UI（仪表盘、管理面板、SaaS 应用）
• ui-ux-pro-max
• shadcn-tailwind

---

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

防止 AI 出错 — 每项任务都要避免以下故障模式：

上下文变化后重新读取文件。 上下文压缩、恢复工作或长时间运行的任务都可能导致记忆过时；采取行动前，请核实当前文件内容。 根据源证据核实生成的内容。 AI 可能会编造 API、名称、声明和文档事实。记录或引用信息前，请检查相关源内容。 删除或重命名前，检查下游引用。 删除某项内容可能导致文档、生成的镜像、配置和调用方过时；先梳理引用关系。 编辑后追踪完整影响链。 修改定义可能会遗漏派生输出和使用方。宣布完成前，请追踪所有受影响的环节。 核实所有受影响的输出，而不仅是第一个。 一项检查通过不代表所有检查都通过；请验证变更可能影响的每个输出界面。 假定现有值是有意设置的——更改前先询问原因。 更改常量、限制、标志、措辞或模式前，请先阅读附近上下文和历史记录。 行动前明确说明模糊之处——不要默默做出选择。 存在多种合理解释时，必须明确提问或说明假设及其风险。 确保共享指导与接收方角色相关。 通用指导必须对每个接收该指导的技能或 Agent 都有帮助；代码专属要求只能放在代码专属规范中。

UI 系统上下文 — 任何涉及 .ts、.html、.scss 或 .css 文件的任务：

实现前必须仔细阅读：

1. docs/project-reference/frontend-patterns-reference.md — 组件基类、存储、表单
2. docs/project-reference/scss-styling-guide.md — BEM 方法、SCSS 变量、混入、响应式设计
3. docs/project-reference/design-system/README.md — 设计令牌、组件清单、图标

请参考 docs/project-config.json，了解项目特定路径。

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

• 必须仔细阅读： 任何 UI 变更前，都必须阅读 frontend-patterns-reference、scss-styling-guide、design-system/README。

必须仔细运用批判性思维和顺序思维——每项主张都必须有适当且可追溯的证据（仓库或代码主张需提供 file:line；研究、产品、内容和文档主张需提供源 URL 或文档章节）；置信度高于 80% 才能采取行动，低于 60% 时不得提出建议。防止幻觉：不要将猜测当作事实；坦诚承认不确定性；独立交叉核对；对自己的判断保持怀疑。

必须仔细落实 AI 防错措施——根据证据核实生成的内容；删除或重命名前追踪下游引用；核实所有受影响的输出；上下文丢失后重新读取文件；行动前明确说明模糊之处。

Prompt-Enhance Closing Anchors

重要，务必注意：遵循此技能中声明的步骤顺序；未经用户明确批准，绝不跳过、重排或合并步骤 重要，务必注意：每个步骤／子技能调用都必须在执行前设为 in_progress，执行后设为 completed 重要，务必注意：每个跳过的步骤都必须说明明确理由；每个已完成的步骤都必须提供简要证据 重要，务必注意：如果 Task 工具不可用，必须维护一个状态同步的等效分步计划跟踪器

结束提醒

重要，务必注意：当前生效的协议（对此技能包含的 SYNC／共享内容块的简要摘要）：

• **防止 AI 出错：**根据证据核验生成的内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。

• **UI 系统上下文：**在进行任何 UI 更改前，阅读 frontend-patterns、scss-styling 和 design-system 文档。

• **批判性思维：**每项主张都需要可追溯的 file:line 证据；只有在置信度 >80% 时才采取行动。

• 强制，重要，务必注意：开始前，使用任务跟踪将工作拆分为小型待办任务

• 强制，重要，务必注意：创建新代码前，在代码库中搜索至少 3 个类似模式

• 强制，重要，务必注意：为每项主张提供 file:line 证据（置信度 >80% 时才采取行动）

• 强制，重要，务必注意：添加最终审核待办任务，以核验工作质量 强制，重要，务必注意：开始前阅读以下文件：

• 强制，重要，务必注意：开始前阅读 references/design-extraction-overview.md

• 强制，重要，务必注意：开始前阅读 references/asset-generation.md

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

[IMPORTANT] 分析任务规模，并在开始前有条理地将其拆分为多个小型待办任务——这非常重要。

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

来源：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full 块）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[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，然后打开其中列出的项目参考文档。对于规范、测试用例、行为变更、公共契约或 docs/specs/ 相关工作，请通过文档索引中列出的本地规范文档处理：当规范/测试/代码必须保持同步时，使用 feature-spec-reference.md、spec-system-reference.md、spec-principles.md 和 workflow-spec-test-code-cycle-reference.md。如果任一文件或必需的参考文档缺失或已过时，请在开展常规项目专属工作前自动运行 $project-init（或范围更窄的底层流程，例如 $project-config、$docs-init、$scan-all 或 $scan --target=<key>）。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 如果提示以明确的斜杠技能/工作流命令开头，则直接执行。否则，将提示与工作流目录和技能列表进行匹配。
2. 分析： 选择最佳方案：直接执行、调用技能、启动标准工作流，或组合自定义步骤。
3. 自动选择： 自行选择最佳方案。不要询问用户是在直接执行、调用技能、使用标准工作流还是自定义工作流之间进行选择。
4. 启动： 对于选定的工作流，调用 $start-workflow <workflowId>；对于选定的技能，调用该技能；对于自定义工作流，直接按顺序执行自定义步骤；对于直接执行，继续处理任务。
5. 创建任务： 当所选路径包含多个步骤时，在执行前为所有工作流/技能/自定义步骤创建任务跟踪项。
6. 执行： 按照上下文说明中的 工作流步骤推进与并行阶段 规则推进 — 由模型驱动；子代理完成与内联调用完成的效果相同，都会推进步骤；并行阶段组必须等待所有成员返回后才能推进，绝不可串行执行。

共享 AI-SDD 协议标记

来源：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 工件契约 — 共享的规范驱动开发规则应保持可移植，并由源文件维护。

1. 将可复用的 AI-SDD 原则保留在 .claude 中；将仓库专属路径、命令、负责人、产品和格式放入项目配置/参考文档。
2. 保持以下周期：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. 通过决策、任务、TC/测试、源代码证据和文档/规范更新，追踪每项需求或不变量。
4. 从代码提取规范仅可作为参考，直到规范的权威负责人接受为止。
5. 只要具备同步后的上下文，任何受支持的 AI 工具都可以规划、实现、审查或验证；使用多个工具并非必需。
6. 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。——原因：镜像是生成的工件；下次同步时，手动修改会被覆盖。
7. 如果 docs/project-config.json、根指令文件或必需的项目参考文档缺失或已过时，请在开展常规项目专属工作前自动运行 $project-init 或范围更窄的底层流程。

当前参考文档： 当前技能根目录中的 shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• MANDATORY 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 保留在 .claude 中，并将本地规则放在项目文档中。
• MANDATORY 在规范获得正式验收之前，代码到规范的提取仅供参考；任何受支持的 AI 工具都可以在同步后的上下文中执行操作。
• MANDATORY 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• MANDATORY 如果缺少项目配置、根指令文件或必需的参考文档，或这些文件已过时，则项目专属工作会自动通过 $project-init 或范围更窄的设置流程进行。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后随着每个步骤的开始和完成持续同步任务跟踪。

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

开始之前，将工作拆分为小任务（任务跟踪）。添加最终任务：“分析 AI 错误与经验教训”。

提炼经验教训 — 只分析根本原因，不要修复表面症状：

1. 指明失败模式（推理或假设方面的失误），而非症状——“未阅读源代码便假定 API 存在”，而非“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境或代码库？如果不适用，则再抽象一层。
3. 写成通用规则——去除项目专属名称、路径和类名。该规则应适用于任何代码库。
4. 合并：多个错误若源于同一种失败模式，则归纳为一条经验教训。
5. 复发门槛：“如果没有这条提醒，此问题会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复门槛：“$code-review、$code-simplifier、$security-review 或 $lint 能发现这个问题吗？”——能 → 改进审查技能。
7. 两项门槛都通过 → 请用户运行 $learn。 [CRITICAL-THINKING-MINDSET] 运用批判性思维和序列化思维。每项结论都必须有可追溯的证据，且置信度须高于 80% 才能采取行动。 **防幻觉原则：**绝不把猜测当成事实——为每项结论引用来源，坦诚说明不确定之处，自行检查输出是否有误，独立交叉验证，并对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 **AI 注意力原则（首因—近因效应）：**对于较长的提示词或协议，将最关键的 3 条规则同时放在开头和结尾，确保指令遵循在长上下文窗口中依然有效。 **目标驱动执行：**先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 **测试验证意图：**测试必须保护业务规则和不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

常见 AI 错误预防（系统经验教训）

• 上下文压缩后重新读取文件。 编辑前必须在同一上下文中先读取文件；压缩会清除读取状态。编辑前重新读取。
• 批量替换后搜索旧术语。 AI 过度相信查找/替换的完整性。批量编辑后，在整个仓库中搜索遗漏的文档、配置和目录引用。
• 删除前检查下游引用。 删除会连带导致文档/代码过时。先梳理引用文件，再进行删除。
• 记忆丢失后，创建新内容前先检查现有状态。 压缩会清除先前工作的记忆。查询当前状态以继续工作——切勿盲目重复。
• 根据实际代码验证 AI 生成的内容。 AI 会臆造 API、类名和方法签名。记录或引用前，先用 grep 确认它们确实存在。
• 编辑后追踪完整依赖链。 修改定义会遗漏下游使用方。追踪完整依赖链。
• 重命名时，搜索所有使用方的文件类型。 有些文件类型会静默忽略缺失的引用（不会产生编译错误）。搜索代码、模板、配置和生成文件。
• 验证正确性时，追踪所有代码路径。 代码存在 ≠ 代码会执行。追踪提前退出、错误分支和条件跳过——不只检查正常路径。
• 源数据变更后，更新内嵌规范数据的文档。 内嵌派生数据（工作流、架构、配置）的文档会悄无声息地过时。源数据变更时，同时更新所有内嵌该数据的文档。
• 上下文恢复后，验证子 Agent 的结果。 后台 Agent 可能在父 Agent 压缩期间完成——用 grep 验证输出，不要假定其已完成。
• 将完整目标列表与子 Agent 的任务分配交叉核对。 按类别并行分配子 Agent 会遗漏边界项。继续前，将所有任务分配的并集与目标列表核对。
• 子 Agent 只会从其 Agent .md 定义中继承知识——使用自定义 Agent 类型，不要使用内置 Explore。 采用工具 = 权限 + 知识 + 强制执行（编号工作流步骤）。
• 逐步保存子 Agent 的发现，不要等到最后一次性保存。 长时间运行的子 Agent 可能在最终写入前触及截断限制——导致发现丢失。要求按章节追加到报告文件。
• 调试时，修复前先问“这是谁的责任？”。 追踪调用方（数据错误）还是被调用方（处理错误）。在责任所在的层修复——绝不要只修补症状出现的位置。
• 提取/重构后，搜索所有已移除的名称。 主文件“完成” ≠ 次要文件已清理。宣布完成前，在整个范围内搜索每个已移除的符号。
• 假定现有值是有意设置的——更改前先问为什么。 将其模式匹配为“错误”会忽略上下文。更改任何常量/限制/标志前，先阅读注释、git blame 和周边代码。
• 验证所有受影响的输出，而不只是第一个。 一个构建通过 ≠ 全部通过。涉及多技术栈的更改（后端/前端/测试/文档）必须验证每一项输出。
• 复制附近的模式前，先评估是否适用。 最接近的示例 ≠ 满足相同前提——确认新上下文具有相同的约束、基类、作用域和生命周期。
• 整体优先的调试方式——抵制注意力就近陷阱。 不要直接钻进第一个看似合理的原因。列出所有前提（配置、环境变量、路径、数据库、端点、凭据、版本、DI、数据）。根据证据（grep/查询——而非推理）逐一验证。问“什么情况会证伪这个假设？”——如果没有，那它就不是假设。代价最高的失败：在“显而易见”的层里越挖越深，而 bug 实际上位于从未质疑过的层。
• 精准改动——应用 diff 测试（结合上下文）。 两种模式：(1) Bug 修复 → 每一行都必须能追溯到该 bug；不做样式调整；只有由你所做更改导致未使用的导入，才清理孤立项。(2) 审查/增强 → 实施改进，并声明为“超出主要请求的增强：[内容]”。绝不悄悄扩大范围。Diff 测试：“如果没人要求我做 X，这一行还会存在吗？”——如果不会，就删除或明确说明。
• 编码前先指出歧义——不要默默选择。 存在多种有效解读时，分别列出并说明工作量：“[请求] 可能指 (1) [N 小时]、(2) [N 小时]。哪种更重要？”先列出对范围/格式/数量/约束的假设。如果存在更简单的路径，请说明。绝不默默自行选择。
• [强制首要操作] 回复前务必先启用合适的技能或工作流。 将任务与工作流目录及技能列表匹配；通过技能调用或 $start-workflow <workflowId> 启用。在检查前绝不回答或编写代码。跳过 = 违反协议。
• Why-Review 对抗性思维——审查任何计划、决策或设计时应用。 默认立场应为怀疑者，而非验证者：以最有力的方式阐述被否决的方案，反转每个给出的理由（“它牺牲了什么？”），对最重要的 2-3 个假设进行压力测试，开展事前验尸（“已发布，3 个月后失败——什么出了问题？”），提出作者遗漏的 1-2 个替代方案。有相应章节 ≠ 质量高；质量取决于因果推理 + 具体缓解措施 + 证据，而不是“这样更好”或“密切监控”。
• 大型审查的子 Agent 提示词应优先安排写报告。 涉及多个文件的子 Agent 可能在最终写入前耗尽预算——导致发现丢失。设计提示词时确保：(1) 写报告是第一个明确交付项，(2) 按文件/章节逐项追加（而非批量写入），(3) 限定范围，避免读取耗尽预算。若输出在句中截断且没有报告文件 → 启动范围更窄的任务，不要用同一提示词重试。
• 上下文压缩后，继续前重新验证所有先前阶段的结果。 摘要描述的是意图，而非环境状态（git 索引、文件系统、进程）。恢复时，首先审查：git status、重新读取修改过的文件、验证文件系统。每个“已完成”的说法，在证据确认之前都只是未经验证的假设。
• OOM/内存：先检查行数，再检查行大小。 排查顺序：(1) 无界查询——触发条件是否缺少数据库筛选？将筛选推到数据库端；这可消除 OOM。(2) 行是否很大？投影可按比例降低开销。减少行数的投入产出比高于投影。
• 不要将领域概念放入通用/共享/基础设施层。 可复用层（共享库、框架、基础设施模块）不得引用任何使用方专属的领域概念——租户/客户/产品 ID、业务实体、功能规则。泄漏编译并运行后，会在代码评审中悄无声息地通过，同时使“可复用”层耦合到某一个使用方。保持共享类型不含领域概念；通过子类/组合，将领域字段/逻辑下沉到使用方。——原因：与某个使用方领域耦合的层不再可复用。