ns-requirements-enricher

Name: ns-requirements-enricher
Author: nextstage-brasil

github.com/nextstage-brasil開発0143 回インストール1 週間前に更新

ns-requirements-enricher について

ns-requirements-enricherは、issueまたは貼り付けられたスコープをコーディングエージェント向けの実装ブリーフにまとめます。既存の挙動を確認して阻害要因となるプロダクト上の質問を特定し、チャット用ブリーフとGitLab issueのプレビューを区別します。

主な機能

01issueまたはスコープから実装ブリーフを作成
02既存の挙動と関連するプロダクト決定を確認
03阻害要因となるプロダクト上の質問だけを提示
04チャット用ブリーフとissueコメントのプレビューを区別
05人の承認後にのみissueコメントを投稿

活用シーン

01コーディング前に不完全な受け入れ条件を明確化
02GitLab issueとコメントからブリーフを作成
03貼り付けられた機能説明を実装要件に整理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nextstage-brasil/skills --skill ns-requirements-enricher

インストール後、Claude Code で/ns-requirements-enricherを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/

evals.json

references/

comment-template.md

question-checklist.md

詳細

要件の補足

課題を1件、または貼り付けた説明文を1つ入力します。出力はコーディングエージェント向けの実装ブリーフです。質問は、実装を進めるうえで必要な場合に限ります。ブランチ、コード、ステータス、バージョンに関する成果物は作成しません。

PMによる確認ではありません。SDD の Specify／version Clarify でもありません。Relationshipを参照してください。

モードの検出

モード	トリガー	提供内容
Issue	`ISSUE_URL`、またはユーザーが GitLab の課題を指定	コメント本文のチャットプレビュー。人間が草案を検証した後に限り、`add_issue_comment` を内部で実行
Chat	貼り付けまたは説明されたスコープ — 課題 URL なし	画面上にブリーフを表示。投稿を提案しない。「投稿しましょうか？」と尋ねない

フェーズ 2～4 は共通です。フェーズ 1（MCP の読み込み）はissueモードのみです。

MCP フォールバック（SSoT）： GitLab MCP がない、または使用できない場合は、chatモードとして扱います（同じブリーフを作成し、投稿しません）。停止しないでください。フェーズ 1 はスキップします。

セッションの開始

../../ns-harness/references/session-boot.mdを参照してください。MCP またはコードベースの調査を始める前に、セッションの開始を完了してください（ブロッキング）。

開始後の GitLab MCP：mcp-gitlab-usageに従います（初回アクセス時に get_mcp_gitlab_skill のバージョンを確認）。利用できない場合はMCP フォールバックを適用します。

目的

Issue モード — 質問はチャット内で行います。質問への回答がコメントになります。質問を GitLab に投稿することは決してありません。回答後、確定済みのブリーフを表示します。人間が明示的に承認した場合に限り、その本文を投稿します。

投稿するコメント（許可された場合）：

1行目は ✅ — 要件はすでに確定しています。@mention は含めません。
完全な実装ブリーフ（決定事項をすでに反映済み）。質問セクションなし。推奨リストなし。番号で返信するためのフッターなし。

Chat モード — 同じ質問をまとめて行い、その後、確定済みのブリーフをインラインで表示します。GitLab への投稿は提案しません。PRD ではありません。

実装、コミット、課題のステータス変更、ファイル作成、requirements.md の作成、start_execution_planning の呼び出しは行わないでください。

使用する場面

コーディング前にブリーフが必要な ISSUE_URL（issue）
GitLab を使わず、ブリーフ／スコープ／AC をチャットに貼り付けた場合（chat）
実装エージェントがプロダクトの意図を推測してしまう場合の確認
ns-autonomous／人間からの指定が不十分な場合
受け入れ条件が不完全な場合に ns-execution-gitlab-issue の前段階として使用

前提条件

