1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@cvusk

archfit — コーディングエージェント時代のアーキテクチャ適性評価ツール

1
Posted at

archfit — コーディングエージェント時代のアーキテクチャ適性評価ツール

はじめに

コーディングエージェントがソフトウェア開発の現場に浸透してきています。Claude Code、GitHub Copilot、Cursor などの AI エージェントがコードを読み、変更を提案し、PR を作成する時代です。しかし、こうしたエージェントが安全かつ高速に作業できるかどうかは、コードの品質だけでなく、リポジトリの構造に大きく左右されます。

エージェントが最初に読むエントリーポイントは明確か？フィードバックループは高速か？ひとつの変更が全体を壊す危険な箇所は集約されているか？

archfit はこうした問いに答えるツールです。リンターでも SAST スキャナーでもなく、それらの「上位」に位置し、コーディングエージェントが安全に開発できるアーキテクチャ特性を評価します。この記事では、archfit の設計思想から実際の使い方までを解説します。

archfit とは何か

コードではなく「地形」を見る

既存の品質ツールは「コードの中身」を見ます。archfit は「コードが置かれている構造」を見ます。

ツール種別 見ているもの
リンター（ESLint, golangci-lint） コードスタイル・バグパターン
SAST（Semgrep, CodeQL） セキュリティ脆弱性
テストカバレッジ コードの網羅率
archfit リポジトリの構造的特性

コードがどんなにきれいでも、エントリーポイントが不明確で、テストが遅く、危険な変更箇所が散在していれば、エージェントは効果的に作業できません。archfit はこれらのツールと競合せず、補完します。

7 つのアーキテクチャ原則

archfit は 7 つの原則でリポジトリを評価します。各原則はコーディングエージェントと人間の開発者の両方にとって重要な構造的特性です。

原則 問い 具体例
P1: 局所性 変更はリポジトリの狭い範囲だけで理解できるか？ ルートに CLAUDE.md / AGENTS.md があるか、垂直スライスが独自のドキュメントを持つか、依存グラフの結合度は抑えられているか
P2: 仕様優先 契約はスキーマや型で定義されているか？ JSON Schema、OpenAPI、Protocol Buffers などの機械解析可能な仕様があるか
P3: 浅い明示性 隠れた設定なしで振る舞いが見えるか？ .env に対して .env.example があるか、Spring Boot/Terraform/Rails の設定が文書化されているか
P4: 検証可能性 正しさを高速にローカルで証明できるか？ Makefile 等の検証エントリーポイント、テストファイル、CI 設定が存在するか
P5: 危険の集約 認証・秘密情報は集中して保護されているか？ セキュリティ関連ファイルが散在せず集中配置されているか
P6: 可逆性 変更を低コストでロールバックできるか？ デプロイ成果物がある場合にロールバック手順が文書化されているか
P7: 機械可読性 エラー・ADR・CLI は機械にも読めるか？ 終了コードの文書化、CHANGELOG、ADR の記録があるか

クイックスタート

インストールとスキャン

archfit は Go 1.24 以上でビルドできます（CGO 不要）。Docker でも実行可能です。

インストール方法

# go installする
go install github.com/shibuiwilliam/archfit/cmd/archfit@latest

# 対象リポジトリの設定生成とスキャン
archfit init /path/to/your/repo
archfit scan /path/to/your/repo

# Docker で実行
docker run --rm -v "$PWD:/repo" ghcr.io/shibuiwilliam/archfit:latest scan /repo

出力の読み方

すべてクリアな場合と、改善点が見つかった場合の出力例です。

$ archfit scan .

archfit 0.1.7 — target . (profile=standard)
rules evaluated: 14, findings: 0
overall score: 100.0
  P1: 100.0
  P2: 100.0
  P3: 100.0
  P4: 100.0
  P5: 100.0
  P6: 100.0
  P7: 100.0
no findings

$ archfit scan .
archfit 0.1.7 — target . (profile=standard)
rules evaluated: 14 (1 with findings), findings: 1
overall score: 99.3
  P1: 97.5
  P2: 100.0
  P3: 100.0
  P4: 100.0
  P5: 100.0
  P6: 100.0
  P7: 100.0
