analyze-requirements

スキル：要件分析

目的

要件レベルの問題を診断し、曖昧な意図を有効でテスト可能な要件に変換します。開発者が「Xを作りたい」という段階から、明確な問題文、優先順位付けされた要件、明確な制約、限定されたスコープへと進めるよう導きます。これらはすべて、設計や実装を始める前に行います。

---

主な目標

第一の目標：すべての要件がテスト可能で、スコープが明確であり、実際の問題に基づいている、検証済みの要件文書を作成します。

成功基準（すべて満たす必要があります）：

1. ✅ 明確な問題：明確な問題文があり、解決策や技術への言及がありません
2. ✅ IDを使ってテストできる要件：各要件に受け入れ基準と一意の「R-NN」ID（例：R-01、R-02）があります。IDは連続しており、欠番や重複がありません
3. ✅ 制約の一覧：実際の制約（予算、期間、スキル、依存関係）を仮定と分けて記載します
4. ✅ 限定されたスコープ：V1の境界が明確で、延期した項目を列挙し、再検討のきっかけを記録します
5. ✅ ユーザーの確認：ユーザーが検証済みの要件を明示的に承認します（「承認しました」、「よさそうです」、「続けてください」など、同等の表現）
6. ✅ 文書の永続化：要件文書を docs/ARTIFACT_NORMS.md に従って docs/requirements-planning/<topic>.md に書き込み、コミットします

受け入れテスト：このプロジェクトに詳しくない人が要件文書を読んで、問題は何か、誰がその問題を抱えているか、「完了」とはどのような状態か、何がスコープ外かを、確認の質問をせずに理解できますか？

---

スコープの境界

このスキルの担当範囲：

• 曖昧な意図→検証済みの要件文書
• 問題の発見と明確化
• 明確化のための質問と受け入れ基準の作成
• 制約の一覧と仮定の対応付け
• スコープの定義と優先順位付け（V1とそれ以降のバージョン）
• 要件の品質評価（明確さ、具体性、完全性）

このスキルの担当範囲外：

• 設計とアーキテクチャの決定（「ソリューション設計」を使用）
• 実装計画やタスクリスト（実装計画スキルを使用）
• コードの作成（開発スキルを使用）
• コードレビュー（「コードレビュー」を使用）
• 技術の選定（制約条件には言及しますが、技術の選定は設計段階で行います）

引き継ぎのタイミング：要件が検証された（すべての成功基準を満たした）時点で、設計の検討は「ソリューション設計」に引き継ぎます。設計が単純な場合は、実装計画に引き継ぎます。

---

使用場面（ユースケース）

• 新規プロジェクトの開始：開発者が「Xを作りたい」と言った場合、設計を始める前に本当の問題を明らかにし、要件を検証します。
• 機能リクエストのトリアージ：ステークホルダーが曖昧な機能リクエストを提出した場合、問題、スコープ、受け入れ基準を明確にします。
• スコープの肥大化の防止：プロジェクトが拡大し続けている場合、優先順位付けと明確なV1の境界を適用します。
• 要件の検証：既存の要件が不完全に感じられる場合、どの状態にあるかを診断し、改善します。
• 制約の発見：プロジェクト中盤で予期しない障害が見つかった場合、隠れた制約や仮定が作業を妨げる前に明らかにします。

---

動作

インタラクションポリシー

• デフォルト：入力から現在の状態を推定し、最も早い未解決の状態から始めます
• 選択肢の提示：一度に質問は1つだけにします。可能な場合は「[A][B][C]」を提示します
• 確認：設計に引き継ぐ前、および要件文書を書く前に確認します

ハードゲート：検証前に設計しない

DO NOT propose architecture, choose technologies, create designs,
or write code until requirements are validated.

Requirements describe PROBLEMS and NEEDS, not SOLUTIONS.
If a requirement mentions technology, it is a solution in disguise.

第0段階：分類

開始時に宣言します：「設計や実装を始める前に要件を検証するため、要件分析スキルを使用します。」