ホスト環境の AGENTS.md に従います。調査がテスト／サービスに及ぶ場合は Docker／ランタイムの指示にも従います。ツールで Read しないでください。
agents.local.md がある場合は、そこに記載された GitLab MCPのみを使用します。
MCP が利用可能な場合は MCP ツールの契約に従い、それ以外の場合はMCP フォールバックを適用します。

入力

変数	必須	説明
`ISSUE_URL`	Issue モードのみ	GitLab の課題／作業項目の完全なリンク
要件テキスト	Chat モードのみ	ユーザーメッセージ、貼り付けられたブリーフ、または添付されたスコープ

自動投稿はしません。DRY_RUN は廃止済みです。常にプレビューを表示し、人間の検証後に限り投稿します。

フェーズ 1 — 課題のコンテキストを読み込む（issue モードのみ）

chat モードではスキップします。 Chat の情報源は、ユーザーメッセージと貼り付けられたコンテキストです。

URL から project_id（または検索用の project_name）と issue_iid を解析します。

必須の読み取り：

read_issue — タイトル、説明、ラベル、マイルストーン、担当者、関連リンク。
list_issue_comments — スレッド全体。コメント本文を要件の情報源として扱います。

コメント内で誰かを @mention しないでください。起票者、担当者、既存のボットコメントからコピーしたログイン名も対象です。author.username がなくても停止する必要はありません。

要約します（内部処理。まだ投稿しません）。

Goal — 完了時に何が実現しているかを1文で記述
Acceptance — 説明から項目を列挙し、それぞれを明確／部分的／不足に分類
Constraints — あなたのコンテキスト向けにラベル／マイルストーン／期限を記録。不足しているラベルを質問にしない
Already answered — 曖昧さを解消するコメント内の事実。再質問しない
Upstream decisions — 以下のUpstream product decisionsを参照

ユーザーが issue モードを指定したものの ISSUE_URL がない場合は、URL が不足している旨だけを1行で返して停止します。課題の内容を捏造しないでください。MCP を利用できない場合は、停止条件ではありません。MCP フォールバックを適用します。

Chat モード： 会話テキストから同じ Goal／AC／Constraints／Already answered を整理します。

上流のプロダクト判断

この課題が属する範囲について、ワークスペースに PM 成果物がある場合は、質問する前に確認してください。

docs/versions/*/pm/decision-register.md：判断（Q-NN）、矛盾（C-NN）、準備状況
docs/versions/*/pm/prd.md：各要件のビジネスルールと受け入れ条件、未解決の質問

マイルストーン、タイトル、または課題が実装する要件で照合します。明確でない場合は、最も近いものを使い、内部メモにどれを使ったかを1行で記載してください。質問してはいけません。

上流の状態	Enricher の対応
判断が `answered`	回答済みです。再質問しないでください。要件としてブリーフに記載してください
この課題に関わる判断が `open` / `assumed`	上流で推奨されている回答を使い、質問のまとめに含めてください
課題の記述が上流の判断と矛盾している	矛盾を検出します。どちらの結果を優先するか尋ねてください
PM 成果物がない	続行してください。ビジネス判断のスキャンを自分で実施します（フェーズ 3）

チャットに貼り付けられた PRD や判断リストも、ファイルと同じものとして扱います。

フェーズ 2 — まずコードベースを確認する

要求された動作が、アプリケーションのコードにすでに存在するのか、既存の画面／フロー／モジュールを拡張するのか、または新規なのかを判断してください。

対象範囲は、課題が関係する箇所に限定します。コードは内部の根拠としてのみ使います。パス、クラス、ファイル、SQL、コントローラーはメモに記録してください。ブリーフには要件を記載します。画面、列、ユーザーに表示される内容、変更が必要な箇所を記載してください。

関連する場合は、以下を確認してください。

