Archyl Harness

コーディングエージェントはリポジトリを完璧に把握していますが、アーキテクチャについてはまったく知りません。別のエージェントがちょうど今リファクタリングしているサービスを書き換え、2 年前にチームが ADR で禁止した依存関係を持ち込み、すでに存在しないシステムを説明したままのドキュメントを残していきます。

Archyl Harness はこれを解決します。Claude Code、Codex、Cursor、CI ボット、Archyl 自身のマネージドエージェント — どんなコーディングエージェントであっても、ドキュメント化されたアーキテクチャの上に構築された統制されたループで包み込みます。

ブロック 役割 ツール
Context タスクに関連するアーキテクチャの断片だけをエージェントに渡します — 要素、意思決定、Guardrails、オーナー find_relevant_context
Plan 機能要望を、C4 モデルと ADR を尊重した実装計画に変換します plan_work
Guard 適合性ルールに違反する変更を、書き込まれる前にブロックします Guard フック + run_conformance_check
Evolve ループを閉じます。作業結果は要素のメモリとなり、アーキテクチャ変更リクエストのドラフトがモデルを同期させ続けます finish_work_session

エージェントが実行するループ:

plan_work ──▶ start_work_session ──▶ code (Guard watches every write)
                                          │
finish_work_session ◀─── heartbeat ◀──────┘
      │
      ├─▶ leases released
      ├─▶ outcome pinned to the touched elements (memory)
      └─▶ draft Architecture Change Request (optional)

また、すべてのセッションは触れた C4 要素に対してアドバイザリーリースを取得するため、同じサービスで作業する 2 つのエージェントは衝突する前に互いを認識します — それぞれのブリーフィングの中で、そして図の上でリアルタイムに。

設計としてオプトイン

ハーネスはオプトインです。アーキテクチャを文書化しただけでは何も有効になりません。エージェントがこのループに入るのは、次の三つのいずれかを行ったときだけです — MCP サーバーを ?profile=coding で接続する、プロトコルを教える archyl-harness スキルをインストールする、Guard フックを追加する。これらを元に戻せば、そのリポジトリのエージェントは以前とまったく同じように振る舞います。

Archyl のそれ以外の機能は、ハーネスなしで動きます。コンテキスト取得、影響分析、オーナーシップ、適合性チェック、ドリフト検出、そしてメモリシステムは、すべて完全なツールカタログから利用でき、ワークセッションは一切必要ありません。エージェントが読める文書化されたアーキテクチャとして Archyl を使い、このガイドを丸ごと読み飛ばすことも、想定された使い方のひとつです。

二つの半分が別々に導入されるのは、許されていることが違うからです。記録は人によるキュレーションから権威を得ます。ADR も、適合性ルールも、承認された変更リクエストも、人が置いたからこそステータスを持ち、誤った項目は誰かが読んで直すまで静かにそこにあるだけです。一方プロトコルは、エージェントが実際に従う指示を発します。これは性質の異なるリスクであり、既定値ではなく意識的な選択に値します。

この線は製品の外側だけでなく、内側にも引かれています。エージェントは記録を読むことも、記録に書き込むこともできますが、書いたものは日付と書き手の付いたコンテキストとして次のエージェントに返るだけで、決してルールにはなりません。拘束力あるものとして提示されるのは ADR と適合性ルールだけであり、エージェントが記録した何かがその地位に至る道は人間を通ります — ADR にするか、誰かが承認したアーキテクチャ変更リクエストを経るかです。

5 分でセットアップ

ドキュメント化されたアーキテクチャを持つ Archyl プロジェクト（空の場合はまず AIによるディスカバリー を実行してください）と、write スコープを持つ API キー（プロフィール → API キー から作成）が必要です。

オプション A — コマンド 1 つ

リポジトリのルートで実行します:

curl -fsSL https://raw.githubusercontent.com/archyl-com/agent-skills/main/templates/setup.sh | bash

