背景

近年の AI エージェントの発展によって、開発環境は大きな転機を迎えています。 
定型的な実装や既存コードに沿った修正では、AI が人間より速く進められる場面が増えてきました。すでに、人の手だけでコードを書く開発は少しずつレガシーになりつつあります。

一方で、AI に任せれば期待どおりのものができるわけではありません。
何を作るべきか、どの前提を守るべきか、出力されたものを採用してよいかを判断する役割は、依然として人間に残っています。

問題は、AI の開発速度に対して、人間の認識速度が追いつきにくいことです。AI はコード、設計案、テスト、修正案を短時間で大量に出せます。
一方で、人間がそれを理解し、必要な情報を集め、採用してよいか判断するには時間がかかります。

だからこそ、AI に渡す情報と、人間が判断するための情報を分けて整理する必要があります。
単純な作業や定型作業は自動化しつつ、判断に必要な情報をどう見せるかを設計することが重要になります。

私自身、半年ほど開発から離れていた時期があり、戻ってきたときには最新の AI の有効な使い方が分からず、プログラミングの進め方そのものにかなり戸惑いました。

そんな中で、まだ試行錯誤中ですが、整理できてきた部分を個人開発環境の試行錯誤として記事にまとめてみました。 

AI 駆動開発と仕様駆動開発

AI 駆動開発では、AI が短時間で実装案、設計案、テスト、修正案を大量に出せます。
しかし、目的や制約、完了条件が会話の流れに埋もれたままだと、AI はもっともらしい実装を次々に作れてしまいます。
そのため、AI に何を任せるかだけでなく、何を基準に採用するかを先にそろえる必要があります。
こうした AI 駆動開発の課題を克服する考え方として、仕様駆動開発に注目しています。
仕様駆動開発は、作り始める前に「何を実現したいのか」「どこまでを対象にするのか」「どうなれば完了と言えるのか」を言語化し、判断の基準を揃える考え方です。
 

AI 駆動開発と仕様駆動開発の相性がいい理由は、主に次の点にあります。

• AI に渡す前提を明文化できるため、暗黙の期待や制約を勝手に補完されにくくなる。
• AI の出力を評価する基準になり、「それっぽい」ではなく「仕様を満たしているか」で判断できる。
• 実装範囲や非目標を示せるため、AI の余計な機能追加や過剰設計を抑えやすい。
• 人間と AI の認識合わせに使えるため、会話だけに依存せず作業の前提を共有しやすい。
• レビュー観点を作りやすくなり、要件を満たしているか、仕様自体に矛盾がないかを確認しやすい。

ただし、仕様も絶対ではありません。
実装して初めて分かる制約や、仕様自体の不自然さは必ず出てきます。
だから仕様は固定された正解ではなく、AI の出力を理解し、必要なら更新するための判断基準として扱うのがよいと感じています。

見えてきた課題

1 か月ほど手探りで仕様駆動開発を試してみると、単に仕様を書くだけでは足りないことも分かってきました。

AI は仕様を読んで実装できますが、仕様、設計、実装、一時メモ、過去の会話が同じ重さでコンテキストに入ると、どれを判断基準にすべきか曖昧になります。
さらに、実装中に見つかった制約や例外を仕様へ戻す流れがないと、仕様と実装の乖離は少しずつ広がります。

特に難しいと感じたのは、次の点です。

• 仕様が一方向の指示書になりやすく、実装中に見つかった制約や例外を戻しづらい。
• 仕様、設計、実装、一時メモの優先順位が曖昧だと、AI がどれを正として扱うべきか迷いやすい。
• レビューが「仕様に従っているか」だけに寄ると、仕様自体の欠陥や過剰設計を見落としやすい。
• セッション内で生まれた判断や発見がチャットに残るだけだと、次回以降の前提として再利用しづらい。
• エージェントの操作が膨大かつ高速で、すべてを逐次確認すると人間側がボトルネックになりやすい。
• 逆に確認を省きすぎると、危険な Git 操作や意図しない差分が通りやすい。

方針

ここからは、上の課題に対して私が今試している構成例です。
完成した方法論ではなく、「AI の速度を活かしながら、人間が判断できる状態を保つ」ための作業中の設計として書いています。

具体的には、次のような方針です。

• 仕様、設計、検証、判断履歴を分け、AI に渡す前提と人間の判断基準を明確にする。
• 実装中に見つかった制約や例外を、必要に応じて仕様や判断履歴へ戻せるようにする。
• Local context を使い、セッション中の要望、現在地、未確認事項を再開しやすい形で残す。
• hook や wrapper で危険操作の入口を制御し、確認すべきタイミングを自動で拾う。
• skill に判断手順をまとめ、レビューや PR 作成、検証、サブエージェント委譲の観点をそろえる。
• AI の出力を、目的、根拠、変更点、影響範囲、リスク、未確認事項に分けて人間が確認しやすくする。
   

