mstack-write-specs

mstack write specs

リクエストを、ユーザーが承認した、テスト可能な要件を含む仕様書にまとめます。この手法では、すべての決定事項が確定するまでインタビューを行い、その後、すべての要件にテストにできるシナリオがある仕様書を作成します。このスキルで作成するのは仕様書です。仕様書に記載されたものを実装することはありません。

Claude Code と Codex でこのスキルを使う

このファイルはどちらのホストでも同じです。ホストのツール名は記載しません。「質問ツール」または「サブエージェントツール」と書かれている箇所では、ホストに対応するツールを使ってください。

このファイルでの表記	Claude Code	Codex
質問ツール	短い選択肢には AskUserQuestion、長い選択肢にはチャットで番号付きの質問を提示	チャットで番号付きの質問を提示し、回答を待つ
サブエージェントツール	新しいコンテキストで Agent を使う	要点を渡して、読み取り専用の別個の codex exec を実行する。または、セッションにエージェントツールがあればそれを使う
スキルのフォルダー	このスキルの読み込み時にホストが示したベースディレクトリ	読み込んだ SKILL.md があるフォルダー

サブエージェントツールがない場合は、委任された手順を自分で実行し、その旨を伝えてください。以下のファイルは、スキルフォルダー内のパスで参照してください。

基本ルール

1. 事実の確認はあなたの役割、決定はユーザーの役割です。 リポジトリ、ドキュメント、またはツールで確認できることは調べ、見つけた場所を示してください。ユーザーに尋ねるのは、調査では決められない選択肢だけです。
2. 自分で決定してはいけません。 自分で補った決定事項には、理由を添えて「エージェントの判断」と記載し、承認時にユーザーへ提示してください。ユーザーが見ていないデフォルトは、拒否する機会のなかったデフォルトです。
3. 実装ではなく動作を記述します。 要件には、外部から観察できるシステムの動作を記載します。技術的な選択肢と検討した代替案は「決定事項」に記載します。ファイルパスやコードは、仕様書ではなく計画に記載します。
4. すべての要件をテスト可能にします。 各要件には、少なくとも1つ、結果を観察できるシナリオが必要です。また、references/requirements.md の lint を通過する必要があります。
5. 伝えられていないことや、見つけていないことを書いてはいけません。 ユーザーが述べておらず、情報源による裏付けもない内容が仕様書に含まれている場合、それは不備です。
6. このスキルでは実装しません。 ユーザーが仕様書を承認し、その後で次の手順を依頼するまでは、スキャフォールディング、依存関係のインストール、実装を行ってはいけません。

フェーズ

各フェーズはゲートで終了します。ゲートを通過する前に、次のフェーズを開始しないでください。

フェーズ	作業	ゲート
0. 受付と規模の見積もり	目標、問題、目標を満たす最小の変更を言い換えて確認します。入力を分類します（機能、バグの種類、リファクタリング、漠然としたアイデア）。規模を見積もり、モード（下記）を選びます	言い換え、規模、モードをユーザーに伝えます。根拠によってすでに依頼の対象外だと判断できる場合は、その根拠を示して終了します
1. 根拠の確認	リポジトリの指示、既存の仕様書とドキュメント、リンクされたイシュー、変更が影響するコードを読みます	関連部分の現在の動作と、変更が影響する箇所を、引用を添えて説明できます
2. ヒアリング	設計ツリー（下記）に沿って質問を重ねます	未解決事項がなくなり、ユーザーが共通認識を確認します
3. アプローチ	構造的に異なるアプローチを2つまたは3つ、トレードオフと推奨案を添えて、単独のメッセージで提示します	ユーザーが1つを選ぶか、選択を委ね、あなたが選んだ案を記録します
4. 草案	references/spec-template.md を使い、最終パス（下記）に仕様書を作成します	ファイルが存在します
5. 品質チェック	references/quality-check.md と references/requirements.md のリンターを実行します。不合格箇所を最大3回まで修正します	すべての項目に合格するか、残った不合格箇所をユーザーに提示します
6. 独立レビュー	references/quality-check.md の説明に従い、サブエージェントツールを使って新たな読み手にレビューしてもらいます	重要な指摘が残っていないとレビュー担当者が報告するか、ユーザーが1回のやり取りで質問に回答します
7. 承認	パス、簡単な要約、「エージェントの判断」をすべて提示します。このファイルの承認を求めます	ユーザーが書面を明示的に承認します。日付を添えてステータスを「承認済み」に設定します
8. 引き継ぎ	次のステップ（下記）を提案します	ユーザーが次のステップを指定します。このスキルはビルドを行わずに終了します