docs/context/brownfield-map.md
docs/context/system-reverse-spec.agent.md（優先）、なければ system-reverse-spec.md
.nextstage-harness/rules/architecture-rules.md
docs/context/gitlab-sync-config.md（コンテキストのみ）

調査： シンボル／ルート／モジュールを grep し、コントローラー／サービス／ビュー／API／連携機能を読み、テストを確認します。現在の動作、拡張ポイント、権限、イベント／キュー、環境を記録してください。

出力（ブリーフに反映）：

調査結果	ブリーフでの扱い
動作がすでにコードにある	画面が現時点で何をするかを記載してください。パスは不要です。要求によってその動作が変わり、プロダクトの意図がまだ曖昧な場合に限り、質問してください
既存の画面／フローの拡張	ユーザーが開く画面の名前を記載してください。何が維持され、何が変わるかをブリーフに記載します
見つからない	その画面での動作は新規であるとブリーフに記載してください。バージョンの枠組みには触れないでください

バージョンの Clarify は実行しないでください。requirements.md、clarify-contract.md、unknowns-register.md、source/、タスクファイル、PO、バージョンとしてのマイルストーン、Gate 0 のバージョン範囲は作成しないでください。

フェーズ 3 — 質問は最小限に（グリル手法）

ns-spec-driven の Clarify から手法を取り入れてください（references/clarify-requirements.md、clarify-strict.md）：番号付きの質問まとめ、ユーザーが確認できるプロダクト用語、ブロッキング／仮定／省略の区別、未解決の価値判断と矛盾の検出。

バージョンの Clarify ワークフローは実行しないでください（brownfield Step 0.4 での停止、Gate 0、バージョン成果物、skip clarify はありません）。

課題／チャットのテキスト、コメント、上流の判断、コードを突き合わせてください。それぞれの不足点について、_実装エージェントがプロダクトの意図を推測しなければならないか_を検討します。推測が不要なら、質問はしないでください。

ビジネス判断のスキャン（必須）。 テキストのみの曖昧さのスキャンでは、誰も書いていない点を見落とします。この課題で追加または変更するビジネスルールごとに、ビジネス上の各観点と references/question-checklist.md の10のルール確認項目（空、同点、一部のみ、重複、誰が可能か、既存データのデフォルト、取り消し、ユーザーが無視した場合、どの日付か、ほかのどこか）を順に確認してください。スキャン対象は課題が関係する範囲に限定します。1行の UI 修正にリスト全体を適用する必要はありません。

ブロッキングとなる不足がゼロの場合： readyと記載してください。埋め草を作ってはいけません。

「ready」とする前の開発者視点での確認。 チャットにアクセスできないコーディングエージェントの立場で、ブリーフの草稿を読み直してください。そのエージェントがまだ尋ねるビジネス上の質問は、すべて質問のまとめに含めてください。チャットで決定済みなのにブリーフにない事項は、すべてブリーフに追加してください。技術的な質問（アルゴリズム、スキーマ、ライブラリ）は含めないでください。

対象読者

このチャットで人に尋ねる質問です。プロダクトの言葉を使い、開発者／テックリード／運用担当者向けの表現は避けてください。相手に @ を付けないでください。

言葉遣い：一般的なプロダクト／UX用語（画面、ボタン、フィルター、表示内容、タイミング）
スキーマ、SQL、クラス、ブランチ、ラベル、ファイルパス → 内部メモのみに記載してください。質問リストにも、ブリーフにも記載しないでください。

質問にする／前提とする／除外する

ケース	対応
このプロダクトに関する事実がないと、エージェントが完了を確認できない	番号付きの質問と推奨案
ビジネス上の判断：プランまたは消費、実行できる人、既存顧客へのデフォルト、金額または丸め処理、エクスポート内容、取り消せない操作、顧客がすでに確認済みの動作の変更、個人データまたは第三者	デフォルトが明白に見える場合でも、黙って前提とせず、番号付きの質問と推奨案
安全なデフォルト（レイアウト、文言、画面にすでにある UI パターン）で、質問せずにエージェントがリリースできる	前提 — 質問にはしない
説明／コメント／コードにすでに記載されている	除外
あれば望ましい程度のもの／エンジニアの好み	除外するか、前提とする

