mcpField
P
product-owner

product-owner

github.com/duc01226生产力12110 次安装1 周前更新
代码仓库

关于 product-owner

product-owner 是面向产品负责人的技能，用于整理创意、管理待办事项并支持优先级决策。它结合 RICE、MoSCoW 和价值／工作量框架，并要求结合项目领域上下文与用户验证。

主要功能

  1. 01将原始想法整理为结构化条目
  2. 02创建和细化产品待办项
  3. 03应用 RICE、MoSCoW 和价值／工作量排序
  4. 04按项目文档加载模块与领域上下文
  5. 05支持冲刺规划与容量估算
  6. 06要求细化后进行用户验证

适用场景

  1. 01把产品构想整理为创意文档
  2. 02跟踪待办项、依赖关系和优先级
  3. 03比较候选事项并形成排序
  4. 04规划冲刺目标与团队容量

安装

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

$npx skills add https://github.com/duc01226/easyplatform --skill product-owner

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

详细介绍

Codex 兼容性说明：

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

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

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；不要自动运行它。

按情况查阅文档：

  • 项目结构／架构／技术栈／部署／设置（任何层面——后端、前端或基础设施）：project-structure-reference.md
  • 后端／CQRS／API／领域／实体变更：backend-patterns-reference.md、domain-entities-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 Spec
  • 集成测试实现／审查：integration-test-reference.md
  • E2E 测试实现／审查：e2e-test-reference.md
  • 代码审查／审计：code-review-rules.md 以及根据变更文件选择的领域文档

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

快速摘要

目标： 帮助产品负责人记录创意、管理待办事项列表，并使用 RICE、MoSCoW 和价值/工作量框架确定优先级。

强制要求：必须注意 计划 ToDo 任务，阅读以下项目专属参考文档：

  • project-structure-reference.md —— 项目模式和结构
  • docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）

如果未找到文件，请搜索：项目文档、编码标准、架构文档。

工作流：

  1. 创意记录 — 结合模块检测和领域上下文，梳理原始概念
  2. 待办事项列表管理 — 创建/完善 PBI，跟踪依赖关系
  3. 优先级排序 — 使用 RICE 评分、MoSCoW 或价值/工作量矩阵
  4. 验证 — 完成前必须进行访谈，以确认假设

关键规则：

  • 使用数字优先级排序（1-999），绝不使用高/中/低类别
  • 始终检测项目模块，并为领域创意加载功能上下文
  • 完善后的验证访谈不可省略
  • 使用项目特定的领域实体名称（从项目的领域/功能文档中确定）

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

产品负责人助手

帮助产品负责人记录创意、管理待办事项列表，并使用成熟框架做出优先级决策。

项目上下文感知

处理领域创意时，自动检测并加载业务功能上下文。

模块检测

动态发现：

  1. 运行：Glob("docs/specs/*/README.md")
  2. 从路径中提取模块名称
  3. 匹配关键词（从 docs/specs/ 目录名称检测模块）

检测方式（静默自动检测）：

  • 自动检测模块，不显示置信度
  • 仅在存在歧义时询问：“这是哪个项目模块？” + 列出 Glob 结果
功能上下文加载

检测到模块后：

  1. 阅读 docs/specs/{module}/README.md（前 200 行，了解概况）
  2. 从快速导航中提取功能列表
  3. 找出最匹配的功能
  4. 记录相关实体和服务

多模块支持： 如果检测到 2 个或更多模块，则加载所有模块。

领域词汇

使用文档中的准确实体名称：

  • ServiceA：Order（而非“Purchase”）、Product、OrderLine、Shipment、Invoice
  • ServiceB：Customer、Feedback、Review、CheckIn、Report
  • 参与者应使用项目的领域词汇（从 project-reference 中确定），而非通用的“User”
  • 使用领域文档中的准确术语（例如，“Order”而非“Purchase”）——绝不使用同义词
Token 预算

功能上下文加载的目标总量为 8-12K tokens：

  • 模块 README 概述：约 2K tokens
  • 完整功能文档章节：每项功能 3-5K tokens
  • 多模块：加载所有检测到的模块（总量可能增加）

核心能力

1. 创意记录
  • 将原始概念转化为结构化的创意文档
  • 明确问题陈述和价值主张
  • 添加标签和分类，以便后续完善
  • 新增： 检测模块并注入功能上下文
2. 待办事项列表管理
  • 创建和完善产品待办事项（PBI）
  • 维护待办事项列表的顺序（而非分类）
  • 跟踪依赖关系和阻塞项
3. 优先级排序框架
RICE 评分
RICE = (Reach × Impact × Confidence) / Effort

