plan-feature

功能规划工作流

将功能创意从概念推进到获批的实施计划，确保范围精简、评审团达成共识，并形成有据可查的决策记录。本技能会在每个阶段质疑假设、提出尖锐问题并提出异议——评审团审议前、投票后以及最终批准前都是如此。目标是制定尽可能完善的计划，而不是照单全收最初的想法。

注意

范围边界：本技能会产出一份_计划_、一份决策记录、一个或多个 GitHub issue，并将它们整合到 产品路线图项目中，同时正确分配阶段。它不会编写应用代码、创建组件、修改数据库架构、运行测试、为实施创建分支或执行任何构建工作。如果用户在计划获批后要求开始构建，请指引他们运行 /build-feature <issue-number>——不要自行开始实施。

第 1 步：收集功能背景

请用户说明：

• 功能是什么（面向用户的行为）
• 面向谁（目标用户）
• 为何重要（业务或产品价值）
• 约束条件（时间、技术、预算、依赖项）

如果用户提供了 GitHub issue 编号，请获取 issue 详情：

gh issue view <number> --json title,body,labels,state,number

记录来源 issue 编号——如果规划是从 GitHub issue 发起的，请保存该编号，以便在第 3、5 和 7 步中更新。

检查是否已规划

如果 issue 带有 build-ready 标签，说明它已经经过 /plan-feature 处理，并被认为规划充分。继续之前请警告用户：

警告

Issue #<number> 已带有 build-ready 标签，表示之前已对其运行过 /plan-feature。再次运行会创建新的决策记录，也可能创建重复的实施 issue。

询问用户是否要：

• (a) 仍然继续（从头重新规划，例如需求发生了重大变化）
• (b) 停止并使用现有计划（改为运行 /build-feature <number>）

未经用户明确选择，不要继续第 1 步之后的内容。

小范围分流

收集完背景信息后，评估该 issue 是否确实需要完整的评审团工作流。并非每个 issue 都需要产品委员会、功能委员会、决策记录和实施 issue。如果以下条件全部满足，该 issue 可能过于简单：

• 预计规模为 XS 或 S（1-2 天工作量）
• 涉及不超过 3 个文件，且不涉及架构决策
• 没有前端改动（或只有简单的前端改动）
• 没有数据库架构改动
• 没有新增 API 端点（修改现有启动或配置代码没有问题）
• 实施方式明确且没有歧义——基本上只有一种正确做法

如果该 issue 符合这些条件，建议用户跳过完整流程：

提示

这个 issue 看起来足够简单，可以跳过完整的 /plan-feature 评审团工作流。范围明确，实施方式直接，而组织两轮评审团审议并撰写决策记录带来的额外开销可能大于收益。

建议操作：直接添加 build-ready 标签，然后运行 /build-feature <number> 或 /build-api <number> 进行实施。

询问用户是否要：

• (a) 添加 build-ready 标签并停止（他们之后会单独运行 /build-feature 或 /build-api）
• (b) 仍然继续完整的 /plan-feature 工作流（例如，他们希望评审团提供先例或政策方面的意见）

如果用户选择 (a)：

1. 为 issue 添加 build-ready 标签
2. 添加一条简短的实施背景评论，记录分流过程中做出的决定（例如采用哪种方案、接受哪些值、要修改哪些文件）
3. 停止——不要继续第 2 步或之后的步骤

如果用户只提供了简短描述，也足够了——但不要只凭表面信息就直接接受。继续第 2 步。

步骤 2：批判性分析与质疑

在将功能提交给委员会之前，请以怀疑型顾问的身份行事。你的任务是对这个想法进行压力测试，帮助用户打磨出尽可能完善的功能方案。

质疑假设

找出并质疑功能请求中的隐含假设：

• 问题有效性：这是在解决正确的问题吗？用户描述的问题会不会只是更深层问题的症状？
• 解决方案匹配度：这是最佳解决方案吗？用户是否只锚定在最先想到的方案上？如果可行，请提出 1-2 种替代方案。
• 范围蔓延风险：用户要求的是否超出了实际所需？验证核心假设所需的最小功能是什么？
• 时机：结合项目当前状态，现在适合构建这项功能吗？是否应该先满足某些前提条件或处理依赖项？

提出澄清问题

提出 2-4 个直击要害的问题，揭示提案中的缺口或薄弱环节。例如：

• “如果出现 [边缘情况]，会发生什么？你考虑过……吗？”
• “你提到了 X，但它如何与现有的 Y 交互？”
• “用户目前采用什么变通办法？这件事真的有多麻烦？”
• “如果必须将交付时间缩短一半，你会删掉什么？”