規模とモード

• 仕様書は不要。 変更内容はすでに決まっており、1回の作業セッションで完了します。その旨を伝え、終了するか、ユーザーが希望する作業にすぐ進むかを提案します。
• 小規模。 1つのコンポーネントにおける1つの動作です。各セクションは1～2行程度、全体で約30～80行です。デフォルトではクイックモードとし、独立レビューは任意です。
• フル。 それ以外の規模です。デフォルトではゲート付きモードとします。約500行または約25要件を超える場合は、フェーズに分割し、最初のフェーズの仕様化を提案します。
• ゲート付きモードでは、上記のすべてのゲートを実施します。
• クイックモードでは、フェーズ2と3を、アプローチの選択を含む冒頭の1ラウンドにまとめ、そのまま停止せずにフェーズ4～6を実施します。フェーズ7の承認は省略しません。

ヒアリング中に依頼の規模が大きくなった場合は、その旨を伝え、規模の区分を引き上げます。

入力の種類別

• 機能。 標準的な流れです。
• バグの種類（例：「すべての日付パーサーが2月31日を受け入れる」）。仕様化の前に原因を特定する必要があります。原因が不明な場合は、仕様化の前に診断スキルへ引き継ぎます。要件の大半は、望ましくない動作を表す文（「もし……なら、……する」）と、現在の正しい動作を変えずに維持するための要件で構成されます。
• リファクタリング。 ユーザーストーリーは作成しません。要件は観測可能な動作に関する不変条件とし、フェーズ3（アプローチ）をほとんどの要件より先に実施します。
• 漠然としたアイデア。 フェーズ2では、理由、目標、アンチゴール（技術的にはすべて動作していても、失敗とみなされる結果）について、より時間をかけて確認します。

ヒアリング

対象を設計ツリーとしてモデル化します。各判断から、それに依存する判断へ枝分かれします。フロンティアとは、前提となる事項がすでに確定しているすべての判断です。

1. 質問する前に、未確定の項目をすべて4種類に分類します。
   • 事実。 現在のコードの動作、インストール済みのライブラリ、現在の制限などです。調べて出典を示します。質問してはいけません。時間のかかる調査にはサブエージェントツールを使い、それに依存しない質問はそのまま続けます。
   • 見た目と使い心地。 見た目や使い心地に関する質問は、話し合いだけでは決められません。そのラウンドで質問として、使い捨てのプロトタイプを提案します。承諾を得てからスクラッチフォルダーに作成し、結果を「決定事項」に記録します。
   • 進め方の判断。 ファイルの配置、何かの見せ方、さらに調査するかどうかなどです。自分で判断し、選んだ内容を伝えます。
   • 判断事項。 推奨案を添えてユーザーに質問します。
2. 見落としがちな分岐を見つけるため、references/coverage.md の網羅リストを内部で使います。質問票のように読み上げてはいけません。該当しない分岐には質問せず、該当しないことを記録します。
3. フロンティア全体を1つのラウンドで質問します。質問に番号を付けます。それぞれに推奨案を示し、単純に「はい」と答えればその案を受け入れる形で質問します。同じラウンド内の別の未確定事項に依存する質問は、次のラウンドまで保留します。
4. 各ラウンドの冒頭では、前回の回答で確定した内容を簡潔に振り返ります。こちらで補った内容は、ユーザーの発言としてではなく、理由を添えた提案として提示します。
5. 回答を待ちます。その後、確定した回答によって新たな判断が可能になるため、フロンティアを最初から再計算します。後の回答によって以前の判断が変わる場合は、次のラウンドでその分岐を再び取り上げます。
6. ユーザーの発言とコードが矛盾する場合は、矛盾について直接質問します（「コードでは注文全体をキャンセルしていますが、一部キャンセルが可能だとおっしゃっています。どちらが正しいですか？」）。
7. 質問数に上限はありません。ヒアリングが非常に長くなる場合は、対象範囲が広すぎるため、分割を提案します。ユーザーが「まとめて」と言った場合、まだ質問していないすべての分岐は、承認時に記載するエージェントの判断事項か、安全に保留できる未解決の質問のどちらかにします。
8. フロンティアが空になり、すべての分岐を確認し、暗黙の前提が残っていない時点で終了します。Phase 3 に進む前に、共通認識を確認するようユーザーに求めます。
9. 回答された各判断は、ヒアリング記録に1行で記録します（テンプレートを参照）。このファイルはコミットされる可能性が高いため、ユーザーの発言をそのまま引用してはいけません。

