Archprint

Archprint

リポジトリがすでに適用しているアーキテクチャルールを、根拠とともに掘り起こします。

ブラウザーで試す。インストール不要です · クイックスタート · CIで使用 · AIエージェントと使用 · ドキュメント

どんなツールなのか、簡単に説明します

どのコードベースにも、明文化されていないルールがあります。「ページからデータベースに直接アクセスしない」「共有コードからアプリに依存しない」。誰も書き留めていませんが、コードはそのルールに従っています。しかしある日、誰か（またはAIアシスタント）が気づかないうちに破ってしまいます。

ArchprintはTypeScriptプロジェクトを読み込み、コードがすでに従っているルールを見つけ、それぞれの根拠を示します。ルールに従っているファイル数、違反しているファイル、そして判定の確信度がわかります。信頼できるルールを、チームがすでに使っているツールの自動チェックにすることで、違反は数週間後のレビューではなく、次にlintを実行したとき（エディター、コミット前フック、またはCI）に検出されます。

建物を調査して、実際にどのように建てられたかを書き留める建築検査官のようなものです。よそから持ってきたルールブックを渡すのではありません。

• 開発者とテックリード向け： ESLintとdependency-cruiser用に、推論に基づく根拠付きlintルールを生成します。initで生成し、wireで接続して、ejectで削除します。
• レビュアー向け： archprint checkは、プルリクエストで新たに発生したルール違反だけをGitHub上にインラインで表示します。既存の未対応項目は対象になりません。
• AIコーディングエージェントを利用するチーム向け： Claude Code、Cursorなどのエージェントは、コードを書く前にArchprintにプロジェクトのルールと根拠を尋ねられます。
• コードベースを評価するすべての方へ： プロジェクトが実際にどのような構造になっているかを、すばやく率直に把握できます。

CLAUDE.mdはガイダンスです。lintルールは強制適用です。Archprintは、コードベースがすでに示しているパターンから強制適用のルールを生成することで、その隔たりを埋めます。手作業でルールを作るのではなく、信頼できるルールを採用できます。

実際の動作を見る

以下の録画では、ルートからデータベースにアクセスするのはサービスレイヤー経由のみの、小規模な Next.js API であるarchprint-demoを使用しています。

1. コードがすでに従っているルールを見つけます。 各ルールには、その根拠が示されます。

2. あるルールが信頼される理由を確認します。 信頼度のチェックを順を追って見られます。

3. ルールを有効にし、違反が検出される様子を確認してから、すべて元に戻します。 Archprint がファイルを書き込み、ESLint の設定に1行追加します。lint はデータベースを直接インポートするルートにフラグを立て、eject はプロジェクトを完全に元の状態に戻します。

インストール不要で試せます： StackBlitz でデモを開く。 開くとすぐにスキャンが実行され、デモの READMEでは、ESLint でルールを適用し、違反させてから、MCP 経由でルールを尋ねる手順を説明しています。

AI コーディングエージェントで使う

AI コーディングエージェントは、エージェントが外部ツールを使えるようにするオープンスタンダードである MCPを通じて、プロジェクトのルールを Archprint に問い合わせられます。普通の言葉で尋ねると、エージェントが自ら Archprint を呼び出し、根拠とともに回答します。Archprint は報告のみを行います。適用は引き続きリンターで実行されます。

Claude Codeは、適用中のルールとレビュー待ちのルールを一覧表示してから、ルートを追加し、Archprint で変更をチェックしてから結果を報告します。

Cursor も同じように動作します。 これらの録画では、Cursor は Claude ではなく Grok 4.7 に設定されています。デスクトップアプリのチャットでは、エージェントが自ら Archprint のスキャンツールを呼び出しました。このスクリーンショットには、ツールの結果と回答が表示されています。

ターミナル（cursor-agent）でも同様に、ルールを一覧表示してから、ルートを追加し、archprint_check でチェックします。

測定結果：Archprint の有無による同じ質問への回答

デモアプリ（70 ファイル）について、Claude Code（Opus 5.5）に「このリポジトリでは、すでにどのようなアーキテクチャルールに従っていますか？」と尋ねました。それぞれ 5 回実行した結果の中央値［範囲］です。

	Archprint なし	Archprint あり
読み取ったトークン数	81k［58k～96k］	52k［52k～52k］
書き込んだトークン数	1.1k［1.1k～1.4k］	0.6k［0.6k～0.6k］
質問あたりのコスト	$0.083［$0.078～$0.153］	$0.037［$0.032～$0.076］
時間	17 秒［15～19］	10 秒［9～31］
ツール呼び出し数	5［4～10］	2［2～2］

回答から分かったこと：

• どちらも主なルールを見つけました。ルートからデータベースにアクセスする場合は、必ず lib/services/ を経由します。
• Archprint を使った場合、毎回すべてのルールの根拠が示され、ルールに違反しているファイルも 1 つ特定されました（lib/db.ts は設定レイヤーの外で process.env を読み取ります）。Archprint なしでは、これに気づいた回はありませんでした。
• Archprint なしの場合、Claude は Archprint がチェックしない命名規則についても説明しました。

