incu-way-development

开发流程

一种结构化、由关卡驱动的工作流，无需猜测即可交付新功能。从调研和需求收集开始，然后依次进行 PRD、规划、实现、验证和 PR，并在每个关键关卡征得用户明确批准。

---

仓库资格检查（先于所有操作）

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

---

Phase 0 — 调研和需求收集（先于所有操作）

在编写任何代码或项目文档之前，先收集足够的产品和代码库上下文，以避免起草错误的 PRD。

调研清单

1. 阅读 PRD.md（项目根目录）。
2. 阅读 docs/ 中的所有现有文档，以及 docs/prds/ 中的所有 PRD。 如果 docs/requirements/{slug}/TICKET.md 中存在针对该请求的精炼工单 （由 incu-way-po 生成），请先阅读：将其验收标准作为 PRD 的初始功能需求，并核实（而不是重新推导）其中的可行性说明和受影响模块映射。
3. 从产品角度澄清请求：
   • 请求变更的内容
   • 面向的对象
   • 客户端或利益相关方的期望
   • 成功的标准
   • 已有的约束或非目标
4. 了解代码库上下文：
   • 与请求相关的当前行为
   • 可能受影响的模块、入口点、集成和测试
   • 应予以保留的现有模式
   • 与现有功能的冲突、重叠或依赖关系
   • 同一产品中可能受影响的其他仓库——检查中心仓库的 CLAUDE.md 中是否有 repos: 部分（若存在，以此为准）；否则查看 ~/.ways/config.yaml 中的 linkedRepos（格式：incu-base 的 global-config 规则，始终安装并启用）；两者都未列出本仓库，只表示这是单仓库产品
5. 根据请求调整调研深度：
   • 对于范围小且说明明确的变更，轻量调研即可
   • 对于含糊、涉及面广或对客户敏感的请求，在起草任何内容之前深入调研
6. 如果仍存在关键未知事项，先提出有针对性的澄清问题，再进入 PRD 阶段。

Phase 0 退出条件

进入 Phase 1 之前，Claude 应能够说明：

• 要解决的问题和请求的变更
• 变更的目标对象以及客户/利益相关方的期望
• 目前已知的成功标准或完成定义
• 可能受影响的文档、模块、流程或集成
• 所作出的假设
• 仍需用户提供意见的未决问题

如果 Claude 无法有足够把握地回答这些问题，就不要起草 PRD。先提出澄清问题。

---

隔离设置（Phase 0 后立即进行）

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

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

严格按照用户的回答操作： 提问后立即停止；在用户选择之前，不要创建分支或 worktree。

如果当前检出中有未提交的更改，在切换分支或创建 worktree 之前停止并询问。

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

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

后续所有工作——PRD、计划、代码、文档、提交——都在当前检出中的此分支上进行。绝不要直接向 develop 或 main 写入文件。

选项 B — 单独的 worktree

仅在 .worktrees/ 下创建 worktree。不要询问用户路径。

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

后续所有工作——PRD、计划、代码、文档、提交——都只能在此 worktree 中进行。绝不要直接向 develop 或 main 写入文件。

---

状态跟踪 — .ways/state.json

遵循 ways/v1alpha1 状态契约——规范的 .ways/state.json 格式（schemaVersion 2），以始终启用的 state-contract 规则形式提供；ways add 会将其放入项目，因此它已在你的上下文中（无需指定路径）。对于维护者，该规则在本仓库中的源目录为 ways/rulepacks/state-contract/。请勿在此技能中复制或臆造架构。

流程专属值：

• flow：feature
• way：incu/dev · discipline：development（可选填写 way 清单中的 wayVersion）
• 分支模式：feat/{slug}
• 初始 phase：discovery
• isolationType：branch 或 worktree，取自 Phase 0 中的隔离方式选择
• 文档：docs/prds/{slug}/PRD.md、docs/prds/{slug}/PLAN.md、docs/prds/{slug}/TESTING.md
• 门禁：prd、plan、testing、pr-develop、pr-main

会话开始时，如果 .ways/state.json 存在，则读取它。如果其 branch 与当前的 feat/{slug} 分支匹配，报告当前阶段／下一步／待处理门禁，并从该状态继续。如果文件不存在，或文件存在但其 branch 不匹配（这是从已合并功能继承的过时文件），则从 Phase 0 开始，并在选定隔离方式后立即于 .ways/state.json 创建／覆盖该文件。每次状态转换时，也要更新 lastPhase（即将离开的阶段）。