入力の品質を簡潔に評価します：

ディメンション	範囲	確認項目
明確さ	0–100%	明確な解釈がありますか？用語は定義されていますか？
具体性	0–100%	コンテキストが示されていますか？成功基準に言及していますか？スコープは限定されていますか？
完全性	0–100%	必要な情報がすべて提示されていますか？制約条件に言及していますか？

判断マトリクス：

合計スコア	アクション
< 40%	状態RA0（問題の発見）から開始します
40–70%	最も早い問題状態を特定し、そこから開始します
> 70%	迅速に検証し、ギャップに注目します

第1段階：診断 — 現在の状態を特定する

状態の順序に沿って進めます。状態を飛ばさないでください。問題が明確でない場合は、要件について議論しません。

状態 RA0：問題の記述がない

症状：解決策から始めている（「Xを作りたい」）。機能の一覧に根拠となる問題がない。「誰もがこれを必要としている」という推論。誰がどのような問題を抱えているかを明確に言えない。

重要な質問（一度に1つずつ）：

• 「このアイデアにつながった具体的な不満や困りごとは何ですか？」
• 「人々（またはあなた）は今日、何をしていますか？」
• 「これが存在しなかったらどうなりますか？誰が、どのような影響を受けますか？」
• 「あなたがユーザーなら、今このことを考えるきっかけは何ですか？」

介入：

• 問題文の概要：誰がどのような問題を抱えていて、その問題がなぜ重要なのかを明らかにします
• 「5人のユーザー」テスト：恩恵を受ける具体的な人を5人挙げます（たとえそのうち1人が自分自身でもかまいません）
• ジョブ理論：「[状況]のとき、[動機]のために[結果]を得たい」
• 問題の考古学：特定の不満が生じた出来事までさかのぼります

終了基準：解決策への言及がない問題文が存在します。

状態 RA1：解決策優先の考え方

症状：問題が明確になる前に技術を選んでいる（「データベースが必要」、「Reactを使うべき」）。要件がニーズではなく実装を記述している。技術に触れずに要件を説明できない。

重要な質問：

• 「この機能の背後にあるニーズは何ですか？」
• 「この技術が存在しなかったとしても、何が必要ですか？」
• 「自分の問題を解決しようとしていますか、それとも他者の解決策を複製しようとしていますか？」
• 「この技術は必須ですか（制約）、それとも単に使い慣れているだけですか（好み）？」

介入：

• 「解決策を取り除く」演習：実装に関する言葉を使わずに要件を説明します
• 機能の抽出：各要件を技術用語なしで「システムは[動詞]しなければならない……」と書き換えます
• 制約と好みの区別：必須の制約とデフォルト設定を分けます

終了基準：すべての要件が実装ではなくニーズを記述しています。技術への言及は削除されているか、真の制約として明示的に記録されています。

状態 RA2：曖昧な要件

症状：「完了」がどのような状態かを説明できない。形容詞に基づく要件（「高速」、「簡単」、「直感的」）。テストできない要件。「ユーザーは……できるべき」という表現に具体性がない。

重要な質問：

• 「具体的なシナリオの例を挙げられますか？」
• 「優れた実装と比べて、期待外れの実装とはどのようなものですか？」
• 「このニーズを満たすために最低限必要なものは何ですか？」
• 「この要件が満たされたかどうかを、どうすれば確認できますか？」

介入：

• 受け入れシナリオの作成：「[コンテキスト]が与えられたとき、[アクション]を行うと、[結果]となる」
• 具体性の段階：誰が具体的に何をしますか？いつですか？
• 「完了とは……」の演習：満たすことのできる最小限の内容を説明します
• テスト可能性の確認：テストを書けないなら、要件をまだ理解できていません

終了基準：すべての要件に受け入れ基準があります。形容詞だけの要件はありません。

状態 RA3：隠れた制約

症状：予期しない依存関係が後になって判明する。制約の一覧が明示されていない。仮定が事実として扱われている。議論の中で障害が見つかる。

