仕様書（OpenSpec）の受入条件を実装検査へつなぐ——仕様・決めた検査項目・変更後の照合

「いい感じに動く」では、開発の終わりを決められない

申請内容から回答案を作るAIを開発し、画面が動く試作ができたとします。担当者は「便利そう」と感じても、どの条件なら受け入れてよいかが決まっていないと、次々に要求が増えます。文章が自然、回答が速い、対象外を止める、保存先へ届く、といった品質が混ざっているためです。開発の前に、誰がどの入力を使い、どんな結果なら業務に使えるかを定めると、仕様と検証を結び付けられます。受入条件は最後のチェックリストより、作る範囲を決める材料になります。

社内の設備利用申請から受付内容と確認事項を整理する場面を考えます。入力は申請文と設備一覧、出力は対象設備、希望期間、不足項目、回答候補とします。設備を予約する操作は含めず、担当者が候補を確認するまでを最初の範囲にします。仕様の管理をOpenSpec、作業と検証・受入の進行をLangGraphへ分担する設計が考えられます。設備一覧の取得と候補作成の依存関係、使える設備の制約、一覧の版を明示することで、回答が何に基づくかを確認できます。

技術名を選ぶだけでは、仕事の意味は明確になりません。設備名が特定できたときと、候補が複数残ったときに何を返すかを決め、担当者が予約の前に確かめる情報へ結び付けます。試作ではその判断ができるかを評価し、予約操作や時間短縮の実測は別の確認対象にします。

受入条件を、利用者の判断から書く

「正しい回答を返す」だけでは検査できません。設備名が一意なら対象を返す、期間が不足していれば確認事項を返す、一覧にない設備なら対象外と示す、予約が完了したとは書かない、と条件を分けます。担当者が業務に使えるかを判断する際、何を確認するかを先に書く方法です。入力例と期待する出力を並べると、曖昧な語を具体化できます。速度についても、何秒という目標を置く前に、資料取得から表示までか、AIの生成部分だけかを決めます。

受入条件には、してよいことと、しないことを含めます。回答候補を作る仕事なら、登録済みの設備から候補を選ぶことは許されても、空いていそうな設備を推測して予約することは対象外です。対象外を明示すれば、後から機能追加を検討する際に影響が見えます。禁止事項を増やすためではなく、今回の成果を定義するために境界を置きます。新しい操作が必要になったら、その権限と結果の確認を別に仕様へ追加します。既存の許可で進められる範囲を何度も問い直す必要はありません。

業務担当が「確認しやすい」と求める場合は、対象、根拠、未解決の点が同じ画面で見える、といった条件へ変えます。好みを完全に機械で判定できるとは限りませんが、人が何を見るかを明確にすれば、レビューの基準になります。

受入条件が複数ある場合は、必ず満たす条件と、比較して選ぶ品質を分けます。予約完了と誤表示しないことは必須ですが、説明の言い回しには複数の許容案があります。全部を固定の文面へ合わせるより、業務上の意味を保つ条件と表現の好みを区別します。

通常例の隣に、情報不足の例を置く

正常な申請だけを仕様にすると、不足がある入力でAIが推測してしまう可能性があります。「会議室を来週使いたい」という入力では、どの部屋か、来週の何日か、利用時間が不明です。出力は予約候補の確定ではなく、必要な確認事項とします。入力が空、設備名が複数に当たる、日付が過去、資料を取得できない、といった例も仕様へ含めます。情報不足の扱いは実装後の例外ではなく、業務の通常の一部として設計します。

確認待ちの間に進められる仕事もあります。担当者への質問文を作る、取得済みの設備情報を整理する、といった成果は残せます。ただし未確定の日時を使って予約完了の文を作らない条件が必要です。待っている理由と残る成果を分けて表示します。設備一覧を読めなかった場合は、一覧に存在しないと断定せず「参照できず」と返します。欠落、対象外、接続失敗で次の対応が変わるため、その違いを仕様に残すと、実装する人と確認する人が同じ判断をできます。