更新节点（阶段 → 写入内容）：

时机	phase	文档／门禁／步骤
PRD 草拟完成	prd	PRD.md → in-review
门禁 1 通过	plan	PRD.md → approved；门禁 prd → passed
计划草拟完成	plan	PLAN.md → in-review
门禁 2 通过	implementation	PLAN.md → approved；门禁 plan → passed；根据 PLAN.md 中的任务生成 steps——每个可执行任务对应一项，且所有项状态均为 todo
实施期间	implementation	将每个步骤标记为 in-progress → done（或 blocked）——每完成一个步骤就立即写入状态文件，绝不要等到阶段结束时再批量写入
验证	validation	写入 TESTING.md 后，将其状态设为 approved
门禁 3 通过	review	门禁 testing → passed
PR feat→develop 已创建	pr-develop	门禁 pr-develop → 仍为 pending；将其 url 设为 PR 链接
PR 已合并至 develop	pr-develop	门禁 pr-develop → passed
PR develop→main 已创建	pr-main	门禁 pr-main → 仍为 pending；将其 url 设为 PR 链接
PR 已合并至 main	done	门禁 pr-main → passed

在门禁 2 生成的 steps 数组，就是看板上展示进度（例如 3/7）的依据。步骤 ID 可以沿用计划中的阶段标签（A1、A2、B1 等）。

不要自行提交 .ways/state.json——只需写入该文件。当用户希望持久化检查点时，建议调用 incu-way-prepare-pr，将其与该状态转换对应的文档／代码一起提交。

---

Phase 1 — 草拟 PRD

目标： 根据 Phase 0 的探索工作，为新功能编写一份重点明确的 PRD。

保存位置

docs/prds/{prd-slug}/PRD.md

Slug 格式：{zero-padded-id}-{kebab-feature-name} 示例：003-contact-export、007-auto-tagging-rules

**查找下一个 ID——检查所有可能已被占用的位置，而不只是当前检出分支。**只查看当前分支的计数器会发生冲突：多个功能并行开发时会冲突；从同一基础分支创建的多个 worktree/分支分别计算出相同的“下一个”编号时也会冲突，而且实际发生过这种情况。仅扫描并不能杜绝冲突：两个 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 从本仓库的每个 worktree 中解析出的都是相同共享路径（而不只是当前检出目录），因此锁在各个 worktree 间可见，这正是实际发生这种竞争的地方。该锁与 incu-way-po 共用（incu-way-prd-slug.lock，共用同一编号空间：docs/prds/ + docs/requirements/），但不与 incu-way-bugs 共用（使用单独的编号空间）。
1. 列出当前检出目录中 docs/prds/ 和 docs/requirements/ 已使用的 ID。
2. 列出本仓库的所有其他 worktree（git worktree list），并读取它们的 docs/prds/ 和 docs/requirements/；兄弟 worktree 中的 PRD 不会出现在此处的 git status 中，但它就在磁盘上。
3. 获取默认分支（git fetch origin {default}），并列出该分支上已经合并的内容（git ls-tree --name-only origin/{default} -- docs/prds/ docs/requirements/）；其他人在此分支创建后合并的 ID 还不会出现在你的本地树中。

取以上三处找到的最高 ID 再加 1，并在释放锁之前立即创建 docs/prds/{id}-{slug}/（即使只创建一个空占位文件也足以预留）。然后才能释放锁（上面的 trap 会自动执行此操作，即使上述某个步骤失败也不例外）。真正杜绝同一台机器上竞争的是在锁仍被持有时完成预留，而不是仅靠扫描：第二个 Agent 的步骤 1 只有在锁释放后才能开始，而届时该 ID 已经存在于磁盘上。对于两台不同机器之间尚未获取最新内容的竞争，此方法仍然无能为力；这是没有中央注册表的客户端计数器固有的限制。

如果此功能来自 incu-way-po 工单，请沿用工单的 slug，使 docs/requirements/{slug}/ 和 docs/prds/{slug}/ 保持对应。

PRD 结构

# PRD — {Feature Name}

## Status
Draft | In Review | Approved | In Progress | Done

## Problem
One paragraph. What pain does this solve? Who feels it?

## Goals
Bulleted list. Measurable outcomes where possible.

## Non-goals
What is explicitly out of scope.

## User stories
- As a [role], I want [action] so that [benefit].

## Functional requirements
Numbered list. Concrete, testable.

## Non-functional requirements
Performance, security, accessibility constraints.

