incu-way-po

产品需求流程

一种以关卡为驱动的工作流，用于将原始需求转化为一个或多个可直接用于开发的工单——每个工单都经过实际代码库验证：哪些可行、哪些不可行、会影响哪些部分，以及哪些仍需人工决策。目标是在 incu-way-development 或 incu-way-bugs 启动之前，而不是进行过程中，回答所有未决问题。

此流程位于开发流程的上游：

raw need ──▶ incu-way-po ──▶ TICKET.md (Ready) ──▶ incu-way-development (Phase 0 consumes it)
                                                └▶ incu-way-bugs (for defect-shaped items)

这是一个分析流程。与 incu-way-docs 和评估流程一样，它不会维护 .ways/state.json。它只编写需求文档，不编写代码。输出位于 docs/requirements/{slug}/TICKET.md——每个工单一个文件夹，工单 slug 的设计旨在让它在开发开始时成为 PRD slug。

应根据需求调整规模。一个小型的单仓库变更只需简短的可行性评估和一个工单——不需要启动发现项目。分析深度取决于模糊程度和影响范围。

---

仓库资格检查（任何操作之前）

在 Phase 0 之前，检查 ~/.ways/config.yaml 的 blacklist（格式：incu-base 的 global-config 规则，始终启用）是否包含当前仓库。如果匹配，告知用户此仓库已被 incu-way 列入黑名单，并询问是否仍要继续（一例例外）或停止——在用户回答之前不要运行任何阶段。文件不存在或未匹配：正常继续。

---

Phase 0 — 需求收集与可行性调查（只读）

目标： 充分了解需求和代码的实际情况，以便判断哪些可行、哪些不可行，以及哪些必须由人工决定。此阶段不会写入任何文件。

需求收集

1. 以产品层面的表述记录需求：
   • 正在解决什么问题，谁会受到影响
   • 客户端或利益相关方期望达到什么结果
   • 已知的约束和非目标
   • 如何衡量成功
2. 阅读现有产品背景资料：PRD.md、docs/、docs/requirements/ 中的先前工单，以及 docs/prds/ 中相关的 PRD。

确定受影响的仓库

3. 询问用户此产品涉及哪些仓库；如果 hub 仓库的 CLAUDE.md 中存在仓库列表（repos: 部分），则读取该列表——只要存在，就始终以它为准，因为它与产品一同进行版本管理。如果不存在 repos: 部分，则回退到 ~/.ways/config.yaml 的 linkedRepos（格式：incu-base 的 global-config 规则，始终启用）：查找包含当前仓库的分组（如果有），并将该分组中的其他仓库视为涉及范围，除非用户另有说明。对于单仓库产品，这很简单；对于多仓库产品（例如 Web 应用 + API + workers），在开始调查前列出需求可能涉及的所有仓库。

可行性评估（逐个仓库，以代码为依据）

4. 只读调查范围内的每个仓库：与需求相关的当前行为、可能受影响的模块、入口点、集成，以及需要保留的现有模式。
5. 记录可行性情况，并提供可追溯到 repo:path:line 的依据——不得臆造：
   • 当前系统已经支持的内容
   • 通过合理工作量可以实现的内容
   • 不进行较大改动就无法实现的内容（以及原因）
   • 哪些跨仓库契约会发生变化：API、事件、架构、共享包——以及由此产生的仓库间顺序约束
6. 将所有未知事项明确列为未决问题——绝不将其当作假设。为每个问题标注：现在需要用户或利益相关方答复，还是可以通过进一步调查解决。

阶段 0 退出标准

在 Gate 1 之前，Claude 应该能够说明：

• 问题和预期结果（从产品角度描述）
• 可能受影响的仓库和模块
• 可行性情况：目前支持 / 可以实现 / 无法实现，除非投入较大工作
• 跨仓库契约变更及其顺序约束（涉及多个仓库时）
• 尚未解决的问题，并为每个问题标注能够解决它的人

不要根据名称或 README 中的说法推断行为。如果代码没有说明白某件事，那它就是一个尚未解决的问题，而不是假设。

---

Gate 1 — 范围和工单拆分

撰写任何工单之前，先提出：

## Proposed scope and split

- **Need:** {one-line restatement}
- **In scope / out of scope:** {explicit}
- **Ticket split:** {one ticket, or several — per repo, per increment, or feature vs bug —
  each independently deliverable, with slugs and dependency order}