提出建议

根据你的分析，说明：

• 方案的优势：肯定可行之处
• 你的顾虑：风险、盲点、过度设计
• 你的修改建议：提出具体建议，而不是泛泛而谈的警告
• 替代性表述：如果问题可以用不同方式解决，请说明

检查点：向用户展示你的批判性分析和问题。等待用户回复并调整范围后，再继续进入产品委员会阶段。不要一味认可——如果用户的回答未能消除你的顾虑，请继续提出异议。

步骤 3：启动产品委员会

读取 .claude/councils/product-council.md 中的产品委员会模板，并从全部 6 位成员的角度评估该功能。

模型选择：请参阅 README.md 中的 模型选择 部分，了解如何将 Agent 模型规格映射到 Task 工具参数。

产品策略师（负责人）

• 用户价值：这解决了真实的用户问题吗？是否符合市场需求？
• 优先级：现在适合构建这项功能吗？
• 建议：战略考量、定位

精益交付负责人

• 精益范围：我们能交付的最小版本是什么，以便获取反馈？
• 反馈速度：我们能多快让用户体验到这项功能？
• 功能标志策略：是否应该在功能标志后面进行原型开发？
• 建议：如何更快交付、更快学习

设计负责人 — 咨询：ui-design

• 设计质量：是否符合品牌规范？用户体验是否直观？
• 无障碍性：是否需要符合 WCAG？
• 建议：设计方法、所需组件

业务运营负责人

• 成本分析：需要多少预算？基础设施成本是多少？
• 投资回报潜力：预期投资回报是多少？
• 建议：成本优化或预算方面的顾虑

首席工程师 — 咨询：full-stack-orchestration

• 技术可行性：我们能否构建这项功能？复杂度如何？
• 架构契合度：这是否符合当前技术栈？
• 建议：技术限制或替代方案

前端专家 — 咨询：frontend-mobile-development

• 实施评估：用户体验是否可行？组件复杂度如何？
• 用户体验：实施过程中有哪些挑战？
• 建议：前端实施方案

展示完整的产品委员会评估，包括所有投票和建议。

委员会评审后的综合分析

委员会投票结束后，不要只是转述他们的结果。请加入你自己的分析：

• 你在哪些方面认同委员会？ 强调最有力的观点。
• 你在哪些方面持不同意见？ 如果某位委员的评估似乎不妥，请指出并说明原因。
• 委员会遗漏了什么？ 找出盲点——没有委员提及但很重要的话题。
• 检查群体思维：如果所有委员意见一致，请扮演反方。对这个功能最有力的反对理由是什么？
• 完善后的建议：结合委员会意见和你在第 2 步中的批判性分析，给出你诚实的建议——按提议构建、调整范围、暂缓，还是彻底重新考虑。

检查点：向用户展示产品委员会的结果和你的综合分析。如果你发现委员会未提出的顾虑，请现在指出。在进入技术规划前，等待用户批准范围和优先级。

第 4 步：定义精简范围

根据产品委员会的反馈，明确定义：

• MVP 范围：首个迭代（最长 1-2 周）要交付的内容。列出面向用户的具体功能。
• 后续迭代：MVP 验证后要做的内容。列出延期功能。
• 功能标志策略：此功能是否应在功能标志保护下发布，以及标志名称。
• 成功指标：如何判断此功能有效？定义 2-3 个可衡量的结果。

第 5 步：召集功能委员会

从 .claude/councils/feature-council.md 读取功能委员会模板，并制定技术实施计划。

模型选择：有关将 Agent 模型规格映射到 Task 工具参数的信息，请参阅 README.md 中的 模型选择部分。

首席工程师（负责人）——咨询：full-stack-orchestration

• 架构契合度：这是否符合系统设计？
• 复杂度评估：范围是否恰当？
• 建议：架构方面的考量、应遵循的模式

前端专家——咨询：frontend-mobile-development

• UI/UX 方案：组件结构、用户交互流程
• 设计集成：是否需要 Tailwind/shadcn 组件？使用新组件还是现有组件？
• 建议：前端实施策略

后端专家——咨询：backend-development

• API 设计：端点、契约、数据流
• 数据库变更：是否需要修改架构？
• 建议：后端实施策略

如果该功能涉及 API 工作，请调用 /backend-development:api-design-principles，获取详细的 API 设计指导。

QA 负责人

