TL;DR
- 非エンジニアが GitHub Issue を書く → AI が要件を質問で詰める → 実装する → PR を出す。ここまで自動で回る仕組みを、toC サービスのモノリス(Laravel 9 + Vue 3)に 2 日で入れた
- プロセスは AWS 公式 OSS の AI-DLC、実行基盤は GitHub Actions + Claude Code (claude-code-action)
- で、素直に組むと動かない。**「GitHub 上だと AI の質問が 3〜4 件しか出てこない」**という地味に致命的な不具合の原因が 4 つ重なっていて、全部潰すまでが本番だった
- この記事は技術編。これをやってみて感じた「エンジニアの仕事の変化」は別記事に書いた(※2本目のリンクをここに)
作ったもの
レーンは 3 本。それぞれ独立して動く。
| レーン | 起動条件 | やること | コード変更 |
|---|---|---|---|
| 開発依頼 | Issue に ai-request ラベル or @claude コメント |
AI-DLC のプロセスで要件質問 → 設計 → 実装 → PR | する(専用ブランチ) |
| 仕様質問 | Issue に question ラベル |
現行仕様を「結論 → 根拠(ファイル:行)」で回答 | しない |
| PR 自動レビュー | 人間が PR を open / draft 解除(全自動) | セキュリティ優先でレビュー + 判定ラベル付与 | しない |
入口は Issue テンプレート。「何をしてほしい?」「なぜ?」「対象の画面」「完成イメージ(任意)」の 4 項目で、@claude 宛の申し送り文までプリセットしてある。専門用語ゼロで依頼できる。
AI-DLC って何
AWS が公開してる開発ライフサイクルのフレームワーク。要件定義から運用までの 32 ステージを、PM・アーキテクト・QA・セキュリティといった 11 種の AI エージェント(ペルソナ) が分担して進める。「AI が勝手に作る」んじゃなくて、ステージごとに人間の承認ゲートがあるのと、チームのルールを階層化された Markdown(org → team → project)に蓄積していく設計なのがミソ。
導入自体は配布物をリポジトリにコピーするだけ。……のはずだった。
全体の流れ
設計上いちばん大事な前提がこれ。GitHub Actions は @claude コメント 1 回ごとに完全に新しいセッションが立ち上がって、前回の会話を何も覚えてない。 引き継がれるのは「作業ブランチにコミットされたファイル」と「Issue のコメント履歴」だけ。だから AI-DLC の状態(質問と回答、進行位置、監査ログ)をステージごとにブランチへコミットさせて、次の実行はそこから再開する規約にした。Issue のコメント欄が公式の議事録になる。口頭で補足しても AI には届かない。
ハマった穴(この記事の本編)
導入は 1 日で終わった。そこから「ローカルだと完璧なのに、GitHub 上だと質問が 3〜4 件で止まる」という現象と数日戦った。原因は 1 個じゃなくて 4 個重なってた。
穴 1: headless では対話ツールが仕様として使えない
Claude Code の headless モード(CI 実行)では、ユーザーに選択肢を出す AskUserQuestion ツールが許可リストに入れても拒否される。これはドキュメントに書いてある仕様。一方 AI-DLC 側は「構造化質問はすべて AskUserQuestion で描画する」と定めている。つまり素のままだと、質問を出す口がそもそも存在しない。
対処: リポジトリの規約(CLAUDE.md)に「Actions 実行時はこの規約を無効化して、質問は gh CLI で Issue コメントとして投稿する」という上書きを明記した。
穴 2: AI が質問を「自己検閲」する
ツール固有の制約(1 回最大 4 問)と、プロセス側の「質問数の目安(〜5-8 問)」を、AI が上限だと誤解して質問を勝手に削ってた。「多すぎるかもしれない」って空気を読むんですよ。AI は放っておくと無難な平均に回帰する。
対処は打ち消しの明文化。
質問の数に上限は無い。件数を理由に質問を削ることと、「多すぎるかもしれない」という自己検閲を禁止する。聞き漏らして誤った実装をするより、多く聞くほうが常に良い。
これを入れたら、ローカルと同じ水準(1 ステージ 8 問以上)が出るようになった。
穴 3: --allowedTools は「排他的な」許可リスト
headless では権限確認プロンプトが出せないので、--allowedTools に列挙しなかったツールは全部自動拒否される(--permission-mode も無視される)。僕は最初 Bash 系しか列挙してなくて、ファイル読み書きも Issue コメント投稿もできない状態を自分で作ってた。列挙漏れは「AI が何もしないで終わる」という分かりにくい形で表面化する。
# 修正後のイメージ。コアツールと gh CLI を全部明示列挙する
claude_args: >-
--model opus[1m]
--allowedTools "Read,Write,Edit,MultiEdit,Glob,Grep,LS,Task,WebSearch,
Bash(git:*),Bash(gh issue comment:*),Bash(gh pr create:*),..."
ついでに --model も明示しないと既定モデルに落ちて、質問の質が目に見えて下がる。
穴 4: settings.json の ask は CI では実質 deny
Claude Code の権限設定で「確認してから実行」(ask)にしていたコマンドは、確認する人間がいない CI では全部拒否になる。うちは git commit / git push を ask にしてたので、AI が作業をコミットできず、セッション終了と同時に数時間分の作業が消える事故が起きた。AI 自身が Issue に「権限をください」って報告してきて発覚した。
対処: CI で必要なもの(commit / push / テスト実行)は allow へ。危険な形(force push、本番ブランチへの直接 push)だけ ask に残す。ask は「CI では拒否・ローカルでは確認」として働くので、危険操作の置き場としてはむしろ便利だった。
細かい穴も置いておく
-
checkout は既定ブランチに着地する:
issue_commentイベント起動だと作業ブランチにいない。自分で switch する手順を規約化しないと、毎回ゼロからやり直して同じ初期質問を無限に繰り返す -
対話前提の hook が CI で迷走: 「保護ブランチ上なら作業ブランチ名を人間に聞く」ローカル用 hook が、対話相手のいない CI で発火して止まる。
GITHUB_ACTIONS環境変数で早期 return -
スコープ自動判定が日本語で誤動作: 依頼文の単語数を空白区切りで数えるロジックなので日本語だと安全弁が効かない。
deployとかsecurityって英単語が 1 個混ざるだけで別プロセスに誤ルーティングされる。自動判定はやめて明示指定の規約に - 公式配布物にも gitignore の穴があった: ランタイム状態の一部が追跡対象に漏れてた。実機で 1 回動かして初めて見つかるやつ
教訓を一言でまとめると: ドキュメント通りに組んだものは 7〜8 割まで。残りは実機で端を検分しないと見つからない。 これは AI が作ろうが人間が作ろうが、AWS の配布物ですら変わらなかった。
安全装置とお金の話
AI に本番のコードベースを触らせるので、多層防御にしてある。
- path-guard: AI の作業ブランチの PR が禁止パス(CI 定義・デプロイスクリプト・エージェント設定・規約ファイル自体)に触れたら CI で機械的に落とす。人間の PR は素通し
- 承認ゲート: 要件・各ステージ・最終(= PR レビュー)のすべてで人間が承認。自動承認はさせない
- 権限の 3 段階: allow(CI で必要)/ ask(危険操作: ローカルは確認、CI は拒否)/ 禁止パス(CI で強制)
- コストの防波堤: トークン従量課金なので、あえてターン上限は設けず、API 側の月次支出上限(Spend limit)を唯一の蛇口にする
コスト感で言うと、3 レーンのうち勝手に走るのは PR レビューだけなので、コストドライバーは PR の流量。レビュー 1 本で数十円〜数百円のオーダー。開発依頼レーンは 1 案件の単価こそ大きいけど、人間が起動しない限り 1 円もかからない。
まとめと、次にやること
- 「Issue から PR まで」の配線は通った。エージェントを日常的に使う開発者が世界でまだ 14% という調査を見るに、非エンジニアまで開いてる組織はけっこう先頭のほうだと思う
- ただし「導入した状態」と「運用が回った状態」は別物。次はパイロット案件を 1 本完走させて、質問の質・成果物・コストを実測する
- その先は、PR ごとに使い捨ての検証環境を立てて、依頼した本人がブラウザで動作確認できるようにする構想(ローカル開発環境の Docker 構成をそのまま 1 台のホストに載せて、閉じたら
down -vで完全消去)
これを作ってみて感じた「エンジニアの仕事そのものの変化」は、長くなったので別記事に書いた。
参考リンク
- awslabs/aidlc-workflows — AWS 公式の AI-DLC
- anthropics/claude-code-action — GitHub Actions で Claude Code を動かす公式 Action
- Addy Osmani — The 70% Problem / The 80% Problem in Agentic Coding