AIに開発を任せると、コードを書く速さより「どこが変わったのかを確認する時間」が問題になりがちです。ファイル名だけの差分を、認証・請求・画面といった仕事の単位で見渡せたら、誰に何をレビューしてもらうかを決めやすくなります。
Archwhereは、リポジトリに構成要素と担当ファイルを宣言し、Gitの変更をその地図へ載せるオープンソースの開発ツールです。v0.2.0は2026年10月31日14時05分47秒JSTに公開されました。ふくふくでは同日、Mac上の架空の注文管理リポジトリでCLIを動かしました。
未登録ファイルは検出できました。しかし自動修正は、今回の教材の「請求」ファイルを「認証」へ追加しました。その後のcheckは成功します。成功が示すのはモデルの形式やファイル対応の整合性であり、業務上の分類が正しいという保証ではありません。
何をする道具か：ファイルの差分を、機能の言葉へ置き換える
中心となるのはarchitecture.jsonです。component（構成要素）ごとに名前、種類、担当パス、依存先などを書きます。たとえばsrc/auth/**を「認証」、src/web/**を「画面」と宣言します。**は配下のファイルをまとめて指定するパターンです。ArchwhereはGitの差分とこの宣言を照合し、触れた構成要素を表示します。
これはCLI自身がLLMでコードの意図を読み解く仕組みではありません。宣言したパスとの照合が基本です。構成図の矢印も、宣言した依存関係を表します。実行中の全通信や、コード内部の依存を網羅的に観測した図ではありません。v0.2.0のREADMEと実装で確認できます。
| 機能 | できること | 読み違えないための注意 |
|---|---|---|
| 変更のマッピング | 変更ファイルを構成要素に割り当て、security種別やwatchパターンに応じて注意を表示 | 表示がないことは、安全性の証明ではない |
| check | 宣言の形式、参照先、Git管理対象ファイルの未登録などを検査 | まだGitに追加していない新規ファイルまで網羅する検査ではない |
| check --fix | 未登録ファイルの割り当てを推測してモデルを変更 | ディレクトリなどに基づく推測。意味の正しさは人が確認する |
| doc／Mermaid出力 | 宣言した構成と関係を文書や図の記法にする | 自動的に最新の実設計を発見する機能とは異なる |
| heat | Git履歴から変更の多い領域を示す | 本番の処理負荷や障害発生率ではない |
| mission | 構成図からGitHub上の会話やエージェントの作業につなぐUI | 今回は未試用。GitHubの権限や接続先AIの設定が別途必要 |
日本の開発現場で使うなら、まずレビューの振り分けに
国内でも、AIが作った変更を誰がどの深さまで確認するかが課題になっています。カウシェの開発記事では、決済や認証などのリスクと、人がレビューする範囲を整理しています。DMMの開発記事では、PRレビューの指摘をAI向けルールへ反映する取り組みを紹介しています。これらはArchwhereの導入事例ではありませんが、差分と責任範囲を結び付ける必要性を考える材料になります。
導入するなら、最初から全社の設計図を完成させる必要はありません。「認証」「請求」「利用者画面」などレビュー担当が異なる数領域から始めます。AIのPRが認証に触れたら認証担当が確認する、複数領域なら境界の入出力を確認する、といった運用です。これは本誌が提案する使い方であり、レビュー時間の削減を実測した結果ではありません。
利用条件：今回の再現手順はNode.jsとGitだけ
package.jsonのNode.js要件は18以上、ライセンスはMITです。今回のCLI試用はmacOS・arm64、Node.js v24.22.1、Gitを使用しました。追加のnpm依存パッケージやAI契約を入れず、公開ソースのv0.2.0を固定して実行しています。Windows／Linuxでの動作は本記事では未確認です。説明は英語中心ですが、モデルの日本語名はCLIとMermaidの出力に表示できました。
確認時点でnpmレジストリのarchwhereへの取得は404となり、npm経由の配布を確認できませんでした。そこで、以下は実際に試せたGitHubのタグ指定を使います。今後の最新コードと、ここで検証した0.2.0を混同しないでください。
MITライセンスのCLIと、接続先AIの利用料は別です。GitHub Actionsの利用枠や外部エージェントの契約も確認します。missionはGitHub認証を使ってIssueやコメント、マージなどを扱う実装を含むため、今回は起動していません。
教材で試す：まず3つの構成要素を登録する
Archwhere練習用リポジトリをダウンロードしてください。中身はarchitecture.json、説明書、文字列を定義するだけのJavaScriptです。実際の認証・請求処理も通信も実装していません。既存の業務リポジトリには入れず、新しい練習用フォルダで進めます。コマンドはmacOS向けです。
mkdir archwhere-labcd archwhere-labgit clone --depth 1 --branch v0.2.0 https://github.com/tapaskar/archwhere.git archwhere# ダウンロードしたZIPをこのフォルダへ置いてから展開unzip archwhere-02-demo.zipcd archwhere-demogit init -b maingit add .git -c user.name="Local Trial" -c user.email="trial@example.invalid" commit -m "initial sample"node ../archwhere/bin/archwhere.js check初回は「3 components, 0 flows, every tracked file mapped」と表示されます。認証・画面・構成と説明の3要素に、すべてのGit管理対象ファイルが対応したという意味です。0 flowsは、業務フローをこの教材では宣言していないことを表します。
printf 'export const policy = "token-required";\n' > src/auth/login.jsnode ../archwhere/bin/archwhere.jsこの変更では「認証 [security]」「src/auth/login.js」と、設定した「認証ルールを人が確認」が表示されました。securityはモデルに付けた種類、watchは指定した文字列パターンへの注意です。この例のtokenという文字が、実際に安全な認証方式を実装しているわけではありません。
未登録の請求ファイルを追加すると、何が起きるか
mkdir -p src/billingprintf 'export const invoiceLabel = "請求デモ";\n' > src/billing/invoice.jsgit add src/billing/invoice.jsnode ../archwhere/bin/archwhere.js checkcheckは終了コード1となり、未登録ファイルsrc/billing/invoice.jsを報告しました。ここまでは狙いどおりです。ところが修正候補は、components.auth.pathsへこのファイルを足す内容でした。今回の構成とパスでは、請求を独立した要素と判断せず、既存の認証へ寄せたのです。
node ../archwhere/bin/archwhere.js check --fixnode ../archwhere/bin/archwhere.js check実行後のarchitecture.jsonでは、authのpathsにsrc/billing/invoice.jsが追加されました。1行目は検出したエラーにより終了コード1を返し、再検査を案内します。2行目は終了コード0で「3 components」と表示されました。CLIが示すとおり、修正したパターンを人が確認する必要があります。checkの実装を含むソースも参照してください。
| 試した段階 | 結果 | 何を確認できたか |
|---|---|---|
| 初期モデルをcheck | 成功・3要素 | 宣言と管理対象ファイルが対応する |
| 認証ファイルを変更 | 認証と注意文を表示 | 宣言した担当領域へ差分を割り当てられる |
| 請求ファイルをGitへ追加 | 失敗・未登録1件 | モデルの更新漏れを検出できる |
| --fix後に再検査 | 成功・3要素 | 誤った業務分類でも対応が付けば成功しうる |
| 人が請求要素を追加 | 成功・4要素 | 意図した分類をモデルへ反映できる |
直すときは、パスだけでなく「誰の責任か」を決める
この教材では請求を認証と別の責任範囲として扱います。architecture.jsonのauth.pathsからsrc/billing/invoice.jsを削除して、元の["src/auth/**"]へ戻します。そのうえでcomponentsの中に、次のbillingを追加します。JSONの既存要素との間にカンマが必要です。
"billing": { "name": "請求", "kind": "feature", "paths": ["src/billing/**"], "deps": []}node ../archwhere/bin/archwhere.js checknode ../archwhere/bin/archwhere.js docnode ../archwhere/bin/archwhere.js --format mermaidふくふくの再検査も4要素で成功しました。docでは構成の一覧とMermaid記法が出力され、宣言した「画面→認証」も確認できました。教材のdepsは練習用の宣言です。請求から認証への依存などを実システムに合わせて記述する判断は、別途必要です。
実務で価値が出るのは、未登録の変更を単に通すのではなく「新しい構成要素なのか」「既存要素へ入るのか」「どの担当が確認するか」をPRで決めるところです。CIのcheck成功だけで自動マージしてよい、と判断する使い方は避けます。
既存リポジトリへ広げる前の確認
v0.2.0のinitは、--inferを付けた場合に既存構成からの推定を行います。引数なしのinitはサンプルを使うため、自分のシステムが自動解析されたと解釈しないでください。またinitはGitHub Actions用のワークフローも作成します。今回の教材は、これらを使わずarchitecture.jsonを直接用意しています。
本番へ取り入れるなら、まず検証用のブランチで構成定義だけをレビューし、担当範囲と既存のCIに合うか確認します。エージェント連携やmissionは次の段階です。公式READMEのGitHub認証、Issue、Claude連携やWebhookの条件を読み、誰の権限でどの操作が行われるかを確かめます。今回、実PRへの接続やAIへの指示・応答、マージは試していません。
変更したファイルとarchitecture.jsonの対応を確認してください。checkの成功を設計・セキュリティの正しさとは扱わないでください。
未登録ファイルがあれば、既存要素へ入れる案と新しい要素を作る案を、業務上の責任と依存関係から比較してください。パス名だけで結論を出さず、不明点は質問として残してください。
まず変更案とレビュー担当の候補を示し、承認前に--fixやモデルの書き換え、GitHubへの投稿、マージは行わないでください。修正後はcheckの結果と、人が確認すべき意味上の判断を分けて報告してください。複数エージェント間の会話を扱うmurmurの記事と合わせて考えると、Archwhereは「どの領域の変更か」を整理する役割です。道具を増やす前に、見落としやレビューの迷いが減るかを、小さいリポジトリで確かめるのがよい出発点です。
仕様・試用確認：2026年10月31日JST、Archwhere v0.2.0、ソースコミット01e36f4ed7bef1442bba8928efc78d2ef689c9dd。MacのローカルCLIと架空教材を使用。Mermaid記法の出力は確認しましたが、missionのUI、実エージェント連携、Windows／Linux、レビュー時間や品質改善の比較は未実測です。