Archsteer

ArchSteer

AI開発時代のための、常に最新のアーキテクチャ制御プレーン。

AI エージェントは今や、どのアーキテクトがレビュー、文書化、ガバナンスを行うよりも速くコードを書きます。 ドキュメントはすぐに古くなり、実際のアーキテクチャは見えず、構造上の決定は知らないうちに行われ、意図されたアーキテクチャは編集のたびに乖離していきます。ArchSteer は常に最新のアーキテクチャの信頼できる唯一の情報源＋ガバナンスプレーンです。コードから実際のアーキテクチャを導き出し、常に最新のドキュメントと ADR を自動生成し、主要な決定をすべてアーキテクトに提示して承認を得ます。また、宣言された意図をコードレベルの適合性関数として適用し、AI エージェントがローカルの粗雑な実装を複製するのではなく、規約に沿うよう誘導します。

すべては、コードから導出された単一のモデル（.archsteer/model.json）を投影したものです。

デフォルトでローカル実行： X線解析とガバナンスのワークフローはローカルで実行され、リポジトリのソースコードがアップロードされたり実行されたりすることはありません。初回スキャン前にアカウント、API キー、設定は不要です。クラウドへのスナップショット公開は、明示的な別コマンド push で行います。

                    .archsteer/model.json  (single source of truth)
                                 │
   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE
  model    living docs   fitness     agent     report.html
  from     + auto ADRs   functions   guardrails  (drift/
  source   + diagrams    + ratchet   + MCP       decisions)

インストール

Claude Code プラグインとして（Claude Code をお使いの場合におすすめです）：

/plugin marketplace add einvoice-dev1/archsteer
/plugin install archsteer@archsteer

これにより、同梱の MCP サーバー（current_architecture、get_target_pattern、check_file。uvx 経由で動作するため、別途 pip install は不要）に加えて、エージェントがいつ独自に X線解析、チェック、誘導を行うかを教えるスキルと、/xray／/check コマンドがインストールされます。マニフェストについては .claude-plugin/plugin.json を参照してください。

CLI として（任意のエディター／エージェント、または単独で動作します）：

pip install archsteer                 # regex engine + local MCP server; no parser toolchain required
pip install "archsteer[treesitter]"   # optional native acceleration

（0.4.1 以降、MCP サーバーは基本インストールに含まれています。pip install "archsteer[mcp]" も引き続き、何も行わないエイリアスとして動作します。）

対応言語： JavaScript／TypeScript（Next.js App Router を認識し、tsconfig.json のパスエイリアス解決に対応。@/lib/x は実際の内部エッジとして解決され、実在しないサードパーティ依存にはなりません）、Python、Java（Spring を認識）、Salesforce Apex（SOQL／DML＋トリガー／ハンドラー／セレクターの規約）。 レイヤー検出では、まずソース内のシグナル（Spring ステレオタイプアノテーション、Apex のクラス名規約、Next.js の予約ファイル名（ディレクトリに関係なく、page.tsx → page、layout.tsx → layout、route.ts → api））を使い、その後ディレクトリ名を使います。

クイックスタート

まずはリポジトリで以下を実行し、生成された .archsteer/report.html を開いてください。

archsteer init && archsteer map && archsteer report

次に、必要な制御を追加します。

archsteer init      # scaffold .archsteer/ + a starter rule pack auto-matched to your stack
archsteer map       # build model.json from source
archsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid) — includes a "Start here" hub/entry-point guide and a file-level component map
archsteer graph <path>  # one component's direct dependencies + dependents — no intent required, just dropped into an unfamiliar file
archsteer govern    # conformance + drift score by rule
archsteer adr       # draft ADRs: new structural decisions + widespread rule violations
archsteer baseline  # accept current debt — the ratchet
archsteer steer -f src/controllers/payment.js -t "add refund endpoint"
archsteer check     # CI/pre-commit: fail on NET-NEW violations only
archsteer install-hooks   # wire `check` into a local git pre-push hook
archsteer report    # self-contained .archsteer/report.html

init はスタックを自動検出し、それに合ったベースラインのルールパックを適用します。規約に合わせて .archsteer/architecture.yaml を編集するか、明示的に選択してください。

