Aegis

Aegis

AI コーディングエージェント向け DAG ベースの決定論的コンテキストコンパイラー

日本語版 README | 技術ガイド

Aegis は、AI コーディングエージェントにアーキテクチャガイドラインを適用する MCP サーバーです。RAG の代わりに、依存関係のエッジで構成される DAG を使用して、指定されたターゲットファイルに必要なドキュメントだけを決定論的にコンパイルします。検索も順位付けもありません。決定論的です。

クイックスタート

1. IDE の MCP 設定に Aegis を追加します（インストールを参照）
2. AI エージェントに次のように依頼します。「このプロジェクト用に Aegis を初期化して、アダプタールールをデプロイしてください。」
3. エージェントが aegis_init_detect → aegis_init_confirm → npx @fuwasegu/aegis deploy-adapters を自動的に実行します

データベースは、プロジェクトのルートにある .aegis/aegis.db に保存されます。.aegis/ ディレクトリには専用の .gitignore が含まれているため、手動設定は不要です。

インストール

Aegis は 2 つの MCP サーフェスを使用します。両方が必要です。

agent サーフェスだけでは、プロジェクトの初期化や提案の承認はできません。この分離により、人間の承認なしに AI エージェントがアーキテクチャルールを変更できないようにしています。(INV-6)

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初期化後、deploy-adapters は .cursor/rules/aegis-process.mdc を生成します。これは、コードを書く前に Aegis を参照し、その後に違反を報告するようエージェントに指示する Cursor ルールです。

Claude Code

claude mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
claude mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初期化後、deploy-adapters は CLAUDE.md に `` セクションを追記します（存在しない場合は作成します）。

Codex

codex mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
codex mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初期化後、deploy-adapters は AGENTS.md に `` セクションを追記します（存在しない場合は作成します）。

注： Codex の MCP サポートは CLI のバージョンによって異なります。MCP を利用できない場合でも、エージェントは生成された AGENTS.md の指示に従って Aegis のガイドラインを利用できます。

使い方

1. プロジェクトを初期化する

admin サーフェスを使用して、空のナレッジベースで Aegis を初期化します。

aegis_init_detect({ project_root: "/path/to/your/project", skip_template: true })
aegis_init_confirm({ preview_hash: "<hash from detect>" })

空のナレッジベースが作成されます。次の手順でアーキテクチャドキュメントを追加します。

次に、CLI を使って AI コーディングツール用のアダプタールールと Agent Skills をデプロイします。

npx @fuwasegu/aegis deploy-adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # specific adapters only

2. 開発中に使用する

agent サーフェスは、AI コーディングエージェント向けのツールを提供します。拡張コンテキスト（タグ駆動のドキュメント）を使う場合の推奨フローは、セッションごとに aegis_get_known_tags を 1 回呼び出し（tag_catalog_hash をキャッシュ）、その後 intent_tags を compile に渡すことです。

aegis_get_known_tags({})
aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: ["<tags from known_tags>"]
})

代わりに、オプションのサーバー側 SLM タガー（--slm が有効な場合）に plan からタグを推定させる場合に限り、intent_tags を省略してください（ADR-004）。SLM を使わずに拡張コンテキストをスキップするには、intent_tags: [] を渡します。

ベース DAG のみ（拡張コンテキストをスキップします。intent_tags: [] によって拡張コンテキストが無効になり、SLM によるタグ付けもスキップされるため、--slm の有無にかかわらず同じように動作します）。

aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: []
})

編集対象のファイルに関連するアーキテクチャガイドライン、パターン、制約が返されます。

3. アーキテクチャドキュメントを追加する

初期化後、コードベースを分析してナレッジベースに内容を追加します。aegis_import_doc を admin サーフェスで使用し、ファイルパスに接続する edge_hints を指定してアーキテクチャドキュメントを追加します。

aegis_import_doc({
  file_path: "/absolute/path/to/docs/architecture-guide.md",
  doc_id: "architecture-guide",
  title: "Architecture Guide",
  kind: "guideline",
  tags: ["architecture"],
  edge_hints: [
    { source_type: "path", source_value: "src/domain/**", edge_type: "path_requires" }
  ]
})

file_path を使用すると、ディスクから直接内容を読み込めるため、LLM のコンテキストウィンドウによる切り詰めを回避できます。インポートごとに proposal_ids が返されます。ドキュメントを有効にするには、これらを承認してください。

インポートしたドキュメントをソースファイルと同期した状態に保つには、次のようにします。

aegis_sync_docs()   # detects changes via content hash, creates update_doc proposals

aegis_import_doc と aegis_sync_docs は、どちらも admin サーフェスを必要とします。詳細な手順を含む一括インポートのワークフローについては、deploy-adapters を介してデプロイする aegis-bulk-import スキルを参照してください。

