良い仕様の作成
あなたはめったに仕様を白紙から作成しません。プレーンテキストで変更を説明し、/rasen:propose は要件とシナリオをドラフトし、次にそれを良いものにします。このページはその最後の部分についてです — 「良い」とはどのように見えるか、および AI をそれに向けてどのように操縦するか。
これは 変更のレビュー のコンパニオンです：レビューはドラフトの弱いスポットをキャッチしており、作成は強いものがどのように構成されているかを知ることです。
仕様はコードではなく動作です
仕様はあなたのシステムが行うことを言い、コード構築方法ではなく、誰でもチェックできる用語で。それは要件（動作ステートメント）とシナリオ（それらを証明する具体的な例）で構成されています。
### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate
方法 — キュー、ライブラリ、テーブルスキーマ — を design.md またはコードに保ちます。動作と実装が 1 つの要件に混合されると、要件はテスト可能であることを停止し、コードが変更された瞬間に古い状態になり始めます。
良い要件の内容
良い要件は 1 つの動作です。他の誰かがテストするために渡すほどに単純に述べられています。
1 ステートメント、1 つの
SHALL/MUST。 要件に 3 つの「そしてまた」句がある場合、それは実際には 3 つの要件です。分割。観察可能。 コード外の誰かが保持するかどうかを判断できるはずです。「システムは アップロードが 10 MB を超える場合はエラーバナーを表示しなければならない」は観察可能です。「システムは 大きなアップロードをグレースフルに処理しなければならない」ではなく。
正しい強度。 Rasen は RFC 2119 キーワードを使用しており、異なるものを意味します：
キーワード 意味 MUST/SHALLハード要件。交渉不可。 SHOULD強い推奨事項、正当な例外の余地あり。 MAY真にオプション。 デフォルトで
MUST/SHALLに到達します。SHOULDを使用するのは、あなたが本当に「正当な理由がない限り」を意味する場合のみです。
要件のテスト：コードを見たことがないテスターが、それが渡されたかどうかを判断できますか？ そうでない場合、シャープニングが必要です。
良いシナリオの内容
シナリオは要件が報酬に値する場所です。各シナリオは自動化されたテストになる可能性のある具体的な GIVEN / WHEN / THEN です。
- それは要件を実行します。 要件を他の単語で単に言い直すシナリオは何もテストしません。特定の状況と特定の結果を持つ特定の状況にします。
- 重要なケースをカバー、幸せなパスだけでなく。 有効なログインは簡単です。空の入力、期限切れのトークン、2 番目のクリック、問題が発生したもの — これらはバグが生まれる場所であり、シナリオが最も価値がある場所です。
- タイトルの場合を命名します。 「シナリオ：期限切れトークンを拒否」はレビュアーに一目でカバーされるものを伝えます。「シナリオ：テスト 2」ではなく。
有用な習慣：承認する前に、私が壊れるのを見たくない 1 つのケースは何ですか？ — そしてシナリオがそれを命名していることを確認します。
正しい種類のデルタを選択
変更は 3 つのセクションタイプで仕様への編集を説明しています。正しいものを使用すると、アーカイブされた仕様が誠実になります：
## ADDED Requirements— 以前は存在しなかった新しい動作。## MODIFIED Requirements— 既に存在していて変更されている動作。完全な新しいバージョンを含めます。変更に関する簡潔なメモがレビュアーを助けます。## REMOVED Requirements— 去りつつある動作、理由に関する行付き。
アーカイブ時に、ADDED はメイン仕様に付加され、MODIFIED は古いバージョンを置き換え、REMOVED は削除されます。実際の変更を ADDED としてマークすると、競合する要件が 2 つ終わります。新しい動作を MODIFIED として説明すると、置き換えるものがありません。確信がない場合は、現在の仕様を開いて、要件が既にあるかどうかを確認します。
変更の適切なサイズ設定
単一の最も一般的な作成エラーは、単語がない要件ではなく、3 つの変更しようとしている変更です。
良い変更には、1 つの意図があります。文で説明できます。 「ダークモードトグルを追加。」「ログインエンドポイントをレート制限。」「セッションをクッキーから移行。」変更の説明に多くの「そしてまた」が必要な場合、それは分割するシグナルです。
変更が大きすぎることを示唆:
- 提案のスコープは、関連のない機能のリストのように読みます。
- レビューには午後が必要になるため、誰もしません。
- 2 人は衝突なく作業できませんでした。
- 半分のタスクは自分で出荷できました。
より小さな変更は、確認するのが簡単で、1 つの焦点の合った セッションで構築するのが簡単で、6 ヶ月後にアーカイブが残っているときに推論するのが簡単です。複数の変更を並列で実行できます — 編集 & 反復 と ワークフロー を参照してください。
反対のことも起こります：1 行のタイプミス修正は 3 つの要件と設計ドキュメントを必要としません。セレモニーを賭けと一致させます。
AI を良いドラフトに向けて操縦する方法
/rasen:propose は最初のドラフトを行うため、得られるものの質は与える品質を追跡します。要件を手で書く必要はありません — AI をよく目標にする必要があります：
- 意図と境界を述べます。 「OS 設定に続く最初の読み込みのダークモードトグルを追加 — 既存のテーマ API に触れないでください。」 スコープ外の半分はスコープ内の半分と同じくらい重要です。
- あなたが気にするケースを命名してください。 「既にテーマを手動で選択したユーザーのシナリオがあることを確認してください。」 AI は指すものをカバーします。
- それから編集。 それはプレーン マークダウンです。曖昧な
SHALLをしっかり、テストしないシナリオを削除、逃した場合を追加 — または AI に尋ねます：「タイムアウト要件は曖昧です、30 分に固定します。」
ドラフト、シャープン、繰り返し。いくつかのラウンドが信頼できる仕様を生成するため、ポイント全体です。
クイックチェックリスト
- 各要件は 1 つの観察可能な
SHALL/MUSTの動作です。 - 実装詳細は要件に焼き込まれていません。
- すべての要件には、実際にそれを実行する少なくとも 1 つのシナリオがあります。
- 重要なエッジとエラーケースはシナリオを持つため、幸せなパスだけではありません。
- デルタは現在の仕様に対して ADDED / MODIFIED / REMOVED を正しく使用します。
- 全体の変更には、1 つの意図があります。文で説明できます。