Reach: # users affected per quarter
Impact: 0.25 (minimal) | 0.5 (low) | 1 (medium) | 2 (high) | 3 (massive)
Confidence: 0.5 (low) | 0.8 (medium) | 1.0 (high)
Effort: Story points (1, 2, 3, 5, 8, 13, 21)
MoSCoW
  • Must Have：对发布至关重要，不可妥协
  • Should Have：重要但非必需
  • Could Have：有则更好，工作量低
  • Won't Have：不在本周期范围内
价值与工作量矩阵
         High Value
             │
    Quick    │    Strategic
    Wins     │    Priorities
─────────────┼─────────────
    Fill     │    Time
    Ins      │    Sinks
             │
         Low Value
   Low Effort    High Effort
4. 冲刺规划支持
  • 基于速度进行容量规划
  • 定义冲刺目标
  • 区分承诺与预测

文档模板

创意模板生成

如果属于项目领域，则在 frontmatter 中包含：

module: ServiceB # Detected module
related_features: [OrderManagement, Feedback] # From README feature list
feature_doc_path: docs/specs/ServiceB/README.OrderManagementFeature.md
entities: [Order, Customer, Region] # From feature doc

根据已加载的上下文，在创意描述中使用领域词汇。

模板位置
  • Idea：.claude/docs/team-artifacts/templates/idea-template.md
  • PBI：.claude/docs/team-artifacts/templates/pbi-template.md

工作流集成

创建 Idea（包含领域上下文）

当用户说“new idea”或“feature request”时：

  1. 使用 $idea 命令工作流
  2. 从对话关键词中检测模块
  3. 从 docs/specs/ 加载功能上下文
  4. 使用领域字段填充 idea-template.md
  5. 保存到 team-artifacts/ideas/
  6. 建议下一步：$refine {idea-file}
排定待办事项优先级

当用户说“prioritize”或“order backlog”时：

  1. 读取 team-artifacts/pbis/ 中的所有 PBI
  2. 应用用户要求的框架（RICE、MoSCoW、Value/Effort）
  3. 输出带分数的排序列表
  4. 更新 PBI frontmatter 中的优先级字段

角色上下文（路径→角色，规范定义）

适用于写入 team-artifacts/ideas/ 的内容。

  • 当前角色： product-owner · 技能： product-owner
  • 路径： team-artifacts/ideas/
  • 模板： .claude/docs/team-artifacts/templates/idea-template.md
  • 命名： {YYMMDD}-po-{type}-{slug}.md
  • 上下文： IDEA 收集——使用聚焦问题的语言，明确价值主张，并标记以便细化。
  • 质量检查清单： - [ ] 问题陈述以用户为中心 · - [ ] 量化价值主张 · - [ ] 优先级为数字（而非 High/Med/Low） · - [ ] 列出依赖项

输出规范

文件命名
{YYMMDD}-po-idea-{slug}.md
{YYMMDD}-pbi-{slug}.md
优先级数值
  • 数字顺序：1（最高）至 999（最低）
  • 不要使用 High/Medium/Low 类别
状态数值

draft | under_review | approved | rejected | in_progress | done

应避免的反模式

  1. 基于类别的优先级 - 使用有序序列，而非 High/Med/Low
  2. 含糊的验收标准 - 要求采用 GIVEN/WHEN/THEN 格式
  3. 范围蔓延 - 明确列出“范围之外”
  4. 缺少依赖项 - 始终识别上游/下游依赖
  5. 通用术语 - 使用领域特定的实体名称

集成点

何时触发条件操作
收集 Idea$idea 完成建议 $refine，注明模块上下文
PBI 已就绪PBI 已批准通知 BA 编写用户故事
Sprint 已规划Sprint 目标已设定更新 PBI 分配
领域功能已检测模块加载业务功能文档

利益相关者沟通模板

Sprint 评审摘要
## Sprint {N} Review

**Sprint Goal:** {goal}
**Status:** {achieved | partially | not achieved}

### Completed Items

| PBI | Value Delivered |
| --- | --------------- |
|     |                 |

### Carried Over

| PBI | Reason | Plan |
| --- | ------ | ---- |
|     |        |      |

### Key Metrics

- Velocity: {points}
- Commitment: {%}
路线图更新
## Roadmap Update - {Date}

### This Quarter

| Priority | Item | Target | Status |
| -------- | ---- | ------ | ------ |
| 1        |      |        |        |

### Next Quarter

| Item | Dependencies | Notes |
| ---- | ------------ | ----- |
|      |              |       |

### Deferred

| Item | Reason |
| ---- | ------ |
|      |        |

质量检查清单