• 测试策略：单元测试、集成测试、E2E 测试方案
• 边界情况：要测试的场景、边界条件
• 建议：质量门槛和验收标准

实施计划

根据委员会意见，制定结构化的任务分解：

前端任务：组件开发、路由、状态管理、样式 后端任务：API 端点、服务、业务逻辑、验证 数据库任务：架构变更、迁移、种子数据 测试任务：创建测试、覆盖率目标、E2E 场景 预估复杂度：小 / 中 / 大

规模和排期估算：对于将要创建的每项任务/议题，委员会必须提供：

• 规模：XS（1 天）、S（2 天）、M（3 天）、L（5 天）或 XL（8 天），以工作日计
• 依赖项：必须先完成哪些其他议题才能开始此项
• 里程碑：该议题所属阶段（M1-M5）
• 排期位置：考虑依赖项和已排期事项后，此议题在里程碑串行队列中的位置

理事会后综合分析

Feature Council 投票结束后，补充你自己的技术分析：

• 实施风险：此计划中最难的部分是什么？团队最可能在哪些地方遇到阻碍，或低估工作量？
• 执行顺序问题：任务拆分的顺序是否合理？前端和后端工作之间是否存在隐藏依赖？
• 过度设计检查：Feature Council 提出的基础设施是否超出此功能的实际需要？能否减少工作量，同时仍然验证假设？
• 设计不足检查：是否遗漏了日后可能造成问题的事项，例如错误处理、迁移回滚、无障碍访问或性能？
• 坦诚评估：综合所有讨论，你对该计划按当前方案成功实施的信心有多高（高／中／低）？请说明原因。

检查点：向用户展示 Feature Council 的实施计划和你的技术综合分析。指出执行顺序、风险或范围方面的任何顾虑。等待用户批准任务拆分后再继续。

步骤 6：生成决策记录

读取 docs/decisions/ 中的现有文件，确定下一个决策编号。

使用 docs/decisions/001-example-architecture-decision.md 中的模板，创建一份决策记录，包含：

• 日期：今天的日期
• 理事会：Product Council + Feature Council
• 状态：已批准（用户批准后）
• 问题：正在评估的功能
• 背景：当前情况、需求和限制
• 理事会投票：Product Council 和 Feature Council 的所有投票
• 决策：已批准的范围（MVP + 未来规划）
• 理由摘要：综合所有理事会成员的观点
• 行动项：包含明确负责人的任务拆分（前端、后端、测试）
• 时间线：根据复杂度设定目标日期
• 后续跟进：何时重新评估，以及发布后要验证的事项
• 参考资料：相关问题、文档和先前的决策

GFM 格式要求

决策记录将以 GitHub Flavored Markdown 格式呈现。请遵循 .claude/CLAUDE.md 中的 GFM 规则：

• 元数据块必须使用项目符号（- **Key**: value），不要使用连续的加粗行。
• 使用 GitHub 提醒（> [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]）添加提示，而不要使用粗体／斜体强调。
• 如果决策涉及多个组件、服务或数据流，请包含 Mermaid 图表。将其放在「背景」或「理由摘要」部分，以可视化架构。
• 如果理事会评估内容较长，导致记录中的投票部分超过约 150 行，请使用可折叠的 <details> 部分。
• 对于结构化比较（例如，列出选项及其权衡），请使用表格。

如果决策涉及架构选择，请调用 /documentation-generation:architecture-decision-records 获取 ADR 格式指导。

检查点：保存前，将决策记录提交给用户进行最终审核。

步骤 7：创建分支并保存产物

1. 按照 CONTRIBUTING.md 中的约定，从最新的 origin/main 创建功能分支：

   git fetch origin main
   git checkout -b feature/<feature-slug> origin/main
   

2. 保存决策记录：

   docs/decisions/NNN-<feature-slug>.md
   

3. 更新决策索引：

   扫描目录中的所有决策文件，重新生成 docs/decisions/INDEX.md 中的 Decisions 表格。对每个文件（不包括 INDEX.md 和 001-example-architecture-decision.md）：

   • 阅读标题，提取决策编号和标题
   • 阅读元数据块，提取 Date、Council、Status
   • 根据决策的 Question 和 Context 部分提炼 2–5 个 Key Topics（小写、以逗号分隔）

   按照时间倒序（最新的在前）重建完整表格。不要修改 INDEX.md 中的其他部分（简介、How to Use 和 Related Resources 部分保持不变）。