これらの数値は慎重にご覧ください。どちらの列でも、読み取ったトークン数の約 50k は Claude Code 自身のシステムプロンプトによるもので、今回測定したのは小規模なリポジトリ 1 つのみです。より大きなリポジトリはまだ測定していません。 手法、ハーネス、すべての回答。

Claude Desktop、Claude Code、Cursor などのクライアントのセットアップについては、MCP のセットアップをご覧ください。

クイックスタート

Node 20 以降が必要です。tsconfig.json があるフォルダーで、以下を実行してください。モノレポでは、scan と recommend はルートも受け付け、すべてのアプリを対象にします。一方、init と generate は一度に 1 つのアプリ（例：apps/web）を対象にします。複数のアプリがあるルートで実行すると、処理を停止してアプリを一覧表示し、アプリを 1 つ指定して再実行するよう求めます。

# 1. See the rules your code already follows, with the evidence. Changes nothing.
npx archprint scan .

# 2. Ask why one rule is trusted (use a rule label from the scan)
npx archprint explain AP-001 .

# 3. Set up enforcement for the rules your code already follows cleanly,
#    and record what to review or adopt next in .archprint/config.json
npx archprint init .

# 4. Connect the generated rules to your ESLint / dependency-cruiser config (one managed line)
npx archprint wire

# 5. Run your linter as usual. Your code passes today; a new import that breaks a rule fails.
npx eslint .

# To undo everything, exactly:
npx archprint eject

ルール違反を検出する様子を見る。 手順 4 の後で、意図的にルールに違反してみましょう。たとえば、ルートファイルからデータベースクライアントを直接インポートしてから、リンターを実行します。これが、ブラウザーで操作できるデモで紹介している一連の流れです。

npx を使わずにプロジェクトへ追加するには、npm install --save-dev archprint を実行します。

手順を追ってセットアップする場合は、次のコマンドを実行してください。

# Inspect the evidence behind one rule
archprint explain AP-002 apps/web

# Write the auto-trusted (mechanical) rules to .archprint/, only for the linters your repo uses.
# Structural-inference rules are held for review; add --include-structural to emit them too.
archprint generate apps/web

# Confirm the generated rules pass on your repo before wiring
archprint generate apps/web --check

# Generate a single rule by id after reviewing it (including a SUGGEST rule)
archprint generate apps/web --rule AP-001

# Adopt only the rules you choose, including reviewed layer boundaries
archprint generate apps/web --include-structural --rules AP-002,no-utils-to-app

# Recommend a rule set from the evidence and the detected stack (fresh repos too)
archprint recommend apps/web

# Upgrading from 0.5.x? Move an older archprint-rules/ setup to the .archprint layout
archprint migrate

または、ソースからビルドします。

git clone https://github.com/Tommkruix/archprint
cd archprint
npm ci
npm run build
node dist/cli.js scan <path-to-your-app>

何を信頼するかの判断基準

Archprint は意図的に慎重に設計されています。誤ったルールは、ルールがない場合よりも大きな害をもたらすからです。候補となる各ルールは、有効になる前に2つのチェックを通過します。

1. 十分な証拠がありますか？ 5ファイル中5ファイルがパターンに従っていても証明にはなりませんが、40ファイル中40ファイルなら証明になります。Archprint は各ルールを、ルールがどの程度の頻度で成り立つかと、何ファイルを対象に検証したかを組み合わせた標準的な統計指標であるウィルソンスコアの下限値で評価します。各ルールは次の3つのグループに分類されます。

• AUTO（適用可能）：適合率の95％下限値が90％以上で、例外が最大3件、かつ役割が高い確度で分類されています。
• SUGGEST（暫定）：パターンがファイルの少なくとも80％で成り立ち、役割の確度が少なくとも50％であるものの、AUTO の条件を1つ満たしていません。たとえば、信頼度の下限が90％未満（ファイル数が少なすぎるか、パターンに反するファイルが多すぎる）、パターンに反するファイルが3件を超える、または役割の確度が80％未満の場合です。レビュー用に提示され、自動生成はされません。
• REJECT：十分な傾向がありません。

2. ルール自体が間違っている可能性はありますか？ Archprint がフォルダーの目的を誤って推測した場合、数値上の条件を満たしていてもルールが間違っていることがあります。そのため、曖昧さのないシグナルに基づく機械的なファミリーのみが、レビューなしで信頼されます。これには、禁止されたインポート（AP-001、AP-002）、循環依存関係、テストの分離、インポートスタイル、コンソールの分離、パブリック API のバレルが含まれます。実際のリポジトリ4件で3ラウンドにわたり敵対的な正確性監査を行った結果、各ラウンドでこれらに誤検出はありませんでした。循環依存関係を除くすべては lint ルールとして記述されます。十分なファイル数があり、ゲートを通過した循環依存のないコードベースでは、「循環依存関係なし」が採用され、archprint check によって各プルリクエストで適用されます（循環の検出にはインポートグラフ全体が必要なため、lint ルールはありません）。