重要な質問：

• 「どのような外部依存関係がありますか？」
• 「実際に利用できるリソース、スキル、時間は何ですか？」
• 「それが事実だと判明した場合、このプロジェクトを頓挫させるものは何ですか？」
• 「まだ検証していないのに、事実だと思い込んでいることは何ですか？」

介入：

• 制約の一覧：予算、期間、スキル、依存関係、統合を実際の制約として列挙します
• 仮定の対応付け：検証済みの事実と未検証の仮定を分けます
• リスクのプレモーテム：「6か月後、この取り組みは失敗しました。なぜですか？」
• 依存関係の発見：これより前に必要なものは何ですか？

終了基準：実際の制約と仮定を明確に区別した制約の一覧が存在します。

状態 RA4：スコープの肥大化

症状：すべての機能が同じくらい重要に感じられる。V1の境界がない。「これをやるなら……」という追加がある。要件が満たされるより速く増えている。

重要な質問：

• 「3つだけ出荷できるとしたら、何を出荷しますか？」
• 「中核となる問題を解決したまま削減できるものは何ですか？」
• 「最小限の有用なバージョンは何ですか？」
• 「延期した項目を再検討するきっかけは何ですか？」

介入：

• 削減優先の方法：すべてを対象にして始め、必要なものだけを追加します
• 順位付け：同順位を認めず、厳密に並べ替えます
• ウォーキングスケルトン：最も薄い有用なバージョンを特定します
• MoSCoW：必須／すべき／できれば／対象外
• 再検討の明確なきっかけを付けた、延期機能の一覧

終了基準：V1の境界が明確です。延期した項目にはきっかけが記載されています。スコープ内の項目に曖昧さがありません。

状態 RA5：要件の検証済み

指標：

• 解決策への言及がない問題文が存在する
• すべての要件を受け入れ基準によってテストできる
• 制約（実際の制約と仮定）が列挙されている
• 明確なV1の定義によってスコープが限定されている
• 内容を知らない人に説明しても、要件を理解してもらえる

次のステップ：検証済みの要件文書を「ソリューション設計」に引き継ぎます。

第2段階：検証 — ユーザーに確認する

1. 要件の概要を構造化された形式で提示します（「出力」セクションを参照）
2. 明示的な承認を求めます：「これらの要件は、必要な内容を正確に反映していますか？」
3. 必要に応じて反復します：ギャップが見つかった場合は、該当する状態に戻ります

第3段階：定着 — 文書を作成する

1. 出力先を決定します：
   • デフォルト：docs/requirements-planning/<topic>.md
   • 互換性：docs/需求/<topic>.md を使用している既存のプロジェクトでは、一時的にそのパスを維持できます
   • 別の場所を希望するかユーザーに確認します
2. 出力テンプレートに従って文書を作成します
3. バージョン管理にコミットします
4. 完了を宣言して引き継ぎます

---

入力と出力（入力＆出力）

输入（输入）

• 用户请求：模糊的想法、功能请求、问题陈述或需要验证的现有需求。
• 项目上下文：现有代码库、文档、约束（在探索过程中发现）。
• 用户响应：对诊断问题的回答、评估反馈、已验证需求的批准。

输出（输出）

已验证的需求文档

# [Topic] Requirements

**Date:** YYYY-MM-DD
**Status:** Validated
**Approved by:** [User name or "User"]

## Problem Statement

[Who has what problem and why it matters. No solution or technology references.]

## Need Hierarchy

### Must Have (V1)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-01 | [Testable need] | Given [X], when [Y], then [Z] | Validated |
| R-02 | [Testable need] | [Measurable criterion] | Validated |

### Should Have (V1 if time permits)

| ID | Need | Acceptance Criteria | Status |
| :--- | :--- | :--- | :--- |
| R-03 | [Testable need] | [Criterion] | Validated |

### Could Have (Post-V1)

| ID | Need | Trigger to reconsider | Status |
| :--- | :--- | :--- | :--- |
| R-04 | [Deferred need] | [When to revisit] | Deferred |

