🍝 Spaghetti Guard (spag)

AI開発のコード崩壊を防弾する、3段防衛ワンストップ CLI セーフティネット

spaghetti-guard（略称 spag）は、AIエージェント（Antigravity、Cursor、Claude Code、Aiderなど）を用いた高速自動コーディングにおいて、コードベースの「スパゲッティ化（構造破壊・アーキテクチャ無視・過度な複雑化）」を**「予防」「検知」「延命」の3段防衛ライン**で防ぐための、プロジェクトへの一度きりのセットアップ CLI ツールです。

💡 なぜ Spaghetti Guard なのか？

AIコーディングの台頭により、プロンプトだけで高速にコードを生成する「Vibe Coding（バイブコーディング）」が普及しました。しかし、プロジェクトが成長するにつれて以下の深刻な課題が発生します。

• アーキテクチャの無視・崩壊: レイヤー境界（例: コアからコントローラーへの逆依存）を無視した密結合コードをAIが勝手に生成する。
• 関数の肥大化（神クラスの降臨）: 1ファイルに何千行もの処理を詰め込み、人間が解読不能な巨大ファイル化が進む。
• デグレード（既存機能の損壊）: 新機能の追加やリファクタリング時に、AIが既存の挙動を破壊してしまう。

spaghetti-guard は、spaghetti-guard.config.yaml 1枚で独自の開発ルールを注入し、AIエージェントに厳格な開発防衛網（ガードレール）を強制します。

🛡️ コア設計思想：3段防衛ライン

Spaghetti Guard は、AI開発におけるコード崩壊を以下の3つの防御壁でブロックします。

【Spaghetti Guard 3段防衛ライン】
┌─────────────────────────────────────────────────────────────┐
│ 1. 予防 (Prevention)   : AGENTS.md + specs/ + Spec-Kit       │
│    ➔ AIに開発憲法と仕様の遵守を事前に強制                     │
├─────────────────────────────────────────────────────────────┤
│ 2. 検知 (Detection)    : dependency-cruiser / PyTestArch    │
│    ➔ レイヤー境界違反・ファイル肥大化をテストで自動ブロック │
├─────────────────────────────────────────────────────────────┤
│ 3. 延命 (Preservation) : spag freeze (Characterization Test) │
│    ➔ 既存挙動をテストで固め、デグレードゼロでリファクタ   │
└─────────────────────────────────────────────────────────────┘

1. 予防 (Prevention / Spec-Driven):
   • spag init 実行時に AGENTS.md（開発憲法）と specs/（仕様書）を自動生成。
   • Spec-Kit (specify) と連携し、AIは仕様書に記述されていない勝手なコード変更や破壊的改修を行えなくなります。
2. 検知 (Detection / 境界 & セキュリティテスト):
   • JS/TS では dependency-cruiser、Python では pytest-archon を自動セットアップ。
   • インポートのレイヤー境界違反やファイル行数上限（max_file_lines）オーバーに加えて、Gitleaks 連携および組み込みパターン判定による API キー・秘密鍵の混入を全自動で検知・ブロックします。
3. 延命 (Preservation / テスト凍結):
   • テストのないレガシーコードや複雑なファイルを変更する前に spag freeze <file> を実行。
   • AI自らに現在の挙動を固定する「仕様化テスト (Characterization Test)」を全自動で生成させ、デグレードリスクをゼロにしてからリファクタリング（Refactor）に入らせます。

⚙️ 防衛を支える主要メカニズム

• シムファイル戦略 (Shim Strategy): AGENTS.md を「単一真実のソース」としつつ、Cursor (.cursorrules) や Antigravity (.agent/rules/rules.md) 用の参照シムを自動生成し、ルールのコピペや同期ズレを完全に排除します。
• Gitleaks 連携 & シークレット漏洩防止 (Secret Scanner): gitleaks バイナリが存在する場合は高速ディープスキャン、未インストール環境では OpenAI / Anthropic / Gemini API キーや秘密鍵を検出する組み込みパターンエンジンが自動動作。
• コンテキスト圧縮 (Context Compression / Headroom 連携): 100行/10KB超の長文ログやドキュメントを自動検知し、要約ハッシュ化（headroom_compress）して処理するルールをAIへ強制し、メモリ枯渇を防ぎます。
• MCP (Model Context Protocol) サーバー & 自律修正: Cursor や Claude Desktop などの外部AIと直結。境界違反検知時にAI自身が最大3回の自動修正ループを回して自律修復します。
• 対話型 TUI チャット (REPL): npx spag を引数なしで実行するだけで、ターミナル上にダッシュボードとチャットUIが起動。AIと直接設計の壁打ちやリファクタリング指示が行えます。

