# docs-handbook 全文 開発文書の書き方に関する個人ハンドブック。要求・要件・仕様・設計の4層モデルで 開発文書を整理している。以下に全4文書の本文をそのまま連結している。 ======================================================================== # 層の越境パターン集 カテゴリ: 概念 概要: 層が静かに越境する15の型。下向きの先取りと上向きの追認を、症状と直し方で整理する URL: https://docs-handbook-9dg.pages.dev/raw/concepts/layer-crossing-patterns.md ======================================================================== # 層の越境パターン集 層を分ける理由は「なぜ工程として必要なのか」で述べた。 だが実際の文書では、層は宣言だけでは守られない。書いているうちに静かに越境する。 越境には方向がある。**下向き**（上位層の文書に下位層の判断が先回りして書かれる）と、 **上向き**（下位層で発生した都合が、検証されないまま上位層の決定として居座る）である。 方向によって症状も直し方も違うため、分けて扱う。 判定の基準はひとつ。**その記述を「正しい」と言える人が、その文書の検証者と一致しているか**。 一致していなければ越境している。 以下の例は、業種・システム種別を意図的に散らしてある。 越境は特定のドメインの癖ではなく、層を扱うかぎりどこでも起きるためである。 --- ## 下向きの越境: 上位層が下位層を先取りする ### 1. 要求に解決策が書かれている もっとも頻度が高く、もっとも損失が大きい。 | | | |---|---| | 症状 | 要求定義書の目的欄に、作るものの名前が書いてある | | 例（EC） | ✗「レコメンドエンジンを導入する」
✓「カゴ落ち率を32%から20%に下げる」 | | 例（社内） | ✗「勤怠管理システムを刷新する」
✓「月次締めの差し戻しを月40件から5件以下にする」 | | 失われるもの | 代替案の検討余地。カゴ落ちは送料表示のタイミング変更で解ける可能性があるが、レコメンドと書いた時点で検討対象から外れる | | 直し方 | 「それができると何が嬉しいのか」を3回問う。システムの話でなくなったところが要求 | 解決策が要求の位置に座ると、以降の全層がその解決策を前提に積み上がる。 要求が間違っていたと分かるのは運用に入ってからで、そのときには修正コストが桁で変わっている。 ### 2. 要求に成功基準がない | | | |---|---| | 症状 | 「業務を効率化する」「顧客満足度を向上させる」で止まっている | | 例（サポート） | ✗「問い合わせ対応を改善する」
✓「一次回答までの中央値を8時間から2時間にする」 | | 失われるもの | 受入テストの根拠。発注者が「それが欲しかったものか」を判定できない | | 直し方 | 数値と期限を入れる。入れられないなら、まだ要求が言語化されていない | V字モデルで要求に対応するのは受入テストである。 検証者が正誤を言えない要求は、対応する検証が空になる。 ### 3. 要件に技術選定が入る | | | |---|---| | 症状 | 実現手段が要件として合意されている | | 例（Webサービス） | ✗「Redisでセッションを管理できること」
✓「複数サーバー構成でもログイン状態が維持されること」 | | 例（モバイル） | ✗「Firebase Cloud Messagingで通知を配信すること」
✓「在庫が復活した商品を、登録者に30分以内に通知できること」 | | 失われるもの | 設計の自由度。要件として合意した以上、後から別の手段に変えるのが契約上の変更になる | | 見分け方 | 製品名・ミドルウェア名・アーキテクチャ名が出てきたら設計層 | ### 4. 要件に画面が入る | | | |---|---| | 症状 | 要件定義書に画面レイアウトやボタン配置が書かれている | | 例（予約サービス） | 要件は「予約の変更が予約者本人でできること」。
「マイページ内に変更ボタンを置く」は仕様の話 | | なぜ起きる | 発注者に説明するとき、画面があるほうが伝わるため | | 問題 | 説明のための画像が、いつのまにか合意事項として扱われる | | 直し方 | 画面を出すなら「これはイメージであり仕様ではない」と明記する。合意対象は文章側 | ### 5. 要件定義書でクライアント向けと内部向けが混ざる | | | |---|---| | 症状 | 発注者に説明する内容と、実装者向けの補足が同じ節に同居している | | 問題 | 発注者は読めない箇所を読み飛ばし、実装者は合意済みと未確定の区別を失う | | 直し方 | 章または節の単位で分離し、どちらが合意対象かを明示する | 同じ文書に2種類の読者がいるとき、層の境界より先に**読者の境界**が壊れる。 ### 6. 仕様に判定不能な語が残る | | | |---|---| | 症状 | 「適切に処理する」「必要に応じて考慮する」「十分な性能を確保する」 | | 例（社内文書） | ✗「承認者が不在のときは適切に処理する」
✓「承認待ちが3営業日を超えたら代理承認者へ自動転送する。代理承認者が未設定の場合は申請者の部門長に通知し、申請は差し戻さない」 | | 問題 | 仕様の検証者はテスター・レビュアーである。正誤を判定できない記述は、仕様の役割を果たしていない | | 直し方 | 「これをどう試験するか」を書いてみる。書けないなら決まっていない | ### 7. 仕様が正常系しかない | | | |---|---| | 症状 | 入力と出力は書かれているが、上限・0件・エラー・同時実行が書かれていない | | 例（予約） | 「空き枠を選んで予約できる」だけが書かれ、最後の1枠を2人が同時に押した場合が書かれていない | | 例（社内文書） | 同じ規程を2人が同時に編集して保存した場合の扱いが未定義。後勝ちか、警告を出すか、版を分けるかが決まっていない | | 何が起きるか | 実装者が実装中に決める。決めた事実がどこにも残らない | | 直し方 | 入力・出力・条件・例外の4点セットを埋めきるまで仕様としない | 未定義の例外系は消えるのではなく、コードの中に無記名で確定する。 ### 8. 設計書が実装のコピーになっている | | | |---|---| | 症状 | クラス名とメソッド名の一覧はあるが、なぜその構造にしたかがない | | 書くべきこと | 「注文と在庫引当を同一トランザクションにせず、非同期にした。理由はピーク時のロック競合を避けるため。採らなかった案は同期＋悲観ロックで、整合性は単純になるが秒間注文数の上限が読めなかった」 | | 問題 | コードを読めば分かることしか書いておらず、コードから読み取れない判断が残っていない | | 直し方 | 検討して**採らなかった案**とその理由を書く。設計書の価値はそこにある | --- ## 上向きの越境: 下位の都合が上位に昇格する 下向きは書き手の先走りだが、上向きは**追認**である。 起きてしまったことを事後的に正当化するため、指摘されにくく、発見が遅れる。 ### 9. 実装の都合が仕様として確定する | | | |---|---| | 症状 | 実装中に判明した制約が、そのまま仕様書に反映される | | 例（外部連携） | 配送会社のAPIが1分1回までだったため、追跡情報の更新間隔を1分にした。それが「仕様」として書かれ、なぜその値かは残らない | | なぜ問題か | 上の層へ差し戻さず、コードで解決してしまっている | | 正しい手順 | 仕様の検証者（レビュアー）に判断を戻す。その上で仕様を変えるなら、変更として記録する | 結果として同じ仕様に落ち着くこともある。問題は結論ではなく、**誰が決めたかが残らない**ことにある。 ### 10. 設計上の制約が要求の目標を書き換える | | | |---|---| | 症状 | 下位層の妥協が積み重なり、要求の成功基準が未達になっているが、誰も気づかない | | 例（社内文書） | 全文検索のインデックス更新が重いため、反映までを「1時間以内」に緩めた。要求にあった「承認された規程を関係者がすぐ参照できる」は成立しなくなっているが、仕様書上は整合している | | なぜ起きる | 仕様の変更として処理されるため、要求層まで影響が伝わらない | | 直し方 | 仕様を変えるとき、上位の成功基準に触れるかを必ず確認する | これは越境の中でもっとも静かで、もっとも危険な種類である。 文書上はすべて整合しているのに、要求が達成できない状態が完成する。 ### 11. 仕様変更がバグ修正として処理される | | | |---|---| | 症状 | 「不具合対応」として振る舞いが変わっている。仕様書は更新されていない | | 例（社内文書） | 規程の改定時に、旧版へのリンクが自動的に新版を指すよう変更した。仕様書に版の参照方法の記載がなかったため「バグ」として処理されたが、実際には「当時どの版を参照していたか」を監査時に追えなくする仕様変更 | | 問題 | 仕様書と実態がズレる。次に仕様書を信じた人が誤る | | 見分け方 | 「決めたとおりでない」がバグ、「決めたことが間違っていた」は仕様変更 | 逆方向（仕様変更をバグ修正と主張する）は、受託では費用負担の争点に直結する。 層の区別がそのまま契約の区別になる場面である。 --- ## 層の運用そのものの失敗 ### 12. すべての変更が最下層で処理される | | | |---|---| | 症状 | どんな要望も「ではコードをこう直します」から会話が始まる | | 例 | 「もっと使いやすくして」に対し、ボタンの色と配置の調整を繰り返す。要求層で「誰がどこで詰まっているか」を確かめていないため、何度直しても評価が変わらない | | 直し方 | 受けた時点で「これは要求／要件／仕様／設計のどれの変更か」を先に言語化する | 層を分けた本来の効能は、変更時の影響範囲の特定にある。 これが失われると、層は文書の飾りになる。 ### 13. 「設計書」という名の全部入り | | | |---|---| | 症状 | 1つの文書に背景・機能一覧・画面・テーブル定義が同居している | | 問題 | 検証者が特定できない。誰もレビューを完了できず、承認だけが形式的に行われる | | 直し方 | 分割の基準は分量ではなく検証者。読む人が変わるところで切る | ### 14. 上の層が更新されない | | | |---|---| | 症状 | 仕様書と設計書は最新だが、要件定義書が初版のまま | | 例 | 途中で対象ユーザーが「店舗スタッフのみ」から「本部を含む」に広がったのに、要件定義書は店舗前提のまま。権限設計の議論が毎回ふりだしに戻る | | なぜ起きる | 日々参照するのは下の層だけで、上の層は「合意済みの過去」として凍結される | | 直し方 | 上位層は変更頻度が低いだけで、変わらないわけではない。変えたら書く | ### 15. 層をまたいで用語が揺れる | | | |---|---| | 症状 | 同じ対象が層ごとに違う名前で呼ばれている | | 例（EC） | 要求では「お客様」、要件では「会員」、仕様では「ユーザー」、設計では `customer`。未登録の購入者を含むのかどうかが誰にも分からない | | 問題 | 同じものか別のものかが読み手に判断できず、追跡が切れる | | 直し方 | 用語集を要求層に置き、下位層はそれを参照する | --- ## 越境を見つけるためのチェック 文書を書き終えたら、次を順に確認する。 1. この文書を「正しい」と言えるのは誰か。その人がすべての記述を判定できるか 2. 製品名・技術名が上位層に混ざっていないか 3. 「適切に」「必要に応じて」で終わっている記述はないか 4. 実装中に決めたことが、無記録で文書に反映されていないか 5. 下位層の変更が、上位層の成功基準に触れていないか 6. 前回から上位層は本当に変わっていないか いずれも「なぜ工程として必要なのか」で挙げた問いの言い換えである。 **この判断は誰が検証するのか**。答えられない記述が、越境した記述である。 ======================================================================== # 開発プロセスの全体像 カテゴリ: 概念 概要: 開発プロセス全体の見取り図。各工程が何を決め、何を残すか URL: https://docs-handbook-9dg.pages.dev/raw/concepts/process-overview.md ======================================================================== # 開発プロセスの全体像 システム開発は「作るものを決める」工程と「作って届け、動かし続ける」工程からなる。 本ハンドブックでは前半の4つを **4層モデル** と呼び、中心的に扱う。 この分類は本ハンドブックの独自定義であり、ISO/IEC/IEEE 12207(共通フレーム)・ISO/IEC/IEEE 29148・V字モデルなどを源流に実務向けへ整理したもの(後述「標準規格との対応」を参照)。 ## 定義する工程(4層モデル) ### 要求 **なぜやるか**。ビジネスと業務の話であり、唯一システムの話をしない層。 主語はユーザーや発注者。背景・目的・成功基準(数値)・制約・スコープ外を明らかにする。 - 例(設備保全):「設備の突発停止による生産ラインの停止を月20時間から5時間に減らしたい」 - 例(動画レコメンド):「初月で解約する利用者を減らし、継続率を60%から75%にしたい」 - 例(社内文書検索):「類似の社内文書を探す時間を半日から30分にしたい」 - 残す文書: 要求定義書(PRD) ### 要件 **何を実現するか**。要求を満たすためにシステムに求める機能・性質。 ここから主語が「システムは〜」になる。 - 例(設備保全):「設備の振動と温度から異常の兆候を検知し、担当者に知らせられること」 - 例(動画レコメンド):「利用者ごとに視聴傾向に沿った作品を提案できること」 - 例(社内文書検索):「全部門の社内文書をキーワードで横断検索できること」 - 残す文書: 要件定義書 ### 仕様 **どう振る舞うか**。システムを外から見た振る舞いの取り決め。 入力・出力・条件・例外を定め、「正しい/間違い」を判定できる基準になる。 - 例(設備保全):「振動が基準値の1.5倍を10分超え続けたら警告、同一設備への通知は1時間に1回まで」 - 例(動画レコメンド):「トップに10件、視聴済みは除外、視聴履歴が3件未満の利用者には人気順を返す」 - 例(社内文書検索):「キーワードは100文字まで、結果は関連度順に20件表示」 - 残す文書: 画面仕様書、API仕様書、バッチ仕様書 ### 設計 **どう作るか**。仕様を実現する内部構造と技術の選択。 ここで初めて実装の中身の話になる。 - 例(設備保全):「センサー値を1分間隔で時系列データベースに蓄積し、移動平均との乖離で判定」 - 例(動画レコメンド):「協調フィルタリングを日次バッチで計算し、結果を利用者ごとにキャッシュ」 - 例(社内文書検索):「Elasticsearchでkuromoji解析、match_phraseクエリ」 - 残す文書: 設計書(アーキテクチャ、DB設計、シーケンス) ## 作り、届け、動かす工程 ### 実装 設計に従いコードを書く。決め事はコーディング規約・レビュー観点・ブランチ戦略として残す。 実装中に仕様や設計の矛盾が見つかったら、コードで勝手に解決せず上の層へ差し戻す。 ### テスト 作ったものが**上の層の決め事どおりか**を確かめる。検証対象は層と対応する: 単体テスト↔設計、結合テスト↔仕様、システムテスト↔要件、受入テスト↔要求(V字モデル)。 - 残す文書: テスト計画、テスト観点表 ### リリース 作ったものを利用者に届ける。手順の再現性と、失敗時に戻れることが要点。 - 残す文書: リリース手順書、チェックリスト、ロールバック基準 ### 運用 動かし続け、問題から学ぶ。監視・障害対応・改善のサイクル。 ここで得た知見が次の要求の種になり、プロセスは一周する。 - 残す文書: 運用手順、障害対応フロー、ポストモーテム ## 標準規格との対応 本ハンドブックの分類は独自定義だが、以下の標準・モデルを源流としている。 ### ISO/IEC/IEEE 12207 と共通フレーム ソフトウェアライフサイクルプロセスの国際規格。開発だけでなく、企画・運用・保守・廃棄まで含むプロセス全体を定義する。IPAの「共通フレーム」はこれを日本向けに拡張したもので、日本のSIにおける工程分割(企画→要件定義→設計→実装→テスト→運用・保守)の事実上の出どころ。 - 共通フレームの工程との対応: 企画・要件定義プロセス ≈ 要求/要件、方式設計〜詳細設計 ≈ 仕様/設計、以降は実装〜運用にそのまま対応 - 特徴は要件定義より前の「企画(超上流)」を明示的に工程化していること。本ハンドブックの「要求」はここに相当する ### ISO/IEC/IEEE 29148(要求工学) 要求の獲得・分析・記述に関する規格。要求を段階の異なる文書として区別する: | 文書 | 内容 | 本ハンドブックでの対応 | |---|---|---| | StRS (Stakeholder Requirements) | ステークホルダーが何を必要としているか | 要求 | | SyRS (System Requirements) | システムが何を満たすべきか | 要件 | | SRS (Software Requirements) | ソフトウェアが何を満たすべきか | 要件〜仕様 | 英語ではいずれも requirements であり、「要求/要件」の訳し分けは日本語圏の工夫。この規格の「ステークホルダーの要求とシステムの要件は別物」という区別が、4層モデルの上2層の根拠になっている。 ### V字モデル 工程とテストレベルの対応関係を示すモデル。左辺(定義)と右辺(検証)が層ごとに対になる: | 定義(左辺) | 検証(右辺) | |---|---| | 要求 | 受入テスト | | 要件 | システムテスト | | 仕様 | 結合テスト | | 設計 | 単体テスト | 「各層はそれぞれ検証できる相手が違う」という4層モデルの根拠はこの対応にある。層を省くと、対応する検証が根拠を失う。 ### 日本のSI慣行(外部設計/内部設計) 「仕様」を要件と設計の間の独立した層として立てるのは、外部設計(外から見た振る舞い)/内部設計(中身)という日本の伝統的な工程分割に由来する。海外では仕様(functional spec)を要件側に含めるか設計側に寄せるかは揺れており、独立層として扱うのはこのハンドブックの選択である。 ## 全体の関係 ``` なぜ 要求 何を └ 要件 振る舞い └ 仕様 作り方 └ 設計 └ 実装 → テスト → リリース → 運用 ─┐ なぜ(次) 要求 ←──────────────────────────┘ ``` - 前半4層は**抽象から具体への段階的詳細化**。工程であると同時に、完成後も残る文書の階層でもある - 変更が起きたら「どの層の変更か」を最初に見極める。要求の変更を仕様の修正だけで受けると、文書と実態がズレていく - 確定の順序は開発形態で前後する。受託はおおむね上から下へ、自社プロダクトではプロトタイプ(仕様・実装)が先行して要求が後から明確になる逆流も起きる ======================================================================== # コードから何が読めるか カテゴリ: 概念 概要: コードから復元できる層とできない層。要求だけが原理的に復元できない理由 URL: https://docs-handbook-9dg.pages.dev/raw/concepts/what-code-reveals.md ======================================================================== # コードから何が読めるか 引き継いだシステムに、コードしか残っていないことがある。 前任者は退職し、設計書は初版のまま、要件定義書は見つからない。動いているコードだけがある。 このとき「コードを読めば全部わかる」と言われることがある。半分は正しい。 だが**層によって復元できる度合いは決定的に違い、要求だけは原理的に復元できない**。 その線引きを明らかにするのがこの文書の目的である。 これは4層モデルを逆向きに辿る話にあたる。 他の文書が「上から下へ書く」ことを扱うのに対し、ここでは「下から上へ読む」ことを扱う。 ## 復元可能性は層によって違う | 層 | 復元可能性 | 残っているもの | 消えているもの | |---|---|---|---| | 設計 | ほぼ完全 | 構造・技術選択・データモデル | 検討して採らなかった案とその理由 | | 仕様 | 高い | 入力・出力・条件・例外（分岐とバリデーションとして） | どれが意図的な決定で、どれが暗黙の既定値か | | 要件 | 部分的 | 何ができるか | 何ができるべきか。実装されなかった要件 | | 要求 | 復元不能 | なし | 目的・成功基準・スコープ外の判断・代替案 | 下の層ほどコードとの距離が近く、上の層ほど遠い。 これは「開発プロセスの全体像」で述べた抽象から具体への段階的詳細化を、逆から見たものである。 注意すべきは、この表の右列——**消えているもの**が、いずれも「判断」だという点である。 コードに残るのは判断の**結果**であり、判断そのものではない。 ## なぜ要求だけ復元できないのか 理由は2つある。 ### 写像が多対一である 上位層から下位層への対応は一対一ではない。 まったく異なる要求から、同じコードが生まれうる。 例えば「関連文書をキーワードで検索できる」という実装は、次のどの要求からも導かれる。 - 調査にかかる時間を短縮したい - 担当者が異動しても業務が回るようにしたい - 問い合わせに対して根拠を示せるようにしたい コードはこの3つを区別しない。区別する必要がないからこそ、実装として成立している。 多対一の写像に逆写像は定義できない。これは情報が失われているという以前に、**構造上の帰結**である。 ### 要求はシステムの話をしない層である 「開発プロセスの全体像」で述べたとおり、要求は唯一システムの話をしない層である。 主語がユーザーや発注者であり、対象がビジネスと業務である以上、 その内容はシステムの内部——すなわちコードには最初から現れない。 コードの中を探しても見つからないのは当然で、そこに書かれるべきものではなかった。 ## 意図と事故は同じ形をしている 復元をさらに難しくするのは、**判断の結果と偶然の産物が、コード上で区別できない**ことである。 `LIMIT 20` という記述を見つけたとする。この値の由来は少なくとも3通りある。 1. 業務上の判断。画面で一覧できる件数として決めた 2. 性能上の妥協。件数を増やすと応答が遅くなるため下げた 3. 由来なし。最初に書いた誰かの既定値がそのまま残った コードからはどれか判定できない。にもかかわらず、読み手は多くの場合1だと解釈する。 コードを読むという行為には、**そこに理由があったと仮定する**バイアスが伴う。 さらに厄介なのは、「層の越境パターン集」で挙げた上向きの越境が起きていた場合である。 設計上の制約が要求の目標を静かに書き換えていたとき（同 #10）、 コードには**要求が未達であるという事実まで含めて、整合した状態**が残る。 このコードから逆算すると、達成できなかった状態が「そういう要求だった」として読み取られる。 復元は失敗しない。誤ったものを、矛盾なく復元してしまう。 ## 手がかりと、その限界 読み取れるものがないわけではない。ただし、どの層に届くかを意識して使う必要がある。 | 手がかり | 読めること | 届く層 | |---|---|---| | テストコード | 想定された入力・出力・例外。当時「正しい」とされた振る舞い | 仕様 | | 分岐とバリデーション | 条件と制約。ただし網羅されているとは限らない | 仕様 | | 例外処理の偏り | 特定箇所だけ手厚い防御は、過去に障害が起きた痕跡 | 仕様〜要件 | | 権限・ロールの構造 | 誰が使うシステムか。ステークホルダーの構成 | 要件 | | 命名の揺れ | 立場の異なる関係者の言葉が混在した跡（同 #15） | 要件 | | コミット履歴・課題管理 | 変更の理由。**唯一、要求に届きうる情報源** | 要求 | このうち上5つは、どれほど丁寧に読んでも要件までしか届かない。 要求に届く可能性があるのはコード外の記録——履歴や議論の場——だけである。 マジックナンバーの扱いには補足が要る。 `LIMIT 20` から読み取るべきは値の意味ではなく、**そこに判断があったという事実**である。 値の意味は推測するのではなく、確認すべき項目として記録する。 ## 逆算の罠 コードから要求を推測し、それを要求定義書として書き起こすことには固有の危険がある。 書き起こした瞬間、それは**現状追認の装置**になる。 実装の都合で決まった値が、要求という最上位の権威をまとって固定される。 以降の変更は、その「要求」との整合性を基準に判断される。 これは上向きの越境（同 #9・#10）を、文書化によって恒久化する行為にあたる。 越境はもともと記録されないことが問題だったが、 逆算による文書化は、越境を**正式な決定として記録してしまう**点でより悪い。 生成AIに読ませる場合、この危険は増幅される。 コードを渡して要求を尋ねれば、必ずそれらしい要求が返ってくる。 形式は整い、文体は自信に満ち、検証の手がかりだけがない。 判断の基準はここでも同じである。 **その要求を「正しい」と検証できるのは発注者やユーザーであり、コードではない。** コードは要求の検証者になれない。検証者のいない文書は、合意ではなく推測の固定である。 ## 実務的な着地 引き継いだシステムに文書がないとき、次の方針をとる。 - **復元するのは仕様まで**。コストに見合い、テストコードという裏取りの手段もある。設計はコード自体が最新の記述なので、改めて書くのは変更の理由に限る - **要件は列挙にとどめる**。「何ができるか」は書けるが、「何ができるべきだったか」は書けない。実装されなかった要件は観測できないため、一覧は常に不完全である - **要求は人に聞く**。関係者が残っていれば聞き、いなければ「不明」と書く。**空欄のほうが、推測で埋めた欄より価値がある**。空欄は問いとして残るが、埋まった欄は問われなくなる - **推測を書くなら出所を明記する**。「観測された振る舞いからの仮説」と書き、検証者を人に戻す。仮説と合意事項を同じ体裁で並べない ## まとめ - コードに残るのは判断の**結果**であり、判断そのものではない - 復元可能性は層に依存する。設計と仕様は高く、要件は部分的、要求は原理的に不能 - 上位から下位への写像は多対一であり、逆写像は存在しない - 意図と事故はコード上で同じ形をしており、読み手は理由があったと仮定しやすい - 逆算した要求の文書化は、越境を正式な決定として固定する - 迷ったら問う。**この判断は誰が検証するのか**。コードは検証者ではない 文書は工程の副産物ではなく、判断が行われた証拠である。 コードしか残っていない状況とは、判断の結果だけが残り、証拠が失われた状況にほかならない。 ======================================================================== # なぜ工程として必要なのか カテゴリ: 概念 概要: 層は判断の分離、工程はその並べ方。なぜ分けるのか、なぜ順序があるのか URL: https://docs-handbook-9dg.pages.dev/raw/concepts/why-process.md ======================================================================== # なぜ工程として必要なのか 要求→要件→仕様→設計という分け方は、一見「手続きのための手続き」に見える。 小さな開発なら、頭の中で全部済ませてコードを書き始めても動くものは作れる。 それでもこの分け方が必要な理由を、「層の必要性」と「工程(順序)の必要性」に分けて説明する。 この2つは別の話であり、混ぜると「アジャイルなら不要」のような誤った結論に落ちる。 ## 層の必要性: 翻訳は一足飛びにできない 根っこにあるのは、**ビジネスの言葉とコードの言葉は距離が遠すぎて、一度に翻訳できない**という問題である。 「調査時間を半分にしたい」という要求から、`match_phrase` クエリという実装までの間には、 無数の判断が挟まっている。検索対象は何か、何件表示するか、0件のときどうするか、 どの検索エンジンを使うか。一気に飛ぶと、これらの判断が誰にも見えない形でコードに埋まる。 各層は、この翻訳の**中間チェックポイント**である。重要なのは、層ごとに「正しい」と言える人が違うこと: | 層 | 「正しい」と検証できる人 | |---|---| | 要求 | 発注者・ユーザー(それが欲しかったものか) | | 要件 | 発注者と開発者の双方(それで要求が満たせるか) | | 仕様 | テスター・レビュアー(振る舞いが決めたとおりか) | | 設計 | エンジニア(仕様を満たす作りか) | 層を省くと、**誰も検証できない飛躍**がどこかに埋まる。 「なんとなく動くが、これで良いのか誰にも判断できない」状態は、たいていここから生まれる。 V字モデルが各層にテストレベルを対応させているのは、この検証可能性の裏返しである。 もう1つの役割は**変更時の影響範囲の特定**にある。 「表示件数を30件にしたい」は仕様の変更で、要求は変わらない。 「調査時間の目標を10分にしたい」は要求の変更で、要件から下が全部揺れる。 層が分かれていれば、変更がどの高さの話かを最初に見極められる。 分かれていなければ、すべての変更が「コードをどう直すか」の話に潰れてしまい、 文書と実態が静かにズレていく。 ## 工程の必要性: 順序には理由があるが、状況依存である 層の分離が普遍的な必要性なのに対して、それを**時間順に並べる(工程にする)**理由はもっと現実的な事情による。 ### 手戻りコストの非対称性 要求の間違いは、下流に行くほど修正コストが膨らむ。 仕様まで降りてから「そもそも解くべき課題が違った」と分かれば、仕様も設計も書き直しになる。 運用まで行ってから分かれば、桁が変わる。 抽象度の高い判断ほど先に固めて検証したい、というのが工程順の第一の理由である。 ### 合意と責任の区切り 受託開発では、「要件定義完了で合意し、次へ進む」という工程の区切りが、 そのまま契約・責任・支払いの区切りになる。 どこまでが合意済みで、どこからが未確定かを両者が共有するために、工程は区切りとして機能する。 第三者(別ベンダー、後任、監査)が入る場合も、工程ごとの成果物が引き継ぎの単位になる。 ### ただし、順序は絶対ではない 手戻りコストが小さい環境では、工程順を崩せる。 自社プロダクトでプロトタイプを先に作り、触ってもらってから要求が明確になる、という逆流は健全に起こる。 アジャイル開発は工程を反復の中に畳み込んでいるのであって、判断を省いているわけではない。 見誤ってはいけないのは、**崩れているのは順序であって、判断ではない**という点である。 プロトタイプ先行でも「これは誰の何を解決するのか(要求)」 「この振る舞いで確定か(仕様)」という判断は必ずどこかで行われている。 行われていなければ、それは速い開発ではなく、検証されていない開発である。 ## まとめ: 層は判断の分離、工程はその並べ方の一形態 - **層**は、遠すぎる翻訳を検証可能な単位に区切るためのもの。開発形態によらず必要 - **工程**は、その判断を手戻りコストと合意の都合で時間順に並べたもの。状況に応じて崩せる - 何を省けるか迷ったら、「この判断は誰が検証するのか」を問う。検証者が消える省略は、していない 本ハンドブックが文書の書き方を層ごとに整理しているのは、この判断の分離を文書の形で残すためである。 文書は工程の副産物ではなく、判断が行われた証拠であり、次の変更のときに「どの層の話か」を 見極めるための基準点になる。