スクリプトが API キーとプロジェクトを尋ね、以下の設定をすべて行います。これで完了です — 最初のセッション に進んでください。

オプション B — 手順ごとに

1. coding プロファイルで MCP サーバーを接続します。 リポジトリに .mcp.json を作成するか、既存のファイルに追記します:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp?profile=coding",
      "headers": { "X-API-Key": "${ARCHYL_API_KEY}" }
    }
  }
}

?profile=coding が重要です。ツールの表面積が 189 個からコーディングエージェントに必要な 16 個に絞られ、エージェントのコンテキストが小さく保たれて選択肢が明確になります。

2. プラグインをインストールします（Claude Code）:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-developer@archyl-marketplace

これにより、スキル（セッションプロトコルをエージェントに教える archyl-harness を含む）と Guard フックがインストールされます。

3. Guard を有効化します。 エージェントが動作する環境で 2 つの変数をエクスポートします:

export ARCHYL_API_KEY=arch_...
export ARCHYL_PROJECT_ID=<your project uuid>

Guard に必要なのはこれだけです。Guard は fail-open です。これらの変数がない場合（またはネットワークがない場合）は何もしないため、ワークフローを壊すことは決してありません。

最初のセッション

エージェントに任意の変更を依頼してみましょう — たとえば「公開 API にレート制限を追加して」。ハーネスをインストールしていると、次のことが起こります。

コーディングの前に、エージェントは作業を宣言します:

▶ start_work_session(task: "add rate limiting to the public API",
                     agentName: "claude-code/vincent")

# Harness Session
- Session ID: 4c2e…
- Gate: warn
  - error-level guardrail applies: no-direct-db-from-handlers
- Leased elements: container `ApiGateway`, component `RateLimiter`
- Conflicts: none

## Most relevant elements
- ApiGateway (container) — handles all public traffic …
## Related decisions (respect these)
- ADR-017: All throttling is enforced at the gateway [accepted]
## What previous sessions did here
- ApiGateway (claude-code/sarah, 3 days ago): extracted auth middleware …

これでエージェントは、どこで作業すべきか、どの意思決定が制約になるか、前のエージェントがそこで何をしたかを把握できます — リポジトリ全体を読むことなく。

コーディング中、Guard はエージェントが書き込もうとするすべてのファイルを適合性ルールと照合します。critical な違反はルールとその修正提案を示して書き込みをブロックし、エージェントは修正して作業を続けます。

完了時、エージェントはループを閉じます:

▶ finish_work_session(sessionId: "4c2e…",
    summary: "Added token-bucket rate limiting in ApiGateway middleware",
    decisions: ["limits configured per-plan in Redis"],
    createChangeRequest: true)

リースが解放され、要約は次のエージェントのために ApiGateway のメモリとしてピン留めされ、アーキテクチャ変更リクエストのドラフトが Archyl に届いて、C4 モデルをどう更新すべきかを人間がレビューできるようになります。

各決定はそれぞれ独立したメモリとして記録されます。後のセッションは、そのセッションが残した他の内容に触れることなく、決定を置き換えたり、再確認したり、そのまま古くなるに任せたりできます。決定は将来のエージェントに、日付と書き手が付いたコンテキストとして返されます — 決してルールとしてではありません。エージェントに拘束力あるものとして提示されるのは ADR と適合性ルールだけであり、決定がその地位を得る道が変更リクエストです。

エージェントを見守る: Fleet コンソール

Agent Hub → Fleet を開くと進行中の作業が見えます。何体のエージェントが稼働しているか、どの C4 要素が現在リースされているか、そしてアクティブなセッションごとにタスク・保持している要素・ゲート・ハートビートの鮮度を示すカードが並びます。終了したセッションは各自が報告したサマリーとともに 最近のセッション に移ります。

Fleet コンソール — 各エージェントのセッションと、それぞれが保持する要素