🚀 クイックスタート

プロジェクトルートで以下のコマンドを実行するだけで導入完了です。

# 即時実行 (推奨)
npx @naoya.k/spaghetti-guard init

# 略称エイリアスコマンド
npx spag init

パッケージマネージャー別の実行

# npm
npm exec @naoya.k/spaghetti-guard init

# pnpm
pnpm dlx @naoya.k/spaghetti-guard init

# yarn
yarn dlx @naoya.k/spaghetti-guard init

# bun
bunx @naoya.k/spaghetti-guard init

📖 CLI コマンドリファレンス

| コマンド | 概要 | 主なオプション | |---|---|---| | spag init | プロジェクトを自動検知し、防衛設定・AGENTS.md・境界テストを生成 | --lang <python\|node\|auto>, --yes | | spag check | 境界違反、ファイル行数制限、仕様カバレッジを即時検証 | --staged, --strict, --json | | spag freeze <file> | 対象ファイルの現在の挙動を固定する仕様化テストを自動生成 | --output <path>, --provider <name> | | spag doctor | 開発環境の健全性（uv, npm, pre-commit, 設定衝突等）を診断 | --fix | | spag upgrade | 生成済みファイルと最新テンプレートとの差分を取り込む | --dry-run, --yes | | spag mcp | AIエージェント連携用の MCP (Model Context Protocol) サーバーを起動 | --port <number> | | spag | インタラクティブな対話型 TUI チャット画面 (REPL) を起動 | (引数なしで起動) |

⚙️ 設定ガイド (spaghetti-guard.config.yaml)

プロジェクトルートの spaghetti-guard.config.yaml を編集することで、静的検証ルールや行数制限を動的にカスタマイズできます。

version: "1"

# 1. アーキテクチャ境界ルール (レイヤー依存制限)
architecture:
  boundaries:
    - from: "core/**"
      disallow: ["commands/**", "controllers/**"]
      reason: "コアロジックから上位層への逆依存は禁止"
    - from: "utils/**"
      disallow: ["core/**", "commands/**"]
      reason: "ユーティリティ層は独立していなければならない"

# 2. ファイルサイズ・行数制限
limits:
  max_file_lines: 500
  ignore_patterns:
    - "**/*.test.ts"
    - "**/generated/**"
    - "**/*.tsx"       # UIコンポーネント等を除外可能

# 3. エージェント環境 & コンテキスト圧縮設定
environment:
  agent_detection: auto      # auto | antigravity | claude-code | cursor | none
  compression_strategy: auto # auto (Antigravity時のみheadroom) | headroom | manual-summarize
shim_files: auto             # auto | 指定パスのリスト

# 4. SDD (Spec-Driven Development) 設定
specs:
  required: true
  directory: "specs"

# 5. セキュリティ & シークレット漏洩防止設定
security:
  secret_scan: auto          # auto (gitleaks自動判定) | gitleaks | pattern | none

# 6. AI自動修正ループ制限
autofix:
  max_retries: 3

🛠️ コア技術 & OSS クレジット

Spaghetti Guard は、信頼性の高い最高峰の OSS ツール群をオーケストレーションして構築されています。

• 予防 (Prevention): Spec-Kit / specify (仕様駆動開発エンジン)
• 静的検証 (Node.js/TS): dependency-cruiser
• 静的検証 (Python): pytest-archon
• セキュリティ (シークレット検出): Gitleaks (および組み込みパターン判定エンジン)
• TUI チャット UI: Ink (React for CLI)
• AI 連携: Model Context Protocol (MCP) / Google Gemini API

📄 ドキュメント Web サイト

開発ガイド、アーキテクチャ詳細、FAQ については公式ドキュメントサイトをご覧ください。

• ローカルドキュメントサーバー: cd docs && npm run dev
• ドキュメント URL: http://localhost:3000/docs

📜 ライセンス

MIT License © Naoya K