通常はラウンド形式で進めます。ユーザーまたはリポジトリの指示で1問ずつ質問する場合も、フロンティアを計算し、最も多くの判断を阻んでいる質問から尋ねます。

ラウンド形式

絵文字や太字のラベルは使わず、番号付きの平文でラウンドを記述します。

Round 2. Your last answers settled that reset links go by email only and that
admins cannot send them for other people. Three decisions are open. Answer by
number. A plain "yes" accepts my recommendation.

1. Should a reset link stop working after its first use?
   I recommend yes. A reusable link lets anyone who sees a forwarded email take
   over the account.

2. Should a link expire 30 minutes after it is sent?
   I recommend yes. The app already ends idle sessions after 30 minutes (session
   settings, read this morning), so users meet one limit instead of two.

3. Should the expired-link page offer a button that sends a new link?
   I recommend yes. Without it the user has to find the reset form again.

Once question 2 is settled I will ask about the wording of the expiry message.

未解決の項目

草案の作成中は、未確定の項目をすべてインラインで [NEEDS CLARIFICATION: <specific question>] と記します。承認時にこのマーカーが残っていてはいけません。それぞれ、ラウンドで回答を得るか、進め方や軽微な事項であればエージェントの判断事項として記録するか、安全に保留できる場合は「未解決の質問」に移します。未解決の質問に移せるのは、安全に保留できる場合だけです。つまり、回答によって要件、進め方、対象範囲が変わらない場合に限ります。その場合は、担当者と保留できる理由を明記します。リポジトリを調べれば答えがわかる質問を、未解決の質問にしてはいけません。

承認

承認とは、ユーザーがパスにある記述済みの仕様書を読める状態になった後に、それに明示的に同意することです。次のいずれも承認には当たりません。

• アイデア、再生内容、またはアプローチへの同意；
• 以前の「とにかく書いて」や「それで十分」；
• 沈黙、または質問ツールでのデフォルトや事前選択済みのオプション；
• 概要、計画、またはアプローチの承認；
• レビュアーの報告または独立した読者の報告；
• 「最善だと思うようにして」。推奨案を提示し、それに対する明示的な同意を得てください。

承認済みの仕様書を編集すると、再度承認されるまでステータスはドラフトに戻ります。承認後に追加する場合は、削除またはタイムラインの変更を伴うか、新しい仕様書の作成として扱います。

仕様書の保存場所

保存場所の選択はプロセス上の判断です。決定してパスを伝え、質問はしないでください。該当する最初の項目を使用します。

1. ユーザーが指定した場所。
2. リポジトリのエージェント向けまたはコントリビューター向けの指示にあるルール。
3. 既存の仕様書の規約：openspec/ フォルダーがある場合（その変更フォルダーの構成を使用）、specs/ または .specify/ フォルダーがある場合（その番号付き機能フォルダーを使用）、または docs/specs/、docs/rfcs/、docs/design/ のうち既に存在するもの。
4. デフォルトの docs/specs/<yyyy-mm-dd>-<slug>.md。slug には fix-payment-timeout のように、動詞と名詞を組み合わせた2～4語の名前を使用します。

書き込む前に、そのパスに既存のファイルがあれば読み込んでください。ドラフトは最初の未解決項目から再開します。承認済みの仕様書は、新たな承認を得た場合にのみ変更します。長時間にわたるインタビューでは、中断後に再開できるよう、進行に合わせてインタビューの記録をファイルに書き込んでください。ユーザーから依頼されない限り、コミット、プッシュ、プルリクエストの作成は行わないでください。

引き継ぎ

次のステップを提案し、ユーザーから明示的な指示があった場合にのみ実行してください。

1. 段階的な計画。 mstack-plan がインストールされている場合は使用してください。保存先を確認し、仕様書を計画フォルダーに spec.md としてコピーしたうえで、mstack のレビューワークフローで実行できる、レビュー済みのテストファーストな計画を作成します。インストールされていない場合は、仕様書のパスを計画の先頭に記載し、計画が仕様書を根拠とするようにしてください。
2. 縦割りスライスでのチケット作成。 各チケットは、それ単独で実演でき、1回の作業セッションで完了できる、狭い範囲のエンドツーエンドの経路とします。仕様書のシナリオからチェックボックス形式の受け入れ条件を作成してください。
3. 直接実装。 承認済みの変更が1回の作業セッションで完了する場合に限ります。
4. 停止。

計画作成またはチケット作成のスキルがインストールされている場合は、その役割を明示して使用してください。インストールされていない場合は、上記の簡単な説明に従ってください。承認済みの仕様書は、その後の作業を拘束する権威ある文書です。