test-specs-docs

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 在此 Codex 镜像中，规划时优先使用 plan-hard 技能。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先为所有步骤创建／更新任务跟踪，并随着进度变化保持同步。
• 用户提问提示意味着要在 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 开始，然后仅打开与任务相关的文件。

[IMPORTANT] 务必注意保持任务跟踪同步、保留证据关卡，绝 NEVER 跳过强制步骤。

[DEPRECATED] 此技能已合并到 $tdd-spec。请改用 $tdd-spec [direction=sync]。

• 正向同步（功能文档 → 仪表板）：$tdd-spec [direction=sync]
• 反向同步（仪表板 → 功能文档）：$tdd-spec [direction=reverse]
• 双向协调：$tdd-spec [direction=full]

所有同步算法、孤立项检测、过时状态跟踪和质量关卡现均位于 $tdd-spec 的 ## Mode: Sync to Dashboard 部分。

快速摘要

目标： [DEPRECATED] 此技能已合并到 tdd-spec。正向同步请使用 $tdd-spec [direction=sync]，反向同步请使用 $tdd-spec [direction=reverse]，双向协调请使用 $tdd-spec [direction=full]。

工作流：

1. 检测 — 对请求范围和目标产物进行分类。
2. 执行 — 通过有证据支持的操作完成所需步骤。
3. 验证 — 确认约束、输出质量和完成证据。

关键规则：

• 务必注意，声明必须有证据支持（file:line），且置信度 >80% 才能采取行动。
• 务必注意，在每个步骤开始／完成时更新任务跟踪。
• 绝 NEVER 跳过强制工作流或技能关卡。

---

收尾提醒

重要：务必注意，先执行第 1 阶段的压缩，再进行结构增强；保留语义不变。 重要：务必注意，优化时绝不要修改 YAML frontmatter、代码块、表格或 SYNC 标签正文。 重要：务必注意，明确列出证据门槛以及强制执行的工作流／技能步骤，并确保其可执行。 重要：务必注意，添加最终审核任务，以检查输出质量和未解决的风险。

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

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

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制执行，非常重要，务必注意，至关重要。无论任何原因，都不得跳过。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最佳匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 按照以下结构直接询问用户：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [BestMatch Workflow]（推荐）”
   • 选项 2：“启用自定义工作流：[step1 → step2 → ...]”（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤则手动依序执行
5. 创建任务： 为工作流的所有步骤创建任务跟踪
6. 执行： 按顺序执行每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项主张都需要可追溯的证据，置信度须高于 80% 才能采取行动。 反幻觉原则： 绝不要将猜测当作事实陈述；为每项主张注明来源，坦承不确定之处，自查输出错误，独立交叉核实，始终对自身信心持审慎态度——没有证据的确定性是所有幻觉的根源。 AI 注意力原则（首因－近因）： 在长提示词／协议的开头和结尾都放置最重要的 3 条规则，以便指令在长上下文窗口中仍能得到遵循。

经验教训

经验教训

[CRITICAL] 经过艰难排查得出的项目调试／架构规则。在形成假设或编写代码之前，务必注意并应用。

快速摘要

目标： 防止已知故障模式再次发生——涵盖调试、架构、命名、AI 编排和环境。

首要规则（始终应用）：

• 务必注意：在提出代码层假设之前，验证所有前置条件（配置、环境、数据库名称、DI 注册）
• 务必注意：修复责任层——绝不要用针对特定调用方的防御性代码修补症状出现的位置
• 务必注意：并行异步操作与仓储／UoW 搭配时，使用 ExecuteInjectScopedAsync——绝不要使用 ExecuteUowTask
• 务必注意：按用途而非内容命名——添加成员就必须重命名，说明抽象已失效
• 务必注意：每处理完一个文件，就增量保存子 Agent 的发现——绝不要拖到最后批量处理
• 务必注意：Windows bash 环境中，先验证 Python 别名（where python／where py）——绝不要假定 python／python3 可用

---

调试与根因推理