構造的なファミリーは、パスから「レイヤー」や「役割」を推測するため、誤りが生じる可能性があります（レイヤーと役割の境界、UI とデータの分離、エントリーポイントの純粋性、サーバーとクライアント、フィーチャースライスとアプリの分離、環境変数へのアクセス、ワークスペースパッケージ API、ストーリーの分離）。依存関係の衛生状態は適用すると過剰に警告される可能性があり、依存関係の宣言も同様に保留されます。これらはすべて、統計スコアにかかわらず、同等に良好な実績を得るまではデフォルトでレビュー対象として保留され、--include-structural を指定した場合にのみ適用ルールとして記述されます。誤っている可能性のあるものは、明示的にオプトインしない限り適用されません。

生成されるルールは、生成時点で適合状態が保たれるようになっています。それぞれのルールは、推測の根拠となった既知の例外ファイルを許容するため、採用しても lint は成功した状態を維持し、新たな違反は引き続き検出されます。また、証拠に一貫性がないルールは、自己整合性チェックによって書き出しが拒否されます。生成したルールを接続する前にコードに対して実行するには、archprint generate --check を使用します。

検出できるもの

提供方法： Auto = 適用ルールとして有効（機械的なファミリー）。Review = デフォルトでレビュー対象として保留され、--include-structural を指定すると出力されます。Check = 各プルリクエストで archprint check により適用されます。Report = 表示のみで、適用はされません。

Archprint はスタック（Next.js、Nest、SvelteKit、Nuxt、Remix）を認識し、React（.tsx）、Angular（.component.ts、.directive.ts）、Vue と Svelte の単一ファイルコンポーネント（.vue／.svelte ファイルの <script> ブロックを読み取ります）にわたって UI コンポーネントを分類するため、コンポーネントを考慮したルールはフレームワークにかかわらず適用されます。

検出器	推論できるルール	提供形態
禁止されたインポート（AP-001、AP-002）	AP-001：リクエストエントリ（ルートハンドラー）はDBクライアントをインポートしてはなりません。AP-002：サーバーエントリはUIレイヤーをインポートしてはなりません	自動
循環依存	モジュールグラフは非巡回である必要があります。循環がない場合に採用され、新たな循環があると archprint check が報告します	チェック
テストの分離	本番コード（テスト以外のコード）はテストファイルや spec ファイルをインポートしてはなりません	自動
依存関係の健全性	サードパーティーパッケージは、依存関係の src／internal 内部を使わず、公開エントリからインポートします	レビュー
依存関係の宣言	インポートするサードパーティーパッケージはすべて package.json に宣言する必要があります（幻の依存関係や推移的依存関係は不可）	レビュー
インポートスタイル	深い相対インポート（../../../）よりも、ワークスペースエイリアスを優先します	自動
コンソールの分離	ライブラリ（CLI 以外）のコードは console.* を呼び出してはなりません	自動
公開 API（バレル）の境界	機能やパッケージの外部にあるファイルは、内部を深くインポートせず、index バレルを介してインポートする必要があります	自動
レイヤーの境界	あるレイヤーのファイルは別のレイヤーをインポートしてはなりません。支配的な依存方向から推論します	レビュー
役割の階層化	意味上の階層は依存方向を維持します（REPOSITORY は SERVICE を、SERVICE は CONTROLLER をインポートしてはなりません）	レビュー
エントリの純粋性	フレームワークエントリ（ページ、ルート、レイアウト）は、他のファーストパーティーコードからインポートしてはなりません	レビュー
UI／データの分離	再利用可能なUIコンポーネントは、DB／データレイヤーを直接インポートしてはなりません	レビュー
サーバー／クライアントの境界	Next.js の "use client" モジュールは server-only モジュールをインポートしてはなりません	レビュー
機能スライスの分離	features／modules／slices／domains コンテナー内の兄弟スライス同士は、互いをインポートしてはなりません	レビュー
アプリの分離	apps／services コンテナー内の兄弟アプリ同士は、互いを直接インポートしてはなりません	レビュー
環境変数へのアクセス	process.env は config／env レイヤーでのみ読み取ります	レビュー
ワークスペースパッケージ API	モノレポのワークスペースパッケージは、ソースへの深いパスではなく、パッケージ名でインポートします	レビュー
ストーリーの分離	Storybook の .stories ファイルは、他のコードからインポートしてはなりません	レビュー
孤立モジュール	何からもインポートされず、フレームワークエントリでもないファイル（デッドコード候補）	レポート
推移的な到達可能性	通常のインポートルールを通過するものの、中間レイヤーを介して漏れ出すレイヤー境界	レポート
recommend（および init）では、各ルールファミリーを次の層に分類します。コードがすでに従っているルール（今すぐ適用）、Archprint が報告するもののコードでは記述していないルール、根拠が乏しいルール（確認して採用）、そして類似リポジトリでは一般的に従われているものの、まだコードでは従っていないルール（初日から採用）。各推奨には、そのルールをすでに適用している類似リポジトリ（検出されたスタック、該当しない場合は全体）の割合が記載されており、数万件の公開 TypeScript リポジトリを対象とした調査から得られたものです。そのため、学習に使えるコードが少ない新しいリポジトリでも、厳選されたデフォルトではなく、エコシステムの実態に基づいたスタック対応のベースラインを得られます。

