最近、社内でAIエージェントを開発フローに組み込む取り組みを進めていて、ちょっと逆説的なことに気づいた。
AIが実装をどんどん肩代わりしてくれるほど、私の仕事は楽になるどころか、ある種のプレッシャーが増している。実装はAIに任せるとして、「じゃあ何を作るか」「なぜそれを作るのか」は誰が決めるのか。そこが曖昧なまま自動化を進めると、間違ったものを以前より速く作るだけになってしまう。
そんなことを考えているうちに、システム開発の上流工程について整理を書き留めておきたくなった。
上流工程が「難しい」と分かったのは、失敗してからだった
私が上流工程の本質的な難しさを実感したのは、10年近く前にアサインされたEC系のシステムリニューアル案件でのことだ。
クライアントの要望は「今より使いやすいシステムにしたい」という一言だった。それを真に受けて、ヒアリングをほとんどしないまま設計を始めてしまった。プロトタイプを見せたタイミングで、関係者全員から「そういう意味じゃなかった」が返ってきた。
システム部門が求めていたのは管理画面の操作性で、営業部門は顧客向けUIの改善を期待していて、経営陣はデータ分析ダッシュボードをイメージしていた。「使いやすい」は三者三様だった。
# 当時のヒアリング結果メモ（実態は曖昧な言葉の羅列だった）
requirements:
- "使いやすいシステム"
- "今より速く動くもの"
- "データがちゃんと見えるように"
# これ全部、解釈が関係者ごとに違っていたこの経験以降、「なぜそれが必要か」と「誰にとって何が問題か」を引き出すことが、設計の技術よりも先にあると意識するようになった。上流工程でズレが生じると、後工程のどんな技術的な努力も埋め合わせられない。
AIが得意なことと、苦手なことの境界線
今のAIは「与えられた仕様通りのものを作る」ことが非常に得意だ。コードを書く、テストを書く、ドキュメントを生成する。こうした作業は、正直なところ人間のジュニアエンジニアより速くて正確なことも多い。
しかし「そもそも何が問題か」という問いには、AIはまともに答えられない。それは当然で、AIが答えるためには、ビジネスの文脈・組織の事情・担当者の経験・過去の失敗という暗黙知が必要だ。それらは大抵、どこにも文書化されていない。
# AIに丸投げすると失敗するケースの典型（実体験から）
task_description = """
このシステムをリニューアルしてください。
要件: ユーザーが満足するもの
"""
# AIは「ユーザーが満足するもの」を最も合理的な解釈で実装する
# → そのAIの解釈が、クライアントの意図と一致している保証はゼロ
# → 速く、丁寧に、間違ったものが出来上がる上流工程は「要件を文書に落とす作業」ではなく、「ステークホルダーの頭の中にある曖昧な意図を、構造化して合意を形成するプロセス」だ。これはAIを補助に使えても、AIが主体になれる仕事ではないと思っている。
ここは好みが分かれるところですが、私は「要件定義はどこまでいっても人間の仕事」という立場をとっている。対話の中でしか引き出せない情報があるし、言語化できていない期待値を言語化すること自体が価値の提供だからだ。
意思決定の「なぜ」を残すことが、後工程の品質を決める
もう一つ気づいたことがある。要件定義の本質的な価値は「何を作るか」を決めることだけではなく、「なぜそう決めたか」を記録することにある。
プロジェクトが長期化すると、当初の判断理由を誰も覚えていなくなる。担当者が変わる。「なぜこの仕様になっているのか」を説明できる人がいなくなる。後からAIがコードを修正しようとしたとき、「これを変えていいのか」の判断基準がなくなる。
## 意思決定ログ（自分が今使っているテンプレート）
### 決定事項: [何を決めたか]
- 日付: YYYY-MM-DD
- 背景: なぜこの決定が必要だったか
- 検討した選択肢: A案 / B案 / C案
- 採用した選択肢: A案
- 採用理由: [具体的な根拠]
- 捨てた選択肢の理由: B・Cを採用しなかった理由
- 承認者: [ステークホルダー名]
- 再検討トリガー: [この決定を覆す可能性のある条件]このログをREADMEやWikiに残しておくと、AIに渡す文脈として機能する。「この設計にはこういう理由がある」という背景を持ったうえで、AIは変更の影響を考えながらコードを修正できる。背景がない状態では、AIは現状のコードからしか判断できない。設計の意図は伝わらない。
ドキュメントにはこう書いてあるけど、実際に運用してみると「決定の文脈」を残すことの価値は、チームが大きくなるほど、AIが介在するほど、指数的に上がっていくと感じている。
ドキュメントのつながりを設計する：トレーサビリティと構造管理
「決定の理由を残す」ことの延長として、最近意識するようになったのが「ドキュメント同士のつながり」だ。
要件定義書、基本設計書、詳細設計書、テスト仕様書。プロジェクトが進むにつれてドキュメントは増えていくが、それらが孤立した状態になっていることが多い。要件定義書を読んでも、どの設計判断がその要件に対応しているのか分からない。設計書を変更したとき、どのテストケースに影響するか把握できない。これを「トレーサビリティの断絶」と呼ぶ。
炎上プロジェクトの多くは、「ドキュメントはある、でもつながっていない」状態から悪化していった。今思えば、その状態はAI活用においても致命的だ。
# トレーサビリティを意識した要件管理の例
requirements:
- id: REQ-001
title: "管理者がユーザーアカウントを停止できる"
derivedFrom: null # ビジネス要件の最上位
implementedIn:
- "design/user-management.md#account-suspension"
- "src/services/UserService.ts"
testedBy:
- "TEST-012"
decisionRef:
- "decisions/003-admin-role-scope.md" # なぜこう決めたかこういう構造があると、「REQ-001が変わった場合、どの設計書・コード・テストが影響を受けるか」が一目で分かる。AIにこの構造を渡せば、影響範囲を踏まえた上でコードを修正してもらえる。ない状態では、AIは現状のファイルから推測するしかなく、依存関係の見落としが起きやすい。
一方で、ドキュメントが増えるほど「ドキュメント自体の構造管理」も重要になる。どんなに内容が充実していても、探せなければ意味がない。そしてAIにとって探せないドキュメントは、存在しないも同然だ。
# ドキュメント体系の例（現在試行中の構造）
docs/
├── 00_overview.md # プロジェクト概要・参照マップ
├── requirements/ # 要件定義
│ ├── business/ # ビジネス要件（経営・業務レイヤー）
│ └── system/ # システム要件（機能・非機能）
├── design/ # 設計書
│ ├── architecture.md # システム全体像
│ └── api/ # API設計（エンドポイント別）
└── decisions/ # 意思決定ログ（ADR形式）
├── 001-db-selection.md
└── 002-auth-approach.mdドキュメントに命名規則と階層を持たせることで、「このドキュメントを変更したら、どの下位ドキュメントに影響が伝播するか」が構造から自然に分かるようになる。ここが整っていないと、ドキュメントが「作りっぱなし」になり、プロジェクトが進むほど参照されなくなっていく。
ぶっちゃけ、規模が小さいうちはやりすぎに見えるかもしれない。でもAIが開発フローに介在するなら話が違う。ドキュメントは「人間が読むもの」という認識から、「AIが参照するコンテキスト」としての機能を意識した設計に移行する必要がある。上流工程のドキュメント体系は、開発チームの知的資産であると同時に、AIに渡すプロンプトの品質を決めるインフラでもある、というのが今の自分の考えだ。
上流工程の価値は、AIが進化するほど高くなる
ぶっちゃけ、上流工程を丁寧にやることの重要性は、以前よりずっと増していると感じている。
実装がAIにシフトするほど、人間が担う価値のある仕事は「何を作るか」の意思決定に集約されていく。技術的な実装力は相対的に差別化要因になりにくくなっていく一方で、「ビジネス要件を正確に引き出し、構造化して、関係者の合意を形成する力」はまだしばらく人間の専売特許だと思っている。
AIへの指示の質は、要件の質に直結する。曖昧なタスクをAIに渡すと、曖昧な成果物が返ってくる。逆に、背景・制約・成功条件が明確なタスクを渡せば、AIはかなりの精度で動いてくれる。
// AIに渡すタスクの品質は上流工程の質で決まる（改善の余地あり：実際にはもっと複雑なネゴシエーションが必要）
type WellDefinedTask = {
what: string; // 何を作るか（要件）
why: string; // なぜ作るか（背景・目的）
constraints: string[]; // 制約（変えてはいけないこと）
successCriteria: string[]; // 完了条件（何ができたら終わりか）
decisionContext: string; // 関連する意思決定の背景
};
// whatだけのタスクとfull contextのタスクでは、AIの成果物の質に天と地の差がある今思えば、自分がこの10年で最も価値を発揮できたのは、コーディングのスキルよりも「ステークホルダーへの問いかけ方」や「曖昧な要求を構造化する力」だったかもしれない。当時はそんなに意識していなかったけれど。
上流工程はエンジニアリングではないという意見も聞く。でも私は逆に、AIが実装を担う時代において、「何を作るかを問い続ける能力」こそが、エンジニアとして持ち続けるべき最も大切なスキルになりつつあると思っている。
振り返って
AI活用を進めるほど、「上流工程を丁寧にやろう」という気持ちが強くなっている。自動化できるから雑でいいではなく、自動化するからこそ正確に定義しなければならない。曖昧さをAIに渡すと、AIはその曖昧さを忠実に実行してくれる。それが問題だ。
今後は「AIに渡せる粒度のタスクに分解する力」「意思決定の理由を残す習慣」が、PMやテックリードとして問われるスキルになっていくと感じています。まだ試行錯誤中ですが、上流工程の価値を組織として意識的に高めていきたいというのが、今の正直なところです。