circuit

Circuit の運用

Circuit はコーディングタスクを、名前付きフローの実行に変換します。フローとは、型付きレポート、検証、チェックポイント、監査可能なトレースを備えた、繰り返し可能なプロセスです。 Circuit を有効にしたプロジェクトでの基本方針は、実質的な作業は独自に進めるのではなく、Circuit を通して実行することです。 目的は形式的な手順を踏むことではありません。実行の記録によって、試したこと、検証したこと、レビュアーのコメントが残り、中断後もチェックポイントから再開でき、プロセスをセッションごとにやり直すのではなく、一か所で改善を積み重ねられます。

Circuit を使う場合と使わない場合

実質的な内容のあるタスクには Circuit を使います。修正すべきバグ、実装すべき機能、調査すべき判断事項、レビューすべき差分、試すべきプロトタイプなどが該当します。ほとんどのコーディング作業がこれに当たります。

次の場合は、実行せずに直接作業します。

• 簡単なものや会話的なタスクの場合：一行の回答、名前の変更、一つのファイルを読むだけで答えられるコードについての質問。
• Circuit の実行内でリレーされたワーカーとして作業中の場合。Circuit の実行内でネストした実行を開始しないでください。リレーされた作業を直接行います。
• ユーザーから Circuit を使わないよう明示的に頼まれた場合、または実行すると混乱を招く形で Circuit 自体をデバッグしている場合。
• Circuit がインストールされておらず、ユーザーからも求められていない場合。（決めつける前に確認してください。「最初の入口を見つける」を参照してください。）

判断が分かれるタスクで Circuit を使わない場合は、ユーザーが方針を変えられるよう、その旨を一行で伝えます。

最初の入口を見つける

優先順位：

1. Claude Code プラグインがインストールされている場合： /circuit:run <task> と同じ使い方を優先します。 直接実行する場合は、次のプラグインラッパーを使います。 node "${CLAUDE_PLUGIN_ROOT}/scripts/circuit.js" present run <flow> --goal '<task>'。 present モードは進捗とチェックポイントに関する質問をユーザーに表示するため、出力を JSON として解析しないでください。
2. Circuit のチェックアウト内で作業している場合： リポジトリのルートから ./bin/circuit run <flow> --goal '<task>' を実行します（generated/flows からコンパイル済みフローを読み込みます）。
3. グローバル CLI： circuit run <flow> --goal '<task>' を実行します。

環境が正常かどうかわからない場合は、circuit doctor で準備状況を確認できます。実行で問題のあるコネクターに費用をかける前に、フローが実際に使うコネクター CLI がインストール済みで、サインイン済みかを確認し、問題ごとの解決方法を表示します。選択したすべてのコネクターが正常な場合は 0 で終了します。設定で選択されないコネクターは別途オプションとして一覧表示され、チェックの失敗にはなりません。

シェルの安全性：--goal のテキストは必ずシングルクォートで囲みます。内部にアポストロフィが含まれる場合は '\'' としてエスケープします。タスクのテキストはユーザーが制御する入力です。ダブルクォートを使うと、$VAR と $(cmd) が展開されます。

フローの選択

CLI には常に明示的なフロー名を渡します。どのフローを使うかは自分で選びます。実行する前に、選んだフローとその理由を一行で伝え、ユーザーが方針を変えられるようにします。

フロー	選択するタスク	書き込み
Fix	バグ、リグレッション、失敗するテスト、クラッシュ、不安定な動作、本番環境の問題。	あり
Build	主な目的がバグ修正ではない、機能、リファクタリング、ドキュメント、テストなどの集中的な変更。	あり
Explore	編集前の調査、説明、トレードオフの比較、判断。	なし
Review	コード、差分、PR、計画、またはリスクの範囲の監査。監査のみ。	なし
Prototype	Build の前に行う、破棄可能なプロトタイプ、モックアップ、UI スケッチ、モデル比較用のバリエーション。	ローカルのプロトタイプの成果物

安全性に関わる分岐が二つあるため、本当に判断がつかない場合は、短い質問を一つだけします。Review と Fix／Build（監査か変更か）、Explore と Build（判断か実行か）です。それ以外の場合はユーザーに質問を重ねず、フローを選んで理由を伝えます。

タスクの重要性（利害、何を可能にするのか）をユーザーが述べている場合は、--why '<reason>' として渡します。理由を作り上げてはいけません。