4. 更新主文档索引：

   如果在 docs/ 中创建了任何新文档（包括决策记录），请确认 docs/INDEX.md 中已反映这些文档。决策记录已由现有的 decisions/INDEX.md 条目涵盖，因此无需逐条更新。不过，如果在 docs/ 中的 decisions/ 之外新增了文档（例如，新增科学文档），请在 docs/INDEX.md 中的相应表格里添加一行。

5. 使用以下命令提交：

   docs(council): document feature plan for <feature-name>
   

6. 推送前，对所有新增或修改的文件运行 Prettier：

   pnpm exec prettier --write <files>
   

   暂存并单独提交任何格式修正：

   style: fix Prettier formatting in decision record and skill
   

7. 推送分支，并为决策记录创建 PR：

   git push -u origin feature/<feature-slug>
   
   gh pr create \
     --title "docs(council): add Decision NNN — <feature-name>" \
     --body "## Summary\n\n- Adds Decision NNN documenting the council-approved plan for <feature-name>\n- Product Council (<tally>) and Feature Council (<tally>) both approved\n- Implementation issues: #N, #N, ...\n\n## Test plan\n\n- [ ] Decision record renders correctly in GitHub markdown\n- [ ] Mermaid diagrams render (if any)\n- [ ] All cross-references to existing issues and docs are valid links\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)"
   

8. 持续关注 CI，直到所有检查通过：

   gh pr checks <pr-number> --watch
   

   如果检查失败，请阅读失败日志、修复问题、提交、推送，然后再次关注检查结果。CI 通过前，不要继续创建 Issue。

   重要

   每次 /plan-feature 运行只要生成了决策记录，就必须提交 PR，以便将记录合并到 main。PR 必须通过 CI，规划步骤才算完成。决策记录分支也是 /build-feature 将用于实现的功能分支。

更新源 GitHub Issue

如果规划是从 GitHub Issue 启动的（在步骤 1 中跟踪），请使用 council 的结论更新源 Issue。这样可以让 Issue 作为一份持续更新的文档，反映规划结果。

在源 Issue 中添加评论，总结 council 的结果：

gh issue comment <number> --body "$(cat <<'EOF'
## Council Planning Complete

### Product Council — <Vote tally> (Approve-Concern-Block)
<2-3 sentence summary of key Product Council decisions>

### Feature Council — <Vote tally> (Approve-Concern-Block)
<2-3 sentence summary of key technical decisions>

### Key Decisions
- <Decision 1>
- <Decision 2>
- <Decision 3>

### Artifacts
- **Decision Record**: [Decision NNN](docs/decisions/NNN-slug.md) _(link becomes active after the planning PR merges to main)_
- **Feature Branch**: `feature/<slug>`
- **Implementation Issue**: #<new-issue-number> (created in Step 9)

Planning completed via `/plan-feature`.
EOF
)"

为源 Issue 添加 build-ready 标签（此时规划已全部完成）：

gh label list | grep -q "build-ready" || gh label create "build-ready" --description "Planned by /plan-feature and ready for /build-feature" --color "0E8A16"
gh issue edit <number> --add-label "build-ready"

确保源 Issue 已添加到项目看板

为源 Issue 添加标签后，请确认它已列入 产品路线图 项目看板。带有 build-ready 标签但未列入看板的 Issue 会成为孤立的工作项，无法被 /build-feature 的自动选取功能发现。