パック	検出条件	ベースラインルール
java-spring	pom.xml / build.gradle	永続化処理はリポジトリ内のみ；コントローラーはリポジトリにアクセスしない；ハードコードされたシークレットを使用しない；外部への呼び出しはサービス内に限定
salesforce	sfdx-project.json / force-app	SOQL はセレクター内のみ；トリガーにロジックを含めない；コントローラーで DML を行わない；ハードコードされたシークレットを使用しない；コールアウトはサービス内に限定
python-service	pyproject.toml / requirements.txt	永続化処理はリポジトリを介する；API ハンドラーは薄く保つ；ハードコードされたシークレットを使用しない；外部への呼び出しはサービス内に限定
nextjs-app-router	package.json に next があり、app/ ディレクトリがあり、express がない	データアクセス（Supabase/Prisma/生の SQL）とサードパーティへの呼び出しは lib/ またはルートハンドラー内に限定；ハードコードされたシークレットを使用しない
express-to-next	package.json（フォールバック、または express がある場合）	リポジトリパターン；Express から Next.js への移行；ハードコードされたシークレットを使用しない；外部への呼び出しはサービス内に限定

依存関係に next があり、app/ ディレクトリがあるリポジトリには App Router パックが適用されます。express を含む package.json（Next への移行中の場合も含む）には、代わりに移行用パックが適用されます。これらは異なる問題であり、ルールも異なります。

すべてのスターターパックにはセキュリティベースラインが含まれています。ソースコード内のどこにも認証情報／API キー／トークンをハードコードせず、サードパーティへのすべての外部呼び出しをサービス層に限定します。これにより、初日からアーキテクチャに加え、AI エージェントが最も頻繁に持ち込む 2 つのセキュリティ上の問題もガバナンスの対象になります。

archsteer init --pack salesforce   # override the auto-detection

3 つの設計上の保証

1. 凍結ではなくラチェット。 archsteer check がブロックするのは、ベースラインに対する新たな違反のみです。チームは機能をリリースし続けながら、技術的負債を減らしていけます。
2. 慎重で、アーキテクトが関与する ADR。 対象を絞った 2 つの情報源を使い、どちらもレビューを任意とします。自動コミットは決して行いません。経時的には、外部境界の変更（新しい依存関係、新しいデータストア、新しいレイヤー）を対象とし、内部の再編成は対象外です。単一のスナップショット内では、3 つ以上のコンポーネントで違反しているルールを対象とします。これは、check／govern に任せる一度限りの問題ではなく、承認または緩和する価値のある実際のパターンです。ドラフトは冪等です。再実行しても、すでにディスク上にあるものが重複することはありません。
3. エージェントを的確に誘導。 CLAUDE.md、AGENTS.md、.cursor/rules/archsteer.mdc（常時有効な Cursor ルール）に挿入されるガードレールは、対象ファイルに範囲を限定し、適用される ADR を示します。モデル全体をコンテキストウィンドウに流し込むことはありません。

意図の宣言 — .archsteer/architecture.yaml

target: "Migrate Express + raw SQL to Next.js route handlers + the repository pattern"
layers: [route, controller, service, repository, model]
rules:
  - id: no-raw-sql-outside-repository
    type: required_layer_for_data_access
    allowed_layers: [repository]
    operations: [RAW]
    severity: error
    adr: .archsteer/adr/0001-repository-pattern.md
    steer: "Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere."

ルールの種類：required_layer_for_data_access、forbidden_import、forbidden_data_access、forbidden_layer_edge、forbidden_security_finding（ハードコードされたシークレット）、および required_layer_for_external_call（外部への HTTP／SDK 呼び出しを特定のレイヤーに限定）。

AI エージェントでの使用（MCP）

archsteer mcp は、stdio 経由でローカル MCP サーバーを実行します。これはお使いのエディター／エージェントによって起動されるもので、当社がホストするものではありません。ディスク上の .archsteer/ に init／map／govern がすでに書き込んだ内容のみを読み取るため、ネットワーク呼び出しはなく、お使いのマシンからデータが外部に送信されることもありません。次の 3 つのツールを公開します。

