adrkit

人間が作成したプランとエージェントが作成したプランのための決定メモリ — gitから離れることなく、機械可読で、CIで強制可能で、エージェントが判読できるアーキテクチャ決定記録です。

ほとんどのADRツールは、Markdownテンプレートと静的サイトジェネレーターにすぎません。それらは決定を記録するだけで、決定に何かをさせることはありません。adrkitはレコードをMarkdown本文を伴う型付きデータとして扱い、affectsという1つのフィールドを追加します。これにより、ツールは*「このプルリクエストを統治する決定はどれか？」*という問いに答え、その答えを次の決定が行われている場所に置くことができます。

クイックスタート

CLIは@adrkit/cliとして公開されており、adrバイナリを提供します。公開アーティファクトは**Node 22+**を対象としています：

npx @adrkit/cli lint                 # validate the corpus in docs/adr
npx @adrkit/cli explain src/payments/api.ts   # which decisions govern this file?

またはプロジェクトに追加します（Bun優先のリポジトリではbun add -D @adrkit/cli / bunxを使用できます）：

npm i -D @adrkit/cli

純粋なライブラリは独立してインストールできます：npm i @adrkit/core @adrkit/evaluator。

クイックスタートガイドと完全なコマンドリファレンスを参照してください。

Related MCP server: agentic-os-mcp

出発点の選択

コンテナの使用法

ADR-0032を含む最初のロックステップリリース以降、リリースはghcr.io/mbeacom/adrkitでマルチアーキテクチャOCIイメージとして公開されます。自動化では不変のvX.Y.Zタグを固定してください。vXとlatestは、そのロックステップリリースが完了した後にのみ移動します：

docker run --rm --read-only --network none \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z lint

docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z mcp

MCPコマンドは、MCPがstdioを使用するためstdinを開いたままにします。そのリポジトリマウントは読み取り専用であり、サーバー契約に一致します。MCPクライアント設定では絶対ホストパスを使用してください。意図的に書き込むCLIコマンド（new、または--dry-runなしのmigrate）では、--read-onlyとマウントの:roサフィックスを省略してください。イメージは非ルートのnodeユーザーとして実行されます。ホストのUID/GIDが異なる場合は、--user "$(id -u):$(id -g)"を追加してください。SELinuxホストでは、適切なバインドマウントラベル（例：:Z）を追加してください。

デフォルトのイメージは、認識されないセレクターをadrサブコマンドとして扱います。明示的なセレクターは、cli/adr/adrkit、mcp/adrkit-mcp、ci/adrkit-ci、queue-action/adrkit-queue-actionです。デフォルトの--helpはこれらのセレクターを説明します。cli --helpはCLIコマンドリファレンスを開きます。コンテナは-h、container-help、--container-helpも予約しています。help lintなどのCLIヘルプサブコマンドは、それ以外は変更されずに通過します。

同じソースをDockerまたはPodmanでローカルにビルドします。目的別のcli、mcp、ci、queue-actionターゲットは、ローカルポリシーとSBOM検査のために分離されています。レジストリはオールインワンのadrkitターゲットのみを公開します：

docker build -f Containerfile -t adrkit:local .
docker build -f Containerfile --target mcp -t adrkit-mcp:local .
docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  adrkit-mcp:local

2つのCIエントリポイントは既存のGitHub Actionsランタイム契約を維持します。GITHUB_WORKSPACE、イベントペイロードとリポジトリ環境、INPUT_*値、トークンを期待します。ホスト型GitHub Actionsの場合、このリポジトリから提供されるActionsの方がシンプルなインターフェースです：mbeacom/adrkit/packages/ci@v0およびmbeacom/adrkit/packages/ci/queue@v0。コンテナの公開とリカバリはdocs/RELEASING.mdに文書化されています。

どのようなものか

adr queueは、コーパスの決定的で読み取り専用のプロジェクションとしてレビューバックログを出力します — 同一の入力に対してはバイト単位で同一です：

