最終更新: 2026/06/22 18:56
commonid: knowledge-architecture-overviewtype: how-tostatus: active
pageaudience: human

AI エージェントの知識構造の全体像

結論を先に: AI エージェント (Claude Code) に与える指示・知識は、1 つのファイルではなく 6 つの層に分けて置いている。理由は 3 つ。常時読む量を軽くする・取り返しのつかない操作を機械的に止める・何をなぜ守らせているかを後から監査できるようにするため。このページはその全体を 1 枚で見渡す入口で、経営者・非エンジニアにも読めるように書く。層ごとの詳細仕様・撤退条件は agent_knowledge_layers.md が正典。

1. 用語定義（このページで使う呼び名）

このリポジトリは 1 つの会社システムを複数の構成単位で運用している。構成単位の総称は「ドメイン」と呼ぶ。技術的な独立性を強調する文脈では「サブシステム」、説明の場では「アプリの塊」と言ってもよい。

識別子技術名このページでの呼び名
masGAS 会計本体会計本体（GAS）
drpdrp審査パイプライン（DRP）
web_app / webappwebapp-client SPAWeb アプリ
docsdocs サイトドキュメント（docs）

このほか、本ページ固有の用語を 2 つ定義する。

  • クローン: 同じリポジトリの複製。実装担当の main と、ドキュメント担当の doc がそれぞれ別のクローンで並行作業する。
  • ロード: エージェントがセッション中にそのファイルを読み込むこと。「常時ロード」は毎回必ず読む、「オンデマンド」は必要になった時だけ読む、の意味。

2. 全体像の図

エージェントの 1 セッションを時間軸で見ると、知識は次の 3 つのタイミングで効く。