期待する出力を一字一句の文章で固定する必要はありません。必要な項目、根拠の対応、避ける断定を定め、自然な言い換えは許す方法があります。文章の好みと業務上の正しさを分ければ、検査が表現の揺れだけで失敗することを減らせます。

仕様、設計、作業を混ぜずにつなぐ

仕様は利用者から見た動作、設計はその動作をどう作るか、作業は実装と検査の手順です。設備申請なら、期間が不足したら確認へ返すという仕様に対し、日付の形式検査とAIによる文脈読取りを組み合わせる設計が考えられます。作業には入力画面、資料取得、候補生成、確認表示、検査ケースの作成を登録します。技術の名前だけを仕様へ並べても、利用者が何を受け取るかは分かりません。逆に仕様を長い説明文だけにすると、実装する対象が抜ける場合があります。

OpenSpecは変更ごとの目的や仕様、設計、作業を整理する道具です。導入したことだけで仕様を自動作成するものではありません。対象の実装と検査を対応させ、実際の作業が終わったかを確認する必要があります。設備申請では各受入条件に入力例と検査を付け、どの条件を機械で確認し、どれを人が確認するかも記します。期間の欠落を検知する処理があっても、質問の意味が伝わらなければ修正が必要です。文章上の仕様が整ったことと機能が完成したことを別に扱います。

設計の選択には理由を残します。日付の形式は通常のプログラムで判定でき、用途の解釈にはAIが役立つ、と区別すれば、後で失敗原因を調べる入口になります。全てをAIへ任せることを、設計の前提にする必要はありません。

依存関係は「終わった」より「使える」で定める

設備一覧の取得が終わっていても、今回の申請に対応する一覧か、必要な項目があるかを確認しなければ、候補作成へ渡せません。後続が始められる条件を「前の作業が終了」ではなく「今回の入力に対応する結果を受け入れた」と定めます。設備名の候補を確認した後に利用日が変わるなら、回答案の期間も作り直します。成果と入力を結び付ければ、どの変更がどの後続に影響するかを説明できます。進行の順序だけでなく、結果の意味を依存関係へ含めます。

仕様の変更は一か所で管理し、作業項目、依存関係、制約、版を同じ変更へ結び付ける方法が考えられます。複数の場所で別々に計画を直すと、画面だけ新しい条件を使い、検査は古い条件のままになる場合があります。設備一覧の更新が候補作成へ伝わるか、期間の制約が表示と検査で一致するかを確認します。書込みの経路を限定する場合も、誰が変更できるかと変更を後続へ伝える条件を定めます。基盤の名前より、変更が一貫して伝わる仕組みが必要です。

並行して進められる仕事も明示します。画面の表示設計と、設備一覧の読取り検査は独立して進められる場合があります。一方、予約操作の実装は今回の対象外です。作業の依存関係を整理すると、待つ必要がある仕事と先に進められる仕事を分けられます。

計画の表示は、関数や処理名の列挙より、申請を読む仕事、不足を確認する仕事、候補を受け入れる仕事として示すと役立ちます。担当者が選択して入出力と根拠を見られる工程図なら、着手の順序だけでなく、どの判断を待っているかを共有できます。

検査は、仕様の各条件に対応させる

受入条件の一覧に、どの検査で確かめるかを付けます。期間不足なら確認待ち、未知の設備なら対象外、資料取得失敗なら参照できず、正常なら必要な候補を返す、と対応させます。実装と同じ処理をなぞるだけの検査では、仕様の誤りに気付けません。人が先に期待結果を定め、実際の出力と比較します。対象が一件も検査されていない状態を成功にしないことも必要です。検査の実行が成功したという記録だけで、全ての受入条件を満たしたとは扱いません。

