{"id":50824915,"url":"https://github.com/shibuiwilliam/agent-reference-architectures","last_synced_at":"2026-06-13T17:33:22.833Z","repository":{"id":360169409,"uuid":"1248976891","full_name":"shibuiwilliam/agent-reference-architectures","owner":"shibuiwilliam","description":"AI Agent Reference Architecture Patterns","archived":false,"fork":false,"pushed_at":"2026-05-25T10:19:10.000Z","size":190,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T10:30:48.993Z","etag":null,"topics":["agent-architectures","ai-agents","architecture-patterns","reference-architecture"],"latest_commit_sha":null,"homepage":"https://shibuiwilliam.github.io/agent-reference-architectures/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shibuiwilliam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T08:22:22.000Z","updated_at":"2026-05-25T10:19:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shibuiwilliam/agent-reference-architectures","commit_stats":null,"previous_names":["shibuiwilliam/agent-reference-architectures"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shibuiwilliam/agent-reference-architectures","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shibuiwilliam%2Fagent-reference-architectures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shibuiwilliam%2Fagent-reference-architectures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shibuiwilliam%2Fagent-reference-architectures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shibuiwilliam%2Fagent-reference-architectures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shibuiwilliam","download_url":"https://codeload.github.com/shibuiwilliam/agent-reference-architectures/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shibuiwilliam%2Fagent-reference-architectures/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34294411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-architectures","ai-agents","architecture-patterns","reference-architecture"],"created_at":"2026-06-13T17:33:22.103Z","updated_at":"2026-06-13T17:33:22.825Z","avatar_url":"https://github.com/shibuiwilliam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AIエージェント本番アーキテクチャ・パターン\n\n意思決定層（**程度の調整**と**相反する仕組みの選定基準**）を中心に据えた、AIエージェントを本番システムに組み込むためのソフトウェアアーキテクチャ・パターン集です。\n\n単なるパターンの羅列ではなく、**「どのパターンを、どの目盛りで、どちらの仕組みで採るか」を根拠（どの駆動変数が効いたか）とともに決められる**ことを目標としています。\n\n## 想定読者\n\n| 読者 | 使い方 |\n|------|--------|\n| 人間（設計者・レビュア） | 設計判断の根拠を引く、レビューの観点リストにする |\n| コーディングエージェント | `docs/` の生マークダウンを読み込み、AIエージェントを含む構成を設計し人間に提案する |\n\n## 5層モデル\n\n設計判断を、固定値ではなく「目盛り（程度）」と「二択（相反）」として扱い、少数の駆動変数から導きます。\n\n| 層 | 問い | 道具 |\n|---|------|------|\n| L0 なぜ難しいか | 普通のソフトと何が違うか | 設計力学 F1–F17 |\n| L1 何を配分するか | 何をどれだけ使えるか | 7つの予算 |\n| L2 どう決めるか | 目盛り/二択を何が左右するか | 9つの駆動変数 |\n| L3 どこまで回すか | 各設計変数のちょうど | 程度（ダイヤル） |\n| L4 どちらを採るか | 排他的な仕組みのどちら | 相反（フォーク） |\n| L5 何を組むか | 実装する再利用部品 | パターン A–G（39件） |\n\n根本原則：**確率的な核（LLM）を、決定論的な殻（コード）で包む。**\n\n## パターン一覧（39件）\n\n| ドメイン | テーマ | パターン |\n|---|---|---|\n| **A** | 実行方式 | A1 同期エッジ / A2 耐久非同期 / A3 同期ファサード / A4 進捗ストリーミング / A6 適応タイムアウト・リトライ / A7 期限・予算カスケード |\n| **B** | オーケストレーション | B1 決定論的な殻 / B2 ワークフロー骨格 / B3 予算付き自律ループ / B4 計画-実行-検証 / B5 Supervisor-Worker / B6 Critic-Judge・多数決 / B7 モデルルーター |\n| **C** | ツール・セキュリティ | C1 ツールゲートウェイ / C2 読取自由・書込ゲート / C3 ドライラン・コミット / C4 冪等コマンド包装 / C5 Capability Lease / C6 Confused Deputy防御 / C7 サンドボックス / C8 サーガ・補償 |\n| **D** | メモリ・コンテキスト | D1 階層化メモリ / D2 コンテキスト予算配分 / D3 メモリ書込ゲート / D4 減衰・版管理 / D5 Prompt Registry / D6 禁止領域付きキャッシュ |\n| **E** | 安全性・HITL | E1 リスクベース承認 / E2 Policy-as-Code / E3 ガードレールサンドイッチ / E4 構造化出力 / E5 Autonomy Ladder |\n| **F** | データ整合性 | F1 短トランザクション・長セッション / F2 イベントソーシング・リプレイ |\n| **G** | 観測・運用 | G1 二層観測 / G2 全ホップトレース / G3 シャドウ・カナリア / G4 評価ハーネス / G5 サーキットブレーカ・縮退 |\n\n各パターンには frontmatter で `forces` / `driving_variables` / `forks` / `related_patterns` / `alternatives` が機械可読メタとして付与されています。\n\n## ディレクトリ構成\n\n```\n.\n├── CLAUDE.md                  作業規約（Claude Code が自動読込）\n├── PROJECT.md                 プロジェクト憲章\n├── pyproject.toml             ビルド依存（uv で管理）\n├── mkdocs.yml                 サイト設定・nav\n├── .github/workflows/         GitHub Pages 自動デプロイ\n├── scripts/                   validate / gen_indexes / new_pattern\n└── docs/\n    ├── index.md               トップページ\n    ├── for-agents/            コーディングエージェント向けガイド・提案プロトコル\n    ├── concepts/              第I部 地盤（力学・予算・駆動変数・5層モデル）\n    ├── degrees/               第II部 程度（ダイヤル）\n    ├── forks/                 第III部 相反（フォーク）\n    ├── patterns/              第IV部 パターン A–G（39件）\n    ├── decision/              第V部 意思決定フロー\n    ├── antipatterns/          第VI部 アンチパターン\n    └── reference/             用語集・機械可読インデックス\n```\n\n## セットアップ\n\n[uv](https://docs.astral.sh/uv/) が必要です。\n\n```bash\n# 依存インストール\nuv sync\n\n# ローカルプレビュー（http://127.0.0.1:8000）\nuv run mkdocs serve\n\n# 本番同等の厳格ビルド\nuv run mkdocs build --strict\n\n# frontmatter スキーマ・統制語彙・リンク切れ検証\nuv run python scripts/validate.py\n\n# ドメイン index・機械可読インデックスの再生成\nuv run python scripts/gen_indexes.py\n```\n\n## コーディングエージェント向け\n\nこのリポジトリはコーディングエージェントが読み込んで設計提案に使うことを想定しています。\n\n- **機械可読インデックス**: `docs/reference/pattern-index.md` — 全パターンの `id` / `forces` / `driving_variables` / `forks` を1表に集約\n- **設計提案プロトコル**: `docs/for-agents/decision-protocol.md` — 駆動変数の評価から候補選定・目盛り決定・提案出力までの手順\n- **生マークダウン配信**: 公開サイトでは `mkdocs-llmstxt` により `/llms.txt`（索引）・`/llms-full.txt`（全文連結）を生成\n- **リポジトリ直読**: `docs/**/*.md` を直接読めば frontmatter 込みでメタ抽出が可能\n\n## デプロイ\n\n`main` ブランチへの push で GitHub Actions が `mkdocs build --strict` を実行し、GitHub Pages に公開します。\n\n初回セットアップ時に以下が必要です:\n\n1. `mkdocs.yml` の `site_url` / `repo_url` を自リポジトリに合わせて書き換える\n2. GitHub リポジトリの Settings → Pages → Source を **GitHub Actions** に設定する\n\n## ライセンス\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshibuiwilliam%2Fagent-reference-architectures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshibuiwilliam%2Fagent-reference-architectures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshibuiwilliam%2Fagent-reference-architectures/lists"}