プロジェクトに書き込まれる内容

archprint generate（および init）は、.archprint/config.json と、リポジトリですでに実行されていて、適用するルールがある各リンター用のファイルを1つずつ書き込みます。一般的な ESLint プロジェクトでは config.json と eslint.mjs の2ファイルが作成されます。dependency-cruiser のルールも採用するリポジトリでは、3つ目のファイルが作成されます。archprint は ESLint と dependency-cruiser を検出するため、使っていないツールの設定が残ることはありません。--emit <eslint|dependency-cruiser|all> を指定すると、出力形式を強制できます。

• .archprint/config.json（常に作成）：採用した各ルールの正確な定義、採用時に記録された根拠と生成時の解決モード（archprint check はこのファイルを読み込むため、チェック時にルールを再推論しません）、理由とともに許可した例外、現在適用されているルール、追跡のみで報告されるルール、レビュー待ちのルール、採用する価値のあるルール、および eject で削除される管理対象の出力ファイル一覧。
• .archprint/eslint.mjs（ESLint がある場合）：推論された ESLint ルール（マーカーに基づくインポート禁止、no-restricted-imports によるインポートスタイルの境界、コンソールの分離、構造ルールを含め、dependency-cruiser を使用しない場合はレイヤー境界、未宣言の（ファントム）依存関係、サーバー／クライアントの境界、パッケージ内部へのアクセス、エントリポイントの純粋性）をすべてインライン化した、自己完結型の ESLint フラット設定ファイルです。追加のプラグインは不要です。既存の ESLint 設定にルールを追加するもので、既存の設定ですでに TypeScript を解析できます。そのため、このファイルをコミット、公開したり、別のリポジトリに渡したりして、1行で採用できます（import archprint from './.archprint/eslint.mjs'）。例外はレイヤー境界です。ファイルを基準にアプリを特定するため、生成した場所でのみ適用されます。**/.archprint/** は自動的に無視されます。インポート禁止（AP-）ルールと構造ルールは、生成されたローカル ESLint プラグインとしてこのファイルに含まれているため、ESLint 設定を接続するだけで適用され、追加のインストールは不要です。
• .archprint/dependency-cruiser.json（dependency-cruiser がある場合）：機械的に判定できる境界（公開 API の深いインポート、テストの分離）を含む forbidden ルールセットが1つ作成されます。レビュー待ちのルール（レイヤー、役割のレイヤー分け、機能スライス、アプリの分離、エントリポイントの純粋性、依存関係の内部へのアクセス、ファントム依存関係、サーバー／クライアント）は、レビュー後に --include-structural を指定した場合のみ追加されます。
• README.md の管理対象セクション：現在適用されているルール、追跡のみで報告されるルール、レビュー待ちのルール、採用する価値のあるルールをまとめたものです（init または generate --readme が書き込みます）。また、生成されたファイルがフォーマッターの対象外になるよう、管理対象の .prettierignore エントリも追加されます。

--expand を指定すると、.archprint/ 内に詳細な成果物も追加で書き込まれます。ファミリーごとの ESLint および dependency-cruiser の JSON、合格・不合格のフィクスチャを含むルールごとのカード（.md）、eslint-plugin-boundaries の要素型設定、ts-arch のテスト、Mermaid および Graphviz DOT 形式のレイヤー図が含まれます。

同期の維持とクリーンな削除。 generate（または init）を再実行すると .archprint/ が更新され、根拠がなくなったルールは削除されるため、出力がコードから乖離することはありません。wire は、リポジトリで使用している各適用ツール（フラット形式の ESLint 設定、.dependency-cruiser.json）に管理対象の参照を1つ挿入します。この参照は再生成後も維持されます。安全に編集できない設定（たとえば JS 形式の dependency-cruiser 設定）の場合は、貼り付ける正確なスニペットを出力します。eject は Archprint のファイルと接続された参照をすべて削除し、各設定を完全に元の状態に戻します。generate --check は生成された ESLint ルールをリポジトリに対して実行し、合格するかどうかを報告するため、接続前に確認できます。0.5.x からアップグレードしますか？ archprint migrate を使うと、以前の archprint-rules/ 構成をこのレイアウトに移行し、設定の参照をその場で付け替えられます。

CI での使用

archprint check は、チームが init または generate で採用したルールについて、ベースブランチと比較し、変更によって新たに発生した違反のみを報告します。既存の未対応項目は表示されず、各指摘には根拠が付いています。どの CI でも動作し、GitHub では各指摘をプルリクエスト上にインラインで表示します (デモ用プルリクエストで確認)。

GitHub では、archprint check Action（ GitHub Marketplace）を使用します：

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: Tommkruix/archprint-action@v1

プルリクエスト自体をチェックアウトするため、checkout ステップは不要です。Action を使わず、通常のステップで同じチェックを行う方法：

# .github/workflows/archprint.yml
name: archprint
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - run: npx archprint check --base ${{ github.event.pull_request.base.sha }} --format github

• デフォルトでは警告です。 新しい違反があったときにジョブを失敗させるには、--fail-on new（または Action の fail-on: new）を追加し、ブランチ保護でこのジョブを必須のステータスチェックに設定すると、新たな違反を追加するプルリクエストはマージできなくなります。

• 採用済みルールのみを対象にします。 check は、init と generate が書き込む .archprint/config.json 内の採用済みルールを読み込み、そこに記録されたルールのみをチェックします。対象は機械的なルールと、--include-structural で採用した場合のレイヤー境界です。同じプルリクエストで採用されたルールは一覧表示されますが、そのプルリクエストに対する違反として数えられることはありません。

• 解決先のないインポートは TypeScript の役割です。 CI で tsc --noEmit を実行するか、デフォルトで実行される next build の型チェックを利用してください。プロジェクト独自のモジュール解決に基づき、モジュールが見つからない場合（TS2307）を報告します。Archprint はこのルールを生成しません。また、TypeScript アプリでは、import/no-unresolved や dependency-cruiser の not-to-unresolvable は、paths エイリアス、パッケージの exports、?raw などのバンドラー用サフィックスに対して誤検出しがちです。

• 正当な例外には理由が必要です。 ファイルがルールに違反する正当な理由がある場合は、その理由を記録します： npx archprint allow AP-001 app/api/health/route.ts --reason "Health check queries the database directly"。 これは .archprint/config.json の allowed リストに追加され、check はその違反を数えなくなり、理由とともにプルリクエストに表示します。次回の archprint generate では、生成されるルールがそのファイルを違反として報告しなくなります。理由のない項目は拒否され、コード上で不要になった項目は指摘されます。dependency-cruiser（公開 API）を通じて適用されるルールは、まだその側では対象外です。

• ルールの削除は必ず通知されます。 プルリクエストで .archprint/config.json が削除された場合、またはベースブランチにあるルールが削除された場合、check は警告を表示し、チェック対象から外れるルールをすべて列挙します。ルールの削除はチームの意図的な判断である可能性があるため、ジョブは失敗しません。この判断にレビューを必須とするには、CODEOWNERS エントリーを追加し、ブランチ保護で「Require review from Code Owners」を有効にします：

  /.archprint/ @your-team
  /.github/workflows/ @your-team
  

• アップグレード： 0.8.x 以前からアップグレードする場合は、採用済みルールを記録するために archprint generate を一度実行してください。実行するまでは、check は実行されなかったことを通知して終了コード 0 で終了します。0.9.0 から 0.11.x までのセットアップはそのまま動作します。check は引き続き rules.json と allow.json を読み込み、次回の generate で両方を config.json に移行します。

• その他の CI システム： --format json はバージョンごとにキー付けされた出力を返し、終了コードが動作上の契約となります：0 は問題なし、--fail-on new 指定時の 1 は新しい違反あり、2 は CI の設定に問題あり（例：ベースコミットを含まないシャロークローン）。全履歴をチェックアウトしてください（fetch-depth: 0 またはお使いの CI に相当する設定）。

• フォークからのプルリクエストでも安全です。 読み取りアクセスのみが必要で、シークレットを使用せず、コードを実行することもありません。

MCP のセットアップ

archprint mcp は Archprint を stdio 経由の MCP サーバーとして実行するため、エージェントはコードを書く前に、リポジトリがすでに従っているアーキテクチャルールと、その根拠を確認できます。読み取り専用のツールを 4 つ公開します：archprint_scan、archprint_recommend、archprint_explain、archprint_check です。各ルールは平易な言葉とその根拠、違反しているファイル、archprint がそのルールを強制するのか、レビュー用に保留するのか、報告のみを行うのかとともに返されます。archprint_explain にはスキャン結果に含まれる任意のルールラベル（たとえば AP-002 や env-access）を渡せます。archprint_check は、エージェントが現在の変更で違反している採用済みルールを、未コミットの編集も含めて報告するため、エージェントは作業を終える前に修正できます。Claude Desktop、Claude Code、Cursor、または任意の MCP クライアントから接続してください：

{
  "mcpServers": {
    "archprint": { "command": "npx", "args": ["-y", "archprint", "mcp"] }
  }
}

エージェントへの質問例。 ツール名を指定する必要はありません。エージェントが選択します：

• 「このリポジトリがすでに従っているアーキテクチャルールは何ですか？」
• 「env-access ルールに違反しているファイルはどれですか？ どう修正すればよいですか？」
• 「新しい API ルートを追加します。このコードベースでは、どのルールに従うべきですか？」
• 「今すぐ強制すべきルールと、採用を検討する価値のあるルールはどれですか？」

コードはお使いのマシンにとどまります。 この既定のサーバーはローカルで動作し、ローカルのチェックアウトを読み取るため、プライベートコードにはこちらを使用してください。利用している Git ホストにかかわらず、ソースがマシンの外に出ることはありません。

サーバーが起動しない場合。 クライアントにサーバーの起動に失敗した、または npx が見つからないと表示された場合、クライアントからシェルの PATH を参照できていません。Dock やスタートメニューから起動したデスクトップアプリは PATH を読み込まないため、Node を nvm や Homebrew からインストールしている環境ではよく起こります。npx のフルパスだけでは不十分です。npx 自体が PATH 上の node を必要とするためです。たとえば /opt/homebrew/bin のように、dirname "$(which node)" が出力するフォルダーを両方に指定してください：

{
  "mcpServers": {
    "archprint": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "archprint", "mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

エディターをターミナルから起動する方法もあります。その場合、シェルの PATH が引き継がれます。

ワンラインでのインストール。 Claude Code では：

claude mcp add archprint -- npx -y archprint mcp

Cursor では、上記の JSON をプロジェクト内の .cursor/mcp.json（すべてのプロジェクトに適用する場合は ~/.cursor/mcp.json）に配置し、Settings > MCP で archprint を有効にしてください。

URL を指定して公開リポジトリをスキャンする。 archprint mcp --http は、代わりにリモートサーバーを実行します。リポジトリを一時ディレクトリに浅くクローンし、同じ読み取り専用の分析を実行して結果を返した後、クローンを削除します（対象は github.com、gitlab.com、bitbucket.org の公開 URL のみです。書き込みや保持は行いません）。この場合、ツールには repo URL（および任意の ref）を渡します。既定では 0.0.0.0:8848/mcp で待ち受けます（自分のマシンだけで使う場合は --host 127.0.0.1 を設定し、ポートを変更する場合は --port／$PORT を設定します）。また、/health（/healthz を予約している Cloud Run ではこちらを使用します）と /healthz でヘルスチェックに応答します。リクエストのたびにクローンとスキャンを行うため、誰でもアクセスできるサーバーでは、誰かのために計算リソースを消費します。このコストを許容しない限り、Cloud Run の IAM などを使って認証の背後に配置してください。

ツールは読み取り専用で、リポジトリに書き込むことはありません。ルールを実際に生成して適用するには、CLI の generate／wire を使用してください。

比較

既存の TypeScript ツール（dependency-cruiser、eslint-plugin-boundaries、Nx、Sheriff、ts-arch）は、すべて手動で作成したアーキテクチャルールを適用します。Archprint は実際のインポートグラフからルールを推論し、提案する前に、各ルールを統計的な根拠に基づいて判定します。その後、これらのツールの形式で出力するため、既存のスタックを置き換えるのではなく、補完します。

各ツールのドキュメント（TypeScript エコシステム）と照合して確認済みです。重要なのは、他の TypeScript ツールでは埋められていない次の 2 つの列です。

ツール	アーキテクチャルールを適用	インポートグラフから自動推論	統計的な根拠を付与
Archprint	はい	はい	はい
dependency-cruiser	はい	いいえ	いいえ
eslint-plugin-boundaries	はい	いいえ	いいえ
@nx/enforce-module-boundaries	はい	いいえ	いいえ
Sheriff	はい	いいえ	いいえ
ts-arch	はい	いいえ	いいえ
madge / knip	分析のみ	いいえ	いいえ

正直に補足すると、他のエコシステムでは Tach（Python）と ArchLint（Java）がモジュール境界を自動推論しています。そのため、Archprint 独自の領域は、TypeScript エコシステムにおける自動推論と統計的な根拠に基づく判定の組み合わせです。また、Archprint は依存関係の循環、孤立したモジュール、到達可能性の検出では dependency-cruiser、不要なコードの検出では knip と機能が重なります。競合するのではなく、生成したルールをこれらのツールの形式で出力します。

コマンド

• archprint init [path]：設定不要でセットアップします。技術スタックを検出し、コードがすでに従っているルールを適用して、.archprint/ と管理対象の README セクションを書き込みます。オプション：--expand、--include-structural、--out <dir>、--fast、--force。
• archprint scan [path]：リポジトリがすでに従っているルールを、根拠とともに報告します。変更は行いません。--deep はバレルとエイリアスをたどって解決します。
• archprint explain <id> [path]：1 つのルールについて、例外ごとのコードフレーム、修正方法、使用すべきでない場合、適用方法を含むゲートの内訳を表示します。
• archprint recommend [path]：リポジトリの根拠と検出された技術スタックに基づいてルールセットを推奨します（新規リポジトリでも機能します）。書き出せる各ルールを適用する、インストール済みのツールも示します。
• archprint generate [path]：リポジトリで使用しているリンター向けに、自動的に信頼される機械的なルールを .archprint/ に書き込みます。構造的なルールはレビュー用に保留されます。--emit <eslint|dependency-cruiser|all> は出力形式を指定し、--only <family> と --rules <ids> は出力を絞り込みます（--rules は、AP-002、import-style、レイヤールールの no-lib-to-app など、指定したルールだけを残します）。--check は生成したルールをリポジトリに対して実行し、--readme は README セクションを追加し、--expand はファミリーごとのファイル、カード、フィクスチャ、グラフも書き込み、--rule <id> はレビュー済みのルールを 1 つ出力します。さらに、--include-structural、--no-graph、--out <dir>、--fast も指定できます。
• archprint check [path]：--base <branch or commit> との比較に基づいて、変更によって発生した、採用済みルールへの違反を報告します。--fail-on new を指定しない限り、警告のみです。--format text|json|github、--out <dir>。CI での使用を参照してください。
• archprint allow <rule> <file> --reason "..."：理由を付けて、1 つのファイルで採用済みルールを 1 つ破ることを許可し、.archprint/config.json に記録します。check はそれを違反数に含めず、プルリクエストに一覧表示します。generate は生成されたルールによるフラグ付けを停止します。--remove は許可を取り消します。
• archprint wire：管理対象の可逆的な参照を介して、生成されたルールをリポジトリで使用している適用ツール（フラットな eslint 設定、.dependency-cruiser.json）から参照できるようにします。--out <dir>、--dry-run。
• archprint eject：Archprint が生成したファイル、設定、管理対象の README セクション、接続した参照を削除し、各設定を正確に元の状態に戻します。--out <dir>、--dry-run。
• archprint migrate（別名 upgrade）：古い archprint-rules/ のセットアップを .archprint/ のレイアウトに移行し、設定をその場で接続し直します。--dry-run。
• archprint mcp：Archprint を MCP サーバーとして実行し、Claude、Cursor、その他のエージェントが読み取り専用の scan、recommend、explain、check ツールを呼び出せるようにします。デフォルトでは stdio 経由で提供します。--http は、URL で指定した公開リポジトリをスキャンするリモートサーバーを実行します（scan、recommend、explain）。

scan --json、recommend --json、check --format json は、スクリプトで利用できる、バージョンをキーとする安定した JSON を出力します。終了コードが契約です。成功時は 0、エラー時は 1（check の場合、--fail-on new を指定して新しい違反があったとき）、CI のセットアップが原因で check を実行できなかった場合は 2 です。

実際のリポジトリでの例

inbox-zero の実際のスキャン（コミット 11281be 時点の apps/web、TypeScript ファイル 2,232 個）を、各セクションの最初のルールに絞り込んだもの：

Scanned 2,232 TypeScript files
Workspace aliases: 18 resolved

GENERATED RULES
  AP-002  no-ui-layer-in-server-entry      confidence 97%
          A request handler must not import UI components.
          Evidence: 216 of 217 files it applies to follow it (99.5%)
          Exceptions: 1

LAYER BOUNDARIES (review before enforcing)
  utils !-> app  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 451 app file(s) depend on utils
          Exceptions: 3
  utils !-> components  layer boundary   confidence 99%
          Evidence: 650/653 utils files conform (99.5%); 160 components file(s) depend on utils
          Exceptions: 3
  hooks !-> app  layer boundary   confidence 94%
          Evidence: 65/65 hooks files conform (100%); 121 app file(s) depend on hooks

AP-002 は機械的なファミリーなので、適用ルールとして自動生成されます。レイヤーの境界は推定されたものなので、レビュー用に表示されます。--include-structural を指定しない限り、適用ルールとしては書き込まれません。各数値は推定ではなく、インポートグラフから測定したものです。

同意するレイヤー境界を採用する

フォルダー名がレイヤーと誤解される可能性があるため、レイヤー境界はレビュー待ちの状態になっています。根拠を確認したら、ID で同意する境界を採用します。utils !-> app はルール no-utils-to-app になります。

# 1. Read the boundaries and their evidence
archprint scan apps/web

# 2. Write the rules you chose: AP-002 plus two of the boundaries above
archprint generate apps/web --include-structural --rules AP-002,no-utils-to-app,no-hooks-to-app

# 3. Reference the generated rules from your ESLint config (once)
archprint wire

dependency-cruiser を使わない場合、各境界は .archprint/eslint.mjs の archprint/no-utils-to-app のような ESLint ルールになり、追加のプラグインは不要です。dependency-cruiser を使う場合は、代わりにそちらに追加されます。このルールは、すでに境界に違反しているファイルを除外するため、リンターの結果は問題なしのままです。また、相対パスまたはエイリアスによる境界を越えた新しいインポートを検出します。archprint check はプルリクエストで新たな違反を報告し、archprint allow は正当な例外を記録します。--rules は指定したルールだけを残すため、同じ実行ですべての対象ルールを指定してください。CI で archprint のバージョンを固定している場合（たとえば GitHub Action の archprint-version）、まずそこで 0.13.0 以降を使用してください。ルールのリファレンスには、このルールが参照するインポートとファイルが正確に記載されています。

技術的なメモ

高速モードと詳細モード。 scan はデフォルトで高速な指定子レベルのパス（型チェッカーなし）を実行します。generate はデフォルトで詳細なパスを実行し、バレルやワークスペースのエイリアスを経由して解決します。生成が確定のタイミングだからです。構造分析（循環依存、孤立、到達可能性、パブリック API）は常に高速グラフを使用します。これらについては詳細な解決と同じ結果が得られ、実際、パブリック API の検出には高速グラフが必須です（詳細な解決ではバレル経由で解決され、バレルとその先の実装の違いを示す情報が失われます）。

決定性。 同じバージョンの同じリポジトリからは、常に同じ出力が生成されます。分析は純粋で、結果はソートされます。ランダム性はなく、分析エンジンのバージョンは厳密に固定されています。

ステータス

npm で公開されており、実際のリポジトリで安心して実行できます。すべてのルールはデフォルトでレビューが必要で、1 つのコマンド（archprint eject）で元に戻せます。また、決定性があり、生成されたルールは推論元のコードに対して必ず問題なしとなります。

• 大規模環境で検証済み： 最新の調査（archprint 0.12.2、2026 年 10 月）では、公開 TypeScript リポジトリ 92,861 件に対して scan を実行し、クラッシュはありませんでした。494 件（0.5%）は取得できないかタイムアウトしました。そのほとんどは削除済みか、非常に大規模なリポジトリでした。全ワークフロー（init、check、allow、generate、check、wire、eject）を層化サンプルの 2,019 件で実行したところ、バグが 1 件見つかりました。Next.js の [id] のようなルートフォルダーで発生する例外のバグで、0.12.3 で修正されました。実行できたリポジトリ 2,012 件はすべて、eject 後に実行前と完全に同じ状態に戻りました。
• 現在、本番環境で使用可能： scan と recommend、プルリクエスト向けの check、および機械的なルール群の自動適用に対応しています。生成時の自己整合性チェック、新規リポジトリ向けの init スキャフォルダー、React、Angular、Vue、Svelte にわたるフレームワーク対応も備えています。エンジン（20 個の検出器、信頼度ゲート、自己完結型の ESLint ファイル、dependency-cruiser、ts-arch、レイヤーグラフ向けの出力機能）は実装済みで、テストも完了しています。
• 今後の課題： 構造的なルール群を自動適用に向けて強化すること（ファイルごとの実用的な役割信頼度指標、レイヤーの凝集度、役割分類器の順序）。
• バージョンは引き続き 0.x です。 そのため、CLI の仕様とルール形式はマイナーバージョン間で改良される場合があります。これは成熟途上の仕様であり、実験的な分析ではありません。コンパクトな .archprint/ レイアウトは 0.6.0 で導入され、archprint migrate は以前のセットアップをその場でアップグレードします。

関連ベンチマークの AgentRuleBench は、ガイダンスと強制適用のどちらがよいかという問題を直接評価します（検証対象の境界について、事前登録された誠実な帰無結果が得られています）。

ここで使う用語

• インポート： 別のファイルのコードを使用するファイル内の行です。Archprint のルールでは、どのファイルがどのファイルをインポートできるかを定めます。
• Lint ルール／リンター： コードに対して実行される自動チェックです（最も一般的なのは ESLint です）。コードを書く際に問題を検出します。
• AUTO／SUGGEST／REJECT： ルールに対する Archprint の信頼度です。詳しくは信頼する対象の決定方法をご覧ください。
• 機械的／構造的なファミリー： 曖昧さのないシグナルに基づくルール（レビューなしで信頼されます）と、フォルダーの役割を推測する必要があるルール（レビュー待ちになります）を指します。
• MCP： AI エージェントが Archprint などの外部ツールを使用できるようにするオープン標準です。

ドキュメント

完全なドキュメントは tommkruix.github.io/archprintとdocs/にあります：はじめに、概念（信頼度ゲート、機械的なルールと構造的なルール、高速処理と詳細処理、生成／接続／取り外しのライフサイクル）、およびルールファミリーのリファレンス（各ルールが検出する内容、提供方法、使用すべきでない状況）。

コントリビューション

CONTRIBUTING.mdをご覧ください。このプロジェクトでは、自身の Lint、型チェック、テストを実行します。すべての変更でカバレッジをしきい値以上に保ち、変更セットを追加します。

ライセンス

MIT