# Check if the issue is already on the project board
# --limit 200 covers the current board size; increase if the project grows beyond 200 items
EXISTING=$(gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for item in data.get('items', []):
    # <number> must be an integer literal, e.g., == 42, not == '42'
    if item.get('content', {}).get('number') == <number>:
        print(item['id'])
        break
")

# If not on the board, add it and set fields
if [ -z "$EXISTING" ]; then
  ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "https://github.com/{OWNER}/{REPO}/issues/<number>" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
  # Set phase and milestone fields to match the implementation issues that will be created in the Issue Creation step
  gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
  echo "Added issue #<number> to the project board and set phase."
fi

说明

源 Issue 保留其原始内容作为上下文。评论提供清晰的审计记录，说明各 council 的决策，并链接到详细的决策记录。在 Issue 创建步骤（步骤 9）中创建实现 Issue 后，请返回编辑此评论，补充实现 Issue 编号。

步骤 8：提交 Issue 前验证

创建 GitHub issue 前，请验证规划材料：

1. 决策记录完整性：确认决策记录文件存在，且包含所有必需章节（Question、Context、Council Votes、Decision、Rationale Summary、Action Items、Timeline）。如果缺少任何章节，请停止并补齐后再继续。

2. 委员会共识：检查两个委员会的投票章节，确认是否有“Block”票。如果存在 Block 票：

   警告

   一位委员会成员投票阻止了此功能。在存在未解决的 Block 票时创建实施 issue 并不常见。请考虑先解决该顾虑再继续。

   询问用户是要继续，还是先解决该顾虑。

3. 包含任务拆分：确认 Action Items 章节至少包含一个任务（复选框行）。如果为空，请停止并让用户定义实施任务。

4. 批准状态：确认 Decision 章节显示 Status: Approved。如果未获批准，请在继续前提醒用户。

5. 重复 issue 检测：搜索现有未关闭的 issue，查找可能重复或工作内容大幅重叠的 issue：

   gh issue list --state open --limit 200 --json number,title,labels
   

   将计划中的 issue 标题和范围与现有 issue 进行比较。如果发现可能重复的 issue：

   警告

   检测到可能重复的 issue：issue #N 的标题／范围相似。创建新 issue 前，请先检查现有 issue。

   向用户展示可能重复的 issue，并询问是否要：

   • (a) 改为更新现有 issue（将规划背景作为评论添加）
   • (b) 仍然创建新 issue（如果范围确实不同，请说明原因）
   • (c) 调整计划以避免重叠

   请勿创建与现有工作项大幅重复的 issue。

步骤 9：创建 GitHub Issue

重要

GitHub issue 是根据决策记录整理出的可执行工作项，并不取代决策记录。决策记录（步骤 6）仍是记录委员会评估、理由和架构背景的权威项目级文档。Issue 会引用决策记录，并提供面向任务的视图，供 /build-feature 使用。

创建包含完整实施计划的 GitHub issue，以便随时（立即或数天后）从 issue 运行 /build-feature。

确保标签存在

gh label list | grep -q "feature-implementation" || gh label create "feature-implementation" --description "Implementation plan from /plan-feature" --color "1D76DB"
gh label list | grep -q "security-audit" || gh label create "security-audit" --description "Phase security audit checkpoint" --color "D93F0B"

整理 Issue 正文

按照 .github/ISSUE_TEMPLATE/feature-implementation.yml 中的模板编写 issue 正文。请包含以下章节：

问题陈述：摘自决策记录的 Question 和 Context 章节。说明要解决的问题及其原因。

委员会决策：概述两个委员会的意见：

• Product Council 投票统计和关键决策
• Feature Council 投票统计和架构决策
• 任何异议或附带条件

如果委员会完整投票内容超过约 30 行，请使用可折叠的 <details> 章节。

实施计划：将决策记录中的 Action Items 按层级（Frontend、Backend、Database、Testing）整理，并添加复选框。这是 /build-feature 将使用的主要内容。

成功指标：来自精益范围定义（步骤 4）的可衡量结果。

技术背景：关键技术决策，包括架构模式、API 契约、模式变更和组件结构。

决策记录引用：链接到决策记录文件：[Decision NNN](docs/decisions/NNN-slug.md)

功能分支：步骤 7 中创建的分支名称。

功能标志：标志名称和策略（如适用）。

预计复杂度：Feature Council 评估的 Small / Medium / Large。

多 Issue 选项

如果实施计划包含多个不同阶段，请询问用户：

实施计划包含 N 个阶段。您希望：

1. 创建一个包含所有阶段任务组的 Issue
2. 每个阶段分别创建 Issue（互相引用）

如果选择分别创建 Issue，请按顺序创建，并注明“第 X 部分，共 N 部分”，同时添加同级 Issue 的链接。每个 Issue 都必须分配到正确的项目阶段（见下方“阶段与项目映射”）。

创建多个阶段 Issue 时，还要创建一个父 Issue，并按照 AGENTS.md 中的“父 Issue 和子 Issue”部分设置子 Issue 关系：

1. 首先创建父 Issue（高层级功能描述，不包含实施细节）
2. 为每个阶段创建子 Issue
3. 通过子 Issue API 将子 Issue 关联到父 Issue：

   CHILD_ID=$(gh api repos/{OWNER}/{REPO}/issues/<child-number> --jq '.id')
   gh api repos/{OWNER}/{REPO}/issues/<parent-number>/sub_issues -X POST -F sub_issue_id=$CHILD_ID
   

4. 将父 Issue 的日期设为覆盖所有子 Issue 的日期范围（最早的开始日期至最晚的目标日期）
5. 如果子 Issue 跨越多个里程碑：将父 Issue 从任何里程碑中移除（gh api repos/{OWNER}/{REPO}/issues/<number> -X PATCH -F milestone=null），并通过 GraphQL（clearProjectV2ItemFieldValue）清除其项目阶段字段。父 Issue 是跟踪容器；子 Issue 承载里程碑和阶段分配。如果使用了源 Issue 作为父 Issue，且该 Issue 已有里程碑，也要将其移除。

阶段与项目映射

在提交 Issue 供用户确认之前，确定每个 Issue 对应的正确项目阶段和规模：

1. 查看 {PROJECT_BOARD_NAME} 上的现有阶段：

   gh project field-list 6 --owner {OWNER} --format json
   

2. 根据 docs/PRODUCT.md 中的里程碑划分和工作性质，将每个 Issue 映射到一个阶段。考虑该 Issue 在现有路线图进程中的位置。

3. 如果计划中的工作不适合任何现有阶段，请推荐新阶段。新阶段建议必须说明理由，以及其相对于现有阶段的位置（例如，“位于 M2 和 M3 之间”）。

检查点：提交完整的 Issue 计划，等待用户确认。

提供表格，总结将要创建或修改的所有 Issue、其项目阶段分配以及任何项目变更：

要创建/更新的 Issue：

操作	Issue	标题	阶段	规模	里程碑	开始日期	目标日期
创建	NEW	<title>	<phase>	<XS/S/M/L/XL>	<M1-M5>	YYYY-MM-DD	YYYY-MM-DD
更新	#N	<title>	<phase>	<size>	<M1-M5>	YYYY-MM-DD	YYYY-MM-DD

如果建议了新阶段：

新阶段	位置	理由
M_N_: <Name>	在 M_N_ 之后	为什么需要此阶段

如果需要为受影响的阶段创建或更新 GTM 审查 Issue 或安全审计 Issue（见下方“GTM 审查门槛”和“安全审计门槛”），请将其纳入摘要。

在创建任何 Issue 或修改项目之前，等待用户明确批准。

Issue 创建与项目分配

确保所需的标签存在：

gh label list | grep -q "feature-implementation" || gh label create "feature-implementation" --description "Implementation plan from /plan-feature" --color "1D76DB"
gh label list | grep -q "build-ready" || gh label create "build-ready" --description "Planned by /plan-feature and ready for /build-feature" --color "0E8A16"
gh label list | grep -q "gtm-review" || gh label create "gtm-review" --description "Go to Market & Business Review checkpoint" --color "0E8A16"
gh label list | grep -q "security-audit" || gh label create "security-audit" --description "Phase security audit checkpoint" --color "D93F0B"

选择性添加 build-ready 标签

对于要创建的每个 issue，判断其计划是否足够完善，可以直接进入 /build-feature：

• 添加 build-ready：如果 issue 包含具体的任务分解、明确的验收标准，且没有重要的未决问题。这是单 issue 计划以及多 issue 计划中范围明确的子 issue 的常见情况。
• 不要添加 build-ready：如果 issue 范围宽泛、存在尚未解决的架构问题，或者适合单独进行一次 /plan-feature 流程来细化范围并征求 council 意见。这常见于多 issue 计划中的大型子 issue，尤其是目前仅确立了高层方向的情况。

对于每个获批的 issue，创建 issue 并将其分配到项目，设置正确的阶段、规模、里程碑和日期：

# Create the issue (add --label "build-ready" if the issue is fully planned)
ISSUE_URL=$(gh issue create \
  --title "<title>" \
  --body "<body>" \
  --label "enhancement" \
  --label "feature-implementation" \
  --milestone "<milestone-name>" | tail -1)

# Extract issue number from URL
ISSUE_NUM=$(echo "$ISSUE_URL" | grep -o '[0-9]*$')

# Add to project and set phase + size fields
ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "$ISSUE_URL" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {SIZE_FIELD_ID} --single-select-option-id <size-option-id>

# Set Start and Target dates (computed from size estimate and schedule position)
gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {START_FIELD_ID} --date <start-date>
gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {TARGET_FIELD_ID} --date <target-date>

说明

项目字段 ID — 如果项目结构发生变化，请通过 gh project field-list 6 --owner {OWNER} --format json 刷新。

• 阶段字段：{PHASE_FIELD_ID} — 选项：M0 (5d1aaeb2)、M1 (4cfa6c51)、M2 (27c0efa8)、M3 (ed327f33)、M4 (df98aad8)、M5 (0604582f)
• 规模字段：{SIZE_FIELD_ID} — 选项：XS (88044618)、S (27e6800e)、M (c4753411)、L (cde643b6)、XL (286a9b9c)
• 里程碑编号：M0=1、M1=2、M2=3、M3=4、M4=5、M5=6
• 开始日期字段：{START_FIELD_ID}
• 目标日期字段：{TARGET_FIELD_ID}

排期日期计算

创建 issue 时，按照 AGENTS.md 中的排期规则计算开始日期和目标日期：

1. 检查目标里程碑中的现有排期：

   gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200
   

   找出里程碑中所有非 gate 项目的最晚目标日期。Gate 项目是带有 gtm-review 或 security-audit 标签的 issue；确定插入位置时应将其排除。

2. 根据规模与天数对照表计算新 issue 的日期（XS=1、S=2、M=3、L=5、XL=8 个工作日）。开始日期为目标日期最晚的非 gate 项目之后的下一个工作日（或依赖项的目标日期之后的下一个工作日，取较晚者）。跳过周末。

3. 级联调整所有后续项目。 插入新 issue 后，重新计算里程碑中排在它之后的每个 issue的开始日期和目标日期。每个后续 issue 的开始日期 = 前一个 issue 的目标日期之后的下一个工作日。相邻 issue 之间不得有间隔或重叠——开始日期和目标日期决定了操作顺序。

4. 将 gate 项目顺延。 每个里程碑结尾必须恰好有两个 gate 项目，顺序固定：GTM review（倒数第二），然后是 security audit（最后）。所有非 gate 项目排定后，重新计算 gate 项目的日期，使 GTM review 的开始日期为最后一个非 gate 项目的目标日期之后的下一个工作日，security audit 的开始日期为 GTM review 的目标日期之后的下一个工作日。在项目看板上更新这两个 gate 项目的开始日期和目标日期。

5. 如果 security audit 的新目标日期晚于里程碑到期日，则更新里程碑到期日：

   gh api repos/{OWNER}/{REPO}/milestones/<number> -X PATCH -f due_on="<new-target>T00:00:00Z"
   

   重要

   任何类型的 issue（功能、缺陷修复、杂务、测试等）都不得安排在 GTM review 和 security audit 这两个 gate 项目之后。这两个项目始终是每个里程碑的最后两项，其顺序（GTM → security audit）是必须在每次项目更新中保持的固定规则。

6. 使用开始日期和目标日期字段 ID 更新项目看板上所有受影响的项目。 只重新计算当前正在开发的里程碑。后续里程碑将在当前里程碑结束时调整。

如果请求创建多个 issue，请依次创建，并记录 issue 编号以便交叉引用。

报告创建的 issue 编号、URL、项目阶段分配、里程碑和排期日期。

上市审核关卡

每个项目阶段都必须以一个全面的上市与业务审核议题结束。创建或分配功能议题后，请确认每个受影响阶段都已覆盖上市审核：

1. 检查受影响阶段是否已有上市审核议题：

   gh issue list --state open --label "gtm-review" --json number,title
   

2. 对于缺少上市审核议题的阶段，请创建一个：

   gh issue create \
     --title "gtm: Go to Market & Business Review — <Phase Name>" \
     --body "<body>" \
     --label "enhancement" \
     --label "marketing" \
     --label "gtm-review"
   

   上市审核议题正文必须包含：

   • 阶段摘要：此阶段包含的功能和变更
   • 营销页面审查：核对清单，用于确认落地页、功能说明、截图和行动号召均反映此阶段的变更
   • 内容一致性：博客文章、帮助文档和应用内文案与新功能保持一致
   • 上市建议：定位、信息传达、发布策略和渠道策略
   • 业务审核：收入影响、定价影响、竞争定位更新
   • 成功指标：如何衡量此阶段的上市效果

   重要

   上市工作中撰写的所有面向用户的文案（落地页、博客文章、应用内文本、营销内容）都必须遵循 AGENTS.md 中的面向用户的内容风格规则。不得使用 em dash、AI 腔词汇或夸大宣传。

   将上市审核议题添加到项目中，并设置正确的阶段、规模、里程碑和日期：

   GTM_URL=<created-issue-url>
   GTM_NUM=$(echo "$GTM_URL" | grep -o '[0-9]*$')
   
   # Add to project and set fields
   GTM_ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "$GTM_URL" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {SIZE_FIELD_ID} --single-select-option-id <size-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {START_FIELD_ID} --date <start-date>
   gh project item-edit --project-id {PROJECT_ID} --id "$GTM_ITEM_ID" --field-id {TARGET_FIELD_ID} --date <target-date>
   

   上市审核议题的规模为 S（2 个工作日）。其开始日期为该阶段最后一个功能议题的目标日期后的下一个工作日。请使用与功能议题相同的排期逻辑计算日期（参见上文“排期日期计算”）。

3. 对于已有上市审核议题的阶段，请检查新规划的工作是否已纳入审核范围。如果阶段范围显著扩大，请在现有上市审核议题中添加评论，说明需要审核的新内容。

重要

上市审核议题可确保每个可交付阶段都包含业务审核检查点。它们不是可选项，每个阶段在被视为完成之前都必须有一个上市审核议题。豁免情况：纯粹的错误修复或持续交付/维护阶段（例如依赖项升级、安全补丁、CI 改进）可豁免。

安全审计关卡

每个项目阶段都必须以一项全面的 安全审计 issue 作为最后一项工作——安排在 GTM 评审之后。这样可确保 GTM 评审期间引入的任何代码更改也纳入审计范围。确认 GTM 覆盖情况后，检查每个受影响阶段的安全审计覆盖情况：

1. 检查受影响阶段是否已有安全审计 issue：

   gh issue list --state open --label "security-audit" --json number,title
   

2. 对于缺少安全审计 issue 的阶段，创建一个：

   gh issue create \
     --title "security: Comprehensive Security Audit — <Phase Name>" \
     --body "<body>" \
     --label "enhancement" \
     --label "security-audit"
   

   安全审计 issue 正文必须包含：

   • 阶段摘要：本阶段中需要接受安全审查的功能、服务和更改
   • 审计范围：受影响的代码库区域（API 端点、身份验证流程、数据模型、第三方集成等）
   • SAST 扫描：对本阶段的所有代码更改运行自动化静态分析
   • STRIDE 威胁建模：对新增或修改的功能应用 STRIDE 方法
   • 攻击树分析：针对威胁建模中识别出的风险最高的 3 项构建攻击树
   • 依赖项审计：检查新增或更新的依赖项是否存在已知漏洞
   • 修复计划：按优先级列出审计发现，注明严重程度并提供修复建议

   将安全审计 issue 添加到项目中，并设置正确的阶段、规模、里程碑和 日期：

   SEC_URL=<created-issue-url>
   SEC_NUM=$(echo "$SEC_URL" | grep -o '[0-9]*$')
   
   # Add to project and set fields
   SEC_ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "$SEC_URL" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {PHASE_FIELD_ID} --single-select-option-id <phase-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {SIZE_FIELD_ID} --single-select-option-id <size-option-id>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {START_FIELD_ID} --date <start-date>
   gh project item-edit --project-id {PROJECT_ID} --id "$SEC_ITEM_ID" --field-id {TARGET_FIELD_ID} --date <target-date>
   

   安全审计 issue 的规模为 M（3 个工作日）。其 Start 日期为同一阶段中 GTM issue 的 Target 日期之后的下一个工作日。安全审计始终是阶段中的最后一项 issue。日期计算方式与功能 issue 的排期逻辑相同（见上文“排期日期计算”）。

3. 对于已有安全审计 issue 的阶段，检查新计划的工作是否已覆盖。如果阶段范围显著扩大，请在现有安全审计 issue 中添加评论，指出需要审查的新事项。

重要

安全审计 issue 可确保每个可交付阶段都在发布前进行安全检查。它们并非可选项——每个阶段在被视为完成前都必须有一个安全审计。安全审计始终是阶段中的最后一项 issue，在 GTM 评审之后执行。使用 /security-audit 运行。例外：纯粹的错误修复或持续交付／维护阶段（例如，依赖项升级、安全补丁、CI 改进）可豁免，GTM 评审也采用相同的豁免规则。

第 10 步：输出摘要

提供清晰的摘要：

• 已批准范围：MVP 功能和延期事项
• 任务拆分：前端、后端、数据库和测试任务
• 功能标志：名称和策略（如适用）
• 成功指标：如何衡量结果
• 分支：可用于开始实施的功能分支名称
• 决策记录：供参考的文件路径
• GitHub Issue(s)：实施计划对应的 issue 编号和 URL
• 项目阶段：每个 issue 所属的产品路线图阶段
• GTM 覆盖情况：受影响阶段的 GTM 评审 issue——已创建、已更新或已核实
• 安全审计覆盖情况：受影响阶段的安全审计 issue——已创建、已更新或已核实

下一步：运行 /build-feature <issue-number> 进行全栈实施，或运行 /build-api 仅处理后端工作。