こんにちは！アポロ株式会社です。
弊社では、社内勉強会として「コーディングエージェント勉強会」を隔週で行っています📚
今回は、その内容を一部抜粋して皆さんにシェアさせていただきます。
ぜひ、この投稿を読んでみて、Claude Codeをより深く学びたい！ と思った方。
ぜひ、次回の勉強会にご参加ください！
この記事は「コーディングエージェント勉強会 #3」の内容を一部解説しています。
実際の画面操作・設定ファイルの実例を含む動画もオンデマンドで視聴が可能です。ぜひ、こちらもお申込みください。
📺 [オンデマンド配信の申込はこちら]
勉強会当日の登壇資料・デモ映像を含む全編が視聴可能です。
この記事でわかること
-
Claude Codeが途中で止まって許可を求めてくる原因と根本的な解決策
-
settings.jsonのallowlistを使った権限設定の具体的な方法 -
Makefileによるコマンド一元管理でエージェントを安定稼働させるテクニック
-
ghコマンド・Cloud CLIを使った最小権限設計のベストプラクティス
-
Playwright MCPサーバーでE2Eテスト環境を整備し、フィードバックループを自動化する方法
-
--dangerously-skip-permissionsを安全に使える3つの条件
よくある悩み：「許可ボタンを押すためだけに席に張り付いている」
Claude Codeを使い始めた多くの開発者が直面する問題があります。
「全部任せられるはずなのに、なぜか席を離れられない」
原因はシンプルです。途中でClaude Codeが止まって、許可を求めてくるからです。ファイルの読み込み、テストの実行、ちょっとしたコマンド実行のたびに確認ダイアログが出る。本当にやりたかった仕事を一時中断され続けるストレスは想像以上です。
本記事では、エージェントが1〜2時間自律的に動き続ける開発環境を構築するための3つのポイントを解説します。
目標: 要件定義と設計さえ終われば、実装→テスト→プルリクエスト作成まで、エージェントが人間の介入なしにやり遂げる環境を作る。
解決策の根本：「命令で制御」から「権限で制御」へ
なぜCLAUDE.mdに「〇〇はしないで」と書いても意味がないのか
初心者がよくやりがちな対策が、CLAUDE.mdや指示文に「この操作は絶対にしないでください」と書き込むことです。しかし、これは根本的な解決策になりません。
理由は、LLMはプロンプトを100%遵守するとは限らないからです。特に長時間のタスクほど、エージェントが把握すべきコンテキストが膨大になり、細部の命令はだんだん守られなくなっていきます。
設計原則: 「やらないで」ではなく「できなくする」
開発しやすい環境・しにくい環境の違い
3つのポイント
ポイント1：適切な権限設定
settings.jsonのallowlistとは
Claude Codeはsettings.jsonのpermissions.allowフィールドに許可するツール・コマンドを登録できます。ここを適切に設定することで、「安全な操作は自動実行・危険な操作のみ人間に確認」というフローが実現します。
何を許可して、何を許可しないか
✅ 許可すべきもの（副作用が限定的で繰り返し安全なコマンド）
- テスト実行（npm test、pytest など）
- lint・フォーマット
- ビルド
- docker compose up / down
- フィーチャーブランチへの git push
- プルリクエストの作成・更新
⚠️ 慎重に判断すべきもの
- 外部APIへの書き込み
- 特定のクラウドサービスへのアクセス
❌ 許可すべきでないもの（不可逆な変更）
- 本番環境へのデプロイ
- git force push
- 本番DBへの操作
- Terraformの実行
- CIワークフローの変更
判断基準: 「このコマンドは実行しても安全か？」ではなく、「仮に誤った使い方をされても、環境側で安全が担保されているか？」という観点で判断する。
Makefileによるコマンド一元管理
コマンドを1個ずつallowlistに追加し続けるのは非効率です。Makefileにコマンドをまとめて、make *を一括許可するのが実用的なアプローチです。
Makefileには2つの効果があります。
効果① 権限管理の簡素化
make *の一文でMakefile内の全コマンドを許可できます。
効果② エージェントの動作安定化
Makefileを見ることでエージェントが「このプロジェクトではこの手順で開発すればいい」と把握し、毎回ブレなく同じ品質で作業してくれます。
Makefileに含めるコマンドの例：
make doctorの活用: 環境構築後にmake doctorを実行させ、全項目がクリアになるまでエージェントに繰り返させることで、セットアップを完全自動化できます。
Makefileを育てるコツ: 最初から全部作らなくて大丈夫です。許可ボタンを何度も押しているコマンドに気づいたら都度追加していきます。エージェント自身に「さっき何度も使ったコマンドをMakefileに追加して」と頼むのも有効です。
GitHubの権限はリポジトリ側で制御する
git操作の権限は、allowlistではなくGitHubのブランチ保護ルール・トークンスコープで制御するのがポイントです。
エージェントに許可する操作：
✅ フィーチャーブランチへの push
✅ プルリクエストの作成・更新
✅ issueの作成・コメント
GitHub側で制限する操作：
🚫 mainへの直接 push（ブランチ保護ルール）
🚫 force push（ブランチ保護ルール）
🚫 PRのマージ（トークンスコープで制限 → 必ず人間が行う）
🚫 issueのクローズ
「PRのマージは必ず人間が行う」というルールを維持することで、エージェントがどんな動作をしても本番環境・mainブランチは人間の確認なしに変更されません。
ポイント2：CLIツールの活用と最小権限の設計
ghコマンドでGitHubフローをそのまま自動化
ghコマンドはClaude Codeと相性が非常に良いツールです。人間がGitHubで行っていた操作をそのままエージェントに引き継がせられます。
ghコマンドで実現できること：
-
バグを検出してissueを自動作成
-
issueの内容を読んで実装
-
プルリクエストの作成・レビューコメントの取得
-
別エージェントとの連携（後述）
エージェント間連携の活用例:
① Claude Code がローカルで実装
↓
② gh コマンドでプルリクエストを作成
↓
③ Codex が PR 作成をトリガーに自動レビュー
↓
④ Claude Code がレビューコメントを読んで修正
↓
⑤ 人間が最終確認してマージ
Claude CodeとCodexのような異なるモデルを組み合わせることで、一方が見落とすバグをもう一方が発見するという相乗効果も生まれます。
最小権限の原則：本番DBが消された実例から学ぶ
実際に起きた事故: Claude Codeによって削除されてしまったという事例がネット上で報告されています。
こうした事故を防ぐために、CLIツールにも最小権限の原則を徹底的に適用します。
ポイント3：テスタビリティの高い環境の構築
このポイントが最も開発体験を変えてくれます。
テスタビリティの高い環境とは何か
「システムを使うユーザーと同じ環境で、エージェントがテストできる環境」のことです。単体テストだけでなく、E2Eテスト環境を整備することがコーディングエージェント活用の最重要ポイントです。
Claude Codeが自律的に開発を進める理想サイクル
① 機能を実装する
↓
② アプリケーションを起動する
↓
③ テストを実行して動作を確認する ←── ここが鍵
↓
④（失敗）原因を調査して修正する
↓
⑤ 再テストして確認する
↑_________________________↓
繰り返し
このサイクルを人間の介入なしで回せるかがすべてです。
単体テストだけでは結合部分のバグが見落とされ、PRを作成した時点でバグが残っているということが頻繁に起きます。エージェントにも人間と同じようにブラウザ操作でテストさせることで、これを防ぎます。
Playwright MCPサーバーの導入
Playwright MCPサーバーを導入することで、Claude Codeは以下の操作を直接行えるようになります。
具体的な活用例:
従来の自動テストでは「ボタンが押せない」は検出できても、「ボタンは押せるがレイアウトが崩れている」の検出は非常に難しく、細かいテストコードを大量に書く必要がありました。Playwright MCPを使えば、エージェントが実際にブラウザでアプリを操作し、視覚的な問題も自分で発見・修正できます。
これにより以下のサイクルが完全自動化されます：
実装 → ブラウザ起動 → UI操作テスト → 不具合発見 → コード修正 → 再テスト
重要: テスト環境を一度構築すれば、一晩エージェントに任せておくだけで自動テストが完了している環境が実現します。他の何よりも先にここに投資することを強くお勧めします。
よくある質問（FAQ）
Q. MakefileとClaudeのスラッシュコマンドはどう使い分ければいい？
A. 目的が異なります。
Makefileのコマンドは「毎回必ず同じことをシステムが自動実行する」もの（例：make db-reset）。
スラッシュコマンドは「状況を読んでエージェントが柔軟に判断・実行する」もの。
基本的な操作はMakefileに、応用・状況依存の操作はスラッシュコマンドに入れる、という使い分けが効果的です。
なお、スラッシュコマンドの中でMakeコマンドを呼び出す組み合わせも有効です。
Q. Makefileを許可するとエージェントが悪用できてしまわないか？
A. その通りです。
エージェントはMakefileを自分で書き換えてから実行することで、任意のコマンドを動かせてしまいます。
ただし、コーディングを任せている以上、バックエンドのコードに危険な処理を混入させることも技術的には可能です。
この点はある程度許容した上で、Makefileというレイヤーを挟むことで一定の透明性を確保する、というのが現実的なアプローチです。
エージェントが何を操作したかは定期的に確認しましょう。
Q. allowlistに登録しているのに許可を求めてくるのはなぜ？
A. Claude Codeの既知のバグです。
特に複数行にわたるコマンド（issueの本文、PRの説明文、git commit メッセージなど）の場合に、許可済みのはずなのに人間に許可を求める現象が発生します。
対処法はPreToolUseフックを使って、該当コマンドを自動的にallowする処理を追加することです。
なお、パイプ（|）やアンパサンド（&&）で悪意ある後続処理が続いていないかをフック内で検証した上でallowするようにしてください。
Q. --dangerously-skip-permissionsはどんな時に使えるか？
A. 以下の3条件をすべて満たす場合に限り使用を検討できます。
①ソースコードに機密情報を含まない（オープンソース開発など）
②Dockerコンテナ・VPCなど影響範囲が限定された閉じた環境
③本番環境のAPIやクレデンシャル情報を含まない。
なお「完全クローズドな環境でコーディングさせる」方法は、GitHubへのアクセスができないためPRワークフローが維持できないこと、またLLMがWeb上の最新ドキュメントを参照できずベストプラクティスから外れた実装をしやすくなることから、推奨しません。
まとめ
Claude Codeを本当に自律的に動かすための3つのポイントを整理します。
この3つが揃えば「要件定義と設計さえ終われば席を立ってOK」という開発体験が現実になります。
📺 動画でもっと詳しく学ぶ
本記事の元となった勉強会では、実際のsettings.json・Makefile・フックスクリプトのコードを画面共有しながら解説しています。
オンデマンド配信では以下が視聴できます：
-
実際のプロジェクトで使用しているMakefileの全体像
-
PreToolUseフックの具体的なスクリプト実装 -
記事作成エージェントのデモ（Playwright MCPを使ったサイクルの実演）
など
📺 [オンデマンド配信の申込はこちら]（無料）
次回勉強会は4/27(月)19時～開催予定です！
ぜひ、以下よりお申込みお待ちしております。
エンジニア向けのコミュニティを開設🎉
コーディングエージェント勉強会の先行情報や、日々の小ネタをシェア、こういう時どうやって対処してる？なんていうちょっとしたお悩み相談まで。
ぜひ、アポロのメンバーと一緒にフランクにお話してみませんか？
👉参加希望の方はこちらから
アポロでは現在メンバーを積極的に募集しております。
こちらもご興味のある方は、ご応募お待ちしております！