Coroidは仕様駆動型開発を採用しています。つまり、仕様書は計画からテスト、レビューまでの作業全体で一貫して使用され、各段階で同じ成功定義に基づいて作業が進められます。
文面から始めてコーディング中に詳細を決めるのではなく、Coroidは要求内容を明確な範囲、除外項目、受入基準に変換します。その文書が計画、実装、テスト、最終レビューのための唯一の信頼できる情報源となります。
仕様駆動型開発とは何ですか？
仕様駆動型開発とは、合意された、テスト可能な成果物の記述に基づいてソフトウェアを構築する手法です。仕様書には何が変更されるか、何が変更されないか、適用される制約、およびレビュー者が作業が成功したかを判断する基準が記載されます。
混同しやすい2つの判断を分離します：
- 「仕様書」が成功の定義を定めます。
- 「実装計画」がその達成方法を定めます。
この分離により、コードが存在する前に範囲を修正でき、実装方法を早急に指定する必要もありません。Coroidでは、オプションのSDLCワークフローも有効化できます。これにより、計画開始前に意図と仕様書を承認できます。
Coroidにおけるワークフローの流れ
- **成果物を記述します。**Coroidに必要な結果、関連する背景情報、制約や非目標を伝えます。
- **仕様書をレビューします。**タスクの「仕様書」タブで範囲、除外項目、受入基準を確認します。
- **計画を承認します。**アーキテクトが合意された成果物を順序付けられた実装手順に変換します。
- **構築と検証を行います。**開発者エージェントとQAエージェントが同じ基準に従って変更を実装し、約束された挙動が確実に実現されることを証明します。
- **pull requestをレビューします。**納品された変更内容には、計画、テスト結果、調査結果、証拠が元の仕様書と照らし合わせて記載されます。
これにより、製品の意図からコード、人間のレビュー者が確認できる証拠までの追跡可能性が確保されます。詳細な実行手順については、「タスクがpull requestになるまでの流れ」をご参照ください。
なぜこの余分な手順が必要なのか
「ユーザー検索機能にキャッシュ処理を追加する」という指示には少なくとも4通りの妥当な実装方法があり、完了の定義が存在しません。エージェントがどの方法を選ぶかは運次第です。
仕様書により、実装開始前にその選択を明確にでき、考えを変えるコストが最も低い段階で決定できます。
また、検証の対象も明確になります。受入基準がなければ、「これは正常に動作したか？」という問いは「テストがまだ通過するか？」という弱い問いに変わってしまいます。
仕様書に含まれる内容
| 項目 | 回答内容 |
|---|---|
| 範囲 | 変更される内容 |
| 範囲外 | 意図的に変更しない内容。これにより変更が無秩序に広がるのを防ぎます。 |
| 受入基準 | 正常に動作したかを判断する方法 |
| 背景情報 | 適用される制約、規則、既存の決定事項 |
実行開始前に、タスクの「仕様書」タブで仕様書を閲覧・編集できます。このプロセスに反映される作業説明と補足情報については、「必要な内容を記述する方法.
実例：概要からテスト可能な仕様書まで
元の概要は以下の通りです：
Add caching to the user lookup so repeated requests are faster.これは望ましい成果物を記述していますが、重要な選択肢が未解決のままです。有用な仕様書はこれらの選択肢を境界とチェックポイントに変換します：
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.これにより、計画担当者は実装方法を選択し、QA担当者は基準に基づいてテストを作成し、レビュー者はpull requestと約束された挙動を比較できます。
良い受入基準の条件
会話に参加していない人でも確認できるものでなければなりません。
不十分な例：
Caching works correctly and performance is improved.優れた例：
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.2番目のバージョンでは、開発者エージェントに構築すべき内容、QAエージェントにテストすべき内容、pull requestで確認すべき内容が明確に示されています。1番目の例ではこれらの判断がすべて未定義のままです。
範囲の定義も基準と同等に重要です。
pull requestが過大になる最も一般的な原因は、エージェントが指示を超えることではなく、指示の終了点が明記されていない仕様によるものです。
該当モジュールのリファクタリングを望まない場合は、その旨を明記してください。「呼び出し先を変更しない」という記述は正当かつ有用な指示となります。
よくある仕様の誤り
| 誤り | より良い対応策 |
|---|---|
| 成果ではなく実装内容を記述する | 動作や制約条件を明記した上で、計画に合わせて実装方法を決定させましょう。 |
| 「高速」「安全」「正しく動作する」といった表現を使用する | これらを観測可能な閾値や動作、テスト内容に置き換えてください。 |
| 対象外の項目を記載しない | 変更を加えてはならない隣接するコード、インターフェース、動作を明記しましょう。 |
| 関連性のない複数の成果を一つの仕様にまとめる | 作業を分割し、一つのタスクが一つのレビュー可能なpull requestとなるようにしましょう。 |
| 前提条件を確認せずにチケットをコピーする | リポジトリだけでは把握できない背景情報や判断内容を追加してください。 |
仕様に同意できない場合
仕様を編集しましょう。仕様は実行開始前まで有効な文書であり、修正する方がコードを修正するよりもコストが抑えられます。
仕様により作業が実際には二つに分かれる場合は、それぞれを別のタスクに分割してください。一つのタスクが一つのpull requestとなり、一人の担当者が一度にレビューできるようになります。
次のステップ
小規模な変更を除き、仕様は計画へと発展します。詳細は以下をご覧ください。タスク、計画、スプリント、レーンこれらはコード作成前に作業がどのように分割・承認されるかを説明しています。
よくある質問
仕様と技術設計は同じものですか？
いいえ。仕様は求められる成果と境界条件を定義します。一方、技術設計や実装計画はその成果を得るためのアーキテクチャや手順を説明します。
すべての変更に長文の仕様が必要ですか？
いいえ。曖昧さのない小規模な変更であれば、数行の範囲と受け入れ基準のみで十分です。仕様は意味のある不確実性を排除するものであり、形式ばった手続きを追加するものではありません。
誰が仕様を承認すべきですか？
成果に責任を持つ人が、範囲と基準がチームのニーズに合致しているかを確認する必要があります。制約条件が成果に影響を及ぼす場合は、技術、セキュリティ、コンプライアンス担当者も承認プロセスに参加できます。
作業開始後に仕様を変更できますか？
変更は可能ですが、新しいバージョンを作成し、関連する計画と作業のレビューを実施する必要があります。範囲が黙って変更されると、要求と納品されたpull request間の証拠の連鎖が途切れてしまいます。