• [2026-04-11] 优先全面检查：先验证环境，再看代码。 发生故障 → 列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、凭据、权限、数据前提）→ 在提出代码层面的假设之前，先通过证据（grep/cat/query）逐一验证。最容易陷入的误区：只钻研最接近的层，而问题实际出在别处——例如，花数小时调试“同步超时”，真正原因却是测试 appsettings 指向了错误的数据库。先做成本最低的检查。
• [2026-04-01] 修复前先问“谁负责？” 追踪问题：是调用方（数据错误）还是被调用方（处理错误）？修复负责的那一层——绝不在症状出现的位置打补丁，以免掩盖真正的问题。
• [2026-04-01] 追踪数据的生命周期，而不是错误出现的位置。 跟踪数据：创建 → 转换 → 使用。问题通常出在数据创建错误，而非使用数据的地方。
• [2026-04-01] 代码与调用方无关。 函数/处理器/消费者不知道是谁调用了它们。注释/防护逻辑/消息应描述业务意图——绝不提及特定调用方（测试、种子数据器、脚本）。

架构不变量

• [2026-03-31] ParallelAsync + repo/UoW 必须使用 ExecuteInjectScopedAsync，绝不能使用 ExecuteUowTask。 ExecuteUowTask 会创建新的 UoW，但复用外层 DI 作用域（同一个 DbContext）——并行迭代共享非线程安全的 DbContext，会静默破坏数据。ExecuteInjectScopedAsync 会创建新的 UoW 和 DI 作用域（每次迭代都使用全新的 repo）。
• [2026-03-31] Bus 消息名称必须包含服务名称前缀——核心服务绝不消费功能事件。 前缀声明了架构所有权（AccountUserEntityEventBusMessage = 由 Accounts 负责）。核心服务（Accounts、Communication）是领导者。向核心服务发送消息的功能服务（Growth、Talents）必须使用 {CoreServiceName}...RequestBusMessage——绝不能定义供核心服务消费的自有事件。

命名与抽象

• [2026-04-12] 名称应体现用途，而非内容——“OrXxx”反模式。 HrManagerOrHrOrPayrollHrOperationsPolicy 命名的是成员集合，而非它所保护的内容。添加角色 → 重命名 = 抽象失效。规则： 名称应表达执行/保护什么，而非包含什么。检验： 添加/移除成员是否会迫使你重命名？是 = 由内容决定 = 不妥 → 改为体现用途的名称（例如，HrOperationsAccessPolicy）。注意： 行为习语中的“Or”没问题（FirstOrDefault、SuccessOrThrow）——它表达的是发生的行为，而非成员关系。

环境与工具

• [2026-04-20] Windows bash：绝不假设 python/python3 能解析——先验证别名。 Python 可能不会以这些名称出现在 bash PATH 中。检查：where python / where py。单行命令优先使用 py（Windows Python Launcher）；如果有 JS 替代方案，也可使用 node。

测试专属经验 → docs/project-reference/integration-test-reference.md 的 Lessons Learned 部分。生产代码反模式 → docs/project-reference/backend-patterns-reference.md 的 Anti-Patterns 部分。通用调试/重构提醒 → .claude/hooks/lib/prompt-injections.cjs 中的 System Lessons。

---

收尾提醒

• IMPORTANT MUST ATTENTION 全面优先：在提出代码层面的假设之前，先核查所有前置条件（配置、环境、数据库名称、端点、DI 注册）——优先检查成本最低的项目
• IMPORTANT MUST ATTENTION 修复责任层：绝不要在症状出现的位置打补丁；追溯调用方（数据错误）还是被调用方（处理错误），修复根因责任方
• IMPORTANT MUST ATTENTION 并行异步 + 仓储/UoW → 始终使用 ExecuteInjectScopedAsync，绝不要使用 ExecuteUowTask（共享 DbContext 会导致静默数据损坏）
• IMPORTANT MUST ATTENTION 总线消息前缀 = 架构所有权；功能服务绝不能为核心服务定义事件——使用 {CoreServiceName}...RequestBusMessage
• IMPORTANT MUST ATTENTION 按用途命名——添加或移除成员就会迫使重命名，说明抽象存在问题
• IMPORTANT MUST ATTENTION 子 Agent 必须在完成每个文件/章节后写入发现——绝不要把所有发现都集中到最后一次写入
• IMPORTANT MUST ATTENTION Windows bash：绝不要假设 python/python3 能正常解析——先运行 where python/where py，使用 py 启动器或 node

[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] 执行任何工作流或技能步骤之前，先创建/更新任务跟踪，列出所有计划步骤；之后，每当步骤开始/完成时，都要同步更新任务跟踪。