flowchart LR
  subgraph start["セッション開始時（常時ロード）"]
    c2["② CLAUDE.md
禁止則・役割境界"]
    c3["③ CLAUDE.local.md
このクローンの役割"]
    c4["④ auto-memory の索引
進捗・申し送りの見出し"]
  end
  subgraph work["作業中（必要な時だけロード）"]
    c5["⑤ Skill
操作手順"]
    c6["⑥ docs/_internal
背景・ポリシーの正典"]
    c7["ドメイン規約
.claude/rules・drp/CLAUDE.md"]
  end
  subgraph exec["コマンド実行の瞬間（機械強制）"]
    c1["① hooks + 権限設定
不可逆操作を拒否"]
  end
  start --> work --> exec

設計の原則は 1 行で言える: 常時ロードは軽く、重い手順は必要な時だけ、絶対の禁止は読解に頼らず機械で止める。

3. 6 つの層 — 何を・どこに・なぜ

層置き場所何を置くかいつロードされるか誰に見えるか
① hooks + 権限設定scripts/hooks/ + .claude/settings.json不可逆操作の禁止。main への直接 push・機密のコミット・rm -rf などコマンド実行の瞬間に機械が拒否する。エージェントが読まなくても効くhooks スクリプトは全クローン共有。設定は各クローンでセットアップする
② CLAUDE.mdリポジトリのルート常時効くべき少数の禁止則と役割境界。上限の目安は行数で管理する（§5.1）毎セッション全文全クローンと CI
③ CLAUDE.local.mdリポジトリのルート（git 管理外）このクローンの役割の固定。個人パス・接続設定毎セッション全文そのクローンだけ
④ auto-memoryリポジトリの外（ユーザー個人領域）セッションをまたぐ状態。案件の進捗・次のアクション・行動の補正索引は常時、本文は必要時そのユーザーだけ。main と doc でも互いに見えない
⑤ Skill.claude/skills/呼び出して使う操作手順。例: DRP の API 操作、仕様書生成パイプライン見出しは常時見え、本文は呼んだ時だけリポ横断の手順 4 本は全クローン共有。個人ツールは本人だけ（§5.4）
⑥ docs/_internalリポジトリ内の docs背景・設計・共有ポリシーの正典参照時だけ全員。docs サイトにも公開される

このほかに、ドメイン規約を置く path-scoped rule（.claude/rules/docs.md・gas.md）と nested CLAUDE.md（drp/CLAUDE.md）がある。該当ドメインのファイルを触った時だけロードされる仕組みで、層②の肥大を防ぐ受け皿になっている（ADR-0129）。

この表に中身を書かない層が 1 つある。 ④ auto-memory はリポジトリの外にあり、個人の作業メモに相当する。ここでは「そういう層が存在し、状態の記憶を担う」ことだけを記す。

4. なぜこの構造か（効果の説明）

会社組織にたとえると分かりやすい。

  • 就業規則（層②）は短く、全員が常に守る。分厚くすると誰も読まなくなる。
  • 業務マニュアル（層⑤・⑥）は棚にあり、その業務をやる時だけ開く。
  • サーバ室の物理ロック（層①）は、ルールを読んだかどうかに関係なく不正な入室を止める。
  • 個人の手帳（層④）には自分の進捗とやりかけの仕事を書く。

この分担が狙う効果は ADR-0115 で 3 つに整理されている。

  1. 既知情報の再導出コストの削減: 認証手順や検証コマンドを毎回調べ直すムダをなくす。導入時の実測でセッションあたり 8〜10 回あった再調査を 3 回以下に減らすことが目標値。
  2. 誤実行ゼロ: 「読み忘れたので禁止操作をしてしまった」を、読解に依存しない層①で構造的に防ぐ。
  3. 監査性: どのルールがどこにあり、いつ効くかが一覧できる。本ページと層の責務表がその台帳になる。

5. 周辺の規約・運用（つまみ食い版）

5.1 ルートの行数上限と、置いてよいものの基準

  • KPI-1: ルートの CLAUDE.md は 50 行以下を目標にする。常時ロードされる層なので、長さがそのまま毎セッションのコストになる。
  • KPI-10: ルートに置けるのは「2 ドメイン以上から参照される」「不可逆またはドメイン横断」「ドメイン別ファイルでは検出漏れが起きる」のいずれかを満たす規約だけ。
  • 2 つが競合したら KPI-10 を優先する。現在のルートは 52 行で、1〜2 行の超過は許容範囲内。

5.2 ドメインごとに開く場所を変える運用

作業するドメインに合わせて、Claude Code を開くディレクトリを変える。DRP の作業は drp/ で開く。会計本体（GAS）と横断作業はルートで開く。ドキュメント作業は -doc / -sub クローンで開く。こうすると nested CLAUDE.md と path-scoped rule が自然に効き、無関係なドメインの規約を読まずに済む。

5.3 ロードされたかどうかの確認方法

「規約がロードされたか」の判定の権威は InstructionsLoaded フックログである。エージェント自身の申告や、本文を grep して確かめる方法は見落としが起きるため、根拠にしない。

5.4 Skill の共有範囲と鮮度管理

  • .claude/ は原則 git 管理外。ただしリポ横断パイプライン手順の Skill 4 本（drp-ops / spec-gen-pipeline / prompt-cicd / docs-ops）だけは .gitignore の除外指定で全クローン共有にしている。個人ツールは管理外のまま。
  • Skill が古くなっていないかは CI が監査する（scripts/skill-staleness-lint.mjs）。最終検証日が半年を超えた Skill には警告が出る。

6. このページと詳細仕様の役割分担

ページ役割
本ページ入口。全体像・図解・効果の説明。経営者・非エンジニア向け
agent_knowledge_layers.md正典。層ごとの責務定義・書き分け決定表・運用ルール・月次チェック
ADR-0115決定の記録。採用理由・撤退条件・効果測定の基準値
ADR-0129ドメイン別の分割マップ。nested CLAUDE.md と path-scoped rule の設計

新しい知識を「どの層に書くか」迷ったら、本ページではなく agent_knowledge_layers.md の書き分け決定表（§3） を引くこと。