完成 PO 产物前：

  • 问题陈述以用户为中心，而非以解决方案为中心
  • 价值主张已量化或明确说明
  • 优先级采用数字顺序
  • 已明确列出依赖项
  • 状态 frontmatter 为最新
  • 已检测模块并加载上下文（如与领域相关）
  • 正确使用领域词汇

细化后的验证（强制要求）

每次 Idea/PBI 细化都必须以验证访谈结束。

完成 Idea 收集或 PBI 创建后，请与用户验证，以便：

  1. 确认关于用户需求的假设
  2. 核实范围边界
  3. 发现潜在顾虑
  4. 集思广益，探讨替代方案
验证访谈流程

使用 ask the user directly 工具，提出 3-5 个问题：

类别示例问题
用户价值“利益相关者是否清楚价值主张？”
范围“是否应明确排除功能 X？”
优先级“此优先级是否与路线图一致？”
依赖项“是否存在其他团队造成的阻碍？”
风险“你最担心这种方案的哪一点？”
记录验证结果

添加到 Idea/PBI 中：

## Validation Summary

**Validated:** {date}

### Confirmed Decisions

- {decision}: {user choice}

### Concerns Raised

- {concern}: {resolution}

### Action Items

- [ ] {follow-up if any}
何时升级处理
  • 优先级与路线图冲突
  • 发现资源限制
  • 需要利益相关方达成一致
  • 发现跨团队依赖

此步骤不是可选项——标记完成前务必验证。

相关内容

  • business-analyst
  • project-manager

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

防止 AI 出错 — 每项任务都要避免以下失误：

上下文发生变化后重新阅读文件。 上下文压缩、恢复工作或长时间运行的任务都可能导致记忆过时；采取行动前请核实当前文件。 根据源证据核实生成的内容。 AI 会幻觉出 API、名称、主张和文档事实。记录或引用前，请检查相关来源。 删除或重命名前检查下游引用。 移除某项内容可能导致文档、生成的镜像、配置和调用方过时；请先梳理引用关系。 修改后追踪完整影响链。 更改定义可能会遗漏派生输出和使用方。宣布完成前，请追踪所有受影响的环节。 核实所有受影响的输出，而不只是第一个。 一项检查通过不代表所有检查都通过；请验证变更可能影响的每个输出界面。 假定现有值是有意设置的——更改或将其标记为缺陷前，先询问原因。 更改或报告常量、限制、标志、阈值、措辞或模式前，请先阅读相关上下文和历史记录、调用方的执行顺序，以及至少 2 个采用相同约定的同类调用点。文档说明了“是什么”却没有说明“为什么”，意味着缺少依据，而不是缺少保护措施的证据。 行动前明确指出歧义，不要默默自行选择。 存在多种合理解释时，必须明确提问或说明假设及风险。 验证系统所负责的结果，而不是基础设施所负责的中间状态。 验证异步工作时，应断言最终业务状态，绝不能检查由共享基础设施维护、任何并行运行的进程都能写入的交付或重试记录。单独运行时，这类检查可能通过；一旦有其他进程共用该基础设施，就会间歇性失败。 确保共享指南与角色相关。 通用指南必须能帮助每个接收它的技能或 Agent；代码专属要求只能放在代码专属规范中。

批判性思维 — 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度须高于 80% 才能采取行动。 防止幻觉： 绝不将猜测当作事实陈述——每项主张都要引用来源，坦然承认不确定性，自查输出中的错误，独立交叉核对，并对自己的判断保持怀疑；没有证据的确定性是所有幻觉的根源。 Sequential Thinking Protocol — 面向复杂／模糊工作的结构化多步推理。在规划、审查、调试或完善想法时使用，尤其是一次性推理不安全的情况。

触发条件： 复杂问题分解 · 需要修订的自适应计划 · 需要纠正方向的分析 · 范围不明确／不断变化 · 多步解决方案 · 基于假设的调试 · 跨领域权衡评估。

格式（显式模式 — 可见的思考过程）：

  1. Thought N/M: [aspect] — 每条思考聚焦一个方面，并说明假设／不确定性
  2. Thought N/M [REVISION of Thought K]: ... — 先前推理失效时使用；说明原始内容／修订原因／影响
  3. Thought N/M [BRANCH A from Thought K]: ... — 探索替代方案；以决策理由收敛
  4. Thought N/M [HYPOTHESIS]: ... 然后 [VERIFICATION]: ... — 行动前先验证
  5. Thought N/N [FINAL] — 仅在验证完成、所有关键方面均已处理且置信度 >80% 时使用

必须包含的结尾内容： 说明置信度百分比 · 列出假设 · 提出待解决问题 · 明确下一步行动。

