最終更新: 2026/06/22 18:56
commonid: agent-knowledge-layerstype: how-tostatus: active

AI エージェント向け指示・知識レイヤの責務定義と書き分け規約

⚠️ 本規約は AI エージェント (Claude Code) への指示品質を高めるためのものであり、人間の判断を拘束しない。 このページは AI への指示規約であって人間の行動規範ではない。人間が緊急対応で本規約と異なる操作を行うことを妨げない（→ §7 人間の緊急操作と hooks バイパス）。

  • バージョン: v1.0（2026-06-04・ADR-0115 により制定）
  • 正典: ADR-0115（撤退条件・Confirmation・コスト試算は ADR 側を参照）
  • 見直し: 半年毎（層追加提案の棄却理由も記録する）+ 強制改訂トリガー（→ §2）

1. 6 層モデルと責務定義

AI エージェントへの指示・知識は以下 6 層に分散する。各層の責務を超える内容を書かない。

層場所ロード特性責務書いてはいけないもの
① hooks + permissions.denyscripts/hooks/ + .claude/settings.json読まれなくても効く（技術強制）不可逆操作の禁止（main 直 push・機密コミット・rm -rf 等）読解を要するルール（hooks は判断しない）
② CLAUDE.mdリポルート毎セッション全文ロード常時効くべき少数の禁止則 + 役割境界のみ。目安上限 200 行手順詳細・背景説明・一過性の状態
③ CLAUDE.local.mdリポルート（gitignore）毎セッション全文ロードクローン役割の固定・個人パス・MCP 設定リポ共有すべき運用ルール
④ auto-memory~/.claude/projects/<repo>/memory/索引常時 + 本文オンデマンドセッション横断の状態（案件進捗・次アクション）と個人の行動補正。feedback は禁止形 or 手順形で書く。reference は安定インターフェースのみ（行番号禁止）コード行番号・一過性操作ログ・リポが既に記録する事実
⑤ .claude/skills/<name>/SKILL.md（リポスコープは commit）description 常時可視 + 本文呼び出し時ロード呼び出して使う手順知識（段階ロード形式必須）状態・背景説明（手順の WHY は層⑥へリンク）
⑥ docs/_internal/リポ内 docs参照時のみロード背景・設計・共有ポリシーの正典（内部配置は ADR-0045 に従う）作業の瞬間に想起が必要な手順（→ 層⑤に置き description で想起させる）

2. 改訂トリガー（Claude Code major update の定義）

  • 定義: メモリ・Skill のロード挙動・コンテキストウィンドウ仕様・hooks 実行モデルのいずれかに変更を含むリリース。
  • 検知: Claude Code のリリースノート確認を月次セルフチェック項目に含める。
  • 判定期限: 検知後 2 週間以内に改訂要否を判定・4 週間以内に規約更新 or 据え置き決定（定期見直しを待たない）。

3. 書き分け決定表

新しい知識を書く前に、この表で層を決めてから書く。

知識の種類置き場所
手順（コマンド・操作の再現）層⑤ Skill
状態（案件進捗・次アクション・行動補正）層④ auto-memory
常時禁止則・役割境界層② CLAUDE.md
背景・設計・共有ポリシー層⑥ docs/_internal
不可逆操作の禁止層① hooks

3.1 スコープ責務分担基準

  • リポ固有の手順・知識 → リポスコープ（.claude/skills/ 等のコミット対象。.gitignore は .claude/skills/drp-ops/ のみ tracked 許可）。
  • リポに依存しない汎用個人ツール → ユーザースコープ（~/.claude/）。
  • リポ内文書（docs/・README 等）からユーザースコープ資産への参照は禁止（環境再構築・将来の参画者に無言で壊れるため）。ユーザースコープ依存で運用する資産は §8 のインベントリに記載する。

3.2 tie-breaker（分類に迷ったら）

  • 手順と状態の中間など分類に迷う知識は層⑥に置き、Skill description または memory 索引から参照する（main/doc の独立書込による複数層重複登録を防ぐ）。
  • tie-breaker 適用には「1 ヶ月以内に Skill 化を再検討する暫定扱い」のラベルを義務付ける。
  • tie-breaker 累積が月 3 件を超えたら「分類基準自体が不明確」として本決定表の改訂トリガーとする。
  • Skill description / memory 索引の更新責務者: その知識を書いた本人（main/doc の各セッション）。