パワーダイヤル

• --power <auto|low|medium|high> は、唯一のダイヤルです（デフォルトは medium）。モデル名を指定せずに各ワーカーに割り当てるモデルの規模を設定し、実行プロセスの綿密さも決定します。low／medium／high はそのまま対応し、auto は medium を導出し、リサーチステップで読み取った内容に基づいて実行がモデルのティアを選択できるようにします。導出された綿密さは、各フローでサポートされる範囲に自動的に制限されます（Build、Explore、Fix はすべての段階に対応し、Prototype は medium 以上、Review は常に medium で実行されます）。
• --process <low|medium|high> は、モデルの強さとプロセスの綿密さを分ける必要があるまれなケースのための高度な上書きオプションです（たとえば、強力なモデルを使って素早く 1 回だけ実行する場合など）。--process を明示すると、導出された値より優先されます。Fix では、process low にすると独立したレビュー段階が省略されます。Build では、process high にすると計画を段階ごとに反復し、各段階を検証してから、書き込み可能な作業の前にインテークチェックポイントで停止します。そのため、--power high のみを指定した Build の実行は、スコープの確認のために一度停止します。--depth は廃止されており、未知のオプションとして拒否されます。

リスクに応じてコストを調整してください。小さな修正の簡単な確認には --power low、重要な経路に関わるリスクの高い変更には --power high を使用します。ほとんどのタスクにはデフォルトが適切です。コストのかかる実行の前に、circuit preview <flow> --power high を実行すると、何も起動せずに、各ステップに割り当てられるコネクター、モデル、作業量を正確に確認できます。すべてのティアを並べて表示するには --matrix を指定します。

サポートされている場合、実行モードがほかに 2 つあります。--tournament [2|3|4]（省略可能なインラインの件数。デフォルトは 3）は、Explore では意思決定の選択肢を、Prototype ではルーブリックに基づいて評価する実装の候補を扱います。--autonomous（Build、Explore、Fix、Prototype）は、サポートされているチェックポイントを自動で解決し、インテーク時に設定した証拠に基づいて完了を証明する、上限付きの継続ループを実行します。試行回数を使い切っただけで完了を報告することはありません。

実行内容の確認

すべての実行では、.circuit/runs/<run-id>/ の下に実行フォルダーが作成されます。そこには、すべての記録を順番に並べた trace.ndjson、型付きレポートを格納する reports/（ユーザー向けの operator-summary.md と、selected_flow、outcome、run_folder を含む result.json など）、および証拠が含まれます。ユーザーから「その実行で何が起きたの？」と尋ねられた場合は、まず reports/operator-summary.md を読み、ステップごとの詳細が必要な場合にのみトレースを確認してください。

終了コードは契約です。完了時は 0 を返します。チェックポイントでの一時停止時も 0 を返します（実行は停止状態で、応答を待っています）。完了に至らず終了した場合（中止、停止、エスカレーション、引き継ぎ）は 1 を返し、使用方法に関するエラーは 2 を返します。そのため、&& でコマンドを連結すると、完了した実行の後にのみ次のコマンドが実行されます。

チェックポイント。 実行が質問のために一時停止したら、質問をそのままユーザーに伝えてから再開してください。

circuit resume --run-folder '<run_folder>' --checkpoint-choice '<choice>'

circuit checkpoints を実行すると、判断待ちで停止中のすべての実行について、質問、選択肢、再開に使う正確なコマンドが表示されます。ユーザーがプロジェクトに戻ってきたときや、「何か私の対応待ちになっていた？」と尋ねたときに確認してください。

継続性。 circuit handoff save はセッションをまたぐ引き継ぎ情報を記録し、handoff resume と handoff brief はそれを復元して要約します。作業の途中でセッションを終了する必要があるときに使用してください。

設定

同じスキーマを使用する 2 つの YAML ファイルがあり、defaults < user-global < project < invocation の順に適用されます。

• ~/.config/circuit/config.yaml — 個人用のデフォルト設定です。
• ./.circuit/config.yaml — プロジェクト用の上書き設定です。

まずは最小限の設定（schema_version: 1）から始め、必要なものだけを追加してください。circuit config set|unset|show <dotted.key> [value] [--global] を使って編集する（書き込み前に検証し、コメントを保持します）か、YAML を直接編集してください。