質問の品質

依頼者向けで、特定の画面／フローに関するものであり、1行または選択肢で回答できること
ブロッカーのみ。ユーザーの操作順に 1. 2. … と番号を付ける
上限は 15。細かい質問はまとめる
すべてのブロッカーを1回で尋ねる — 小出しに質問しない（issue モードでコンテキストが不足している場合を除く）

質問の形式（N ≥ 1 の場合は必須）

まずチャットに記載します。PRDではありません。各質問には、受け入れられた場合にコーディングエージェントが適用するデフォルトを含めます。

順序：

関連する事実 — リストの前に、現在画面に表示されている内容と依頼内容の違いを記載します。ユーザーに見える列と動作を記載してください。パス、クラス、ファイルは記載しないでください。バージョン／POも記載しないでください。
各質問：

Q{n} — {short title}
{What the screen does vs what the request says. One or two sentences.}

➡️ Recommended: {concrete default. Name what changes and what stays.}

厳守。 3つのブロックで構成します。タイトル行、本文行、その後に空行を1行置き、次の行に ➡️ を記載します。ピリオドの後に同じ行で ➡️ を続けるのは無効です。矢印が独立した行にない限り、質問を提示しないでください。

無効な例：Q1 — タイトル画面では行が非表示になります。 ➡️ 推奨案：再表示する。

ラベルも回答と同じ言語に翻訳します（ポルトガル語のユーザーの場合：➡️ Recomendado:）。

結びは人と同じ言語で記載します。番号で回答してください（1: …、2: …）。はい／いいえの質問には「すべてはい」または「すべて推奨案で」と回答できます。その後、このチャットで要件を確定します。PRD、バージョン、POには言及しないでください。

チャットのみ。 この質問一式はブリーフの入力です。add_issue_comment の本文には、質問、Recommended: の行、番号での回答を促す結びを記載してはいけません。

推奨案 = コードに基づく安全なプロダクト上のデフォルトです。受け入れられたら、「変更内容」「受け入れ条件」または「前提」に判断として記載してください。チャットで質問が未解決のまま、デフォルトを「前提」にだけ記載してはいけません。

検出項目（issue の粒度のみ）

ID	該当	解決
未確定の値	TBD、範囲、表示動作を表す曖昧な形容詞	質問で明確化またはブリーフで影響とともに前提として記載
矛盾	issue とコメント、上流の判断、現在のコードの間に矛盾がある	どのプロダクト上の結果を優先するかを尋ねます。黙って選択しないでください
曖昧な用語	複数の意味に解釈できる名詞（「会社」「アカウント」「ユーザー」「タイトル」）	どちらを指すか尋ね、可能性の高い意味を推奨案にします
スコープの逸脱	ここでの動作がスコープ外と宣言された事項に依存する、または新しいルールが既存のフローを変更する可能性がある	ここだけに適用するのか、既存のフローにも適用するのかを尋ね、「ここだけ」を推奨します

検出項目ではないもの： ラベルの不足、ブランチ名、GATE 1、マイルストーンをバージョンとして扱うこと、PO、完全なバージョン表記。

技術的な不足事項を翻訳する

内部メモ（公開禁止）	依頼者に確認してから、回答を要件として記載する
テーブル／カラム／クラス	「Club で絞り込む場合、今日その Club に紐づいている人だけが対象という意味ですか？」
ベースブランチ／`develop-*`	質問しないでください
`Team: *` の欠落	質問しないでください
エンドポイント／SQL 結合	「Federation と Role の両方が選択されている場合、その人は両方に一致する必要がありますか。それとも、どちらか一方でよいですか？」

良い例：