findings:
  [info] P1.LOC.003 (repo) — package "." has transitive reach of 23 (threshold 10) — agents must load many neighbors to understand changes here

すべての検出結果にはエビデンス、信頼度、修正ガイドが付属します。スコアは重大度に応じたペナルティで 0〜100 の範囲で計算され、ルール追加でスコアが膨張しない正規化方式です。

自動修正

検出された問題は fix コマンドで自動修正できます。すべての修正は再スキャンで検証され、問題が残る場合は自動ロールバックされます。

archfit fix --all .           # 修正可能な全検出結果を一括修正
archfit fix --dry-run --all . # 変更内容をプレビュー
archfit fix P3.EXP.001 .      # 特定のルールを修正

7 つの Static Fixer が決定的な修正を提供します。

ルール 生成するファイル
P1.LOC.001 CLAUDE.md（リポジトリルート）
P1.LOC.002 AGENTS.md（各スライスディレクトリ）
P4.VER.001 Makefile（test/lint ターゲット付き）
P7.MRD.001 docs/exit-codes.md
P7.MRD.002 CHANGELOG.md
P7.MRD.003 docs/adr/0001-initial-architecture.md
P2.SPC.010 schemas/output.schema.json

CI/CD と運用への組み込み

GitHub Code Scanning（SARIF）

SARIF 2.1.0 形式で出力でき、GitHub Code Scanning と直接統合できます。

# .github/workflows/archfit.yml
- name: Scan
  run: archfit scan --format=sarif . > archfit.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: archfit.sarif

PR ゲートと時系列トラッキング

# PR で回帰を検出（新しい検出結果があれば exit 1）
archfit diff baseline.json

# スコア推移を追跡
archfit scan --json . > .archfit-history/2026-04-26.json
archfit trend --history .archfit-history

# 複数リポジトリを比較
archfit compare api.json frontend.json infra.json --format md

適性コントラクト

チームで適性目標を機械的に強制したい場合、.archfit-contract.yaml を定義できます。

version: 1
hard_constraints:                    # 違反するとスキャン失敗
  - principle: overall
    min_score: 80.0
    scope: "**"
soft_targets:                        # 期限付きの努力目標
  - principle: P4
    target_score: 95.0
    deadline: "2026-06-30"
area_budgets:                        # ディレクトリ単位の検出結果上限
  - path: "src/auth/**"
    max_findings: 0
    owner: "@security-team"

LLM アシスト（オプトイン）

--with-llm フラグで、検出結果に LLM による説明を追加できます。「あなたのリポジトリでなぜトリガーされたか」「具体的にどう修正するか」をリポジトリ固有のコンテキストで教えてくれます。

export ANTHROPIC_API_KEY=sk-...
archfit scan --with-llm .              # 検出結果を補強
archfit fix --with-llm --all .         # コンテキスト依存の自動修正

Claude、OpenAI、Gemini の 3 プロバイダーに対応。基本スキャンは LLM 呼び出しゼロで、API エラー時は静的修正に自動フォールバックします。ソースコードは送信されません。

内部アーキテクチャ

archfit 自体が自らの 7 原則に従って設計されており、make self-scan で自分自身のスキャンに合格することが求められます（メタ一貫性ルール）。

処理の流れ

処理は 3 つのフェーズに分かれます。

  1. Collectors がリポジトリからファクト（事実）を収集する。ファイルシステム、git 履歴、スキーマ、依存グラフ、コマンド実行時間（--depth=deep のみ）の 5 種類。観察のみで判断は行わない
  2. Rule Engine が FactStore（読み取り専用ビュー）を受け取り、各ルールのリゾルバーを実行する。リゾルバーは I/O を行わない純粋関数
  3. Renderers / Fix Engine が結果を出力、または自動修正を適用して再スキャンで検証する

FactStore パターン

archfit の設計の要は、Collector とルールリゾルバーの間に置かれた FactStore です。

type FactStore interface {
    Repo() RepoFacts                // ファイルシステム
    Git() (GitFacts, bool)          // git 履歴（オプショナル）
    Schemas() SchemaFacts           // スキーマ情報
    Commands() (CommandFacts, bool) // コマンド実行結果（deep のみ）
    DepGraph() (DepGraphFacts, bool)// 依存グラフ（Go のみ）
}