仕様の構造の検証に加え、変更対象に対応した固定の検査を実行し、提出された実装と確認した対象が一致するかを照合します。設備申請なら確認した画面や処理が、その後で変更されていないかも記録します。別担当のレビューでは検査範囲が要求に足りるか、未確認の条件があるかを見ます。機械で必須項目を確認しても、利用者が質問の意味を理解できるかは人の確認が必要です。根拠が足りない場合には保留できる基準を設け、機械検査と意味のレビューを受入へつなげます。

検査で失敗したら、結果に合わせて条件を緩める前に原因を調べます。仕様が誤っていた場合は理由を記して変更し、必要な検査も更新します。望む合格を得るために基準を動かさないことが、開発の判断材料を保ちます。

OpenSpecで変更ごとの仕様と作業を整理し、LangGraphで提出待ち、検証、差戻し、別担当レビュー、受入の進行を管理する構成が考えられます。固定検査の結果と対象の実装・仕様のハッシュを結び付け、レビュー後も照合します。これにより、仕様の構造が正しいことと現在の機能が要求を満たすことを別の条件にできます。設備申請では、どの版の設備一覧と画面を検査したかも残し、検査後の変更があれば関係する条件を試し直します。

変更後の受入を、古い合格で済ませない

担当者が、回答候補だけでなく予約の登録も依頼した場合、範囲が変わります。操作権限、登録前の確認、重複を防ぐ条件、登録結果の取得が新たに必要です。前の試作が合格していても、追加した操作の安全や結果は未確認です。変更の目的と受入条件を更新し、追加した範囲の検査を行います。単に作業一覧へ登録の項目を足すだけでは、業務の完了条件が変わったことを扱えません。依頼と成果の対応を見直すことが重要です。

仕様や実装を変更した後は、古い合格結果を流用しないようにします。確認した対象を保存し、現在の成果と一致するかを見ます。レビューの後に修正した場合も、影響する検査を再実行します。設備名の表示だけを直したなら表示の確認へ、期間の解釈を直したなら不足や日付の検査へ戻します。全ての変更を無限に試すという意味ではありません。何が変わり、どの条件へ影響するかを説明し、その範囲を確かめます。確認済みと未確認を分けることで、残る作業を具体的にできます。

新しい要求を全て同じ開発へ取り込む必要はありません。現在の範囲を完成させ、次の変更として分ける選択もあります。納期や費用の判断へ影響する追加は、何が増えるかを示して相談できます。決まった条件を毎回問い直すこととは区別します。

範囲の追加を相談する際には、現行の成果が何を満たし、新しい操作で何が増えるかを並べます。追加の許可、検査、保守が必要な理由を具体的に示すと、利用者は次の開発へ進む価値を判断できます。技術の選択だけを問い直すより、業務の結果と負担へ結び付けます。

受け入れられる仕様は、残る制約も説明する

最初の成果が回答候補の作成までなら、予約は成立していないと利用者へ示します。設備一覧が古い可能性があるなら、取得時点と確認範囲を残します。情報不足を人へ返せても、その人がいつ対応するかは別の運用条件です。仕様に含めないことを隠すと、利用者が機能の外まで期待します。何を入力し、どこまで結果を受け取り、何が残るかを一つの説明にすることで、使い始める判断がしやすくなります。制約を示すことも受入条件の一部になります。

続行の判断では、正常例の成功だけでなく、不足や対象外を適切に返したか、担当者が確認できたかを見ます。期待と違う結果が出た場合、対象を狭める、資料を整備する、接続方法を変える選択があります。仕様は実装を縛るためだけでなく、開発を続ける根拠と中止する根拠を持たせる道具です。受入条件から始めれば、AIが何を答えたかより、業務でどの判断が可能になったかを評価できます。動く試作を、説明できる成果へ変えるための順序として役立ちます。

仕様が完成した段階を、開発全体の完成と混同しません。実装、対応する検査、意味のレビュー、現在の成果の受入がそろって初めて今回の範囲を完了できます。どの段階まで終えたかを報告すれば、利用者も次の判断を根拠に基づいて行えます。