VK Orchestrator

このツールでできること

あらゆる開発を全自動処理！

動作環境

Operating environment

このツールを動かすには次の環境が必要です。

• macOS、または Windows の WSL2（WSLg）上の Ubuntu
• Node.js 20 以上 （導入方法はこちら）
• Claude Code（未導入なら npm install -g @anthropic-ai/claude-code）
  Max 5x プラン以上推奨
• GitHub のアカウントと基本的な GitHub の操作の知識

Node.js が 20 未満の場合 — npm start は処理を始める前に停止し、必要なバージョン・実行中のバージョン・導入方法を表示します。案内に従って Node.js 20 以上を入れ、ターミナルを開き直してから（node -v で確認）やり直してください。

WSL Ubuntu で動かす場合 — システム依存ライブラリの導入・GPU 設定・トラブルシューティングを含む、まっさらな環境からの手順を docs/WSL-UBUNTU-SETUP.md にまとめています。

システム構成

本システムは以下の３つで構成されています。

• VK Orchestrator : issue 処理の進捗制御システム
• VK Agents : issue を処理するための Claude Code のスキル・ルールセット一式
• VK Terminals : issue 処理のタスクを実際に動かす GUI アプリケーション
  ※ GUIの VK Terminals はオープンソースで無料で公開しています。

使い方

How To Use

STEP

01

作業対象の issue に 自分をアサインしてtask-queue ラベルを付ける（依頼を出す）

処理してほしい作業を、作業対象リポジトリの GitHub issue として書き、自分をアサインして task-queue ラベルを付けます。

issue の書き方に決まりはありません。普段チームで issue を書くときと同じように、やってほしいことを書けば大丈夫です。ただし曖昧な指示の場合は設計に AI トークンを多く消費したり、仕様提案・ユーザー確認が必要になってユーザーの判断待ちで自動処理が一時停止します。具体的な指示や完了条件を記載しておくとスムーズに進みます。

出先からでも、GitHub のモバイルアプリなどで issue を作ってアサインとラベルを付けるだけで依頼を出せます。

PC上で Orchestrator が動いていれば、Orchestrator がその issue を自動処理の対象として拾い、タスクリストに登録します。

ただし、この時点ではまだ自動処理は始まりません。タスクは「承認待ち」の状態でタスクリストに並びます。

※ オーケストレーターが task-queue ラベル付きの issue を巡回して取り込むまで若干時間がかかります。巡回間隔は設定画面から指定できますが1分程度が推奨です。

STEP

02

実行方法を決めて「実行待ち」にする（処理を始める）

VK Orchestrator のサイドバーのタスクリストで、登録されたタスクに対して次を指定します。

指定すること	選択肢	意味
実行のしかた	並列 / 直列	同一リポジトリの他のタスクと同時に処理してよいか、順番に 1 つずつ処理するか
マージのしかた	自動マージ / 手動	作業とレビューが完了したあと、自動でマージするか、人がマージするか
優先度	高 / 中 / 低	直列実行における同一リポジトリの issue の処理の優先度

※ GitHub モードの場合は、タスク管理用リポジトリの issue のラベルからも指定する事ができます。

指定したら、タスクのステータスを「実行待ち」に変更してください。これで処理が開始され、ペインが開いて作業が始まります。

AI の振る舞いをカスタマイズする

現状、issue を処理する時のスキルやルールは弊社で運用している設定になっていますが、当然ユーザーや組織によって各種設定は異なりますので、独自の設定に差し替える事ができるようになっています。

• 既存の VK Agenst を部分的にカスタマイズする場合
• 完全に独自の issue 処理スキルを使う場合

VK Agents をカスタマイズする場合

VK Agents は、各ペインで動く Claude Code に持たせるスキル・ルールなどのセットです。

VK Agents は本体に同梱されている vendor/vk-agents-public/ の中にあり、、初回セットアップのときに Claude Code の設定（~/.claude/）へ自動で展開されます。 

その後アップデートで新しい VK Agents が同梱されたときも、npm start の起動時に自動で展開し直されるため、普段は何もする必要はありません。

自分用のスキル・ルールに差し替える

チームの進め方に合わせて、コーディングルールや PR の書き方などを変えたくなることがあります。その場合は、差し替え用のディレクトリに、変えたいファイルだけを置いてください。 そのファイルが本体の代わりに使われます。

置き場所は ~/.vk-agents/overrides/ です（自分で作成してください）。本体と同じディレクトリ構成・同じファイル名で置くのがルールです。

~/.vk-agents/overrides/
├── rules/
│   └── css.md              ← CSS のルールだけ自分用に差し替える
└── skills/
    └── vk-pr/
        └── SKILL.md        ← PR 作成スキルだけ自分用に差し替える

置いていないファイルは本体のものがそのまま使われるため、変えたいファイルだけを置けば大丈夫です。差し替えたファイルはアップデートで上書きされません（差し替え用ディレクトリの中身は読み取られるだけで、書き換えられることはありません）。

いくつか注意点があります。

• 追記ではなく、ファイルまるごとの置き換えです。本体のファイルの内容に自分の記述が足されるのではなく、置いたファイルの内容だけが使われます。元のファイルをコピーして、必要な箇所を書き換えるのが確実です。
• 差し替えられるのは rules/ ・ skills/ ・ agents/ ・ vk-agents-personas/ の中のファイルです。
  skills や agents はオーケストレーターと連携する部分もあるため、実質 rules の差し替えが現実的な運用ラインです。
• 本体に無いファイル名を置いても使われません（本体のどのファイルを差し替えるのかが決まらないため）。
• rules/ の一部のファイルは差し替えの対象外です（対象外になるファイル）。対象外のファイルを置いた場合は、起動時のログにその旨が表示されます。
• なお、~/.claude/ に展開されたファイルを直接書き換えるのは避けてください。次回の展開で上書きされて元に戻ります。

元のファイルは、本体に同梱されている vendor/vk-agents-public/ の中にあります。差し替えたいファイルをここからコピーして使ってください。

完全に独自の issue 処理スキルを使う場合

まずは issue を処理してプルリクを出すまでのスキルを作ってください。デフォルトの issue 処理スキルは 同梱ファイル内の vendor/vk-agents-public/skills/vk-kore/の中にあります。

オーケストレーターと連携するための決まり事（オーケストレーター経由のタスクに Claude Code エージェントがどう振る舞うべきか（automerge での停止禁止・エージェントレビュー完了マーカー（`agent-review-passed`）の付与責務・メタ issue クローズの責務など）は docs/agent-rules.md を参照してください。

その他詳細な技術仕様は同梱の README.md を確認ください。