## Constraint Inventory

### Real Constraints (Validated)

- [Budget, time, skills, dependencies, integrations]

### Assumptions (Unvalidated)

- [Assumptions that need validation, with plan to validate]

## Scope Definition

- **In scope (V1):** [Explicit list]
- **Out of scope:** [Explicit list]
- **Walking skeleton:** [Thinnest useful version]

## Open Questions

- [Any remaining unknowns with plan to resolve]

状态生命周期 (Status Lifecycle)

该技能生成的每个需求条目初始状态应设为 Validated（已验证）或 Deferred（已推迟）。 下游执行、计划或开发流程（例如 breakdown-tasks 和执行 Agent）负责在实施期间更新文档中这些需求的状态（例如更新为 In Progress、Implemented、Dropped 等）。本技能不负责此后的状态更新。

对话与文件

转到文件	保持对话状态
问题陈述	五个为什么探索
需要具有验收标准的层次结构	优先讨论
限制库存	假设发现对话
范围定义	削减/保留谈判
验证需求	澄清问题

---

限制（限制）

硬边界（Hard Boundaries）

• 验证前不进行设计：在需求已验证之前，不要提出架构、选择技术或创建设计。
• 无跳过状态：如果问题不清楚 (RA0)，请勿讨论需求 (RA2) 或范围 (RA4)。依次进行。
• 一次一个问题：不要在一条消息中用多个诊断问题淹没用户。
• 开发人员决定：诊断、提问和指导 - 开发人员对优先级和范围做出最终决定。
• 不接受含糊不清：不接受基于形容词的需求（“快速”、“直观”）。推动可测试的标准。
• 没有解决方案语言：需求必须描述问题和需求，而不是实现。标记并重写解决方案——伪装的需求。

技能边界 (Skill Boundaries)（避免重叠）

不要做这些（其他技能可以处理它们）：

• 设计和架构：提出解决方案、选择技术、创建设计文档→使用“设计解决方案”
• 实施规划：创建任务列表、文件路径、代码结构 → 使用实施规划技能
• 代码编写：编写任何实现代码→使用开发技能
• 代码审查：审查现有代码→使用review-code
• 技能精炼：改进技能文档→使用refine-skill-design

何时停止并交接：

• 用户说“已批准”、“看起来不错”、“继续”→要求已验证，移交给“设计解决方案”
• 用户问“我们应该如何设计这个？” → 移交给“设计解决方案”
• 用户问“你能写代码吗？” → 需求完成，移交给开发工作流程（如果跳过，建议设计步骤）
• 用户说需求“足够好” → 确认满足所有成功标准，然后移交

---

自检（Self-Check）

核心成功标准（必须满足所有标准）

• 问题明确：存在明确的问题陈述，但没有解决方案或技术参考
• 需求可通过 ID 进行测试：每个需求都有验收标准和唯一的“R-NN”ID； ID 连续，无间隙或重复
• 明确的状态管理：每个需求条目均有明确的初始状态（如 Validated），并在输出中包含状态列
• 列出的约束：与假设分离的实际约束
• 范围有界：V1 边界明确，带有延迟项目和触发器记录
• 用户确认：用户明确批准已验证需求
• 文档保留：需求文档写入docs/requirements-planning/<topic>.md并提交

流程质量检查

• 未跳过的状态：按顺序进行诊断状态（未从 RA0 跳转到 RA4）
• 一次一个问题：没有让用户因每条消息的多个问题而感到不知所措
• 没有解决方案语言：需求描述需求，而不是实现
• 开发人员决定：指导和质疑，但开发人员做出了最终优先级和范围调用
• 形容词已解决：没有模糊形容词，仅保留需求（“快速”、“直观”、“简单”）
• 假设分离：未验证的假设与实际约束分开标记
• 已审核的 ID：所有需求 ID 均遵循“R-NN”格式，是唯一的，并用于文档内的交叉引用

健康检查问题

在声明需求已验证之前，问问自己：