3.3 緊急例外パス

緊急時は層⑥の暫定メモとして即時記録してよい。ただし 72 時間以内に正規の層へ移動する。

3.4 層追加ガバナンス

  • 新しい層の追加は ADR を要する。層数上限は 8。
  • 半年毎見直しで層追加提案があった場合、採否にかかわらず棄却理由を記録する。

4. 運用ルール

  • auto-memory 上限: 索引（MEMORY.md）は 50 件上限・TTL 90 日（90 日未参照で自動アーカイブ候補）。執行は書込み時エンフォース — 新規エントリ追加の前に索引行数を確認し、超過する場合は既存の統合・アーカイブを先に行う。月次チェックの行数カウントは backstop（執行漏れの検出）。
  • CLAUDE.md 同時編集競合: main/doc 両方可ファイルのため編集直前に git pull origin main。それでも競合したら後から push する側が解消する（標準 git 運用）。
  • 月次セルフチェック（5 分）: ①複数層への重複登録 ②staleness 警告の放置 ③auto-memory 索引行数（backstop） ④tie-breaker 累積件数 ⑤Claude Code リリースノート確認。

5. Skill の陳腐化対策（層⑤）

  • SKILL.md の front matter に last_verified（YYYY-MM-DD）/ verified_by / target_drp_version（commit SHA 推奨）を必須化。
  • staleness lint 稼働中（scripts/skill-staleness-lint.mjs・main 実装済み）: S1 = last_verified 183 日超で WARN（毎 PR）/ S2 = 必須 front matter 欠落で WARN（毎 PR）/ S3 = DRP デプロイ成功時に target_drp_version と デプロイ SHA を突合。
  • DRP の API ルート・認証フロー・KV 仕様を変更する PR では drp-ops SKILL.md の同期確認をチェック項目とする。

6. 適用例

  • DRP 操作手順（認証・KV 投入・ローカル検証）→ 層⑤ .claude/skills/drp-ops/SKILL.md（ADR-0115 適用第 1 号）
  • 「新規 .md は同一ターンで nav 登録」→ 規範は層②（ドキュメントサイト管理節）+ 行動補正は層④ feedback
  • 案件進捗（ADR 審査キューの状態）→ 層④ project memory
  • 本ページ（層構造のポリシー）→ 層⑥

7. 人間の緊急操作と hooks バイパス

層①（scripts/hooks/pre_bash_guard.sh + permissions.deny）は Claude のツール呼び出しのみを対象とする。人間の緊急操作の正規手順:

  1. 人間が自分のターミナルで直接実行する（hooks の対象外。これが正規のバイパス経路であり、設定変更は不要）。
  2. Claude セッション内で実行結果を共有したい場合は ! <command> プレフィックスで人間がコマンドを実行する。
  3. hooks 自体の恒久変更が必要なら hooks_setup.md の手順で settings.json を更新する（一時的な無効化はしない）。

8. ユーザースコープ依存インベントリ

リポ内文書から参照してはいけない（または参照に注意を要する）ユーザースコープ資産の台帳。半年毎の層責務表見直しと同時に棚卸しする。