リゾルバーはこのインターフェースのみを通じてデータにアクセスし、ファイルシステムに直接触れません。これは archfit 自身の P5（危険の集約）を自分自身に適用した設計です。境界違反は go-arch-lint で CI 時に検出されます。

ルール一覧

core パック（全リポジトリ対象、11 ルール）:

ID 原則 検査内容 重大度
P1.LOC.001 局所性 ルートに CLAUDE.md / AGENTS.md が存在 warn
P1.LOC.002 局所性 垂直スライスが独自の AGENTS.md を持つ warn
P1.LOC.003 局所性 依存グラフの結合度が抑えられている info
P1.LOC.004 局所性 コミットが限られた数のファイルに収まっている info
P3.EXP.001 浅い明示性 設定の文書化（4 エコシステム対応） warn
P4.VER.001 検証可能性 高速な検証エントリーポイントの存在 warn
P4.VER.002 検証可能性 テストファイルの存在 info
P4.VER.003 検証可能性 CI 設定の存在 info
P5.AGG.001 危険の集約 セキュリティ関連ファイルの集中 warn
P6.REV.001 可逆性 ロールバックドキュメントの存在 warn
P7.MRD.001 機械可読性 CLI の終了コード文書化 warn

agent-tool パック（オプトイン、3 ルール）:

ID 原則 検査内容
P2.SPC.010 仕様優先 バージョン付き JSON Schema の提供
P7.MRD.002 機械可読性 CHANGELOG.md の存在
P7.MRD.003 機械可読性 ADR の記録

archfit は言語非依存で、Go、Node/TypeScript、Python、Rust、Java、Ruby、PHP など 20 以上のエコシステムを認識します。Docker、Kubernetes、Terraform、AWS CDK など主要なデプロイ基盤のアーティファクトも検出対象です。

設定

.archfit.yaml で有効なパック、リスクティア、ルール抑制を設定できます。

version: 1
project_type: ["agent-tool"]
profile: standard
packs:
  enabled: ["core", "agent-tool"]
risk_tiers:
  high: ["src/auth/**", "infra/**"]
  low: ["docs/**", "tests/**"]
ignore:
  - rule: P1.LOC.002
    paths: ["packs/legacy-*"]
    reason: "レガシースライスは削除予定"
    expires: "2026-12-31"          # 期限切れは警告表示

主要フラグ: --format {terminal|json|md|sarif}、--fail-on {info|warn|error|critical}、--depth {shallow|standard|deep}、--with-llm、--record <dir>。

設計哲学

archfit の設計を貫く 4 つの哲学があります。

エビデンスであり、判決ではない。 すべての検出結果は重大度、エビデンス強度（strong/medium/weak/sampled）、信頼度（0.0〜1.0）、修正方法を持ちます。error の重大度には strong のエビデンスが必須で、誤検知はバグとして扱われます。

自己参照的な一貫性。 archfit は make self-scan で自分自身のスキャンに合格しなければなりません。自身のコードベースが 7 原則の実践例になっています。

決定論的で再現可能。 JSON 出力は決定論的に並び替えられ（severity desc → rule_id asc → path asc）、テストはネットワーク I/O を一切行いません。

少数の堅牢なルールは大量の弱いルールに勝る。 少数の高品質なルールを重視し、高い重大度には高いエビデンスを要求します。

まとめ

archfit はコードの品質ではなく、コードが置かれている「構造」を評価する新しいツールです。

  • 7 つの原則: 局所性、仕様優先、浅い明示性、検証可能性、危険の集約、可逆性、機械可読性
  • 14 のルール: 2 パック（core 11 ルール、agent-tool 3 ルール）に整理。自動修正はスキャン→修正→検証→ロールバックの完結ループ
  • CI 統合: SARIF による GitHub Code Scanning、PR ゲート、時系列トラッキング、適性コントラクト
  • LLM アシスト: オプトインで Claude/OpenAI/Gemini による説明・修正の補強
  • 言語非依存: 20 以上のエコシステムに対応

archfitを使うことで、皆様のコーディングエージェントがより働きやすく効果を発揮すると幸いです。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?