要件定義を「思想」と「仕様」に分ける — 個人開発で手戻りを減らした運用

結論 — 「思想」を先に固定すれば、仕様は気軽に捨てられる

要件定義を 1 枚の文書に全部詰め込むのをやめました。「思想（なぜ・どうあるべきか）」と「仕様（何を・どう作るか）」を 2 層に分けて書くと、議論の衝突も実装の手戻りも目に見えて減ります。きっかけは Zenn で読んだ要件定義の記事で、設計判断の根拠を思想側に逃がし、仕様を差し替え可能なまま保つ、という整理が腹落ちしたからです。

この記事は、その考え方を個人開発の自分の運用に当てはめてみた記録です。ちなみに AetherEchoes の記事は AI が下書きを書き、私が一次情報に当たって確認・編集してから公開しています。この記事もそうで、元記事の主張のうち私の運用に翻訳できる部分だけを抜き出しました。

思想と仕様は、変わらないものと変わっていいものの違い

ざっくり言えば、思想は「変わらない思考の基盤」、仕様は「フェーズごとに更新される具体物」です。元記事はこれを幹と枝葉に喩えていました。

思想に入るのは、定義・責務・対象範囲・基本方針・データモデルの方針・命名といった、後から「なぜそうなっているのか」を聞かれて答える側の情報です。仕様に入るのは、画面仕様・状態遷移・受入条件のような、作るために必要な具体です。前者は半年経っても効きますが、後者は実装が決まった瞬間から古び始めます。

この線引きが効くのは、捨てる判断が軽くなるからです。仕様は枝葉なので、間違っていたら丸ごと捨てて書き直せばいい。でも幹である思想を捨てると、議論が振り出しに戻る。だから「これは捨てていい紙か、捨てたら全部やり直しになる紙か」を最初に分けておくわけです。

なぜ混ぜると詰まるのか — レビューとスコープクリープ

思想と仕様を 1 枚に混ぜると、レビューが重くなり、スコープがじわじわ膨らみます。これは元記事の指摘でもあり、私の実感とも一致します。

混在した文書をレビューしようとすると、読む側は「この受入条件は本当に必要か」を判断するために、毎回その背景の思想まで遡らされます。背景が同じ紙に書いてあればまだましですが、たいていは暗黙知になっていて、結局は書いた本人しかレビューできない文書が出来上がる。私も過去に、自分にしか直せない仕様書を量産して、レビュー待ちの行列を自分の前に作ったことがあります。レビューできる人間が 1 人しかいない文書は、その人がボトルネックになるだけです。

スコープクリープ（当初の範囲がなし崩しに膨らむこと）も同じ構図です。「ついでにこれも」という要望が来たとき、思想側に「この機能の責務はここまで」と一行書いてあるだけで、断る根拠ができる。元記事では一時保存機能を例に、対象外と判断した根拠を残すことで“ついで要望”に根拠を持って応える、という工夫が挙がっていました。根拠の置き場所が決まっているだけで、断る会話が一気に楽になります。

「操作」ではなく「状態」から設計する

仕様を書くときは、操作から考えず、先に「あるべき状態」を定義してから操作を設計します。これは非ハッピーパス（エラー時・0 件時・権限なし時などの、正常にうまくいく経路ではない分岐）を取りこぼさないための順番です。

操作から設計すると、人はどうしてもうまくいく道、いわゆるハッピーパスから書き始めます。ボタンを押す、保存される、完了画面が出る。ここまでは誰でも書けます。問題は、保存に失敗したとき・一覧が 0 件のとき・同時に二人が触ったとき、という分岐で、これらは「完了状態とはどういう状態か」を先に決めておかないと、設計の途中で初めて存在に気付くことになります。

先に状態を列挙しておくと、操作はその状態に至る経路として後から埋められます。私はこの順番に変えてから、「リリース直前に 0 件表示を作り忘れていた」系の事故が減りました。派手な工夫ではありませんが、効く順番です。

私の運用 — 思想は 1 枚、仕様は使い捨て

具体的には、機能ごとに思想を書いた短い 1 枚を残し、仕様は実装が終わったら気軽に捨てる運用にしています。AetherEchoes の auto-publish を 6 つのスキルに分け直したときが、ちょうどこの考え方を入れた最初でした。

分割前は、1 本のスキルに「どういう記事を出したいか（思想）」と「どの endpoint をどう叩くか（仕様）」がべったり混ざっていて、少し endpoint を変えるたびに思想の記述まで読み直す羽目になっていました。2026 年 5 月に pick / write / verify / video へ責務を分けたとき、各スキルの冒頭に「このスキルの責務はここまで」という思想の一段落を置き、手順の詳細は共有仕様の方へ逃がしました。SKILL.md は 220 行で切られるという仕様上の制約もあったので、思想を冒頭に・捨ててよい手順を後ろに、という配置は実利的にも噛み合いました。

選定の根拠を未来の自分に渡す、という意味では、以前 ツール選定ジャーナルについて書いたとき の発想とも地続きです。「どれを選んだか」だけでなく「なぜ」を残すと、半年後の自分が同じ議論を二度しなくて済む。思想を分けて書くのは、結局その「なぜ」の置き場所を最初に決めておく作業に他なりません。

余談ですが、この「幹と枝葉」という喩えは、コードのリファクタリングでも全く同じことを思います。インターフェース（幹）が安定していれば、実装（枝葉）は何度でも差し替えられる。要件定義もコードも、結局は「どこを固定して、どこを動かしてよいか」を宣言する作業なのかもしれません。もっとも、私の最初の要件定義書は幹と枝葉が絡み合って、自分でもどこから切っていいか分からない蔓みたいになっていましたが。

まとめ — 線を引く場所を最初に決める

思想と仕様を分けるのは、難しい方法論ではなく、「どの紙を捨てていいか」を最初に宣言するだけの習慣です。思想は変わらない幹として残し、仕様は枝葉として気軽に差し替える。状態から設計して非ハッピーパスを先に潰す。この 3 つだけでも、レビューの重さとスコープの膨張はかなり軽くなります。

私はこの線引きを auto-publish の再設計で一度やってから、新しい機能を足すときの心理的な抵抗が減りました。捨てていい紙と、捨ててはいけない紙が分かれているだけで、書くのが軽くなる。要件定義が重いと感じている人は、まず 1 機能だけ、思想の 1 枚を切り出してみるのをおすすめします。