4. 気づいた点を報告する

エージェントがガイドラインの欠落や修正点に気づいた場合は、次のようにします。

aegis_observe({
  event_type: "compile_miss",
  related_compile_id: "<from compile_context>",
  related_snapshot_id: "<from compile_context>",
  payload: { target_files: ["..."], review_comment: "Missing error handling guideline" }
})

5. 提案を確認する

気づいた点は分析され、提案にまとめられます。admin サーフェスから確認して承認してください。

aegis_list_proposals({ status: "pending" })
aegis_approve_proposal({ proposal_id: "<id>" })

プロジェクトの共有（チームのワークフロー）

Aegis では、Git にコミットするバンドル成果物を使って、承認済みの Canonical Knowledge をチームメンバー間で共有できます。これにより、開発者がそれぞれ一からナレッジベースを構築する必要がなくなります。

仕組み

作成ワークスペース（ナレッジメンテナー）

提案を承認した後、現在の Canonical の状態をエクスポートします。

npx @fuwasegu/aegis share-export                # writes aegis-share/manifest.json + canonical.json
npx @fuwasegu/aegis share-export --out /path    # custom output directory

その後、aegis-share/ をコミットしてプッシュします。

レプリカワークスペース（チームメンバー）

更新された aegis-share/ を含む変更をプルした後、次のようにします。

npx @fuwasegu/aegis share-hydrate               # rebuild .aegis/aegis.db from aegis-share/
npx @fuwasegu/aegis share-hydrate --replace     # overwrite existing initialized DB
npx @fuwasegu/aegis share-hydrate --bundle-dir /path  # custom bundle directory

警告： share-hydrate は DB 全体を置き換えます。ローカルの運用状態（気づいた点、提案、コンパイルログ）は保持されません。これは設計どおりです。レプリカワークスペースは共有ナレッジの利用者であり、作成者ではありません。

共有状態の監視

Aegis は、ローカル DB と共有バンドルの間にある差異を自動的に検出します。

• npx @fuwasegu/aegis doctor — 共有状態（in_sync、bundle_newer、local_ahead、diverged、unreadable_bundle）を表示します。対応が必要な状態の場合は終了コード 1 を返します。
• npx @fuwasegu/aegis stats — JSON 出力に project_share を含め、詳細な状態を表示します。
• aegis_compile_context の通知 — バンドルが同期されていない場合、エージェントに対応方法のヒント（例：「share-hydrate を実行して更新してください」）を提供します。

not_configured 状態（aegis-share/ ディレクトリがない場合）は通知されません。共有を設定するまでは余計な通知はありません。

一般的なチームのワークフロー

                    Authoring Workspace                    Replica Workspace
                    ───────────────────                    ─────────────────
  approve proposals ──► share-export ──► git push ──► git pull ──► share-hydrate
                                  aegis-share/ committed

1. 作成者がナレッジベースを操作します（ドキュメントのインポート、提案の承認、同期）
2. 作成者が share-export を実行して、aegis-share/ をコミットします
3. チームが git pull を実行し、その後 share-hydrate --replace を実行します
4. レプリカで compile_context を実行すると、作成者と同じガイドラインが返されます

共同編集（ソースネイティブ）

上記の DB ネイティブのワークフロー（観察 → 提案 → 承認）に加えて、Aegis はソースネイティブの共同編集モードにも対応しています。チームメンバーは aegis-share/source/ の人が読めるソースファイルを編集し、プルリクエストで変更を確認してから、データベースに反映します。

重要なルール： compile_context は常にデータベースから読み込み、ソースファイルを直接参照することはありません。ソースファイルは編集用の形式であり、DB はランタイム用の形式です。

2 つの承認経路

どちらの経路も併用できます。状況に合った方法を使うか、両方を使ってください。

ディレクトリ構成

aegis-share/
├── manifest.json              # Distribution bundle manifest (ADR-017)
├── canonical.json             # Distribution bundle data (ADR-017)
└── source/                    # Collaborative authoring source (ADR-018)
    ├── documents/
    │   └── <doc_id>.md        # Frontmatter + Markdown body
    ├── edges/
    │   ├── path-requires.json
    │   ├── layer-requires.json
    │   ├── command-requires.json
    │   └── doc-depends-on.json
    ├── layer-rules.json
    └── tag-mappings.json

ソースネイティブのワークフロー

# 1. Bootstrap: export current DB to source format (one-time setup)
npx @fuwasegu/aegis share-source-export

# 2. Edit source files (documents, edges, rules, mappings)
#    Create a branch, make changes, open a PR