資産内容なぜユーザースコープか欠落時の代替手順
.claude/skills/adr-kit/references/参照資料 2 ファイル（bizlink-domain.md / langgraph-adrkit-boundary.md）のみ実在。SKILL.md が無いため Skill として自動発見されない。gitignore（.claude/skills/*）で ignored = 非 trackeddocs/adr/README.md が「導入予定」の Skill として参照したが SKILL.md 本体は未導入。参照資料の容れ物だけが残存Skill 化しない（SKILL.md 不在で機能上 Skill でない）。DRP 操作手順の正典は drp-ops で、README の参照は付け替え済み。2026-06-10 知識レイヤー監査で旧「存在しない」記述を実態（references/ 実在）に訂正
.claude/skills/prompt_*.md 3 件prompt_index_restructure / prompt_section_restructure / prompt_spec_review（仕様書リファクタ用プロンプト）gitignore 対象（.claude/*）のプロンプトテンプレート置き場。<name>/SKILL.md 形式でないため Skill として自動発見されない（位置づけ確定・Skill 移行はしない）内容は仕様書リファクタ時の使い捨てプロンプト。欠落時は docs/_internal/04_specs/ のテンプレートから再構成
CLAUDE.local.mdクローン役割・個人パス・MCP 設定設計どおり（gitignore・層③の責務）workspace_rules.md のテンプレートから再作成
MCP サーバ設定claude.ai config スコープ（Box/Drive/Calendar/Gmail）アカウント紐付けの対話認証前提claude mcp list で確認・OAuth 再認証。headless 実行では利用不可前提で設計する
auto-memory~/.claude/projects/<repo>/memory/ユーザー個人スコープ（main/doc 独立。棚卸しは各自実施）リポ側の正典（docs/ADR/changelog）から状態を再構築
Keychain 資格情報DRP Basic 認証等（scripts/keychain_env.sh が参照）secret はリポに置けないKeychain への再登録（手順は drp-ops Skill 参照）

9. 実害 4 件の層別トレース表（参照資料・ADR-0115 §5.3 発効判定）

2026-06-04 セッション監査で確認した誤実行 4 件の層別トレース。

#実害事象当時の記述所在参照されなかった経路分類対処
1SSoT でなく転写プロンプト（test-tc*.mjs）を引用して誤説明SSoT パスは層⑥のみ。手順知識が層⑤に不在作業の瞬間に層⑥の存在が想起されず、目に入った転写コピーを引用層定義欠如起因（「手順は Skill」の基準が無かった）drp-ops Skill に SSoT パスを収載（本実装）+ DRP README §12 明記（PR #1399）
2タスク開始時の changelog・BUG_tracking 読込スキップ層②（Progress tracking 節）に記載済み「役割別読み方」で doc の読み飛ばし対象が広く、当該節が doc 対象であることが非明示層定義欠如起因（層②の役割境界責務の記述不足）CLAUDE.md に「doc も対象」を明記（本実装・ADR-0115 決定 5a）
3外部書込（KV POST 等）の承認拡大解釈どの層にも行動規範の記載なし。層① hooks は Bash 不可逆操作のみ対象で外部 API 書込は対象外ルール自体が不在（層判定の失敗ではない）層定義欠如以外（層①の対象範囲ギャップ + 規範未記載）行動補正は層④ feedback 起票済。技術的強制ギャップは COM-0381 で追跡（クローズ期限 2026-07-04）— 本 ADR スコープ外
4新規 .md の nav 登録失念層②（ドキュメントサイト管理節）に記載済み「.md を書く」作業と紐付く想起の仕組みが無く、書く瞬間に拾われなかった層定義欠如起因（常時ロード層の肥大で個別規則が拾えない — 層②責務超過）行動補正は層④ feedback 起票済 + 書き分け決定表の適用例に収載（§6）

発効判定: 層定義欠如起因 = 3 件（#1, #2, #4）≥ 2 件 → ADR-0115 §5.3 の条件付き承認条件を満たし正式発効。#3 は別 issue（COM-0381）で追跡。

10. ベースライン記録（効果測定基準・ADR-0115 撤退条件）

指標ベースライン（承認前・2026-06-04 セッション監査）目標（導入後 1 ヶ月）
既知情報の再導出8〜10 ツールコール/セッション（認証手順・API スキーマ・検証コマンド・SSoT パスの再調査）3 以下/セッション
誤実行4 件（§9 トレース表）0 件

測定方法: セッション transcript の監査（既知情報の再調査に費やしたツールコール数の集計）。未達 2 ヶ月連続で ADR-0115 撤退条件 (a) 発動。判定前に pre-mortem（原因仮説リストの事前書き出し）を行う。

11. Self-improvement loop（学びの昇格・root CLAUDE.md から移送 2026-06-10）

ミスを発見したら → 修正 → 「同じミスを防ぐルールを CLAUDE.md または該当 docs に追加して」と Claude に依頼する。価値あるものは doc で git pull origin main 後に CLAUDE.md / docs/_internal/ へ昇格させる。どの層へ書くかは本書の層定義（手順=Skill / 状態=memory / 常時禁止則・役割境界=CLAUDE.md / 背景=docs/_internal / 不可逆=hooks / ドメイン規約=.claude/rules・nested CLAUDE.md）に従う。

参照