## Data model changes
Tables, columns, or relations added/modified. Reference `docs/database-schema.md`.

## UI/UX notes
Key screens or flows. Link wireframes if any.

## Open questions
Unresolved decisions that need user input before implementation.

## Conflicts / dependencies
List any conflicts with existing PRDs or features found in Phase 0.

Gate 1 — PRD 审查

编写 PRD 后：

• 确保明确列出尚未解决的假设和待解决问题，而不是自行猜测。
• 明确提出所有待解决问题。
• 说：“PRD 草稿已准备好，位于 docs/prds/{slug}/PRD.md。请先审阅，然后我再继续。”
• 停止。用户表示 OK 之前，不要继续。

---

Phase 2 — 实施计划

**目标：**制定分步计划，将 PRD 需求对应到代码更改。

保存位置

docs/prds/{prd-slug}/PLAN.md

计划结构

# Implementation Plan — {Feature Name}

## Branch / worktree
Branch name: `feat/{slug}`
Isolation mode: current checkout branch | separate worktree

## Phases

### Phase A — {name}
- [ ] Task 1 (file/module affected)
- [ ] Task 2

### Phase B — {name}
...

## Test plan
- Unit tests: what to cover
- E2E tests: critical paths
- Manual validation checklist

## Rollback notes
How to revert if something goes wrong.

Gate 2 — 计划审查

编写计划后：

• 不要将未明确说明的假设视为已获批准的需求。如果关键验收标准仍不明确，请先修正 PRD。
• 说：“实施计划已准备好，位于 docs/prds/{slug}/PLAN.md。请先审阅，然后我再开始编写代码。”
• 停止。用户表示 OK 之前，不要继续。

---

Phase 3 — 实施

**目标：**在用户选择的隔离分支或 worktree 中实现此功能。

设置

继续使用 Phase 1 之前选定的隔离模式。除非用户要求切换模式，否则不要创建第二个分支或 worktree。

实施期间的规则

• 严格遵循 CLAUDE.md 约定（命名、服务端优先、不使用 any 等）。
• 按逻辑检查点推进（架构、API、UI、测试）。每个检查点都运行 pnpm typecheck && pnpm lint && pnpm test，然后告知用户该检查点已就绪，并建议调用 incu-way-prepare-pr 提交 — 不要自行运行 git add/git commit。
• PRD 中的所有功能需求都必须至少对应一项测试。

建议的提交消息格式（供 incu-way-prepare-pr 使用）

feat({slug}): {short description}

- Requirement FR-N implemented
- Tests added: {what}

---

阶段 4 — 验证

目标： 在交接给用户之前，根据 PRD 验证实现。

检查清单（请在要求用户测试前运行）

• 已实现 PRD 中的每项功能需求。
• 测试计划中的每项内容均已通过（pnpm test、pnpm test:e2e）。
• pnpm typecheck 以 0 退出。
• pnpm lint 以 0 退出。
• pnpm build 成功。
• 现有测试无回归。
• 已解决 PRD 中的未决问题（或记录为延期处理）。
• PRD 状态已更新为 In Progress → Done（或 Ready for Review）。
• Snyk 代码扫描通过（无新增问题）。
• Snyk 依赖项扫描通过（无新增问题）。
• SonarQube 扫描通过（无新增问题）。

安全扫描（Gate 3 前必须完成）

对选定的工作位置运行全部三项扫描。修复由此功能的提交引入的每一项问题 — main/develop 中预先存在的问题不在范围内，除非修复很简单。每轮修复后重新扫描，直至扫描通过。

Snyk — 源代码（SAST）： 使用 snyk_code_scan MCP 工具：

path: <absolute path to the selected working location>
severity_threshold: low

Snyk — 依赖项（SCA）： 使用 snyk_sca_scan MCP 工具：

path: <absolute path to the selected working location>
severity_threshold: low
all_projects: true

如果文件夹尚未受信任，请先使用相同路径调用 snyk_trust。

SonarQube：

bash run-sonar.sh

检查输出，查看是否有标记到此功能分支中已修改文件的问题。修复新代码引入的所有 BLOCKER 或 CRITICAL 严重级别问题。

如果 snyk_trust、snyk_code_scan、snyk_sca_scan 或 run-sonar.sh 不可用，请在 docs/prds/{slug}/TESTING.md 中记录缺失的工具，注明失败的确切命令或工具名称，并询问用户是安装/配置该工具，还是仅使用现有验证手段继续。若扫描未运行，不得报告扫描通过。