1. 如果该项目失败，最有可能与需求相关的原因是什么？
2. 开发人员正在构建他们需要的东西或者他们知道如何构建的东西吗？
3. 什么明确不在范围内？
4. 在实际限制下，范围是否可以实现？
5. 哪些假设尚未验证？
6. 不熟悉的人能否正确解释需求？

验收测试

不熟悉该项目的人是否可以阅读需求文档并理解问题、谁有这个问题、“完成”是什么样子以及什么超出了范围——而不需要提出澄清问题？

如果否：要求不完整。返回到最早未解决的状态。

如果是：要求已验证。坚持并移交给“设计解决方案”。

---

示例（示例）

示例 1：Greenfield 项目 —“我想构建一个静态站点生成器”

用户：“我想构建一个静态站点生成器。”

代理宣布：“在任何设计或实施之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 30%，特异性 10%，完整性 10%。从 RA0 开始。

RA0 — 问题发现：

代理：“现有静态站点生成器的具体挫败感导致了这个想法？”

用户：“我厌倦了复杂性。我只想编写 Markdown 并获取 HTML。”

特工：“你今天做什么？”

用户：“我使用 Hugo，但调试配置的时间比编写内容的时间多。”

捕获的问题陈述：“单独的内容创建者浪费时间调试 SSG 配置而不是编写。需要从 Markdown 到 HTML 的零配置路径。”

RA1 — 解决方案优先检查：

代理：“您提到了 Hugo - 有什么关于 Hugo 的具体内容是您需要保留的吗？或者无论使用什么工具，“Markdown → HTML”都是核心需求吗？”

用户：“只是 Markdown 到 HTML。我不在乎如何。”

退出 RA1：需要在没有技术锁定的情况下确认。

RA2 — 特异性：

特工：“最简单有用的版本‘完成’会是什么样子？”

用户：“我将其指向 .md 文件的文件夹，然后获取具有基本样式的 .html 文件的文件夹。”

特工：“你怎么知道输出是正确的？”

用户：“每个 .md 文件都会生成一个 .html 文件。页面之间的链接有效。它在移动设备上看起来可读。”

捕获的验收标准：

• R-01：每个.md文件→一个.html文件（1:1映射）
• R-02：内部链接正确解析
• R-03：输出在移动设备上可读（视口元、可读字体大小）

RA3 — 限制：

特工：“你有什么时间和技能来做这件事？”

用户：“晚上和周末，每周大概 10 个小时。我很了解 JavaScript。”

限制库存： 时间：10 小时/周；技能：JavaScript熟练程度；依赖性：未确定。

RA4 — 范围：

代理：“如果你只能发布 3 个功能，那它们是什么？”

用户：“Markdown 到 HTML、基本 CSS 和具有实时重新加载功能的开发服务器。”

范围定义：

• V1必须：Markdown→HTML，默认CSS，开发服务器
• 延期：主题、插件、自定义模板（触发：V1可用2周后触发）
• 行走骨架：将一个 .md 文件转换为 .html 的 CLI

RA5 — 已验证：代理提供摘要，用户说“看起来不错”。写入“docs/requirements-planning/static-site-generator.md”的文档。

示例 2：边缘案例 — 解决方案伪装的需求

用户：“我需要一个带有 PostgreSQL 数据库、GraphQL API 和 Redis 缓存的 React 应用程序。”

代理宣布：“在任何设计或实施之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 60%（明确的技术），特异性 20%（没有说明问题），完整性 15%。从 RA0 开始。

RA0 — 问题发现：

特工：“这些都是技术选择。你想解决什么问题？谁有问题？”

用户：“哦......我需要跟踪我的小型企业的库存。我目前使用电子表格并不断丢失数据。”

问题陈述：“小企业主由于电子表格的限制而丢失库存数据。需要可靠的库存跟踪。”

RA1 — 解决方案优先清理：

Agent：“让我们在没有技术的情况下重写需求。‘React、PostgreSQL、GraphQL、Redis’都是解决方案。它们代表什么需求？”