• current_architecture — コンポーネント／レイヤー数、適合状況／ドリフト、宣言されたターゲット。
• get_target_pattern — ファイルに適用される不変条件を、ファイルに書き込む前に確認できます。
• check_file — 編集したファイルが適合しているかを、CI を待たずに確認できます。

上記の Claude Code プラグインを使用していますか？ すでに設定済みなので、クイックスタートに進んでください。このセクションの残りは、ほかのすべてのクライアント向けです。

ワンクリックで Cursor に追加できます： Cursor にインストール →

プラグインを使わずに Claude Code に手動で追加する場合や、その他の MCP 対応クライアントの場合：

claude mcp add archsteer -- uvx archsteer mcp    # no separate pip install needed

または、JSON 設定に直接追加します：

{ "mcpServers": { "archsteer": { "command": "uvx", "args": ["archsteer", "mcp"] } } }

（pip／pipx 経由で archsteer をすでに PATH に追加していますか？ {"command": "archsteer", "args": ["mcp"]} も同じように動作します。uvx を使えばインストール手順が不要になります。）

公式 MCP レジストリにも io.github.einvoice-dev1/archsteer として公開されています。

CI ／ pre-commit ／ pre-push

• GitHub Action：.github/workflows/archsteer.yml（マッピングを実行し、ADR のドラフトを作成し、新規分のゲートを実行して、report.html をアップロードします）。
• ローカルの pre-push フック：archsteer install-hooks は archsteer check を .git/hooks/pre-push に組み込みます。プッシュのたびにアーキテクチャ適合スコアを表示し、新規分のエラー違反のみをブロックします（CI と同じラチェットで、フィードバックがより早く得られます）。 archsteer map／check はファイルごとの解析結果を .archsteer/parse_cache.json にキャッシュするため、少数のファイルだけを変更したプッシュでは、リポジトリ全体ではなく、そのファイルだけを再解析します。archsteer install-hooks --uninstall でアンインストールできます。
• husky、pre-commit、または lefthook をすでに使用していますか？ 生の git フックの代わりに、手順として archsteer check を追加します。たとえば、archsteer check を含む .husky/pre-push を作成します。

適合バッジ

リポジトリのスナップショットを situation room にプッシュする（archsteer push）と、最新の適合スコアがライブバッジになります。この README の先頭にあるバッジは、このリポジトリ自身を統治しているものです：

[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)

YOUR-REPO を、archsteer push が報告するリポジトリ名に置き換えてください。90％以上で緑色になり、まだ X 線のみ（architecture.yaml が未宣言）の場合は灰色になります。

デモを試す

cd examples/demo-repo
archsteer init && archsteer map && archsteer report   # open .archsteer/report.html

ロードマップ

• リリース済み — クラウド制御プレーン（Next.js + Supabase）：ドリフト／意思決定の時系列を備えた、複数リポジトリ対応の situation room。archsteer mcp：エージェントが編集中にライブモデルと意図を照会できるローカル MCP サーバー。組織全体を対象とするホスト型 MCP サーバー（Team プラン）により、エージェントは situation room のデータを MCP 経由で使って、「ドリフト指数はいくつか」「保留中の ADR があるリポジトリはどれか」といったリポジトリ横断の質問ができます。専用の Next.js App Router パック（page.tsx／layout.tsx／route.ts からレイヤーを検出し、tsconfig.json のパスエイリアスを解決し、Supabase／Prisma を考慮したデータアクセスを検出します）。archsteer install-hooks：CI と同じ新規分の適合ラチェットを、ローカルの git pre-push フックに組み込みます。 Claude Code プラグイン（スキル + コマンド + MCP サーバーを一度にインストール）。
• 今後 — VS Code 拡張機能（インライン診断、ステータスバーのスコア。CLI／MCP はすでにあらゆるエディターで利用できます）、認証、組織／リポジトリモデル、課金。

開発

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

意外な境界ケース、誤検出、または ArchSteer がより適切に理解すべきスタックを見つけましたか？ 言語、フレームワーク、最小限の再現可能な例を添えて、issue を作成してください。開発者からのフィードバックは、検出器とスタータールールパックに直接反映されます。