執筆時点の私の環境は次のとおりです。

• AI 開発環境: Codex デスクトップアプリ
• 利用プラン: ChatGPT Pro（定額制）
• バージョン管理: GitHub

LLM 利用は、従量課金の API 呼び出しを使わず、定額で利用できるアプリの機能の範囲で開発環境を整備しています。

この構成で狙っているのは、AI に作業させるための入力と、人間が判断するための表示を分けて扱うことです。

4種類のドキュメント

私の開発環境では、AI と人間が判断に使う材料を大きく 4 種類に分けています。

一言でいうと、次のような分担です。

Project docs

Project docs は、プロジェクト全体で共有する正式な文書です。

プロダクトの目的、業務前提、設計方針、共通ルール、用語、文書運用など、長く参照したい判断軸をまとめる層です。
複数の機能や作業にまたがって使う判断をここに置きます。

Project docs は、AI の出力を確認するときの大きな判断軸になります。
ある変更がプロジェクト全体の方針に合っているのか、既存の用語や設計原則から外れていないのかを見るための基準です。

docs/                         # 共有ドキュメントの入口
  README.md                   # docs 全体の案内
  product/                    # プロダクト目的・業務前提
  architecture/               # システム構造・設計判断
  standards/                  # 実装・品質の共通ルール
  operations/                 # 開発プロセス・文書運用
  specs/                      # spec 単位の作業置き場

Spec docs

Spec docs は、1 つの作業単位ごとの仕様文書です。
この運用では、1 spec を 1 つのスプリントに近い単位として扱っています。

私は、要件を決めた後にユーザー体験を定義することで、抽象と具体の両面から AI との認識の差をすり合わせられるようにしています。

Spec docs には、実装中の AI と人間のインターフェースとしての役割を持たせています。
tasks.md で進捗を確認し、実装中に見つかったアイデアや判断は decisions.md に残します。
スプリント終了時には、継続して参照すべき内容だけを Project docs や Agent docs に昇格します。

docs/specs/                   # spec 単位の作業置き場
  README.md                   # spec 運用の案内
  01-XXX/                     # 1 つの変更テーマ
    requirements.md           # 何を作るか
    experience.md             # どんな体験にするか
    design.md                 # どう作るか
    validation.md             # どう確認するか
    tasks.md                  # どう進めるか
    decisions.md              # なぜそうしたか
    context/                  # 作業再開用の一時メモ

Local context

Local context は、実装中のコンテキストを共有・記録するための一時メモです。

会話の中で出てきたユーザーの要望、好み、制約、未確認事項、現在の作業状態、直近の変更、次に見るべき参照などを短く残します。

ただし、context/ は正式な共有文書ではありません。あくまでローカルキャッシュとして扱い、継続利用する判断は Spec docs や Project docs へ昇格します。

docs/specs/01-example/        # 対象 spec
  context/                    # local-only メモ
    intent.md                 # ユーザー要望・方針・制約
    current.md                # 現在地・未解決事項

intent.md と current.md は、役割を分けています。

• intent.md: ユーザーの要望、好み、制約、未決定事項を残す。

• current.md: 現在の branch、対象 spec、直近変更、未解決事項、次アクションを残す。

  

Agent docs

Agent docs は、AI エージェントの振る舞い、判断手順、自動処理との関係を定義する層です。

開発中に毎回発生する確認、記録、危険操作のガード、次に見るべき観点の整理をここで定義しておくことで、AI との作業を効率化しつつ、人間が確認すべき点を見失いにくくします。

ここから少し具体的になります。Agent docs では、主に hook、wrapper、skill の 3 つを分けて考えています。

それぞれの役割を簡単にまとめると、次のようになります。

関係性としては、hook がタイミングを拾い、必要に応じて wrapper が操作を安全に通し、AI は skill を参照して意味的な判断を行う、という分担にしています。

hook

hook は、特定のタイミングで自動実行される処理です。

私の開発環境では、主に Codex Hooks と Git Hooks を使っています。

Codex Hooks は、Codex 上での作業の節目を拾うための hook です。現在は次の hook を使っています。

Git Hooks は、Git 操作の節目を拾うための hook です。pre-commit、commit-msg、pre-push、pre-merge-commit、post-checkout、post-commit、post-merge、post-rewrite を使っています。
commit 前の確認、commit message の確認、push 前のチェック、branch 切替後の記録、commit / merge / rewrite 後の current.md 再生成などを担当します。

Codex Hooks は「AI との会話やツール実行の流れ」を見て、Git Hooks は「Git が実際に状態を変える瞬間」を見ます。
例えば、Codex Hooks で危険な Git 操作を wrapper に誘導し、実際の commit や push の直前には Git Hooks が機械的な最終確認を行う、という関係です。

