メインコンテンツまでスキップ

Slackネイティブなコーディングエージェントの構築

このレシピでは、Slackネイティブなコーディングエージェントのアーキテクチャを紹介します。チケットを割り当てるか、スレッドで @メンションするだけで、エージェントが要件を読み取り、計画を投稿し、使い捨ての開発マシンを起動して、コードの作成とテストを行い、プルリクエストを開きます。さらに、レビューコメントやCIの結果が届くたびに対応し、プルリクエストがマージされたら自らクリーンアップします。

中心となる考え方は関心の分離です。小さくロックダウンされたオーケストレーターがSlack上で動作し、コードには一切直接触れません。実際のコーディングはすべて、使い捨てのRemote Dev Environments(RDE)に委任します。このアーキテクチャのオープンソースのリファレンス実装である bitclaw は、github.com/bitrise-io/bitclaw-publicで公開されています。詳細については、以下のリファレンス実装を参照してください。

エージェントができることClick to copy link​

Slackでエージェントに送る典型的なリクエストは次のとおりです。

  • すでに完全にロールアウトされたフィーチャーフラグを削除する。
  • CIが成功するまで、停滞しているプルリクエストを進める。
  • 以前のプルリクエストをパターンの参考にして、依存関係をアップグレードする。
  • サポートチケットを調査する。
  • 監視ツールに表示されるエラーメッセージに、より多くのコンテキストを追加する。

エージェントのユーザーにチケットを割り当てるだけで、作業が始まります。エージェントは共有チャンネルに短い確認メッセージを投稿し、その後はマイルストーンでのみスレッドを更新します。マイルストーンは、計画、開発セッションの作成、コードのプッシュ、プルリクエストのオープン、CIの結果、レビューフィードバックへの対応、マージ、クリーンアップの完了です。途中の細かい手順をすべて報告することはありません。

プルリクエストとチケットはどちらも、それらを所有するスレッドに紐付けられます。そのため、レビューコメント、CIの結果、チケットの遷移が発生するたびにセッションへ伝わります。エージェントはこれらのイベントに自律的に反応します。レビュー担当者のフィードバックに対応し、チケット上のフォローアップの質問に答え、マージが完了すると開発環境を破棄してチケットを遷移させます。

同じループは、より大規模で長期にわたる作業にも対応できます。たとえば、数日にわたり、複数回のマージコンフリクトが発生する複数ファイルのリファクタリングでも、人間に求められるのは定期的なレビューだけです。

カスタムオーケストレーターを構築する理由Click to copy link​

このようなエージェントは、ソースコード、認証情報、チケットトラッカー、そして公開リポジトリではオープンなインターネットなど、機密性の高いものすべてに同時に触れます。汎用の既製エージェントでは、特定のチームにとって信頼できるエージェントにするための要素を実装できません。たとえば、どの作成者の発言を受け付けるか、どの操作に人間の承認が必要か、ワークフローにおける「完了」とは何か、といった要素です。

オーケストレーターを自分で所有すれば、こうしたすべてを自分で管理できるコードとして保持できます。具体的には、エージェントが持つツール、システムプロンプトの指示ではなく実行可能なチェックとして記述された信頼ルール、チームの実際の働き方に合わせたワークフローです。

オーケストレーター自体を大きくする必要はありません。小さな単一のサービスで構成でき、コードを実行せずに中継、計画、ツール呼び出しだけを行うため、後に他のエージェントに対して実行することになる、委任、レビュー、マージのループと同じ流れでコーディングエージェントを使ってブートストラップするのに適しています。

基本原則: オーケストレーターはコードを書かないClick to copy link​

この設計には、1つの重要なルールがあります。オーケストレーターはコーダーではありません。

  • 1つのSlackスレッドが1つのセッションに対応し、1つの永続的な会話に支えられています。そのため、メッセージ、Webhook、数日後に届くフォローアップの間でコンテキストが失われることはありません。
  • すべての機能は、範囲を絞ったツールとして提供されます。Slackへの投稿、プルリクエストの読み取りと管理、チケットトラッカーの読み取り、ログとメトリクスのためのオブザーバビリティツールへのクエリ、RDEセッションの作成と操作です。
  • Pull requestsとチケットは、それらを所有するスレッドに紐付けられます。そのため、レビューコメント、CIの結果、チケットの遷移は、適切な会話内のメッセージとして届きます。エージェントはイベントをポーリングで確認するのではなく、イベントに反応します。
  • オーケストレーターにはシェルもファイルアクセスもありません。コードを実行できず、チケットトラッカーやソースコントロールのAPIを通じてソースコードを読み取ることもできません。これらのツールは、プロンプトではなくコードで拒否してください。
Ticket assignment ────┐
Slack @mention ───────┼──► one Slack thread = one session (the orchestrator)
Webhooks (PR, CI) ────┘ │ ▲
│ creates and drives │ review, CI, and ticket
▼ │ events route back
RDE session ───── git push ──► pull request
(coding agent + full toolchain)

Remote Dev Environmentsの位置づけClick to copy link​