Q1 — When the filter applies
Today the date filter runs only after Search.

➡️ Recommended: same — checkbox applies only after Search.

質問してはいけない項目： Team ラベルの欠落、どの develop_* ブランチか、どの SQL 関係か。

質問リストの対象外

ラベル、ベースブランチ、GATE 1、スキーマ／クラス／環境、「どのように実装すべきか」、バージョン／PO／バージョンとしてのマイルストーン、十分に見せるためだけの埋め草。

カテゴリを確認してください：references/question-checklist.md。

フェーズ 4 — 実装ブリーフ

対象読者 = コーディングエージェント。対象範囲 = この Issue または貼り付けられた説明。実装上の不確実性を取り除きます。

references/comment-template.md に記入してください。必須セクション：

セクション	内容
現在の動作	指定された画面でユーザーが現在目にする内容。ファイル、クラス、パスは記載しない
変更内容	要件の差分。変更されない内容
受け入れ条件	エージェントが画面上で検証できる手順／結果。OKR／RICE ではない
前提	すでに合意された決定事項と安全な既定値。誤っていた場合の影響

Files / areas は含めないでください。Questions 見出しも含めないでください。未回答の不足事項は、チャットでの質問に対する回答が得られるまでそのままにします。バージョン PRD ではありません。PM の OKR／RICE ではありません。SDD Specify ではありません。

フェーズ 5 — 要件を確定してから GitLab ゲートへ

N ≥ 1： フェーズ 3 の形式で質問をまとめて送信し、そこで停止してください。投稿しないでください。GitLab の本文をまだ貼り付けないでください。

返信を受け取ったら、各回答をブリーフに反映してください。

返信	ブリーフ
Recommended を承認／「all yes」／「all recommended」	その既定値を変更内容または前提に移します。質問は削除します
その他の回答	その決定事項を変更内容／受け入れ条件に記載します。質問は削除します
番号を飛ばした回答	チャットでもう一度質問します。推測してはいけません。質問されたすべての項目が決定するまで、プレビューも投稿もしないでください

確定したブリーフ（テンプレート）を貼り付けてください。その本文に質問を残してはいけません。

モード	確定したブリーフを画面に表示した後
Issue	待機します。人間がその下書きを明示的に承認（yes／post／同等の表現）した場合に限り、`add_issue_comment` を `internal: true` にして投稿します。無断で投稿してはいけません。編集があればプレビューを修正し、再び待機します
Chat	停止します。確定したブリーフが成果物です。禁止事項：投稿を申し出ること、「投稿しましょうか？」と聞くこと、GitLab コメント

N = 0： 質問はまとめません。完成したブリーフを貼り付け、同じゲートに進みます。

投稿／プレビューする本文は ✅ で始まり、ユーザーの言語で準備完了を示す行を含めます（ポルトガル語：✅ Brief de implementação. **Pronto.**）。本文がポルトガル語の場合、この行を英語のままにしてはいけません。@ は含めないでください。

質問が未解決のまま投稿してはいけません。GitLab に ❌ を付ける形式はありません。

実際に投稿した後は、リンクまたは project_id + issue_iid をチャットで伝えます。

この Issue の範囲を超える決定事項（チャットのみ、確定したブリーフの後に1行で記載）：今回決定した事項のうち、他の画面や Issue にも適用されるものを列挙します。依頼者がチームの他のメンバーも読む場所に記録できるようにします。GitLab の本文には絶対に含めないでください。

set_issue_status、update_issue、create_issue、start_execution_planning は使用しないでください。

言語

ユーザー向けの出力全体で言語を統一します。質問、➡️ Recommended ラベル、締めの言葉、簡潔な見出し、冒頭の行、フッターが対象です。ユーザーの言語に合わせます。ポルトガル語で入力されたら、ポルトガル語で出力します。見出しも含めます（Comportamento atual、O que muda、Aceite、Premissas）。本文がポルトガル語なのに、見出しだけ英語にすることは避けてください。