ハートビートが止まったセッションには印が付き、30 分後に自動的に失効します。ここからキャンセルすれば、リースは即座に解放されます。

同じ情報は、実際に目を向ける場所——ダイアグラム上——にも届きます。エージェントが保持する要素にはその名前のバッジが付き、クリックすれば「いま何をしているのか」を尋ねたことになります。宣言されたタスク、ほかに保持している要素、そして最後に応答してからの経過時間が返ってきます。

キャンバス上で作業中のエージェント — バッジが名前を、吹き出しが作業内容を伝える

Archyl のマネージドエージェントでは、実行中のエージェントを操縦することもできます。実行ページでメッセージを書くと、次の推論ステップに注入されます。

ゲート

すべてのセッションはプリフライト判定から始まります:

Gate 意味 エージェントの動作
allow 競合なし、error レベルの Guardrails なし 続行する
warn 別のセッションが対象要素のリースを保持している、または error レベルの Guardrail が該当する 続行するが、列挙されたすべての理由に対処する
deny exclusive: true の場合のみ — 対象要素はすでに作業中 回避策を取らず、ユーザーに報告する

誰とも競合してはならない変更 — スキーマ移行や契約変更 — には exclusive: true を使用してください。

Guard の設定

変数 デフォルト 用途
ARCHYL_API_KEY — Guard の有効化に必須
ARCHYL_PROJECT_ID — Guard の有効化に必須
ARCHYL_API_URL https://api.archyl.com セルフホスト環境向け
ARCHYL_GUARD_BLOCK critical critical は critical の違反をブロック、high は high もブロック、off はブロックを無効化

環境変数の代わりに、リポジトリのルートにコミット可能な .archyl.json を置き、秘密でない側だけを持たせることもできます: { "apiUrl": "…", "projectId": "…" }。API キーは環境変数に残してください。

メモリ

セッションの作業結果は、メモリの自動的な半分にすぎません。エージェントもチームメンバーも、意図的にメモリを書き込むことができます:

▶ remember(projectId: …, element: "ApiGateway", kind: "pitfall",
    content: "The gateway strips custom headers longer than 8KB — payloads must go in the body.")
  • remember は、事実を要素（またはプロジェクト全体）に note、convention、pitfall のいずれかの型でピン留めします。コードにもモデルにも現れない知識 — デプロイ時の癖、歴史的な経緯、壊れやすい箇所 — に使ってください。
  • recall は、作業結果・ノート・規約・落とし穴を含むメモリ全体を、キーワード、要素、種別で検索します。ランキングは語そのものだけでなく意味も織り込むため、「rate limiting」について尋ねたエージェントが、別の誰かが「throttling」について書いたノートにたどり着きます。自分の sessionId を渡しておけば、提供されたメモリの貢献を後から評価に反映できます。
  • find_relevant_context と start_work_session は、該当する要素の最新のメモリを自動的に添えて返します。次のエージェントは、前のエージェントが学んだことから始められます。

メモリの書き込みは重複排除されます。すでにある事実を言い直しても 2 つ目のコピーは保存されず、既存のメモリを確認します（レスポンスは deduplicated: true を返します）。学んだことをエージェントが言い直すのは、ノイズではなく裏付けだからです。似てはいるが同一ではないメモリはそのまま保存され、similarTo として返されます。書き手が黙って矛盾を持ち込むのではなく、意図して置き換えられるようにするためです。

メモリは使われ方からも学びます。セッションが終わるとき、usedMemories はそのセッションが実際に頼りにしたメモリを挙げます。この引用こそが強いシグナルです。引用されたメモリは順位を保ち、5 つのセッションに提供されながらどのセッションからも挙げられなかったメモリは、ノイズとして順位を下げられます。自動的に削除されるものはありません。無視されたメモリはレビュー用のキューに現れ、人が判断します。