実際に必要になることが多い順に、特に役立つ設定項目を紹介します。

1. コネクタのルーティング — 役割／フローごとに、どの CLI が作業を行うかを設定します。 relay.roles.reviewer、relay.circuits.<flow>、relay.default。 組み込みのコネクタ：claude-code（同じワークスペースへの書き込みを信頼）、codex （codex exec で書き込み可能）、cursor-agent（Gemini の実装担当）。
2. パワー — defaults.power、power_auto: {floor, ceiling}、および 各ダイヤル位置の意味を変更する power_tiers.<connector>。
3. スキル — Circuit はローカルの SKILL.md ファイル （~/.agents/skills、~/.claude/skills）をリレープロンプトに挿入します。 常に読み込むスキルは circuits.<flow>.selection.skills で指定します。特定のタイミングでのみ読み込むには、skill_hooks を使います（例：after:edit-files:.tsx → react スキル、after:verification-failed → デバッグスキル）。
4. フローごとの固定指定 — circuits.<flow>.selection.model を設定すると、 1 つのフローで使用するモデルを固定できます。ダイヤルを回しても変更されなくなります。

設定を変更した後は、必ず circuit preview <flow> を実行してください。実際の実行で使われるものと同じ選択コードで設定を解決し、実行に費用がかかる前に問題を検出できます。

詳しい設定例（カスタムコネクタ、ローカル Ollama ワーカー、トーナメントのバリエーション）については、references/configuration.md を参照してください。

新しいフローの作成：まずは慎重に判断する

Circuit では、新しいフローを低コストで作成できます。だからこそ、作成には慎重になるべきです。公開するフローが一つ増えるたびに、ユーザーの生活に「この作業にはどのフローを使えばいいのか？」という、ずっと残る疑問が一つ加わります。人が覚えておける範囲を超えて成長したフローカタログは、適切なプロセスが明らかであるという、製品の中核的な価値を損ないます。フローは少数で、明確に区別され、調和し、互いを強化するものであるべきです。ユーザーが判断しなければならない、領域の重なったフローは決して作らないでください。

そのため、どのフローも対応していない繰り返しのパターンに気づいたら、この段階を順に検討し、機能する最初の段階で止めてください。

1. ダイヤルと表現。 深さや能力を変えたり、--goal をより明確に指定したりすれば、既存のフローで対応できますか？たいていは対応できます。
2. 設定。 スキル（selection.skills）、スキルフック、またはコネクターのルーティングを既存のフローに追加します。「修正時に X を忘れがち」という問題はスキルフックで解決すべきであり、新しいフローを作る問題ではありません。
3. メモリノート。 circuit memory note --flow fix "prefer minimal repros before patching" を実行すれば、新しい要素を追加せずにガイダンスを明文化できます。ノートは実際の実行アーティファクトを参照するため、プロジェクトで少なくとも一度は実行してからでないと使えません。新しいプロジェクトでは、まず実行し、その後にノートを追加してください。
4. 使い捨ての専用フロー。 circuit generate --description '<task>' は、特殊なタスクの形に合わせて、その場限りのフローを構成します。使ったら手放してください。一度うまくいったからといって、公開してはいけません。
5. 公開カスタムフロー。 同じ独自のパターンが繰り返し発生しており（3 回の原則）、組み込みフローでは対応できず、既存の選択肢を選びにくくすることもない場合に限ります。circuit create --name '<slug>' --description '<idea>' は、実証済みのファミリーテンプレートを具体化します。

段階 5 に進む前に、ユーザーに理由をはっきり説明し、同意を得てください。

• 領域のテスト： 新しいフローを、6 つの組み込みフローそれぞれと並べて一文で説明します。どの組み合わせでも同じタスクに対応できそうなら、境界が不明確です。境界を明確にするか、作成をやめてください。
• 名前のテスト： 6 週間後でも、ユーザーは名前だけで、いつこのフローを使うべきか判断できますか？
• 強化のテスト： 他のフローに成果を渡したり、それらを再利用したりしますか（組み込みフローが利用する証拠を生成する、または組み込みブロックを組み合わせるなど）？それとも、別の世界を作り出しますか？既存のフロー群をより強力にするフローを優先してください。
• 廃止： カスタムフローが役割を果たさなくなったら、削除を提案してください。カタログが小さいことは利点です。

