ソフトウェア設計
AgentOSは「AI」よりもワークフローエンジンに近い ワークフローエンジンとは何をしているのか 開発は直線ではなくグラフとして扱われる イベント駆動で動作している LLMの役割はワーカーに近い なぜこの構造が必要なのか 実際の動作の流れ 注意点：すべてが…
「仕様を書いたら実装が始まる」は比喩ではない 仕様から直接コードは作られていない 実際の内部フロー 仕様解析：最初に行われる処理 タスク生成：実際に何が作られるのか タスク依存関係の構築 実装生成のタイミング 「仕様からタスク生成」が意味するもの…
従来の開発ツールはどこを支援していたか LLMが変えたもの なぜ「SDD」になるのか SDDツールが担う役割 実際の開発で起きている変化 リスクと注意点 今後どうなるか ここ1〜2年で、SDD（仕様駆動開発）関連ツールが急に増えました。 Agent系ツール、仕様管理…
仕様がドキュメントであると何が起きるか Spec as Codeの本質 ― 同期の強制 なぜ文章のままでは難しいのか よくある誤解 実際に起きる変化 リスクと注意点 どう考えるべきか Specification as Code（Spec as Code）という言葉は、最近SDD（仕様駆動開発）の…
SDDツールを分類する3つの層 実行層 ― AgentOS系ツール 管理層 ― Speckit系ツール 基盤層 ― Backstage系ツール なぜ混乱が起きるのか よくある失敗パターン リスクと注意点 どう考えるべきか SDD（仕様駆動開発）の話題になると、最近は必ず「ツール」の名前…
なぜ組織構造が重要なのか SDDが機能するチームの基本構造 よくある失敗パターン ― 仕様責任者が存在しない 役割分担の具体例 仕様責任者（Specification Owner） 実装責任者（Implementation Owner） 検証責任者（Validation Owner） SDDがうまく回るコミュ…
形式化とは何を指しているのか なぜ開発が遅くなるのか ― 決定待ちが増える もう一つの遅延要因 ― 承認プロセス 仕様の完全性と探索のトレードオフ 現場で起きる具体的な問題 リスクと注意点 どうすれば速度を落とさないか SDD（仕様駆動開発）を導入したの…
SDDは1つではない ― 3つの「仕様」の正体 設計崩壊パターン1：振る舞い仕様と業務仕様の衝突 設計崩壊パターン2：業務仕様と構造仕様の衝突 設計崩壊パターン3：振る舞い仕様と構造仕様の衝突 なぜ混在が起きるのか 危険な兆候 注意点とリスク ではどう整理…
SDDで起きる最も危険な状態 ― 「仕様が読まれない」 アンチパターン1：仕様が設計ではなく説明書になる アンチパターン2：仕様が更新されない（凍結仕様） アンチパターン3：テストが仕様の代替になる アンチパターン4：仕様が巨大化する（過剰仕様） アンチ…
SDD(仕様駆動開発)はTDDを置き換えるのか TDDが解決しようとしている問題 SDDが解決しようとしている問題 両者の関係を整理する なぜTDDだけでは不足するのか SDDを導入するとTDDは不要になるのか よくある誤解：SDDはテストを増やす手法 導入時の注意点 現…
SDD(仕様駆動開発)における回帰テスト自動化とは何か なぜ回帰テストが必要になるのか 仕様テストはそのまま回帰テストになる 手動回帰テストが増える理由 自動化の対象を間違えると失敗する 回帰テストが機能する条件 CIと回帰テストの関係 よくある誤解：…
SDD(仕様駆動開発)でE2Eテストが増えすぎるのはなぜ起きるのか E2Eテストが増殖するメカニズム SDDにおけるテストの本当の粒度 なぜE2Eに頼ってしまうのか 回避するための設計：アプリケーションサービスの分離 E2Eテストの正しい役割 目安となるテスト比率 …
SDD(仕様駆動開発)ではなぜモックが重要になるのか なぜ実システム依存だと仕様が書けないのか モックが担う役割 モックを使うと設計が変わる モックを誤用すると起きる問題 モックが必要な境界とは モックが増えすぎる危険 モックがないと起きる現場の問題 …
SDD(仕様駆動開発)ではなぜテストコードが仕様書になるのか 従来の仕様書が信用されない理由 テストコードは「動く仕様書」になる なぜコメントではなくテストなのか SDDにおける設計の変化 SDDを導入すると何が変わるか（実際の現場） 注意点：テストが仕様…
SDD(仕様駆動開発)ではなぜUI仕様を最初に書いてはいけないのか UIは仕様ではなく実装の一部 なぜUIから始めると手戻りが起きるのか UI中心開発で発生する典型的な不具合 「ボタンはあるが動作が決まっていない」 「例外処理が後付けになる」 「APIと画面の…
SDD(仕様駆動開発)における受け入れ基準の書き方 受け入れ基準と仕様書の違い 良い受け入れ基準の条件 観測可能である 条件が明確である 判断が二値である Given/When/Then形式の技術 受け入れ基準が弱いと何が起きるか よくある失敗パターン UIを受け入れ基…
SDD(仕様駆動開発)とアジャイル開発は本当に対立するのか なぜ対立して見えるのか 「仕様書＝固定された契約書」という誤解 SDD(仕様駆動開発)の本質 SDDが行うこと アジャイル開発の本質 SDDとアジャイルが補完関係になる理由 実際の開発で起きる変化 SDDを…
SDDでは仕様と設計は同じものではない 仕様とは何を指すのか 設計とは何を指すのか なぜこの分離が必要なのか 実際の開発で起きる変化 設計変更が安全になる理由 よくある失敗 ― 設計を仕様に入れてしまう 仕様の粒度はどこまで書くべきか 注意点 ― 仕様不足…
SDDにおけるSpecificationは「仕様書」ではない なぜドキュメントでは不十分なのか Specificationはインターフェース契約になる テストとの違い 実際の現場で起きる変化 なぜ契約という考え方が重要なのか 注意点 ― Specificationを書きすぎる問題 変更と破…
REST APIは「通信方式」ではなく仕様の表現です リソース設計はドメイン理解の鏡 状態遷移とHTTPメソッド ステータスコードも仕様の一部 よくある誤解：RESTに合わせて仕様を変える REST APIとドメインモデルの対応 注意点：HTTPに依存しすぎない テスト観点…
実装より先にAPI設計をすると設計が安定します APIは画面のためのものではない API設計で見える仕様の不足 ドメインモデルはAPIから逆算できる よくある失敗：テーブル設計から始める HTTPメソッドと仕様の関係 注意点：APIを外部公開前提にしすぎる テスト…
アプリケーションサービスは「ロジックを書く場所」ではありません なぜこの層が必要になるのか アプリケーションサービスの責務 Controllerとの違い ドメインサービスとの違い よくある失敗：バリデーションを書く 外部システム連携はどこに置くか 注意点：…
サービスクラスが太るのは設計が下手だからではありません 典型的な肥大化の例 なぜサービスにロジックが集まるのか ドメインモデルへ移す アプリケーションサービスの本来の役割 それでもサービスが太るケース よくある誤解：サービスを分割すれば解決 見分…
クリーンアーキテクチャは「構造の話」、SDDは「起点の話」です なぜ依存関係が問題になるのか SDDが要求する構造 依存関係の向きが重要な理由 具体例：Repositoryの配置 よくある誤解：レイヤーを分ければクリーンになる SDDとトランザクション境界 注意点…
リポジトリパターンは「設計パターン」から始めると失敗します なぜ直接DBアクセスでは仕様を守れないのか ドメインモデルを通すと何が変わるか ではなぜRepositoryが必要になるのか Repositoryの本質は「コレクションのように扱うこと」 SDDとアプリケーシ…
SDDとDDDは別物に見えて、実は同じ場所を見ています ユビキタス言語とは命名規則ではない SDDで言葉が固定される瞬間 コードに現れるユビキタス言語 なぜSDDとDDDの相性が良いのか テストコードが壊れる理由 よくある失敗：英語にすればDDDになる 実務での進…
ドメインモデルは「クラス設計」からは生まれません SDD（仕様駆動開発）とは何を駆動するのか ドメインモデルの出発点は「状態遷移」 仕様から読み取るべき3つの要素 具体例：予約システムからドメインモデルを抽出する 値オブジェクトが生まれる瞬間 よく…
APIとしてのLLM：AIをソフトウェアに組み込む考え方 なぜAPIとして扱う必要があるのか LLMが得意な役割 LLMが苦手な役割 実際の呼び出し構造 AIアプリ設計の基本パターン 1. 前処理（Pre-processing） 2. LLM呼び出し 3. 後処理（Post-processing） よくある…
AIアプリ設計：LLM時代のソフトウェア設計原則 従来の設計が通用しない理由 AIアプリの基本構造 1. 決定層（Deterministic Layer） 2. AI層（Generative Layer） 3. 検証層（Validation Layer） プロンプトにロジックを書かない 出力は必ず構造化する 重要な…
APIとしてのLLM：AIをソフトウェアに組み込む考え方 なぜAPIとして扱う必要があるのか LLMが得意な役割 LLMが苦手な役割 実際の呼び出し構造 AIアプリ設計の基本パターン 1. 前処理（Pre-processing） 2. LLM呼び出し 3. 後処理（Post-processing） よくある…