重写：

• React 应用程序 →“需要可从多个设备访问的用户界面”
• PostgreSQL →“数据必须在服务器重新启动后保留下来并且不会丢失”
• GraphQL API → “需要灵活查询库存（按名称、类别、位置）”
• Redis 缓存 → “经常访问的数据应该快速加载”

代理：“‘快速加载’可以测试吗？多快可以接受？”

用户：“库存列表页面不到 2 秒。”

退出 RA1：根据需要重写需求。技术选择推迟到设计阶段。

RA2–RA5：继续穿过各州。最终文档在没有技术假设的情况下捕获需求，允许“设计解决方案”探索正确的解决方案（这可能是一个简单的电子表格替代方案，而不是全栈应用程序）。

示例 3：边缘情况 — 项目中期范围蔓延

用户：“我们开始构建一个待办事项应用程序，但现在它需要日历集成、团队协作、文件附件和人工智能驱动的任务建议。我们落后了 3 周。”

代理宣布：“在扩大范围之前，我正在使用分析需求技能来验证需求。”

分类：清晰度 50%，特异性 40%，完整性 30%。范围蔓延症状——从 RA4 开始（早期的状态可能会在 3 周后得到解决，但需要验证）。

快速 RA0 检查：“这个待办事项应用程序解决的原始问题是什么？”

用户：“我需要停止忘记我的自由项目的任务和截止日期。”

问题已确认 — 继续进行 RA4。

RA4 — 范围蔓延干预：

代理：“如果你只能从完整列表中提供 3 个功能，哪 3 个可以解决不忘记任务的核心问题？”

用户：“基本任务列表、带提醒的截止日期，以及……现在就这些了。”

代理：“所以日历集成、团队协作、文件附件和人工智能建议都是核心问题之外的附加内容。我们应该推迟它们吗？”

范围重新定义：

• V1 Must：任务CRUD、截止日期、提醒
• 延期：日历集成（触发：使用提醒 1 个月后）、协作（触发：当自由职业者成为团队时）、附件（触发：用户请求）、AI 建议（触发：100 多个任务）
• 行走骨架：CLI 或简单的 UI，可创建带有截止日期的任务并发送提醒通知

RA5 — 已验证：要求重新聚焦。 3 周的延迟变得可以控制。文档已更新。

---

反模式

解决方案规范

问题：需求描述的是实现，而不是需求。 “系统应使用 PostgreSQL”不是必需的； “数据必须在服务器重新启动后继续存在”。

修复：对于每个要求，询问“是否可以通过不同的方式来满足？”如果是，您捕获的是实现，而不是需求。

利益相关者的虚构

问题：开发人员想象需求而不是发现需求。 “用户会想要……”没有证据。

修复：如果您是用户，请诚实地表达您的需求。如果是为他人构建，请与他们交谈或引用类似的证据。不要发明用户。

无限的积压

问题：需求不断增长，但没有划分优先级。一切都同等重要。

修复：强制等级。如果你只能运送一件东西，那是什么？然后是两个？这揭示了实际的优先事项。

过早的精确度

问题：指定尚不重要的细节。在验证任何人想要通知之前设计通知首选项。

修复：用“[X]已验证后待定”对不确定区域进行存根。精准聚焦 V1 Must 项目。

约束失明

问题：没有清点真正的约束，然后在构建过程中解决它们。

修复：在最终确定需求之前明确限制库存。

---

附录：整合地图

上游（融入此技能）

来源	当	它提供什么
用户请求	新项目或功能创意	原始意图分析
现有文档	项目中期验证	部分需求诊断

下游（该技能进入）

目标技能	当	它收到什么
设计解决方案	要求已验证	验证需求文档作为设计输入
实施规划	设计很琐碎	经验证的需求范围和限制

移交合同

该技能输出	目标技能期望
问题陈述	设计背景
需要具有验收标准的层次结构	功能性需求
限制库存	架构限制
范围定义（V1 边界）	设计范围