修复循环：

1. 处理所有标记的新问题（升级存在漏洞的依赖项、清理输入等）。
2. 运行 pnpm typecheck && pnpm lint && pnpm test，确认没有造成问题。
3. 建议调用 incu-way-prepare-pr 提交修复（fix({slug}): address snyk/sonar findings）— 不要自行提交。
4. 重新运行全部三项扫描。
5. 重复以上步骤，直至三项扫描均报告没有新增问题。

Gate 3 — 用户测试

验证通过后：

• 在 docs/prds/{slug}/TESTING.md 中编写简短的测试指南：
  • 如何启动功能（URL、CLI 命令等）
  • 可执行的分步场景（正常流程 + 边缘情况）
  • 已知限制或延期事项
• 说明：“实现已完成并通过验证。测试指南位于 docs/prds/{slug}/TESTING.md。请测试并告知我结果。”
• 停止。等待用户反馈。

---

阶段 5 — 通过 Pull Request 合并

目标： 通过经过审查的 PR 将功能先集成到 develop，再集成到 main。绝不要直接合并分支 — 始终使用 PR。

分支流程

feat/{slug}  →  develop  →  main
               (PR 1)      (PR 2)

PR 1 — feat/{slug} → develop

用户完成验证后（Gate 3 通过），告知用户分支已准备就绪，并建议调用 incu-way-prepare-pr 推送 feat/{slug}，并向 develop 创建 PR。不要自行推送或运行 gh pr create——只有 incu-way-prepare-pr 这一技能会执行这些操作，而且只有在用户要求时才会执行。

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

Title: feat({slug}): {short feature name}

PR 正文必须包含：

• 摘要： 用 2-4 个要点描述构建了什么以及原因。
• PRD： 链接到 docs/prds/{slug}/PRD.md。
• 测试： 链接到 docs/prds/{slug}/TESTING.md。
• 检查清单： typecheck ✅、lint ✅、tests ✅、build ✅、snyk-code ✅、snyk-deps ✅、sonarqube ✅、用户已验证 ✅。

PR 创建后，将 PR URL 分享给用户。停止。未经用户批准，不要合并 PR。

PR 2 — develop → main

PR 1 合并到 develop 后，建议再次调用 incu-way-prepare-pr，创建从 develop → main 的 PR。

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

Title: release: {slug} — {short feature name}

PR 正文必须包含：

• 此版本包含的功能/修复。
• 指向 develop → feat PR 的链接，以提供完整的差异上下文。

PR 创建后，将 PR URL 分享给用户。停止。未经用户批准，不要合并。

---

快速参考 — 阶段关卡

阶段关卡	触发条件	要说的话	阻塞条件
1	PRD 已编写	"PRD 草稿已准备好，位于 docs/prds/{slug}/PRD.md。请审阅。"	用户表示 OK
2	计划已编写	"实现计划已准备好，位于 docs/prds/{slug}/PLAN.md。请审阅。"	用户表示 OK
3	安全扫描通过且验证通过	"实现已完成。测试指南位于 docs/prds/{slug}/TESTING.md。请测试。"	用户反馈
4	用户已验证	建议调用 incu-way-prepare-pr 创建 feat→develop PR；用户运行后分享 URL	用户批准 PR
5	PR 1 已合并	建议调用 incu-way-prepare-pr 创建 develop→main PR；用户运行后分享 URL	用户批准 PR

---

每个功能的文件布局

docs/prds/{prd-slug}/
  PRD.md        # Feature spec (Phase 1)
  PLAN.md       # Implementation plan (Phase 2)
  TESTING.md    # Testing guide (Phase 4)

---

不要做的事

• 阶段关卡 1 获得批准前，不要编写代码。
• 阶段关卡 2 获得批准前，不要开始实现。
• 阶段关卡 3 后，未经用户签字确认，不要合并到 main。
• 绝不要直接合并分支——无论改动多小，都必须通过 PR。
• 在需求发现、编写 PRD 或制定计划时，不要臆造客户端要求、隐含范围或验收标准。
• 如果请求仍存在足以导致客户端预期、约束条件或可能受影响范围不明确的歧义，不要起草 PRD。
• 不要臆造 PRD 中未列出的要求——如果有不明确之处，将其添加到 Open Questions，并在阶段关卡 1 时提出。
• 宣布实现完成前，不要跳过 pnpm typecheck && pnpm lint && pnpm test。