hook はタイミングを拾う役割に寄せ、判断は skill、実行の安全確認は wrapper に分ける方針にしています。

hook 周りの配置は、次のように分けています。

.codex/
  hooks.json                  # Codex hook 設定
  hooks/                      # Codex Hooks
    context_cache.py          # local context の読み書き
    session_start.py          # セッション開始時
    user_prompt_submit.py     # ユーザー依頼受信時
    pre_tool_use.py           # ツール実行前
    post_tool_use.py          # ツール実行後
    stop.py                   # セッション終了時
  githooks/                   # Git Hooks
    pre-commit                # commit前
    commit-msg                # commit message
    pre-push                  # push前
    pre-merge-commit          # merge前
    post-checkout             # checkout後
    post-commit               # commit後
    post-merge                # merge後
    post-rewrite              # rewrite後

wrapper

wrapper は、危険な操作を安全に通すための入口です。

たとえば、branch 作成、commit、push、merge、履歴書き換え、PR 作成のような操作は、失敗したときの影響が大きくなりやすいです。
そのため、直接コマンドを実行するのではなく、事前確認や禁止条件を持った safe wrapper を通して実行します。

現在は、主に次の wrapper を使っています。

wrapper と補助 utility は .codex/bin/ に置いています。

.codex/
  bin/                        # wrapper
    git-branch-safe           # branch 操作用入口
    git-commit-safe           # commit 操作用入口
    git-push-safe             # push 操作用入口
    git-merge-safe            # merge 操作用入口
    git-rewrite-safe          # amend / rebase / reset 用入口
    gh-pr-safe                # PR 作成用入口
    current-context-refresh   # current.md 再生成 utility
    docs-reference-check      # docs / Agent docs の参照確認

wrapper の役割は、操作前に機械的に確認できることを確認することです。
例えば、差分があるか、対象 branch が危険でないか、対応する spec があるか、古い docs 参照が残っていないか、必要な前提がそろっているかを見ます。
一方で、その変更を採用すべきか、仕様として妥当か、といった意味的な判断は skill や人間レビューに残します。

skill

skill は、AI が判断するときに参照する手順書です。

たとえば、commit 前に何を見るべきか、PR 作成前にどの観点を整理するべきか、spec を作るべきかどうかをどう判断するか、といった判断手順を置きます。
AI に毎回長い説明をするのではなく、場面ごとの考え方を skill として分けておくことで、判断のぶれを減らしやすくなります。

また、skill ではサブエージェントの使い方も定義しています。
大きな作業を 1 つの AI にまとめて任せるのではなく、調査、レビュー、修正、リファクタリングのように役割を分け、必要な場面だけサブエージェントに委譲し、メインセッションのコンテキストを削減しています。

skill 周りの配置は、次のようにしています。

AGENTS.md                     # AI エージェント全体の基本方針
.agents/
  skills/                     # 判断手順
    hook-*                    # hook 前後の整理
    spec-*                    # spec 作成・設計・検証・レビュー
    doc-*                     # local context と正本の見直し
    git-*                     # branch / commit / push / PR / merge 判断

ワークフロー例（push時）

最後に、実際の作業ではどう流れるのかを 1 つだけ例にします。たとえば、push 時の処理は次のようになります。

これは考え方を説明するための例であり、この構成をそのまま採用する必要はありません。

最後に

この開発環境は完成形ではありません。
実際の開発・運用を通して引き続き改善していきたいと思います。

私はプロジェクト開発を、常に複雑さとの闘いと捉えています。

ある程度コーディングの知識がついてくると、機能単体の実装はできても、プロジェクト全体の複雑さが大きくなるほど変更が難しくなります。
設計、仕様、例外処理、過去の判断、運用ルール、レビュー観点。そうした情報が増えるほど、単にコードを書くだけでは進めにくくなります。

AI は、その複雑さを消してくれるわけではありません。
むしろ、局所的な実装速度が大きく上がるぶん、人間が理解できる表示と確認の仕組みが追いつかないと、あとで一気に崩れます。

だからこそAI が生成する膨大な情報をそのまま受け取るのではなく、人間が理解しやすい表示に変換する仕組みが重要になると思っています。
AI のコンテキスト長や処理能力だけでなく、人間が理解できる情報量も意識しながら、開発環境そのものをアップデートしていく必要があります。

AIに全部を任せるのでも、人間が全部を抱え込むのでもなく、AIの実力を十分に発揮でき、人間が判断を見失わない開発環境を作っていきたいと考えています。

技術進歩の先でエンジニアが駆逐されるその日までの短い期間ですが、AIと一緒に開発を頑張りましょう！