コーディングエージェントが必要とする作業は、リポジトリのクローン、パッケージのインストール、ビルドツールやテストスイートの実行、Makefileが指示する内容の実行など、いずれもオーケストレーターの認証情報を保持するマシンでは実行すべきではないものです。代わりに、タスクごとに使い捨てのマシンを用意します。

  • 1つのテンプレート、1回のツール呼び出し。すべてのコーディングマシンを、バージョンを固定した単一のテンプレートから作成します。テンプレートには、スタック、マシンタイプ、そして On create ライフサイクルフックを含めます。このフックで、コーディングエージェントのインストール、gitのみのSSH ID の設定、永続的なターミナルセッションでのエージェントの起動を行います。認証情報は保存済みの入力とセッションの入力で渡します。入力は暗号化され、イメージに組み込まれることはありません。
  • 監視ではなく、指示書を渡す。各セッションは、リポジトリ、チケット、受け入れ基準、ブランチのルールを含む、それだけで完結するタスクの指示書とともに作成します。さらに、行動に関する指示を1つ加えます。入力を待ってブロックせず、最も妥当なデフォルトを選び、その前提をコミットメッセージとpull request descriptionに記録して、作業を続けるというものです。誤った前提は、プルリクエストのレビューで修正されます。
  • セキュリティモデルとしての分離。コーディングエージェントには、プッシュのみが可能なスコープのSSHキーを与え、チケットトラッカーやソース管理プラットフォームへのAPIアクセスは与えません。外部との接点はgitだけです。コードベースに埋め込まれたテキストによってエージェントが操作されたとしても、影響範囲は、人によるレビューを通過する必要があるプッシュ済みのブランチに限られます。オーケストレーターの認証情報がマシンに渡ることはなく、作業が完了するとマシンは削除されます。
  • CIと一致する開発環境。RDEセッションは、CIと同じインフラとスタックで実行します。これにより、「セッションでテストが成功する」ことと「CIでテストが成功する」ことが同じ意味になります。CIが失敗した場合は、失敗したチェックをセッションに伝えることで、コーディングエージェントが一致する環境で再現できます。
  • タスクごとに1台のマシン。複数のチケットを並行して処理する場合は、競合のない、分離された複数の環境を使います。
  • 標準的なツールインターフェース。セッションの作成、操作、削除は、RDE MCPサーバーでの通常のツール呼び出しです。Model Context Protocolに対応する任意のAIエージェントが、同じ方法でセッションを操作できるため、独自の連携を構築する必要はありません。

ベストプラクティスClick to copy link​

実際のリポジトリに対してこのようなエージェントを実行する場合に、必ず守るべきルールを紹介します。

  • ガードレールはプロンプトではなくコードで実装する。 システムプロンプトは動作を誘導しますが、強制はしません。どのツールが存在するか、エージェントが誰のテキストを読めるか、何に承認が必要かは、プロンプトインジェクションでは回避できないハードチェックにしてください。
  • ヒヤリハットはすべてガードレールの欠陥として扱う。 エージェントが承認を確認した途端に自分のプルリクエストをマージしてしまった場合は、以後、マージには人間による明示的な指示を必須にしてください。公開リポジトリでは、信頼できない作成者のテキストをモデルに到達する前に削除し、外部から見えるすべての書き込みを承認または拒否のステップで制限します。
  • 人間は重要な2つの判断に関与する。 マージと、外部から見えるすべての操作です。計画、コーディング、テスト、レビュー担当者への返信は、人間が介在しないほうがうまく機能します。
  • 「停止」を常に機能させる。 停止コマンドは通常のメッセージキューとは別に処理し、実行中のターンの後ろで待たされることなく中断できるようにします。
  • フェイルクローズにする。 作成者が信頼できるか、リポジトリが非公開か、チェックが成功したかを確認できない場合は、安全でない答えであると想定して処理を保留します。
  • 入力作業だけでなく、思考も委任する。 計画のためであっても、オーケストレーターにソースコードを読ませないでください。RDE 内で完全な作業ツリーを前にしているコーディングエージェントが、自分の作業を計画するべきです。タスクにコードの理解が必要になった時点で、そのタスクは RDE に属します。

リファレンス実装Click to copy link​

bitclawは、このアーキテクチャのオープンソースのリファレンス実装です:github.com/bitrise-io/bitclaw-public。MITライセンスで公開されており、そのまま本番環境で実行するのではなく、調べて、必要に応じて改変して使うことを想定しています。マネージドデータベースの代わりにSQLite、プッシュチャネルの代わりにポーリング、通常のログを使用しています。READMEには、各ガードレールと、それが必要になった障害パターンが記載されています。

セットアップは段階的です。数分で動作を確認でき、そこからコーディングエージェントへと拡張できます。

段階設定するものエージェントができること
1. ChatSlackアプリとAnthropic APIキーSlackでメンションされたときに応答する
2. CodeBitriseトークン、workspace、RDEテンプレートリポジトリのクローン、コードの作成、ブランチのプッシュ
3. ShipGitHubトークン、信頼できるOrg、Webhookプルリクエストの作成、レビューやCIへの対応、承認を受けてのマージ

段階1は、environment variablesが3つのdocker runだけで構成されます。

docker run -it --rm \
-v bitclaw-data:/data -v bitclaw-claude:/home/app/.claude \
-p 8080:8080 \
-e SLACK_BOT_TOKEN=xoxb-your-bot-token \
-e SLACK_APP_TOKEN=xapp-your-app-token \
-e ANTHROPIC_API_KEY=sk-ant-your-api-key \
bitriseio/bitclaw-public:latest

段階2が、このリポジトリが存在する理由です。docs/rde-template.mdガイドでは、コーディングエージェントのテンプレート(セットアップスクリプトと少数の保存済みの入力)の作成手順を説明しています。これを実行すると、ボットが実際のコーディング作業をRDEセッションに委任します。

独自の脅威モデリングを行ってください

bitclawのガードレールは実際のインシデントを踏まえて構築されていますが、あくまでリファレンスであり、保証ではありません。自律型エージェントをリポジトリに接続する前に、セキュリティモデルを確認し、自社の信頼境界に合わせて調整してください。

次のステップClick to copy link​