← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0129type: adrstatus: accepted
pagemode: Standardkruchten: Executive/Propertyscope: platformimplementation_status: In Progress — ステップ①②③ + KPI-6/7 完了 (PRproposed_at: 2026-06-09 14:15approved_at: 2026-06-09deciders: [email protected] (単独)business: meta
型付き辺: 出 5 / 入 0
部分修正する: ADR-0123 前提とする: ADR-0045 関連: ADR-0156 ADR-0123 ADR-0067全体は INDEX →

ADR-0129: エージェント設定を作業ドメイン別に階層化する — root CLAUDE.md を普遍規約のみに絞り、GAS は .claude/rules、package は nested CLAUDE.md へ分離する

  • Status: Accepted (accepted-with-residual-risks — 末尾の HITL 残余リスク節参照。PR #1608 merge = 受理の規約により 2026-06-09 受理)
  • Mode: Standard
  • Kruchten Type: Executive/Property
  • Scope: platform
  • Implementation Status: In Progress — ステップ①②③ + KPI-6/7 完了 (PR #1615/#1621/#1622/#1623)、ステップ④⑤ 進行中。詳細は末尾「実装状況」。
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-06-09 14:15
  • 承認日時 (JST): 2026-06-09
  • Deciders: [email protected] (単独)

コンテキスト

§1.1 背景

このリポジトリは性質の違う 4 つの仕事を 1 か所で扱う。GAS 会計本体・DRP（審査パイプライン）・SPA・ドキュメントである。

エージェント設定は root の CLAUDE.md 1 ファイルに全部入っている。現在 172 行・24 section。GAS の制約も DRP のデプロイ規則も docs の文章方針も SPA のテストも同居している。

Claude Code は作業中のフォルダがどこでも root の CLAUDE.md を毎回読み込む。だから DRP の作業中でも GAS の 6 分制限や会計ルールが、docs の作業中でも clasp の手順が、毎回いっしょに読み込まれる。自分の仕事に関係ない指示が常に混ざる。

この入れ子 CLAUDE.md による削減は ADR-0067 で論点として挙がったが、まだ手をつけていない。本 ADR で独立した決定として確定する。

ロード仕様の詳しい説明は末尾の参照（"How CLAUDE.md files load" / claude-code-guide）にある。

§1.2 現状 (As-Is)

  • root CLAUDE.md は 172 行・24 section、冒頭に「役割別読み方」散文 (sub は GAS/Coding/Domain/テスト を読み飛ばし可) を持つ。
  • frontmatter audience (ADR-0123) は任意・非強制で、ファイル単位の機械的読み分けにはなっていない。
  • GAS コードは root 直下 (000_infra〜900_test + templates) に住んでおり、サブディレクトリ CLAUDE.md による scope 分離が原理的に使えない。
  • DRP/docs/SPA セッションでも root 172 行 (~2,600 token) が常時 context にロードされている。

§1.3 課題

  • root CLAUDE.md が常時ロードされるため、作業ドメインに無関係な制約 (GAS 制約・会計ドメイン規則・clasp 手順) が DRP/docs/SPA 作業時も context を占有する。
  • 「役割別読み方」を散文で人間/エージェントに判断させており、機械的に効いていない。
  • 作業種別が増えるたびに root CLAUDE.md へ section を追記する構造で、肥大化が不可避。指示数増で LLM 遵守率が低下する (HumanLayer 実測・ADR-0045/RQ-045)。
  • GAS コードが root 直下に住むため、サブディレクトリ CLAUDE.md だけでは GAS scope 分離ができない。

§1.4 制約・要件

  • Claude Code の paths: 条件ロード機構・nested on-demand ロード機構に全面依存するため、その動作粒度 (glob/prefix/regex、cwd 評価単位) を起案時点で実機確認する必要がある。
  • DRP の「merge=即本番 Cloudflare Workers デプロイ」制約は最高リスクであり、ロード機構の無音失効でこの制約だけが静かに消えてはならない。
  • GAS の列番号ハードコード・add_rows 使用などスプレッドシート構造を破壊しうる不可逆性の高い違反は許容しない。
  • ADR-0067 (monorepo) / ADR-0123 (frontmatter audience) / ADR-0045 (指示遵守率) と整合させる。
  • 全クローン (main/sub) 間で nested CLAUDE.md のロード挙動が一致すること。

§1.5 目標 (To-Be)

各セッションが自ドメインの制約だけを context に載せ、root の肥大化を構造的に止める。root CLAUDE.md は普遍規約のみ ~45 行に絞り、ドメイン規約は条件ロード (GAS=.claude/rules/gas.md paths、package=nested CLAUDE.md) で分離する。

Non-Goals: GAS コードをサブディレクトリ (apps/gas 等) に移設すること (ADR-0067 Phase 3 相当、本 ADR の前提にしない)。人間向けドキュメントへの frontmatter 利用の禁止 (継続可)。

決定

エージェント設定を作業の種類ごとに分ける。やることは 4 つ。

  • root の CLAUDE.md は全員に共通する規約だけにする（約 45 行）。
  • GAS の規約は .claude/rules/gas.md に移す。GAS のファイルを触ったときだけ読み込まれる（paths 指定）。GAS のコードは root 直下にあるため、フォルダ単位でなくこの方式を使う。
  • DRP・SPA・docs の規約は各フォルダの CLAUDE.md に移す（drp/ ほか）。そのフォルダを触ったときだけ読み込まれる。
  • 冒頭の「役割別読み方」の説明文は不要になるので消す。

移行は段階的に進める。①paths の実機確認 → ②各ファイルを root から複製 → ③root を絞る → ④実セッションで確認 → ⑤関連ドキュメントを追従。

ロード機構が静かに壊れるリスクには、Claude Code のバージョン固定・CI の smoke test・二重定義 21 日期限・不可逆違反 1 件で停止、で備える（詳しくは撤退条件と Confirmation）。

読み分けの正式な手段は今後ファイル配置と paths とする。ADR-0123 の audience frontmatter はこの用途では役目を終える。人間向け文書での frontmatter 利用は続けてよい。

判断基準 (Decision Drivers)

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#efficient[Must] (×2.0)DRP/docs/SPA セッションで無関係 context (token) を構造的に削減できるか
2#maintainable[Must] (×2.0)作業種別追加時に root を触らず追記できるか、肥大化を構造的に止められるか
3#reliable[Must] (×2.0)DRP「merge=即本番デプロイ」・GAS 列番号など不可逆制約が無音失効しないか
4#operable[High] (×1.0)移行・運用 (バージョン更新・四半期重複レビュー) が現実的か
5#suitable[Medium] (×0.5)ADR-0067 / ADR-0123 / ADR-0045 と整合し、後任が誤って巻き戻さないか

K.O. criterion: Must 軸 (#efficient / #maintainable / #reliable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

各案 0-5 で評価。加重和 = (Σ score × 係数) / (満点 5 × Σ 係数 6.5) で正規化。

軸係数案A: 階層化 (採択)案B: 現状維持案C: audience 強化案D: GAS 移設+全 nested
#efficient×2.05125
#maintainable×2.05125
#reliable×2.03442
#operable×1.04541
#suitable×0.54332
加重和 (正規化)0.8460.5080.5850.700
K.O. 通過 (Must ≥3)✓❌ (#efficient/#maintainable=1)❌ (#efficient/#maintainable=2)❌ (#reliable=2)

K.O. 通過は案A のみ。加重和も最大で採択。

検討した代替案 (Alternatives Considered)

  • 案A: 階層化 (本決定) — root 最小 + .claude/rules/gas.md + package nested。context が作業ドメインに連動。移行コスト中・段階移行でロールバック容易。ロード機構リスクは緩和策 1〜7 で対応。
  • 案B: 現状維持 (単一 root + 役割別読み方散文) — 不採用。作業種別増で肥大化が加速、常時ロードで無関係 context が増え続け、散文の読み分けは強制力がない (#efficient / #maintainable K.O.)。
  • 案C: frontmatter audience による読み分け強化 — 不採用。ADR-0123 で audience は任意・非強制と確定済みで、ファイル単位の機械的読み分けにならない。CLAUDE.md 本体の常時ロード問題を解決しない (#efficient / #maintainable K.O.)。
  • 案D: GAS をサブディレクトリ移設し全ドメインを nested で統一 — 本 ADR では不採用 (範囲外)。clasp 設定・ビルド・全パス参照の大規模変更で ADR-0067 Phase 3 相当、移行中の #reliable 劣化が大きい。GAS の root 在住は .claude/rules paths で吸収可能。

影響 (Consequences)

§5.1 正の影響 (Good)

  • DRP 1 セッションで現状 172 行 (2,600 token) → 階層化後 root 45 + DRP 25 = 70 行 (1,050 token)。無関係ロードを約 60% (~1,550 token/セッション) 削減。
  • 作業種別追加は該当 rule/nested への追記で完結し、root は触らない構造になる。
  • 「役割別読み方」散文を撤去し、ロール境界がファイル配置 + paths 機構で機械的に表現される。
  • ADR-0067 Gemini 指摘 (nested CLAUDE.md による token 削減) が独立決定として確定する。

§5.2 負の影響 (Bad)

  • 設定が 5 ファイル (root + gas.md + DRP/webapp/docs nested) に分散し、共通規約の置き場判定 (KPI-10) が必要になる。
  • Claude Code の paths: / nested ロード機構という外部仕様への依存が増え、バージョン更新ごとに smoke test 維持コストがかかる。
  • 二重定義期間 (ステップ② 〜 ③) が最大 21 日存在し、その間は両方の更新を意識する必要がある。
  • 後任が ADR-0123 (audience 任意) を根拠に単一ファイルへ巻き戻すリスク (盲点7) → 本 ADR で明示 supersede 関係を記載することで緩和。

§5.3 中立・トレードオフ (Neutral / Trade-offs)

  • #reliable を案B/C より一段下げる代わりに #efficient / #maintainable を大幅に取りに行く設計。#reliable の劣化は緩和策 1〜7 (4 パターン検証マトリクス + バージョン固定 + smoke test + 21 日期限 + 1 件停止 + Workers 制約明記 + 共通規約判定) で 3 (合格ライン) まで戻す前提。
  • KPI-1 (root 50 行上限) と KPI-10 (2 ドメイン以上は root) が競合した場合は KPI-10 (安全性) を優先する (盲点8)。「普遍規約」包含条件は判定チェックリスト (対象ドメイン数・違反時影響範囲・代替記載場所の有無) として root CLAUDE.md 冒頭または CONTRIBUTING.md に明記する。
  • 会計・税務に関する規約 (消費税端数処理等) は文字列差異で重複検出を漏らすリスクがあるため、root に置き nested 複製を禁止する例外ルールを明文化する (盲点3)。
  • CLAUDE.md への Workers 制約記載だけでは実行時違反 (subrequest 50/req 超過) を防げない (盲点6)。wrangler CI ログからの subrequest 計測 / LangGraph グラフ静的解析 lint は将来の検討事項とする。

撤退条件 (Rollback Plan)

以下のいずれかに該当した場合、root スリム化 (ステップ③) を git revert して単一 CLAUDE.md に戻す:

  • .claude/rules/ paths の実機検証 (ステップ①・5 パターンマトリクス) で、GAS パス接触時に gas.md がロードされない／GAS 非接触時にロードされる誤動作が 1 件でも再現 → 移行中止。
  • root スリム化後の実セッション検証 (ステップ④) で、ドメイン制約がロードされず規約違反 (GAS 列番号ハードコード・add_rows 使用等) が 2 件以上発生。
  • 移行後 2 週間以内に「必要な制約が context に出ていない」起因のインシデントが 3 件超発生。
  • 全クローン (main/sub) 間で nested CLAUDE.md のロード挙動が不一致になりワークフローが停止 (即時発動)。
  • 重篤度別トリガー (盲点5): GAS 列番号ハードコード・add_rows 使用などスプレッドシート構造を破壊しうる不可逆性の高い違反は、複数件閾値を待たず 1 件発生で即時ステップ③を停止し人間レビューを挟む。

ロールバック手順: ステップ②まで戻せば root に全 section が残存しているため、ステップ③の単独 PR を git revert するだけで現状復帰できる。nested/rules ファイルは残置しても無害だが、その「無害」はステップ①で Claude Code の複数ファイル優先順位仕様 (後勝ち/上書き/結合) を確認した上での前提とする (盲点3)。

コスト試算

  • root CLAUDE.md: 現在 172 行 → 目標 45 行 (約 74% 削減)。
  • 新規ファイル 5 本作成 (gas.md ~70 行 / DRP ~25 行 / webapp ~10 行 / docs ~20 行 / root スリム化)。
  • context ロード量試算 (1 行 ≈ 15 token 概算): DRP 1 セッションで現状 172 行 (2,600 token) → 階層化後 root 45 + DRP 25 = 70 行 (1,050 token)。無関係ロード約 60% (~1,550 token/セッション) 削減。
  • 移行工数 (AI 活用前提): paths 検証マトリクス 30 分 + 複製 60 分 + root スリム化 45 分 + 実セッション検証 30 分 + 追従 30 分 = 約 195 分。
  • 追加工数: 人間レビュー (root スリム化 PR + 検証マトリクス PR) 約 60 分、バージョン固定 + CI smoke test 構築 約 90 分。
  • 初期合計: 約 345 分 (約 5.8 時間)。
  • ランニング: 新規ドメイン追加時は該当 rule/nested へ追記 (root は触らない) + 四半期重複 section レビュー ~30 分/Q + Claude Code バージョン更新時の smoke test 確認 (自動・確認のみ)。
  • smoke test 実装方式 (盲点5): 実 Claude Code API 呼び出しはレート制限で flaky 化しやすいため、ロードログのファイル検査方式を第一候補とし、実装詳細は移行ステップ①の paths 検証と同じ PR で確定する。flaky 発生時はスキップ禁止・オンコール通知をエスカレーション手順として運用ドキュメントに明記する。
  • BEP: DRP/docs/SPA セッションの context 削減が累積。1 日複数セッション前提で初期工数を約 3〜4 週で回収する見込み (人間レビュー・smoke test 構築込みで楽観補正)。

Confirmation

移行完了後に以下を検証する (各 KPI は 検証手段 / 実行頻度 / 違反時対応 の 3 要素):

  • KPI-1 (root 行数): wc -l CLAUDE.md ≤ 50 行 / CI で毎 PR 機械チェック / 超過時 PR ブロック。KPI-10 と競合時は KPI-10 を優先。
  • KPI-2 (DRP セッション): DRP 作業セッション (cwd=drp 配下) で GAS 固有制約・会計 Domain rules が context に載らない / 移行直後 + 月次目視 / 載った場合は撤退検討。
  • KPI-3 (GAS セッション): GAS 作業セッション (000_infra〜900_test 接触) で .claude/rules/gas.md が載り、docs/DRP 規約が載らない / 移行直後 + 月次 / 載らない場合は撤退検討。
  • KPI-4 (情報損失ゼロ): 24 section 全項目が分割マップどおりいずれかのファイルに 1:1 で存在 / 移行 PR レビュー時に section チェックリスト添付 / 欠落時 PR ブロック。
  • KPI-5 (散文撤去): 「役割別読み方」散文が root から撤去されロール境界がファイル配置と paths 機構で表現 / grep 機械チェック / 残存時 PR ブロック。
  • KPI-6 (paths 検証マトリクス・リスクA/盲点1): ステップ①で 5 パターン (①root 直下のみ ②GAS サブディレクトリのみ ③templates/ のみ ④GAS と非 GAS の混在編集 ⑤非 GAS → GAS の順序操作) の実機ロード結果 + ツール呼び出しレベルのロード状態ログを移行 PR に添付 / 移行前 (ステップ①) / 1 件でも誤動作再現時は移行中止し代替設計 (GAS 常時ロード化 or 案D 早期実施) を検討。実機検証ログ (2026-06-09・Claude Code 2.1.169・5 パターン全 PASS・撤退条件該当 0 件): tasks/adr0129/kpi6_paths_verification_log_2026-06-09.md。
  • KPI-7 (Claude Code バージョン固定 + smoke test・リスクB/盲点2): Claude Code バージョンを .tool-versions (または engines) で固定。バージョン更新 PR で KPI-2/3 相当 smoke test を CI 自動実行 / バージョン変更時 / smoke test 失敗時は更新ブロック。
  • KPI-8 (二重定義期限・盲点4): ステップ②完了から 21 日以内にステップ③をマージ / CI 日次計測 (ファイル作成日 + git log) / 期限超過時は自動 issue 起票。
  • KPI-9 (Workers 制約チェック・盲点6): drp/CLAUDE.md に「Workers CPU time 上限・subrequest (50/req) 上限の事前検証を merge 前必須」を明記 / 分割マップ照合時 / 未記載時 PR ブロック。
  • KPI-10 (共通規約判定基準・盲点7/8): 「2 つ以上のドメインに適用される規約は root に置く」基準 + 「会計・税務規約は root 限定・nested 複製禁止」例外を root CLAUDE.md に明文化し、四半期ごとに nested 間重複 section を検出 / 四半期 / 重複発見時は root への引き上げ PR 起票。
  • KPI-11 (メジャーバージョン再検証・盲点2): Claude Code のメジャーバージョン更新時 (semver major または公式リリースノートに "breaking change" 記載) は smoke test 自動パスに関わらず 人間によるフル 5 パターンマトリクス再検証を必須 / メジャー更新時 / 未実施時はバージョン更新 PR ブロック。
  • KPI-12 (Turborepo inputs・盲点4): 各パッケージの turbo.json の inputs に "CLAUDE.md" / ".claude/rules/**" を追加 → Corrigendum 1 で取り下げ（下記）。turbo inputs はビルド成果物のキャッシュキーであり、成果物に影響しない自然言語の指示書を入れると無関係な再ビルドを生むため不適切。代替は markdown-lint / 専用 hook。

参照 (References)

  • 関連 ADR:
    • ADR-0067 (monorepo 採用) — 準拠。Gemini 指摘「nested CLAUDE.md による token 削減」を本 ADR で独立決定として確定。
    • ADR-0123 (frontmatter audience) — エージェント設定の読み分け機構としては supersede (ファイル配置・paths が正式手段)。人間向けドキュメントへの frontmatter 利用は継続可。ステップ⑤で ADR-0123 の参照節に本 ADR への相互参照を追記済み。
    • ADR-0045 / RQ-045 (指示数増で LLM 遵守率低下・HumanLayer 実測) — 準拠。本 ADR の #maintainable 動機の根拠。
  • 関連 PR/Issue: proposal_2026-06-09_nested-claudemd-split-map.md (24 section の分割マップ・PR #1604 merged) / Session ID 表示 PR #1601 (審査運用の副産物)
  • 外部資料:
    • Claude Code 公式 "How CLAUDE.md files load" / claude-code-guide
    • Cloudflare Workers 制約 (CPU time / subrequest 50/req)
    • Suhr 1999 CBA (加重和正規化の根拠)

Known Limitations / Escalated Residual Risks (HITL ratification required)

本 ADR は Cross-Validation で goalpost ループ検知 (2 連続却下・却下盲点が毎回移動) のため、自動審査を打ち切り「残余リスク付き Accept」として起票された (ADR-0109 Part4)。以下の未解決 critical 盲点は、人間レビュー (この PR の merge = 受理 / close = 却下) で最終判断すること。LLM critic による反復審査では収束しないと判定されたものであり、PR レビューが外部検証器となる。

未解決 critical 盲点:

  • 消費税端数処理ルールがGAS会計とDRPの両方で参照されうるにもかかわらず「GAS固有」と誤判定されてnestedに複製されると、税務申告期に片方だけ改正対応されてe-Tax提出データと内部集計が不一致になる

実装状況

ステップ内容状態
①paths 実機検証 (KPI-6・5 パターンマトリクス)完了 (PR #1615・全 PASS)
②各ドメイン規約を root から複製 (gas/DRP/webapp/docs)完了 (PR #1611 + #1621)
③root スリム化 172→65 行・二重定義解消完了 (PR #1622)
KPI-7path-scoped ロードの静的 lint + ログ解析ゲート完了 (PR #1623)
④実セッション検証 (KPI-2/3・main/sub ロード一致)進行中。移行直後 smoke は #1622/#1621 で実施 (InstructionsLoaded ログで nested/path_glob ロード確認)。月次目視と sub クローン側の確認は継続
⑤追従 (ADR-0123 相互参照・KPI-12 見直し・Status 更新)本 PR で実施
  • Domain rules（会計仕訳ロジック）の配置: ステップ③で「GAS 固有として gas.md に残し root から削除」を採用 (起案者判断)。上記 HITL 盲点の「消費税端数処理」のような純税務ルールは未登録のため当面リスク顕在化なし。将来そうしたルールを追加する際は「普遍規約判定基準」(root) に従い root 限定で置く。

Corrigendum 1 (2026-06-09): KPI-12 取り下げ

  • 訂正内容: Confirmation の KPI-12（turbo.json の inputs に CLAUDE.md / .claude/rules/** を追加）を取り下げる。turbo.json は変更しない。
  • 理由: turbo の inputs はビルド成果物のキャッシュキーである。CLAUDE.md / .claude/rules/** は Claude への自然言語の指示書で、tsc/eslint/vitest の成果物には影響しない。これを inputs に入れると、ドキュメントを 1 行直すたびに全パッケージの type-check/lint/build キャッシュが無効化され無関係な再ビルドを生む。さらに機械 lint は自然言語規約を検査しないため再実行しても得るものがない。盲点4 が想定した「規約変更をコード側チェックに波及させる」効果は得られず、コストだけが残る。
  • 代替: CLAUDE.md / rules の整合性が必要なら markdown-lint や専用 hook（例: path-scoped ロードの静的 lint = KPI-7 / PR #1623）で別途担保する。turbo キャッシュキーには含めない。