C4 Plan
人間は計画の構造と境界を理解し、AI はチャットで承認を得てから実行します。このスキルは計画そのものを置き換えるものではなく、計画の視覚的な層と実行のためのブリーフを生成します。
また、kind: system を使用して現在のシステムを文書化することもできます。これは同じ図とフローを使用しますが、ステータスやステップ、承認プロセスはありません。セクション 5 を参照してください。
チャットが真実の源です。 ビューアーは計画を表示するだけであり、人間はそこで編集することはできません。疑問や変更要求はコメントとして（またはチャットに貼り付けて）届き、あなたはチャットで応答し、すべての変更は YAML を通じて行われます。
あなたは HTML を書いたり、URL を手動で組み立てたりすることはありません。YAML を書き、スクリプトが検証し、リンクを生成し、ブリーフを生成します。
計画 ─► arch.yaml ─► エンコード ─► リンク ─► 人間が確認・コメント ─► YAML を調整 ─► チャットで承認 ─► ブリーフ ─► 実行
スクリプト: python3 <dir-da-skill>/scripts/arch_url.py (stdlib + PyYAML のみ; jsonschema はオプション)。
1. 計画から arch.yaml を生成する
計画と同じ場所に <計画名>.arch.yaml として保存します。スキーマ: schema/arch.v1.json。完全な例: examples/pix.arch.yaml。
ルール:
- 対象はシステム全体ではなく、計画のアーキテクチャです。 計画が作成、変更、削除するものと、理解に必要な最小限のコンテキスト（誰が呼び出すか、誰が呼び出されるか）を含めます。システム全体をモデル化しないでください。
status:new/changed/removed/unchanged(デフォルト)。コンテキスト要素はunchangedのままにします。- C4 階層: ルートに
person、system、external。system内（またはルート）にcontainer、database、queue。container、database（テーブル、マイグレーション）、queue（イベント）内にcomponent。component内にのみcode。 - 計画が作成または変更するものはすべてコードレベルまで開きます。
statusがnew/changedのすべてのsystem、container、database、queue、componentは、codeまで下がるchildrenを持ちます（validateが不足を警告します）。変更されないものは閉じたまま: コンテキストとして扱います。 - レベル 4 (
code): 計画が作成または変更するファイル、クラス、モジュール、関数をpathとともに記述します。既存ファイルが変更される場合はstatus: changedとします。変更するものだけをリストアップし、コンポーネント全体のコードではありません（通常、コンポーネントあたり 2～4 で十分です）。 - 関係は最も具体的な要素を結び付けます（code が存在する場合は code → code）。ビューアーは上位レベルに集約します。
steps: 計画の各ステップに対応し、同じ順序とタイトル。touches= そのステップが作成または変更する要素。flows: 計画適用後のシステムの動作を示します（stepsは構築順序、flowsは実行順序）。1 ～ 3 つのフロー: 主要パスともう一つ重要な障害パス（例：「顧客が PIX で支払う」「QR コードが期限切れになる」）。各hops[]は{from, to, label}で、既存の関係に従い、その方向または応答の逆方向である必要があります。最も具体的な要素（code）を使用し、labelには関係名ではなく、何が起こるかを記述します（例：「PSP を呼び出す前に txid を保存する」）。ビューアーは各ホップのレベルに自動的に降りていきます。constraints: 実装が尊重する必要があるもの。検証可能なルール（「txid による冪等性」「追加的なマイグレーション、テーブルロックなし」）であり、説明ではありません。重要な決定が行われる場所に配置します: 契約、外部システムとの境界、セキュリティ、データ、マイグレーション、中心的なビジネスルール。制約がないものは実行時のあなたの裁量に委ねられます。- リポジトリに契約が存在する場合は、
relations[].contractで参照します。
2. リンクを検証して提供する
python3 scripts/arch_url.py encode <計画>.arch.yaml
- エラー: YAML を修正して再実行します。検証を通過しないリンクは提供しないでください。
- 警告: 意味がある場合は修正します（例：コードレベルまで開いていない新しい要素）。
- リンクを 1 行で人間に提供し、計画が何を変更するかの短い要約を添えます（例：「3 つの新しい要素、2 つの変更された要素」）。人間は C（または コメント）を押してカードをクリックし、質問や変更依頼ができること、承認はこのチャットで行うことを伝えます。
ビューアー: encode は公開バージョン（https://gustavorana25.github.io/c4-model-skill/）へのリンクを生成します（静的; 計画は #hash に含まれ、サーバーには送信されません）。$C4PLAN_VIEWER_URL でホストを変更でき、--local はローカルビルドの viewer/dist/index.html を使用します（ビューアー自体の変更テスト用）。
2b. 組み込みブラウザがある場合: ページを監視する
ブラウザツール（Claude Code のブラウザパネル、Cursor のブラウザ、Chrome 上の Claude）がある場合、リンクを提供するだけでなくそこで開き、人間が計画を確認している間ページを監視します。
チャットが真実の源です。 ページは単なるショートカットです: 人間は 1 つ以上のカードを指してコメントし、あなたはチャットで応答し、ページでは応答しません。ページで変更する唯一のものは、会話が構造を変更した場合の load() による計画です。
encode が生成したリンクをそのまま開きます。それ自体が https:// です。（--local の場合は、viewer/dist/ を http:// で提供します。例: python3 -m http.server; 一部の組み込みブラウザは file:// リンクの #hash を破棄します。）
ページは window.c4plan を公開します（ブラウザの JavaScript ツールで実行します）:
| 呼び出し | 動作 |
|---|---|
await c4plan.next(30000) | 最大 30 秒、次のイベントを待機します。イベントまたは null を返します。最大時間は 40 秒です（ツールは約 45 秒で切断されます）。 |
await c4plan.state() | 現在の状態: url、plan、focus（開いているレベル）、selected（人間が見ているもの）、idleMs（ページ操作がない時間）、doc。 |
c4plan.load(urlOuHash) | ページをリロードせずに図を新しいバージョンに切り替えます。 |
c4plan.stop() | 監視を終了したことをページに通知します。 |
next() のイベント:
{event:"comment", targets:[{id,name}], view, text}: 人間がこれらの要素についてコメントしました（0、1、または複数;viewは開いているレベル）。チャットで応答し、名前を先頭に付けて開きます:「API Pix と Fila de liquidação について: …」。変更要求の場合は、YAML を変更し、encodeを実行し、load(新しいリンク)を呼び出し、何が変更されたかをチャットで伝えます。その後、監視を続けます。{event:"stop", reason:"idle"}: 人間が 10 分間ページを操作せず、監視が自動的に終了しました。終了メッセージ（ステップ 3）を言ってループを終了します。
ループ:
- 開始する前に、チャットで 1 行で伝えます: 「図をブラウザで開き、操作を監視しています。C（またはコメント）を押してカードをクリックし、コメントを入力してください: ここで応答します。すべて問題なければ、ここで承認してください。」 この通知がないと、人間はページを操作してもチャットに何も表示されず、何が起こっているのか理解できません。
await c4plan.next(30000)を繰り返し、各イベントを処理します。nullは単に「まだ何もない」ことを意味します: 再び呼び出し、チャットにはコメントしません。監視は人間がページとやり取りしている間続きます（クリック、キー入力、スクロールのたびにタイマーがリセットされます）; 終了を決定するのはページで、stopで行われます。stopが届いたら停止します。stopでは、チャットで伝えます: 「操作がないため図の監視を停止しました。必要なときはチャットでコメントするか、再度監視を要求してください。」 他の理由で早期に停止する必要がある場合は、c4plan.stop()を呼び出して同じメッセージを伝えます。- 監視中に人間がチャットでメッセージを送信した場合、ループは終了します: メッセージに応答します。その後、
(await c4plan.state()).idleMsを読み取ります: 10 分未満の場合は、人間はまだページにいるため、再通知なしでループに戻ります。承認された場合は、c4plan.stop()を呼び出してセクション 3 に進みます。 - 人間がチャットで「これ」や「この要素」について質問した場合は、
state().selectedを読み取って何について話しているかを確認します。 - あなたが監視していない場合、コメントボタンは
Sobre "API Pix" (pix-api) no diagrama: …のようなテキストをコピーし、人間がチャットに貼り付けられるようにします。括弧内の ID は YAML のものです。
3. 人間がチャットで承認した場合
人間だけが承認でき、チャットでのみ行われます（「承認」「進めて」「OK、実行して」）。沈黙、監視終了、コメントがないことは承認ではありません。
<計画>.arch.yamlにapproved: trueをマークし、ファイルからブリーフを生成します:python3 scripts/arch_url.py brief <計画>.arch.yaml -o <計画>.arch.md- 会話によって最初のリンクから何が変更されたかを数行で要約します（制約、構造、フロー）。
- 計画に
<計画>.arch.mdへの参照を追加し、実行に進みます。
人間がビューアーのリンクを貼り付けた場合（例えば通常のブラウザで開かれたもの）、それは参照用のみです: 有効なバージョンはあなたの <計画>.arch.yaml です。
4. ブリーフを尊重して実行する
<計画>.arch.md は実行中必須です:
- 構造（要素、関係、フロー）とすべての制約に従います。実装が構造の変更や制約の違反を必要とする場合は、停止して質問します。
- 参照された契約 (
contract) は、質問なしでは変更しません。 - 制約の範囲外では、最も単純なものを優先し、既存コードのパターンに従います。
- 人間がチャットで要求したことは、あなたの元の提案より優先されます。
- 最後に、実装されたものを YAML と比較し、差異を報告します（予期しない新しいコンポーネント、関係外の依存関係、変更された契約）。
5. 現在のシステムを文書化する (kind: system)
要求が既存のものを理解または文書化することである場合（「アーキテクチャを文書化」「このシステムの仕組み」「オンボーディング」）、計画はありません: リポジトリを読み、同じ YAML を kind: system で生成します。完全な例: examples/loja.arch.yaml。
version: 1
kind: system
title: オンラインストア
description: システムが何をするかの 1～2 文。
組み立て方:
- 書く前に読みます。 エントリポイント（ルート、ハンドラ、コンシューマ、ジョブ）、マニフェスト（
package.json、docker-compose、インフラ）、マイグレーション、外部サービスクライアントが、コンテナ、データベース、キュー、外部システムを示します。コードが示さない部品を発明しないでください; 不確かな場合はチャットで伝えます。 status、steps、approvedはありません。 すべてが現在のシステムです（validateが残っている場合に警告します）。- フローが主体です。 2～4 つ: ビジネスに最も重要なパス、主要なバックグラウンドタスク、最も一般的な障害ケースです。これらによって、新しい人がシステムを理解します。
- 深さ: 実際の
path（ファイルが存在することを確認）を使用して、フローが通過するものだけをcodeまで下げます。残りはcontainerまたはcomponentで閉じたままにします。 constraintsは、関わる人が知っておくべきハウスルールになります（冪等性、各テーブルに書き込める人、変更できない契約）。- 関係とフローは計画と同じルールに従います（セクション 1）。
提供: encode は計画と同様にリンクを生成します。「5 つのコンテナ、2 つの外部システム、2 つのフロー」のようにシステムの内容を 1 行で伝え、フロータブでフローをたどり、C で質問できることを伝えます。ブラウザがある場合は、ページを監視します（セクション 2b）: コメントは質問であり、あなたはチャットで応答するか、文書の修正として YAML に適用し、load() でリロードします。
リポジトリにバージョン管理可能なテキストとして保存するには、brief が Markdown 文書（要素、関係、フロー）を生成します:
python3 scripts/arch_url.py brief docs/arquitetura.arch.yaml -o docs/arquitetura.md
後で、このシステムに関する計画はこの YAML から開始できます: コピーし、kind を plan に変更し、変更するものを status でマークします。