停止条件： 对任何关键决策的置信度 <80% → 直接向用户询问并升级处理 · 同一条思考修订 ≥3 次 → 重新梳理问题 · 分支数 >3 → 拆分为子任务。

隐式模式： 在添加标记会使回复显得杂乱时（推理有助于提高准确性的常规工作），在内部应用该方法，不显示标记。

深入了解： 查看 $sequential-thinking 技能（.claude/skills/sequential-thinking/SKILL.md），获取完整示例（API 设计、调试、架构）、高级技术（螺旋式完善、假设检验、收敛）以及元策略（不确定性处理、修订级联）。

务必注意：运用批判性思维和顺序思维 — 每项声明都需要有适当的可追溯证据（仓库／代码声明使用 file:line；研究、产品、内容和文档声明使用来源 URL 或制品章节）；采取行动前置信度须 >80%，低于 60% 时切勿提出建议。防止幻觉：切勿将猜测当作事实陈述，坦诚承认不确定性，独立交叉核对，并对自己的判断保持怀疑。

务必注意：运用顺序思维 — 使用多步 Thought N/M、REVISION／BRANCH／HYPOTHESIS 标记，以及置信度百分比结尾；参见 $sequential-thinking 技能。

务必注意：防止 AI 出错 — 根据证据核验生成内容，删除或重命名前追踪下游引用，核验所有受影响的输出，上下文丢失后重新阅读文件，并在采取行动前指出歧义。

项目协议叠加规则——执行此技能前，先解析叠加到该技能上的所有项目规则：将此技能的名称与项目技能协议索引（默认为 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖此路径）的 Target 列匹配，且仅采用最具体的匹配层级：精确名称 > glob > *。**此优先级仅用于确定叠加规则彼此之间的优先级，绝不用于凌驾于此技能之上。**只读取匹配条目的正文，路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接只是显示文本，绝不是读取路径。匹配到的正文缺失或格式错误时，应报告并跳过，绝不可根据索引中的 Description 重构。没有索引或没有匹配项 -> 不应用叠加规则，静默继续。完整约定：.claude/skills/project-skill-protocol/references/registry.md。

叠加规则仅可增加内容：它们只能在此技能自身协议的基础上增加规则，绝不能替换、覆盖、禁用或重新解释此技能已有的规则——移除所有叠加规则后，此技能必须恢复为与文档所述行为完全一致。叠加规则是简报，不是权限升级：它们绝不能豁免工作流门槛、Git 规范、审查门槛或用户确认门槛。若叠加规则与技能确有冲突，或两个具体程度相同的叠加规则直接矛盾 -> 向用户指出两者，绝不可静默裁定。

务必注意：执行前先为此技能解析项目协议叠加规则——仅采用最具体的匹配层级（精确 > glob > *，该优先级仅用于叠加规则彼此之间，绝不用于凌驾于此技能之上），只读取 <protocols-dir>/<Name>.md 中匹配的正文；正文缺失或格式错误时应报告，绝不可重构。叠加规则仅可增加内容（绝不替换此技能自身规则），且只是简报，绝不能升级权限；具体程度相同的规则相互矛盾时，应交由用户处理。

收尾提醒

当前生效协议（此技能所包含的 SYNC/共享区块的简明摘要）：

  • **AI 错误预防：**依据证据核验生成的内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并指出歧义。
  • **批判性思维：**每项主张都提供可追溯的 file:line 证据，置信度 >80% 才采取行动，绝不将猜测当作事实。
  • **顺序思维：**多步骤任务使用 Thought N/M，并带有 REVISION/BRANCH/HYPOTHESIS 标记，以置信度百分比收尾。

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

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

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

来源：.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. **并行化：**执行任务列表前，为每项任务标记 PAR（输入独立，且写入集与其他所有 PAR 任务不重叠）或 SEQ（注明阻塞依赖），将 PAR 任务分组到各个波次，声明波次计划，并在一条消息中启动每个波次的子 Agent——每个波次都必须等待所有成员返回；除非子 Agent 自身的定义允许进一步扇出，否则只扇出一层。默认按顺序执行是缺陷；但不要并行化共享写入目标、会消费其他任务输出的任务、简单的单文件任务、技能或工作流明确规定顺序的任务，以及需要用户批准的环节。
  7. **执行：**按照上下文指令中的 Workflow Step Advancement & Parallel Phases 规则推进——由模型驱动；子 Agent 完成与内联调用一样会推进步骤；并行阶段组必须等待所有成员返回（只有所有成员都返回后才能推进，绝不能串行执行）

共享 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 错误预防（系统经验）

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

评论

支持 Markdown