メモリにはライフサイクルがあり、ただ積み上がるのではなく正しい状態を保ちます。recall が返したメモリが正確だと確かめられたら、confirm_memory で再認定してください。鮮度の時計がリセットされ、より古い情報より上位に残り続けます。事実が変わったときは、両方のバージョンを生かしたままにしないでください。remember(supersedes: "Old title") は古いメモリを置き換えます。置き換えられたメモリは検索からは外れますが、履歴とグラフには残ります。確認されないものはランキング上で緩やかに減衰し（半減期は 45 日）、これからコードを変更しようとしているエージェントにとって、落とし穴は常に単なるノートより上位に来ます。

メモリは Obsidian のようなナレッジグラフを形成します。メモリに title を付けると参照可能になり、ほかのどのメモリからも本文中の [[Title]] で参照できます。リンクは C4 要素の名前（[[ApiGateway]]）や決定（[[ADR-17]]）も解決します。まだ存在しないタイトルへのリンクは保留のまま残り、そのメモリが作成された瞬間に結びつきます。すべてのメモリはバックリンクも示すため、知識は双方向にたどれます。さらに recall はリンクをたどり、上位で一致したメモリは、ウィキリンクでつながった近傍のメモリを via の印付きで一緒に連れてきます。

メモリはアーキテクチャが足元で動いたことにも気づきます。メモリが紐づく要素が変わると、そのメモリはレビュー対象として印が付きます。recall は引き続き返しますが [VERIFY — the element drifted since this was written] と添えられ、消えるのではなくランキングが下がります。その後分割されたサービスについて書かれた事実は、自動的に誤りになるわけではありません——人の目を通すまで信頼できなくなるだけです。

メモリは他の機密コンテンツ列と同様に保存時に暗号化され、UI から管理できます。Agent Hub のメモリパネルと、ダイアグラムの詳細パネルにある要素ごとのセクションです。パネルはトリアージのために作られています——左のレールがレビュー待ち・無視されているもの・古くなったものを数え、残りを種類別に分け、各行が色付きの背骨でどれだけ信頼できるかを一目で示します。

プロジェクトのメモリ — 規約・落とし穴・成果を、信頼度で仕分けて表示

もう一つの問いにはナレッジマップに切り替えます。何を知っているかではなくどこを知っているかです。C4 要素ごとに 1 セル、プロジェクトが何を知っていてその知識がどれだけ新しいかを示します——誰も何も書いていない要素も含めて。多くの場合そちらが有用な半分です。

ナレッジマップ — 各要素について何を知っていて、どこを何も知らないか

CI での利用

同じブロックが GitHub Actions を使ってパイプライン上でも動作します。generate-context は MCP にアクセスできないエージェント向けに archyl.txt のブリーフィングをコミットし、conformance-check はルールに基づいてプルリクエストをゲートし、auto-cr はマージされた変更からアーキテクチャ変更リクエストを起票します。

トラブルシューティング

Fleet コンソールにセッションが表示されない。 エージェントがハーネスのプロトコルなしで接続されています。プラグインがインストールされていること（archyl-harness スキルがプロトコルを教えます）と、MCP の URL に ?profile=coding が含まれていることを確認してください。189 個のツールをすべて備えたカタログでは、エージェントはループに従わず探索に走りがちです。

Guard が何もブロックしない。 これは設計どおりで、fail-open です。エージェントが動作する環境で ARCHYL_API_KEY と ARCHYL_PROJECT_ID の両方がエクスポートされていること、そしてプロジェクトに critical 深刻度の適合性ルールがあることを確認してください。

セッションがアクティブのまま止まっている。 セッションは最後のハートビートから 30 分後に期限切れとなり、リースを自動的に解放します。すぐに解放したい場合は、Fleet コンソールからセッションをキャンセルしてください。

どのエージェントがサポートされていますか？ MCP を話すものであれば、Context、Plan、セッションプロトコルを利用できます。Guard フックとスキルは現時点では Claude Code を対象としていますが、他のエージェントも run_conformance_check や CI のアクションを通じて同じルールを適用できます。