# ARB Queue — 2026-07-25

Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf29903cb00`
7 item(s) | 0 corpus finding(s) | 0 item(s) with findings

## Queue Items

| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | `0005` | Gate proposals with a deterministic-first evaluator … | arb | within-sla | 2027-01-18 | 0/- | 0 |
| 2 | `0015` | Validate descriptors against Backstage field formats … | arb | within-sla | 2027-01-25 | 0/- | 0 |

CIでは、@adrkit/ci Actionが、それらに触れるPRに統治する決定をコメントします — 読み取り専用、コメントのみ、データベースなし、承認なし。CIでの使用を参照してください。

エージェント向け：MCPサーバー

最も差別化されたフック：@adrkit/mcpは、エージェントが、すでに試みられたことを提案する前に、過去の決定 — 却下されたものや置き換えられたものも含む — を取得できるようにする、ローカルな読み取り専用のModel Context Protocolサーバーです。書き込みなし、HTTP/認証なし、モデル・埋め込み・ネットワークへのアクセスなし、永続的なインデックスもありません。正確に4つのツールを公開します：

リポジトリのコーパスに対して実行します：

npx @adrkit/mcp             # or the adrkit-mcp bin
adrkit-mcp --cwd /path/to/repo --dir docs/adr

--cwd（env ADRKIT_MCP_CWD）はGitワークツリーのルートである必要があります。--dir（env ADRKIT_MCP_DIR、デフォルトdocs/adr）はその中で解決されます。stdoutはJSON-RPCフレームのみを運びます。診断情報はstderrに送られます。墓場はデフォルトで含まれます。完全なツール契約については、MCPセットアップガイドとpackages/mcp/README.mdを参照してください。

スペック駆動ワークフロー向け：Spec Kit拡張機能

Spec Kitは、specifyからplan、tasks、implementへと導きます。Spec Kitが行わないのは、生成したばかりのプランをすでに行った決定と照合することや、そのプランに含まれる新しい決定を記録することです — そのため、すべての機能は空のコンテキストから始まり、解決済みの疑問を再審議することになります。

@adrkit/spec-kitがそのループを閉じます：

さらに、チェックの実行を提案するafter_planフックが1つあります。これは構造上オプションであり、フックは書き込みを行わないコマンドにのみ到達できます — draftは意図的にどのフックからも到達不能です。なぜなら、プランフェーズのフックが促されずにレコードを作成すると、決定メモリを記録するのではなく製造することになるからです。

Spec Kit >=0.13.0,<0.16.0に固定され、0.13.0、0.14.4、0.15.1に対してテストされています。Spec Kitコミュニティカタログから利用できます。セットアップについてはパッケージのREADMEを参照してください。

あらゆるコーディングエージェント向け：プラグイン

Spec Kitは1つのワークフローです。現在、プランが実際に書かれる場所は、あなたの決定コーパスの存在を知らないコーディングエージェントの中です。

packages/adapters/agent-pluginは、同じループをポータブルなエージェントコンポーネントとしてパッケージ化します — GitHub Copilot CLI、Claude Code、opencode、およびAPMが対象とするあらゆるものにインストール可能です：

copilot plugin marketplace add mbeacom/adrkit && copilot plugin install adrkit@adrkit
/plugin marketplace add mbeacom/adrkit        # Claude Code, then /plugin install adrkit@adrkit
apm install mbeacom/adrkit/packages/adapters/agent-plugin --target opencode

すべてのコンポーネントはadr CLIをシェルアウトするため、まだインストールしていない場合はそれもインストールしてください — npm i -g @adrkit/cli、またはプロジェクトへの@adrkit/cliの追加です。コンポーネントは$ADRKIT_CLI、次に./node_modules/.bin/adr、次にPATHの順でそれを解決します。

これは意図的にMCP 設定を一切同梱しません: Copilot CLI はプラグインの MCP サーバーをワークスペースの外、かつ Git リポジトリの外で起動するため、adrkit サーバーは initialize 中に終了します。MCP は代わりにプロジェクトごとに配線されます。ホスト固有のセットアップについては プラグイン README を、ADR-0028 も参照してください。バックフィル拡張は ADR-0034 によって承認されています。

ステータス: 本リポジトリから現在インストール可能で、npm パッケージからは独立してバージョン管理されています。これにより、context -> check -> backfill -> draft ループが現在のコーディングエージェントホスト内で利用可能になります。

バックフィルワークフローは、人間が候補を選択するまで読み取り専用です。ソースルーティング、証拠のしきい値、ステータスの扱い、/adr-backfill → /adr-draft の引き継ぎについては、ガイド を参照してください。

ADR-0007 に従い独立したバージョン管理が行われています。元の context/check/draft/queue ワークフローは ADR-0014 の第 1 段階にあります — 単体テストと契約テストのカバレッジに加え、インストール済みホストに対するメンテナーによる検証が行われています。v0.2.0 のバックフィル追加は、契約および静的ホストで検証されており、候補の照合と書き込みがないことを証明する、Copilot の合成コンシューマーによる新しい機能的な実行も行われています。このプラグインに対する、永続的な参照リポジトリでの実行や外部検証は存在しません。

問題

あなたの組織が何かを決定します。6 か月後には誰も覚えておらず、決定は再審議され、コードは合意された内容から乖離していきます。今やエージェントもプランを書きます — 誰もレビューできないほどの速さで、しかも既に決定され却下されたことの記憶なしに。

アイデア

決定記録をマークダウン本文を持つ型付きデータとして扱い、すべてを変える 1 つのフィールドを与えます — その決定が対象とするものを宣言する affects です:

---
id: "0042"
title: Use server-side rendering for authenticated routes
status: accepted
reversibility: one-way-door
blastRadius: cross-team
affects:
  - type: path
    pattern: "apps/web/app/\\(authed\\)/**"   # ( and ) are glob syntax — escape them
  - type: package
    pattern: "next@>=16"
---

これで、ツールは 「このプルリクエストにはどの決定が適用されるのか？」 に答えられるようになり、その答えを次の決定が実際に行われる場所に置くことができます。

機能

• adr lint — レコードを検証し、置き換えサイクルを検出し、互いに暗黙的に矛盾する決定を見つけます。コーパスディレクトリ配下のマークダウンが検出できない場合に警告するため、「checked 0 records」が黙って出力されることはありません。

• adr migrate --from madr — 既存の MADR コーパスを、現在のツールを壊すことなく、その場で追加的に採用します。ステータス、日付、決定者を MADR 3.x のフロントマター、MADR 2.x の * Status: 箇条書き、Nygard の ## Status セクションから読み取ります。--rename は各ファイルを <id>-<slug>.md にリネームします。

• adr explain <path> — ファイルに適用されるすべての決定と、その理由を出力します。決定がファイルに到達する経路は 2 つあり、出力ではそれらを区別します: レコード自身の affects パターンが一致した場合 (via path: src/**)、またはコメント内の @adr 0012 マーカーでファイル自体が決定を宣言した場合 (declared by src/sync.ts:3) です。マーカーにより、affects を狭く保つことができます — 定義ファイルのみ — 一方、周囲のコードは、どの言語でも、スキーマ変更なしに、一度に 1 行ずつオプトインできます。accepted のレコードのみが適用対象として報告され、一致した提案や superseded/rejected/deprecated のレコードは別途リストされます。

• adr check <files...> — 変更されたレコードを検証し、変更されたファイルセットに適用される決定を、インバウンドの @adr 宣言を含めてリストします。マーカー読み取りは、3,000 ファイル / 16 並行読み取り、1 ファイルあたり 64 宣言、1 バッチあたり 10,000 宣言に制限され、すべて --json で報告されます。マーカーの主張とスキャン警告は終了コードに影響しません。

• adr evaluate <proposal> --snapshot <bundle.json> --date YYYY-MM-DD — 提案 ADR と不変のオフラインスナップショットバンドルに対して、決定論的でモデル不要の Pass 0 を実行します。11 のルーブリックルールを適用し、証明されたトリガーがある場合は指名された 1 人のアクティブな人間 (または明示的な unresolved) にエスカレーションし、リッチな Pass0Report とスキーマ互換の evaluationPatch を返します。モデル、ネットワーク、クロック、(ライブラリ内では) ファイルシステムを一切読み取らず、ルーティングのみを行います — 承認も、永続化も、書き込みも一切行いません。

• adr queue — ARB オペレーションキューを出力します: コーパスの review メタデータ (ティア、SLA 状態、承認、異議) の読み取り専用かつ決定論的なプロジェクションを、Markdown または QueueReport v1 JSON として出力します。また、管理された issue の Action でもあります。

• CI コメント — @adrkit/ci GitHub Action は、対象ファイルに触れる、または明示的に宣言する PR に適用される決定を表示します。パターンマッチは via として、PR で作成されたマーカー主張は declared by としてレンダリングされます。コメントは、検査できなかったマーカーファイル、安全上限で省略されたマーカー宣言、読み取ったがバインドできなかった主張も区別します。これらはすべて参考情報であり、ジョブを失敗させることはありません。デフォルトの GITHUB_TOKEN のみで動作し、読み取り専用のフォークトークンでは (ジョブを失敗させることなく) 劣化します。

• MCP サーバー — エージェントが、既に試されたものを提案する前に、却下されたものを含む過去の決定を取得できるようにします。

それは何も承認しません。ルーティングするだけで、人間が決定します。

両方の CI Actions は、移動するメジャータグから使用してください (CI での使用 を参照):

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v4
  - uses: mbeacom/adrkit/packages/ci@v0

なぜプレーンな MADR — あるいは「構造化 MADR」ではないのか？

adrkit のフロントマターは厳密な MADR のスーパーセットであるため、これは「MADR の代わり」ではありません — 既存のコーパスをその場で adr migrate --from madr できます。違いは、レコードが存在した後に何が起こるかです。

テンプレート — より構造化された MADR バリアントを含む — は、決定を書く方法を標準化します。しかし、以下は行いません:

• CI で強制する — adrkit は affects を解決し、対象ファイルを変更する PR に適用される決定をコメントします;

• 「この PR にはどの決定が適用されるのか？」に答える — それには、型付き affects フィールドに対する純粋で再現可能なマッチャーが必要です (ADR-0009)。散文ではなく;

• エージェントに墓地を取得させる — 読み取り専用の MCP サーバーが rejected/superseded/deprecated レコードを公開し、エージェントがそれらを再提案するのを防ぎます。

リンター、リゾルバ、エージェント、CI ジョブに渡すことができるスキーマは、見出しの慣習とは別の成果物です。それがこの全体の主張です。

プロジェクトステータス

adrkit はまだ pre-1.0 ですが、いくつかのサーフェスは今日から使用できます。この表はその短い版です:

設計上のコミットメント

これらは強制されるものであり、願望ではありません。それぞれが、それを決定したレコードにリンクしています。

ドッグフーディング

このプロジェクトのすべての決定は、このプロジェクトによって適用されます。リポジトリの最初のコミットは、それ自体が決定コーパスです — docs/adr/ を参照してください。評価者のルーブリック自体もここでバージョン管理されています。公開されている評価者は現在、決定論的な Pass 0 のみを実装しています。後のパスは、リリースされた動作ではなく、文書化された設計目標のままです。

ライセンス

Apache-2.0 — LICENSE を参照してください。

例外: schema/ の内容は、追加で CC0 の下でリリースされています。このスキーマは共有契約となることを意図しており、競合する実装はライセンスをまったく考慮せずに採用できる必要があります。

ツールチェーン

Bun で構築されています — ADR-0010 を参照してください。Bun は開発依存関係のみです。 このプロジェクトが公開するものは何も Bun を必要としません: CLI、GitHub Action、MCP サーバーは Node 向けであり、CI で Node 22 および 24 の下でスモークテストされています。

コントリビューション

CONTRIBUTING.md を参照してください。「あなたの最初の PR」 の導入経路も含まれます。コントリビューションには DCO の署名が必要であり、認証情報を設定していないクリーンなクローンからビルドできる必要があります。