■ 1. 開発フローの概要と変化
- AIコーディングエージェントの普及により、自分でコードを書く時間が大幅に減少した
- 実装そのものより実装前の設計セッションが開発の中で最も時間のかかる工程となった
- 複数のエージェントを並行して動かすことが日常化した
- 最初に全体を見据えた設計を行い、独立して実行できる単位にタスクを分解することが重要
- 人間は並列実行のための設計やデータモデル・責務の境界といった影響の大きな判断に集中するようになった
■ 2. AIへの指示方法: 詳細手順よりゴールの共有
- ファイルごとの編集手順や関数内部の実装方法を細かく指定しない
- 詳細な手順を渡しすぎると、AIがより良い方法を提案する機会が失われるため
- 「grill-me」スキルなどを使い、設計やデザインについて共通理解が得られるまで徹底的にインタビューを実施する
- 設計前に議論すべき観点:
- なぜこの変更が必要なのか
- 何を満たせば完成なのか
- ドメイン上、壊してはいけない制約は何か
- コンポーネント間の責務をどのように分けるか
- どのような振る舞いを検証できれば正しいと判断できるか
- ゴール、制約、責務の境界、インターフェース、検証すべき振る舞いは事前に議論し、局所的な実現方法はAIに委ねる
■ 3. 実装前の設計セッション
- 複数タスクを並行実行する際、人間がすべてのエージェントを監視し続けることはできない
- 認識のずれが残ったまま実装を始めると、ずれに気づくのはすべての作業が終わった後になる
- 設計セッションではAIの提案に対して受け身にならないことが重要
- ドメイン上の制約や既存アーキテクチャを選んだ理由、提案への違和感を言語化して伝える必要がある
- 責務の分け方、依存関係の方向、拡張性の判断は、AIの提案を材料にしながら人間が判断する
- 何も考えていない状態からAIが魔法のように設計を作ってくれるわけではない
■ 4. 設計書の管理
- 設計の結果はチャット履歴だけに残さず、別のドキュメントとして整理することが望ましい
- 現時点ではGitHub Issueのコメント欄に設計書を置くことが多い
- タスクの進行状況と紐づき、設計書の更新履歴も残るため
- Markdownファイルとしてリポジトリに置く方法も検討に値する（AIが参照しやすい）
- 設計書は以下の2種類に分けて管理する（「意思決定は残し、作業手順は使い終わったら捨てる」）:
- 長く残る設計判断: ADRや設計ドキュメントとして永続的に残す
- 今回の実装だけに必要なタスク分解や進行手順: Issueのコメントなど使い捨てできる場所に置き、実装後に捨てる
■ 5. 並列タスク実行とモノレポ
- 設計完了後、独立して実行できる単位にタスクを分解する
- Git worktreeで作業ディレクトリを分離し、Claude Desktopの別々のスレッドで並列実行する
- CLIよりClaude Desktopを好む理由:
- 複数スレッドの状態を一覧しやすい
- 設計と実装のセッションを分離しやすい
- 図表描画機能で設計の議論を視覚的に確認できる
- worktree環境の整備として、作成時に
node_modulesのシンボリックリンクを作成するhooksを設定する- AIに「設計書を元に実行可能なタスクへ分割し、サブエージェントを並行実行」と指示することも可能
- モノレポの利点:
- 複数領域を横断した依存関係・実装パターンの探索が容易
- 複数の実装セッションが同じ設計書・検証コマンドを参照できる
- 横断的な変更の影響範囲を調査した上でタスク境界を決めやすい
- ポリレポの場合、別リポジトリへの相対パスをプロンプトで示しながらセッションを開始するという方法が有効
■ 6. 自律的な検証環境の整備
- AIが自律的に実装するためには、自分の変更に対してフィードバックを得られる環境が必要
- テスト・型チェック・Lintに加えて、開発サーバーを起動した状態での実動作の確認まで自律的に行えるようにする
- フロントエンドの変更: ブラウザ操作で確認
- APIの変更:
curlでリクエストを送信しレスポンスを確認- 期待する振る舞いは設計段階で決め、確認手順はプロジェクト固有のスキルとして手順化する
- ブラウザ操作には Claude Desktopのブラウザ操作機能を利用する
- フィードバックループの速度向上が重要であり、Vite+スタック（Vite、Vitest、Oxlint、Oxfmt、tsgo）を積極的に採用する
- フィードバックループの改善は、使うモデルやプロンプトと同等に重点的に取り組むべき対象
■ 7. コードレビューの方法
- PR作成後は必ず別のセッションでAIにコードレビューを依頼する
- 実装セッションは自分の変更を正当化する方向にバイアスがかかりやすいため
- AIレビューの役割: 論理的なロジックの誤り、テストカバレッジの不足、局所的な可読性の低さを探す一次チェック
- 人間のレビュー観点:
- 要件を満たしているか
- 責務の境界が設計と一致しているか
- 認証・決済・個人情報・データ移行など高リスクな変更に問題がないか
- すべての行を同じ注意力で読む必要はなくなった
■ 8. CLAUDE.mdとスキルの整備
- 役割の分担:
CLAUDE.md: リポジトリ構造、標準コマンド、プロジェクトの暗黙知、すべての作業で参照する短い原則- プロジェクト固有スキル: 検証手順や定型作業など複数タスクで再利用できる作業パターン
- 個人スキル:
grill-meやコードレビューなど複数プロジェクトで再利用できる作業パターン- AIの動作ログを観察し、迷いが生じた箇所を
CLAUDE.mdやスキルに追記する- スキル作成はタスク完了直後に「今行った作業とフィードバックをもとにスキルとしてまとめて」と指示すると効率的
- 指示文の改善だけではコードベースの問題を解決できない
- 「依存方向を守る」と書くより、パッケージ境界をコード上で明確にしたりLintルールで違反できなくする方が確実
- AIにとって扱いやすいアーキテクチャの条件（新しい原則ではなく、従来から重要とされてきた性質と同じ）:
- 責務の境界が明確である
- 依存方向が一貫している
- 変更の影響範囲を局所化できる
- インターフェースから振る舞いを理解できる
- テストによって境界の振る舞いを確認できる
- 命名やディレクトリ構成から必要なコードを探索できる
■ 9. コードを書く能力と設計能力の変化
- 実際に自分の手でコードを書くことはほとんどなくなった
- 能力変化の内訳:
- 衰えた面: 特定の構文や細かな実装パターンを思い出す機会の減少、局所的なコードの美しさへの注意
- 増えた面: システム全体の俯瞰、責務の境界・依存関係・複数変更統合時の整合性を考える機会
- 現在使っている設計能力は、過去に自分でコードを書き失敗してきた経験に支えられている
- 最初から実装をすべてAIに委ねた場合に同じ設計判断能力を身につけられるかは不明であり、若手育成については別途検討が必要
■ 10. レビューのボトルネックと対策
- AIが複数のPRを同時に作成すると、人間による従来のレビューがボトルネックになる
- 対策: コードレビューを階層化する
- 人間: 全体の設計、高リスクな変更（認証・決済・個人情報・データ移行など）を重点的にレビュー
- AI: 局所的な実装品質の確認（論理誤り・テストカバレッジ・可読性）
- 自動検証: AIレビューと組み合わせて個々の実装を通す
- 実装前の全体設計を人間どうしで相互にレビューしておくアプローチも有効
- PRを小さく分割することもボトルネック軽減に有効
- AIに対してPR分割の観点を相談しながら進め、複雑なgit操作も任せられる
- PR変更の設計意図・変更理由は、AIが作成した場合も担当エンジニア自身が説明できるようにする
■ 11. 承認の最小化
- 逐一承認を求める設定では自律的なフィードバックループを回せない
- 承認対象が増えるほど「承認疲れ」が起き、本当に必要な操作を見逃す可能性が高まる
- サンドボックス環境の整備が重要: AIが誤った操作をしても被害を最小限に抑えられる
- Claude CodeのAutoモードやCodexの「代理で承認」機能のように、AIが承認要否を自律的に判断する仕組みが登場している
- すべての承認をスキップするのではなく、機密データの漏洩・重要ファイルの削除・悪意のあるコードの実行などを検出した場合のみ人間の承認を要求する
■ 12. モデルのコストと性能の選択
- 現在は利用可能な最高性能モデルをほぼ常に使用している
- タスクの分類コストや、能力不足による手戻りを考慮すると高性能モデルへの統一が扱いやすいため
- 設計セッションで誤ると並列実行するすべてのタスクが間違った方向へ進むため、設計段階でモデル能力を節約しない
- 今後の課題:
- 従量課金制移行や並列タスク増加により、モデルの使い分けが必要になる可能性がある
- 比較すべきはトークン単価ではなく、変更完成までの総コスト（実装やり直しやレビュー増加を含む）
- モデル選択に加え、思考の深さを調整する「effort level」という軸も登場している
- 設計など複雑なタスクは高性能モデル、単純作業や既存パターンに従う変更は安価なモデルといった使い分けが一般的だが、現状は人間の勘に頼っている部分が多い
■ 13. AI中毒への注意
- サブスクリプションのリミットを使い切れなければ損をしたように感じるという強迫的な感覚が生じる
- AIが返す非決定的な結果には、ガチャに似た快感がある可能性がある（非決定的な報酬を待つ際のドーパミン活性との類似）
- AI常時稼働と価値ある仕事の進捗は同じではない
- 並列数を増やすほど、レビューや統合の負担も増える
- 必要のないタスクを作りAIの稼働率を上げること自体が目的化していないか注意する
- AIに何をさせるかだけでなく、何をさせないかを判断することも今後の設計対象となり得る