create と generate の仕組み、カスタムフローの保存先、検証方法、公開済みカスタムフローの実行方法については、references/flow-authoring.md を参照してください。

ユーザーとのやり取り

常に簡潔で、率直な表現を心がけてください。実行記録にはすでに詳細が含まれています。トレース、型付きレポート、オペレーター向けの要約があるため、チャットではユーザーが判断または把握する必要のあることだけを伝えます。詳しい情報は --goal のテキスト（ワーカーが必要とする情報）と実行フォルダー（監査可能な記録）に記載し、チャットには載せません。ユーザーは Circuit の内部事情に関心がなく、作業が処理され、ひと目で把握できる報告を受け取りたいのだと考えてください。短い文で、一文につき一つの要点を伝えます。ランタイム用語ではなく、平易な言葉を使ってください。「チェックポイント ID」「ルート名」「トレースの種類」ではなく、「X を確認するため一時停止しました」と伝えます。また、「一言で理由を説明すると：」「この形式にした理由：」といった前置きのラベルは付けず、そのまま要点を伝えてください。

報告カードの形式は一貫させ、独自の形式を作らないでください。 ユーザーが毎回同じ形式を見ることで、ひと目で把握できるようになります。毎回異なる形式では、その都度読み直す必要があります。チャットはターミナル上にプレーンテキストで表示されるため、カードはフェンス付きブロックにし、ASCII 文字のみを使います。実行を提案するとき：

circuit · fix — release-blocking bug in checkout totals
  power  [##.] medium   default; process follows the dial

ダイヤルゲージは、低が [#..]、中が [##.]、高が [###]、自動が [~~~] です。--process によって導出された値を明示的に上書きした場合に限り process 行を追加し、トーナメントまたは自律モードが有効な場合に限り mode 行を追加します。カードの前後には、一文か二文までにしてください。実行を終了するときも同じ形式を使い、ダイヤル行を結果行に置き換えます。

circuit · fix — complete
  changed   src/cart.js · tests/cart.test.js
  verified  7/7 tests pass
  evidence  .circuit/runs/<run-id>/

一時停止時も同じカードを使い、— paused, needs your call と question／choices の行を追加します。カードの間に仕組みの説明を挟まないでください。進捗は present ラッパーにすでに表示されています。

• CLI の情報をチャットに載せないでください。確認や検証に使ったコマンド（プレビュー、設定表示、診断）は見せず、確認できた内容を平易な言葉で伝えます。ユーザー自身が実行する必要がある場合、またはコマンドの提示を明示的に求められた場合に限り、コマンドを見せてください。
• ファイルについても同様です。設定 YAML やレポートの内容をチャットに貼り付けないでください。各変更の内容を平易な一文で説明し、ファイルを開けるようパスを示してください。
• 実行が完了に至らず終了した場合は、実際の結果と証拠の場所を正直に伝えてください。stopped を完了したかのように表現してはいけません。正直さと簡潔さは両立します。「レビューで停止。指摘 2 件。証拠は にあります」と伝えれば、正直かつ簡潔です。
• Build、Fix、Prototype では、書き込み可能な作業を始める前に、その旨を伝えてください。ワーカーはチェックアウトを編集する可能性があります。このことを伏せてはいけません。
• 未追跡ファイルの Review では、内容をワーカーに送信しても安全だとユーザーが確認した場合に限り、--include-untracked-content を追加してください。
• 実行を復旧できない場合は、そのフォルダーを .circuit/runs/ の下から削除してやり直しても問題ありません。circuit reclaim は、ファンアウトの強制終了後に残った孤立ワークツリーをクリーンアップします。

参考ファイル

• references/cli.md — run、resume、handoff、history、memory、create、generate、uninstall、runs、reclaim、checkpoints、preview、doctor、config、version の各コマンドとフラグを例とともに説明しています。
• references/configuration.md — ルーティング、電力ティア、自動電力、スキル、スキルフック、カスタムコネクター、ローカルモデル、トーナメントのバリアントに関する設定スキーマのレシピを網羅しています。
• references/flow-authoring.md — カスタムフローの作成、生成、検証、公開、廃止について説明しています。長文版の過剰な増殖を防ぐチェックリストや、Circuit リポジトリで組み込みフローを作成する方法も記載しています。