- **Feasibility summary:** {supported today / possible / not possible without larger work}
- **Open questions needing you now:** {list}
- **Open questions I can still resolve by survey:** {list}

• 询问：“这是针对 {need} 提出的范围和工单拆分方案。请先确认，然后我再起草工单。”
• 停止。在用户确认范围和拆分方案之前，不要起草工单。

---

隔离设置（Gate 1 之后）

撰写任何文件之前，询问用户希望如何隔离这项工作：

你希望我在当前检出中创建一个新分支，还是创建一个单独的 git 工作树？

严格按照用户的回答操作： 询问后停止；在用户作出选择之前，不要创建分支或工作树。

如果当前检出中存在未提交的更改，在切换分支或创建工作树之前停止并询问用户。

即使需求涉及多个仓库，也要在产品的 中心仓库（拥有 docs/ 的仓库）中编写工单——调查期间只读取其他仓库。

选项 A — 在当前检出中创建分支

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c po/{slug}

选项 B — 创建单独的工作树

仅在 .worktrees/ 下创建工作树。不要向用户询问路径。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/po-{slug} -b po/{slug} origin/develop

此处的 {slug} 是该需求的 slug（例如 po/contact-export）。所有输出都写入所选的工作位置。绝不要直接向 develop 或 main 写入文件。

阶段 2 — 起草工单

目标： 根据已批准的拆分，为每个工单创建一个 docs/requirements/{ticket-slug}/TICKET.md。

Slug 格式： {zero-padded-id}-{kebab-ticket-name}（例如：004-contact-export-api）。 开发开始处理后，工单 slug 会成为 PRD slug，因此必须确保它在两个命名空间中都唯一。

查找下一个 ID — 检查所有可能已占用该 ID 的位置，而不只是当前检出。 只检查当前分支的计数器，一旦有两个需求并行处理，或从同一基线创建的两个工作树／分支各自独立计算出相同的“下一个”编号，就会发生冲突；实际中已经发生过这种情况。仅扫描并不能彻底避免冲突：两个 Agent 可能同时扫描，各自算出相同的编号，然后才创建目录。要避免同一台机器上发生这种情况，请在扫描并预留的整个过程中持有锁：

0. 在扫描任何内容之前，获取同一台机器上的锁：

   LOCK="$(git rev-parse --git-common-dir)/incu-way-prd-slug.lock"
   until mkdir "$LOCK" 2>/dev/null; do sleep 0.2; done
   trap 'rmdir "$LOCK"' EXIT
   

   mkdir 每次只会有一个进程成功，而 --git-common-dir 从此仓库的每个工作树解析出的都是同一个共享路径，因此锁对所有工作树可见。此锁与 incu-way-development 共用（incu-way-prd-slug.lock，共用同一编号空间：docs/requirements/ + docs/prds/），不与 incu-way-bugs 共用。
1. 列出此检出中的 docs/requirements/ 和 docs/prds/ 已使用的 ID。
2. 列出此仓库的所有其他工作树（git worktree list），并读取它们的 docs/requirements/ 和 docs/prds/；同级工作树中的工单不会显示在此处的 git status 中，但它就在磁盘上。
3. 获取默认分支（git fetch origin {default}），并列出该分支上已合并的内容（git ls-tree --name-only origin/{default} -- docs/requirements/ docs/prds/）；其他人自创建此分支以来合并的 ID 尚不会出现在你的本地树中。

在这三处找到的最大 ID 上加一，作为新 ID，并在释放锁之前立即创建 docs/requirements/{id}-{slug}/（即使只创建一个空占位文件也能预留该 ID）。然后才释放锁（上方的 trap 会自动处理，包括失败时）。在仍持有锁时完成预留，才能真正避免同一台机器上的竞争；仅靠扫描无法做到这一点。

TICKET.md 结构

# Ticket — {title}

## Status
Draft | In Review | Ready | Handed off

## Problem / outcome
What pain, for whom, what changes when it ships.

## Scope
In / out. Explicit non-goals.

## Feasibility notes
What the codebase already supports, what this requires, what is not possible without
larger work — each point traceable to `repo:path:line`.

## Affected repositories / modules
| Repo | Modules touched | Nature of change (code / contract / config) |
|------|-----------------|----------------------------------------------|

## Cross-repo dependencies
API/event/schema contracts that change, and the ordering constraints between tickets
or repos. "None" for single-repo tickets.

## Acceptance criteria
Numbered, concrete, testable. These become the PRD's functional requirements.

## Risks / assumptions
Explicitly labeled; every assumption must be confirmed or promoted to an open question.