references/comment-template.md のテンプレートは英語のひな形です。表示または投稿する前に、すべての見出しとフッターを翻訳してください。ユーザーが英語で書いていない限り、英語の見出しをそのまま使わないでください。

チャットと簡潔な説明： ファイルパス、クラス名、SQL、環境変数、コントローラーは含めません。要件だけを記載します（画面、列、動作）。

アンチパターン

1つの返信内で言語が混在している（見出しは英語、本文はポルトガル語、またはその逆）
チャットまたは GitLab コメントに、ファイルパス、クラス名、コントローラー、または Files / areas セクションを含める
質問のまとめ、Recommended: の行、または「番号で返信してください」を GitLab コメントに含める
確定したブリーフを人が確認する前に自動投稿する
チャットモードで GitLab への投稿を提案する
質問をまとめず、1つずつ尋ねる
公開コメント（内部限定ではないコメント）
requirements.md / start_execution_planning / バージョンの Clarify アーティファクト
実装またはブランチ
質問本文と同じ行に ➡️ を付ける（sentence. ➡️）、またはその前に空行を入れない
確定したブリーフを PRD と呼ぶ
埋め草の質問、漠然とした「これはどのように動作すべきですか？」
プラン、権限、既存顧客向けのデフォルト、金額、エクスポート、取り消し、個人データに関するビジネス上の判断を、「前提」に隠して、推奨回答付きで質問しない
上流で回答済みの判断を再度尋ねる、またはこの課題に関係する上流の未決事項を無視する
コメントですでに回答されている事実を再度尋ねる
ブリーフまたは GitLab コメントで @mention を使う（質問者、担当者、または別のコメントから転記したログイン名）
開発に関する質問（テーブル、ブランチ、ラベル、GATE、テストパス、JSON）
バージョン／PO／マイルストーンをバージョンとして扱う／「完全なバージョン」という枠組み
PM の OKR/RICE、または SDD バージョンの Specify / Clarify-Strict にこのスキルを使う

他のスキルとの関係

レイヤー	スキル	使用タイミング	粒度	対象外
PM	`ns-project-manager`	インテーク → RICE、PRD、予算、意思決定記録	OKR、規模、ステークホルダー、バージョン全体に関わるプロダクト上の判断	対象外です。そこで回答済みの判断はここでの入力となり、この課題に関係する未決事項はここで質問します
SDD Clarify-Strict	`/ns-spec-driven`	Specify の前、Gate 0	ディスク上のバージョン	手法は借用しますが、アーティファクトは借用しません
エンリッチャー（このスキル）	`/ns-requirements-enricher`	1つの課題のコーディング前／貼り付けられたスコープ	課題ごとのブリーフ＋限られた質問	プレビュー後、内部コメントまたはチャットのみのブリーフ
Specify	`/ns-spec-driven` Specify	Clarify の後	バージョンの `requirements.md`	課題ごとのブリーフではありません
Execute	`ns-execution-gitlab-issue`	ブリーフが明確になった後	課題を実装します	エンリッチメントではありません
Review	`ns-reviewer`	コード作成後	差分レビュー	エンリッチメントではありません
MCP	`mcp-gitlab-usage`	MCP 呼び出し	ツールのコントラクト	バージョン確認用です。カタログの `depends` ではありません

クイックチェックリスト

参考資料

ファイル	タイミング
`references/comment-template.md`	フェーズ 4～5 — ブリーフ／GitLab の本文
`references/question-checklist.md`	フェーズ 3 — 不足項目の確認
`../../ns-harness/references/session-boot.md`	セッションの開始（ブロッキング）

Markdown 対応

ログインしてコメント

基本情報

作者: nextstage-brasil
リポジトリ: nextstage-brasil/skills
カテゴリ: 開発
インストール数: 143
GitHub スター: 0

問題を報告