ガイドライン駆動開発 - AIエージェントと並走する新しい開発手法
AIコーディングエージェントとの協働を前提とした開発手法。仕様書を「厳格なルール」ではなく「進むべき方向を示すガイドライン」として扱い、AIの力で柔軟に変更を反映する。
はじめに
「仕様書通りに作る」 この言葉に縛られて、柔軟な開発ができなくなった経験はありませんか？
一方で、「とりあえず作ってみよう」と始めて、後から大きな手戻りが発生したことは？
今回は、RedmineCLIの開発を通じて実践した「ガイドライン駆動開発」を紹介します。 AIコーディングエージェントとの協働を前提とした開発手法です。
仕様書を「地図」として扱い、AIエージェントの力を借りて、実装からのフィードバックを素早く反映していく。 これが、AIコーディング時代の開発スタイルです。
従来の開発手法の限界
ウォーターフォールの問題
完璧な仕様書を作ろうとすると、実装前に膨大な時間がかかります。 しかも、実際に作ってみないとわからないことが多い。
RedmineCLIの開発でも、最初に要求定義書を作成しました。 「担当者でフィルタリングする機能」について、こう書いていました。
WHEN `--assignee <user>` オプションを指定
THEN 特定のユーザーのチケットが表示されるこの仕様をAIエージェントに渡して実装させたところ、ユーザーIDを指定する方式で実装されました。 技術的には正しい実装です。 動作も確認できました。
しかし、実際に使ってみると問題が明らかになりました。 Redmineの通常の利用では、ユーザーIDを意識することはありません。 誰がID 42なのか知らないため、当てずっぽうに番号を入力するしかない。 これでは使い物になりません。
仕様書を書いていても、明確でなければ失敗します。
アジャイルの落とし穴
仕様書なしで「とりあえず作ってみよう」と始めるアプローチにも問題があります。
全体像が見えないまま開発を進めると、機能同士の整合性が取れなくなります。 後から「この機能とあの機能を連携させたい」と思っても、設計思想が違うため統合が困難に。 結果として、大規模なリファクタリングが必要になることもあります。
AIエージェントとの協働の難しさ
さらに、AIエージェントを使った開発にも課題があります。
曖昧な指示では、AIが生成するコードは思わぬ方向に進んでしまいます。 「ユーザーでフィルタリングする機能を作って」という指示だけでは、AIはIDベースの実装を選ぶかもしれません。 技術的には正しくても、使いやすさの観点では不適切な実装になってしまうのです。
このため、AIとの協働では常に人間が監督し、方向修正を繰り返す必要があります。 まるで見習いプログラマーに付きっきりで指導するような負担が発生してしまいます。
ガイドライン駆動開発とは
「ガイドライン駆動開発」という言葉は、ここでの造語です。
この手法は、個人開発や小規模チームでの開発に特に適しています。 自分一人で仕様を決定・変更できる環境で、AIエージェントと協働しながら柔軟に開発を進めたい場合に威力を発揮します。
基本的な考え方
仕様書を作成しますが、それを「絶対的なルール」ではなく「進むべき方向を示すガイドライン」として扱います。
重要なのは、AIコーディングエージェントとの協働を前提としていること。 仕様書の変更、コードの修正、テストの更新。 これらすべてをAIエージェントが数分で完了してくれるからこそ、柔軟な変更が可能になります。
登山に例えると
- ウォーターフォール：決められたルートを外れてはいけない
- アジャイル：地図なしで、とりあえず登ってみる
- ガイドライン駆動：地図を持って登るが、AIガイドと相談しながらルートを変更する
RedmineCLIでの実践例
最初に作成した要求定義書には、以下のように書いていました。
担当者フィルタ：--assignee <user_id>
プロジェクトフィルタ：--project <project_id>
ステータスフィルタ：--status <status_id>IDベースの実装は技術的にシンプルです。 実際、最初のバージョンはIDのみ対応でした。
# 使いづらい例
redmine issue list --assignee 42 --project 15 --status 2しかし、実際に使ってみると問題が明らかになりました。 誰がID 42なのか、どのプロジェクトがID 15なのか、覚えていられません。
AIエージェントとの協働でフィードバックを反映
ここでAIコーディングエージェントの出番です。
「名前でもフィルタリングできるように仕様を更新して」
この指示で、AIエージェントはまず要求定義書と設計書を更新してくれます。
その内容を確認し、満足できたら「TDDで実装して」と依頼します。 AIエージェントは、テストケースを先に作成してから実装コードを書いてくれます。
このプロセス全体が数分で完了します。
担当者フィルタ：--assignee <user_id|user_name|@me>
プロジェクトフィルタ：--project <project_id|project_identifier|project_name>
ステータスフィルタ：--status <status_id|status_name>そして、以下のような使いやすいインターフェースになりました。
# 使いやすい例
redmine issue list --assignee @me --project "開発" --status "進行中"技術的には小さな変更ですが、UXへの影響は劇的でした。
自分で使ってみると、その効果は一目瞭然です。 IDを調べる手間がなくなり、直感的にコマンドを入力できるようになりました。
ウォーターフォールとアジャイルの良いとこ取り
ウォーターフォール的要素
全体を見通した仕様書を最初に作成
RedmineCLIでは、開発開始前に以下の文書を作成しました（この文書体系はAWSのKiroというIDEのアプローチを参考にしています）。
- プロダクト概要（PRODUCT.md）
- 要求定義書（REQUIREMENTS.md）
- 技術仕様書（TECH.md）
- 設計書（DESIGN.md）
- ディレクトリ構造（STRUCTURE.md）
- TODOリスト（TODO.md）
この順序には意味があります。 上位の文書ほど抽象度が高く、プロジェクトの根幹に関わる重要な内容を扱います。 上位の文書に変更を加えると、その影響は下位の文書まで波及していきます。
これにより、全体のアーキテクチャと方向性が明確になりました。
アジャイル的要素
要件を1つずつ実装し、動くものを少しずつ作る
MVPとして最初に実装したのは、3つの最低限の機能になります。
auth login- 認証issue list- 一覧表示issue view- 詳細表示
この時点で、基本的な製品としての価値を確認できました。 良かった。
なぜAIエージェントとの協働が前提なのか
従来の開発では不可能だった柔軟性
従来の開発では、仕様変更のコストが高すぎました。
- 要求定義書の更新
- 設計書の修正
- コードの変更
- テストの更新
これらすべてに多大な時間と労力が必要でした。 小さな変更でも、影響範囲が広く、修正作業が膨大になってしまいます。
しかし、AIエージェントとの協働では、状況が一変します。 人間は「何を変えるか」を指示するだけで、AIが「どう変えるか」を実行してくれます。 すべての変更作業が驚くほど短時間で完了するのです。
この劇的なコスト削減により、柔軟な開発が可能になったのです。
仕様書の新しい役割
AIコーディングエージェントを使う場合、仕様書は「人間とAIの共通言語」になります。
## 要求
担当者でフィルタリングできるようにする
## 詳細
- IDだけでなく名前でも指定可能
- @meで現在のユーザーを指定
- 部分一致で検索このような仕様があれば、AIは適切な実装を生成できます。 逆に、仕様が曖昧だと、AIの出力も曖昧になります。
頻繁な更新が可能に
従来、仕様書の更新は大きな負担でした。 しかし、AIエージェントを使えば
「issue listコマンドの仕様を、名前でのフィルタリングに対応するよう更新して」数分で、要求定義書、設計書、実装、テストがすべて更新されます。
実装のポイント
最初の仕様書は「完璧」を目指さない
80%の精度で十分です。 重要なのは、全体像を描くこと。 AIエージェントと一緒に改善していけばいいのです。
実装からのフィードバックを歓迎する
「仕様と違う」ではなく、「より良い方法を見つけた」と考えます。 AIエージェントにその変更を伝えれば、すぐに反映されます。
変更履歴を残す
仕様書の変更履歴は、プロジェクトの学習記録になります。 なぜその決定をしたのか、後から振り返れます。
ドキュメントとコードを同期させる
AIエージェントを活用すれば、この作業も効率化できます。 「コードの変更を仕様書に反映して」の一言で完了します。 とはいえ、仕様書の確認は必要です。 git diffで確認するので、そこまで大変ではありません。
既存手法との比較
ウォータースクラムフォールとの違い
ウォータースクラムフォールは、最初に仕様を固めて、実装はアジャイルで行います。 しかし、仕様の変更は基本的に認められません。
ガイドライン駆動開発では、仕様の変更を前提としています。
Wagile（ウォジャイル）
Wagileは、ウォーターフォールとアジャイルの悪いところを組み合わせた手法として批判されます。 形式的にはアジャイルを採用しながら、実態は変更を許さない硬直的な開発。
ガイドライン駆動開発は、柔軟性を持ちます。
朝令暮改をポジティブに
「朝令暮改」は通常、ネガティブな意味で使われます。 しかし、ガイドライン駆動開発では、これをポジティブに再定義します。
朝の判断が間違っていたら、夕方には修正する
これは、無責任な方針変更ではありません。 新しい情報に基づいた、素早い軌道修正です。
まとめ
ガイドライン駆動開発は、AIコーディングエージェントとの協働を前提とした開発手法です。
この手法は、それほど規模が大きくない、1人で開発するツールで特に能力を発揮します。 プロダクトの仕様を自分一人で変更できるような、柔軟な意思決定が可能な開発環境に最適です。
重要なポイント
- 仕様書は方向性を示すガイドライン
- AIエージェントが変更作業を担当
- 人間は「何を」、AIが「どのように」を分担
- 変化を前提とした開発プロセス
この手法が成立するのは、AIエージェントという強力なパートナーがいるからです。 仕様書の更新、コードの修正、テストの追加。 これらすべてを数分で完了できる時代だからこそ、真に柔軟な開発が可能になりました。
完璧な仕様書を作ろうとして時間を浪費するより、80%の仕様で始めて、AIと一緒に改善していく。 これが、AIコーディング時代の開発スタイルです。
仕様書に縛られるのではなく、仕様書をAIとの共通言語として使う。 それが、ガイドライン駆動開発の本質です。