# 3. Validate before committing
npx @fuwasegu/aegis share-format                 # Normalize formatting (deterministic, in-place)
npx @fuwasegu/aegis share-lint                   # Check for errors (after formatting)

# 4. After PR merge: apply source to DB
npx @fuwasegu/aegis share-materialize            # Applies changes + auto-approves
npx @fuwasegu/aegis share-materialize --dry-run  # Preview changes without applying

# 5. Export updated bundle for replicas
npx @fuwasegu/aegis share-export

CI 連携

マージ前にエラーを検出するため、CI パイプラインに share-lint を追加します。

npx @fuwasegu/aegis share-lint  # exits 1 on errors — suitable for CI checks

フェーズ 1 の制限事項

• ローカルオーバーレイはサポートされていません。すべての変更は共有ソースを通じて行います
• share-materialize は全体を適用します（増分パッチではありません）

拡張コンテキスト向け SLM — オプトイン

Aegis には、任意で SLM ベースの意図タグ付けを行うための llama.cpp エンジンが組み込まれています。SLM はデフォルトで無効です。決定論的な DAG ベースのコンテキストは、SLM なしでも問題なく機能します。

有効にするには、エージェントのサーフェスに --slm を追加します。

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent", "--slm", "--model", "qwen3.5-4b"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

SLM を有効にして初めて起動すると、選択したモデルが ~/.aegis/models/ にダウンロードされます（すべてのプロジェクトで共有されます）。

HuggingFace URI を直接渡すこともできます：--model hf:user/repo:file.gguf

レガシー： Ollama ベースの推論を使用する場合は、--ollama フラグを利用できます。--ollama を使用すると、SLM が暗黙的に有効になります。

リファレンス

MCP ツール — エージェントサーフェス（6 ツール）

MCP ツール — 管理サーフェス（追加の 18 ツール、合計 24 ツール）

CLI サブコマンド

npx @fuwasegu/aegis deploy-adapters                         # Deploy all adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # Deploy specific adapters
npx @fuwasegu/aegis deploy-adapters --project-root /path    # Specify project root
npx @fuwasegu/aegis deploy-adapters --db /path/to/aegis.db  # Use custom DB path
npx @fuwasegu/aegis maintenance                             # Process observations, sync, archive
npx @fuwasegu/aegis maintenance --dry-run                   # Report only (no writes)
npx @fuwasegu/aegis stats                                   # JSON health and usage data
npx @fuwasegu/aegis doctor                                  # Health check summary
npx @fuwasegu/aegis share-export                            # Export to aegis-share/
npx @fuwasegu/aegis share-hydrate --replace                 # Rebuild DB from bundle
npx @fuwasegu/aegis share-source-export                     # Export DB to aegis-share/source/
npx @fuwasegu/aegis share-lint                              # Validate shared source
npx @fuwasegu/aegis share-format                            # Normalize shared source
npx @fuwasegu/aegis share-materialize                       # Apply source to DB
npx @fuwasegu/aegis share-materialize --dry-run             # Preview changes
npx @fuwasegu/aegis --list-models                           # List available SLM models

注記：バージョン追跡が更新されるのは、--targets を指定しない完全デプロイの場合のみです。部分デプロイではバージョン記録が更新されないため、完全デプロイを実行するまで「アダプターテンプレートが古い可能性があります」という通知が表示され続けます。

CLI フラグ（MCP サーバーモード）

開発

ビルド

npm run build    # Compile TypeScript
npm test         # Run all tests (406+)
npm run test:watch

git clone https://github.com/fuwasegu/aegis.git
cd aegis
npm install && npm run build

アーキテクチャ

┌─ MCP Layer (src/mcp/) ──────────────────┐
│ Tool registration, surface separation   │
└──────────────┬──────────────────────────┘
               │
┌─ Core Layer (src/core/) ────────────────┐
│ ContextCompiler, Repository, Init,      │
│ Automation (Analyzers), Tagging         │
└──────────────┬──────────────────────────┘
               │
┌─ Adapters (src/adapters/) ──────────────┐
│ Cursor, Claude rule generation          │
└──────────────┬──────────────────────────┘
               │
┌─ Expansion (src/expansion/) ────────────┐
│ llama.cpp engine, IntentTagger          │
└─────────────────────────────────────────┘

依存関係は下位方向に流れます。Core が MCP、Adapters、Expansion からインポートすることはありません。

主な概念

• Canonical Knowledge：承認済みのアーキテクチャ文書と DAG エッジ
• Observation Layer：エージェントが報告するイベント（コンパイルの見落とし、修正、PR のマージ）
• Proposed Layer：人による承認が必要な自動提案
• Snapshots：Canonical Knowledge の不変でコンテンツアドレス可能なバージョン

ライセンス

ISC