## Open questions
Must be empty — or every remaining item explicitly marked "deferred, accepted by {who}"
— before the ticket can be marked Ready.

## Suggested flow
incu-way-development | incu-way-bugs (with the suggested slug)

起草规则（不可妥协）

• 可追溯。 每项可行性声明都必须引用 repo:path:line。如果无法引用，就将其列为待解问题。
• 可测试。 每项验收标准都必须具体到足以转化为测试。
• 不得臆造。 不得添加用户未在 Gate 1 陈述或确认的要求、范围或验收标准。
• 明确跨仓库事项。 对于多仓库需求，契约变更和顺序约束必须写在工单中，不能只存在于 Claude 的脑海中。

---

Gate 2 — Ready 状态审查

针对每个工单，呈现Ready 状态检查清单：

• 以产品术语陈述问题和预期结果

• 明确范围和非目标

• 已依据实际代码验证可行性（可追溯）

• 已梳理受影响的仓库／模块；已确认跨仓库契约

• 验收标准具体且可测试

• 待解问题已解决，或经用户同意明确推迟

• 说："工单已就绪，位于 docs/requirements/{slug}/。其中包含 Ready 状态检查清单，供你审查。"

• 停止。等待用户审查。

如果“待解问题”部分仍有未解决事项，工单就不能以 Ready 状态通过此关卡。在此处反复迭代——解决问题可能会改变拆分、可行性说明或验收标准——直到用户将每个工单标记为 Ready，或明确接受推迟处理的事项。

---

阶段 3 — 交接

用户在 Gate 2 批准后：

• 将每个工单的状态更新为 Ready。
• **Jira 同步（可选，仅由用户触发）：**如果用户明确提出请求（例如“创建 Jira 工单”或“将此内容同步到 Jira”），则通过 Atlassian MCP 工具根据 TICKET.md 创建或更新 Jira issue，并在工单中记录 issue key。未经用户明确请求，绝不创建、更新或转换 Jira issue——这与 incu-way-prepare-pr 对 git 持久化的处理理念相同。
• 指出下一步：对于每个工单，其建议流程是：当 incu-way-development（或 incu-way-bugs）启动时，其阶段 0 会读取 TICKET.md，并将验收标准作为初始功能需求。

---

Gate 3 — PR

建议调用 incu-way-prepare-pr，推送 po/{slug} 并向 develop 创建 PR。 不要自行推送或创建 PR。

供 incu-way-prepare-pr 使用的建议 PR 标题/正文：

Title: po({slug}): {short need name}

PR 正文必须包含：

• **需求：**问题和预期结果。
• 工单：docs/requirements/{slug}/TICKET.md 文件列表及其状态。
• **拆分理由：**为何采用此拆分方式，以及依赖顺序（多仓库需求）。
• **未解决问题：**已解决问题的数量，以及明确延期且由谁接受的事项。

创建 PR 后，分享 PR URL。停止。用户批准之前不要合并。

---

快速参考 — 各 Gate

Gate	触发条件	应说的话	暂停等待
1	提出范围和拆分方案	“这是针对 {need} 的拟定范围和工单拆分方案。请先确认，然后我再起草工单。”	用户确认
2	已起草工单	“工单已准备好，位于 docs/requirements/{slug}/。其中包含 Definition of Ready 检查清单，供你审核。”	用户审核
3	工单已设为 Ready	建议使用 incu-way-prepare-pr 创建 PR po/{slug} → develop；用户创建 PR 后分享 URL	用户批准 PR

---

产出内容

docs/requirements/{ticket-slug}/
  TICKET.md   # Problem, scope, feasibility notes, repo map, acceptance criteria, open questions

---

禁止事项

• Gate 1 确认范围和拆分方案之前，不要起草工单。
• 存在未解决的未决问题时，不要将工单标记为 Ready——应解决这些问题，或取得用户明确同意将其延期。
• 不要提出无法追溯的可行性判断——请引用 repo:path:line，或记录为未决问题。
• 不要编造用户未确认的需求、范围或验收标准。
• 除非用户当下明确提出请求，否则不要创建、更新或转换 Jira issue。
• 不要在此处编写代码、PRD 或计划——此流程到 incu-way-development 和 incu-way-bugs 启动处为止。
• 不要写入已调研的仓库——调研期间这些仓库为只读；工单应存放在 hub 仓库中。
• 不要直接写入 develop 或 main——请使用 po/{slug}。