← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0045type: adrstatus: accepted
pagemode: Standardkruchten: Property/Executivescope: platformimplementation_status: In Progress (Phase 1 完了: ディレクトリ移行・CLAU…proposed_at: 2026-05-15 21:49approved_at: 2026-05-15deciders: [email protected] (単独)business: meta
型付き辺: 出 10 / 入 3
関連: ADR-0039 ADR-0123 ADR-0068 ADR-0114 ADR-0117 ADR-0028 ADR-0048 ADR-0055 ADR-0061 ADR-0079 細分化された: ADR-0046 ADR-0115 前提とされる: ADR-0129全体は INDEX →

ADR-0045: docs/_internal/ 組織化・内部ドキュメント管理方針の確立

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Property/Executive
  • Scope: platform
  • Implementation Status: In Progress (Phase 1 完了: ディレクトリ移行・CLAUDE.md・_config.json 更新)。frontmatter モデル・enforcement・audience の扱いは後発 ADR-0123 が現行正典 — 下記 Corrigendum (2026-06-09) 参照
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-15 21:49
  • 承認日時 (JST): 2026-05-15
  • Deciders: [email protected] (単独)

Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

Corrigendum (2026-06-09)

本節は追記のみ。以下の §1.5 / §決定 / §5.1 / §Confirmation の該当記述は、後発 ADR の決定で部分的に上書きされている。本文（決定テキスト）は履歴保全のため変更しない。

  1. audience 必須化は撤回（ADR-0123 で supersede）。 本 ADR は §1.5・§決定・§5.1 で frontmatter type/status/audience の必須化を掲げたが、後発の ADR-0123（frontmatter 3 層モデル）が common 必須トリオを id/type/status に確定し、audience 必須化（案 C）を明示的に却下した。

    • → frontmatter モデルの現行正典は ADR-0123。 audience は「推奨・任意・非強制」。推奨値域は both / agent / human（3 値・任意）。main/sub は audience 軸ではなくディレクトリ所有 + nested CLAUDE.md（ADR-0067 論点）で扱う。
    • SSoT: scripts/frontmatter-schema.json / 規約: docs/_internal/05_how-to/frontmatter-lint_rules.md（§6 types・§7 statuses・§7.1 audience・§8 enforced dirs）。

  2. CI enforcement は phased rollout（§1.4 / §Confirmation §152 の「adr-lint.mjs を _internal/ 対応に拡張」を修正）。 _internal/ 全体を一括で ENFORCED_FRONTMATTER_DIRS に加えると未 backfill ファイルが大量に FAIL して CI が赤化するため、per-dir で id/type/status 欠落 0 になったディレクトリから順に強制対象へ追加する段階方式とする。2026-06-09 時点で _internal/ 配下の enforced は 03_decisions/decision_pipeline/ のみ。

  3. §Confirmation line 145 の fitness 命令は信頼できない（既知バグ）。 find docs/_internal -name '*.md' | xargs grep -rL '^---' は本文中の ---（水平線・YAML 区切り等）を frontmatter と誤検出し準拠率を過大評価する。正しい判定は「ファイル1 行目が --- で始まり、かつ id/type/status が揃うか」で、正典実装は scripts/adr-lint.mjs の parseFrontmatter / checkFrontmatter。

    • 2026-06-09 実測（正しい判定）: _internal/ 総 295 本中、FM ブロック無し 121 本 / id/type/status トリオ欠落 192 本 / 完全 103 本（35%）。旧 grep ベースの「欠落 43 本・85% 実装済」は過少カウントだった。

コンテキスト

1.1 背景 (Background)

3モデル（Claude/Gemini/GPT）によるRQ-045調査で、docs/_internal/ の組織化方針について全モデルが合意に達した。arc42（ADR-0039）は docs/dev, docs/arch, docs/spec をカバーするが _internal/ はスコープ外（arc42 founders 明言: https://docs.arc42.org/home/ 参照）であるため、本ADRで _internal/ 専用の構造化・運用方針を確立する。

1.2 現状 (Current State / As-Is)

docs/_internal/ に30本超のファイルがフラットに混在している。ファイル種別（ワークフロー手順・調査記録・AIエージェント設定・進捗管理・財務文書）が無秩序に並列しており、CLAUDE.md 内の参照パスも散在状態である。

1.3 課題 (Problem)

  • 目的のファイルを見つけるのに平均2〜3分の検索コストが発生（2026-05 ts_kuma本人による実測、n=5、対象ファイル: git_workflow.md / hooks_setup.md / failure_patterns.md 等。体感値であり組織規模拡大時に再計測を推奨）。
  • Jr.メンバーのオンボーディング時に「どこに何があるか」の口頭説明が必須で、初回30〜60分の説明コストが発生（想定値: Jr.入社想定2名ベース）。
  • ファイル移動のたびに CLAUDE.md 内の複数箇所のパス参照更新が必要。

1.4 制約・要件 (Constraints & Requirements)

  • arc42 統合は不可（arc42 スコープ外明言のため）。_internal/ を維持する必要あり。
  • ADR-0028 の 6 ステージ・ワークフローと整合させる必要あり。
  • 既存の Claude Code 標準ツール環境を前提とする（AI支援前提の移行）。
  • CI（GitHub Actions）で frontmatter lint を強制可能であること。
  • 移行コストは AI 活用前提で約4時間以内に収めること。

1.5 目標 (Goals / To-Be)

「ステージ番号 → ディレクトリ → ファイル」の3ステップで目的のファイルに到達できる構造を確立する。具体的には:

  • ADR-0028 ステージ順に対応した番号付きサブディレクトリ（00〜06、07 は archive 予約）を導入。
  • 全 _internal/*.md に YAML frontmatter（type/status/audience）を必須化。
  • 実行プロンプトを .claude/skills/ へ分離し、設計資料は docs/_internal/04_specs/ に残す。
  • RQ ライフサイクルを open → active → synthesized → archived に形式化。

Non-Goals: arc42 への統合、_internal/ 外のドキュメント構造変更、サブディレクトリ内の2階層化（半年後に再評価）。

決定

案A「ADR-0028 ステージ順に対応した番号付きサブディレクトリ（00〜06）」を採用する。 biz/ は全ステージの前提・文脈（Stage 0相当）として先頭に配置し、数字プレフィックスでOS側のソート順を強制する。全 _internal/*.md に YAML frontmatter（type/status/audience）を必須化し、CI lint でマージブロックする。命名規約として *-pipeline（AI自動実行）は 03_decisions/ または 04_specs/pipeline/ へ、*-workflow（人間手順書）は 05_how-to/ へ、lifecycle 系は 06_ops/ へ配置する。実行プロンプトは .claude/skills/ へ分離し、agents/ 内旧 prompts/ は prompt-design/ にリネームする。RQ ライフサイクルは open → active → synthesized → archived に形式化し、Rule of Three（同種3本未満は専用ディレクトリ不要）で構造肥大を抑制する。

検討した代替案 (Alternatives Considered)

評価軸の判定基準: ◎ 明確な改善 / ○ 同等 / △ 一部劣るが許容 / × 明確に劣る

評価軸（重み）案A 番号付きサブディレクトリ（推奨）案B arc42完全統合案C フラット+frontmatter案D 現状維持
認知負荷最小化（40%）◎ ステージ番号で3ステップ到達△ arc42知識前提で学習コスト高× 30本走査が必要× 問題継続・悪化
Jr.オンボーディング（25%）◎ 番号＋名前で自己説明的△ arc42前提知識必要× 全ファイル列挙が必要× 口頭説明30〜60分継続
将来拡張性（20%）◎ Stage追加で自然拡張△ arc42スコープ制約あり× ファイル増で破綻× ファイル増で加速度的悪化
移行コスト（10%）○ 約4時間（AI活用前提）× 1日超（arc42再設計必要）◎ 2時間以下◎ 0時間
AI適性（5%）◎ 構造化でコンテキスト効率高○△×
加重スコア（合計）◎ 最高△△×
  • 案B arc42完全統合 — 不採用理由: arc42 founders が _internal/ はスコープ外と明言。無理に統合すると arc42 の意図を歪め、Jr.に arc42 前提知識を要求する学習コストが発生する。
  • 案C フラット+frontmatter — 不採用理由: frontmatter のタグベース検索はエディタ依存でCLI作業時に機能しない。フラット30本構成ではファイル種別把握のため初回15〜30分の追加読み込みコストが発生し、認知負荷の根本解決にならない。ファイル増で破綻する。
  • 案D 現状維持 — 不採用理由: 「変えないコスト」を明示するために評価。Jr.入社ごとに30〜60分/人の説明コストが継続発生し、ファイル増加（年10本ペース）に伴い検索コストが加速度的に悪化する。

コスト試算（AI活用前提）:

作業AI活用工数手動工数（参考）
ファイル移動・リネーム（30本）20分150分
frontmatter追加（30本）45分300分
_config.json nav更新15分30分
CLAUDE.md パス参照更新20分60分
CI lint スクリプト実装90分240分
テスト・動作確認45分60分
合計235分（約4時間）840分（1.75人日）

金銭換算: 実作業 約[MASKED:AMOUNT] + PRレビュー [MASKED:AMOUNT] = 初期投資合計 約[MASKED:AMOUNT]。ランニングコスト約60分/月 ≈ [MASKED:AMOUNT]/月。BEP: 検索コスト削減込みで約2ヶ月、ランニングコスト差額のみで約5ヶ月。

影響 (Consequences)

5.1 正の影響 (Good)

  • ファイル探索コストが「30本走査」から「ステージ番号→ディレクトリ→ファイル」の3ステップに短縮（目標: 30秒以内、Review After で再計測）。
  • Jr.オンボーディングの口頭説明コスト（30〜60分/人 × 想定2名 = 60〜120分）を削減。番号＋名前で自己説明的な構造になる。
  • frontmatter（type/status/audience）の必須化により、ファイル種別・状態・対象読者が機械可読になり、CI lint で品質を強制可能。
  • ADR-0028 のステージ番号と整合することで、ワークフロー全体の一貫性が向上。Stage追加（07以降）にも自然に拡張可能。
  • Claude Code のコンテキスト効率が向上（構造化により AI のパス推論精度が上がる）。
  • Rule of Three により、サブディレクトリの過剰増殖（YAGNI 違反）を抑制。

5.2 負の影響 (Bad)

  • 初期移行コストとして約4時間（AI活用前提）+ PRレビュー1時間 ≈ [MASKED:AMOUNT] の初期投資が発生。
  • 移行直後の72時間以内に、AIエージェント（Claude Code）の旧パスキャッシュによるエラーが発生するリスク。.claude/projects/ 配下のメモリファイルにも旧パスが残存する可能性あり。
  • 新規ファイル作成時の frontmatter 記載忘れリスク。CI lint でブロックするが、PR 作者の手戻りが発生する。
  • 移行中のリンク切れリスク（CLAUDE.md / _config.json nav / 他ADR 参照）。
  • ランニングコストとして frontmatter 追加・Rule of Three チェックで月60分 ≈ [MASKED:AMOUNT]/月 が継続発生。
  • 半年後に _internal/ が50本超になった場合、サブディレクトリ内の2階層化を再検討する必要あり（追加移行コスト）。

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

  • arc42 統合圧力の再燃リスク: Jr.増員時に「arc42 に統合すべき」議論が再発する可能性。ADR-0039 のスコープ外明言を周知することで収束コストを下げる。
  • Rule of Three の判定主体: PR作者の一次判定 + ADRオーナー（ts_kuma）の最終確認という二段階運用。判断のブレを許容する代わりに、自動判定の硬直性を回避。
  • 07_archive/ の予約: 将来の Stage 7+ 追加時には本 ADR を amend する前提。番号体系の柔軟性は犠牲になる。
  • 実行プロンプトの .claude/skills/ 分離: ドキュメント検索範囲が _internal/ と .claude/skills/ の2箇所に分かれるが、用途が明確に異なるため許容。

撤退条件 (Rollback Plan)

移行前準備: git tag before-adr-0045-migration でスナップショット作成。逆リネームスクリプト scripts/migrate_internal_rollback.sh および migration_mapping.json（旧パス→新パスのマッピング）を移行PRに同梱。

ロールバック発動の判定閾値（いずれか一つに該当した場合に発動）:

  • 移行完了後72時間以内に旧パス参照エラーが5件超発生
  • CI frontmatter-lint の偽陰性（正常ファイルを違反と誤検知）が3件以上続く
  • Jr.メンバーから「構造が分からない」苦情が移行後1週間以内に2件超発生
  • CLAUDE.md のパス参照不整合により開発ワークフローが停止（即時発動）

完全ロールバック手順:

  1. git checkout before-adr-0045-migration -- docs/_internal/ でファイル構造復元
  2. git revert <migration-commit> でコミット取り消し
  3. _config.json の nav 配列を旧状態に復元
  4. CLAUDE.md のパス参照を旧状態に復元

部分ロールバック（CLAUDE.mdパス参照のみ）:

cat migration_mapping.json | jq -r 'to_entries[] | "s|" + .value + "|" + .key + "|g"' | xargs -I{} sed -i {} CLAUDE.md

frontmatter 追加分のみ巻き戻す場合: git revert <frontmatter-commit>。

Review After 2026-08-15（移行完了から3ヶ月後）チェック項目:

  • 07_archive/ ファイル数
  • Rule of Three 適用漏れ件数
  • Jr.メンバーからのナビゲーション苦情件数
  • frontmatter 運用ランニングコストの実測値更新
  • 「探す時間」の再計測（n=5、目標値: 30秒以内）

Confirmation (準拠確認 / Fitness Function)

本 ADR の遵守を継続的に検証する fitness function:

判定指標と計測方法:

指標計測コマンド目標値
直下残存ファイル数find docs/_internal -maxdepth 1 -name '*.md' | wc -l0本
frontmatter 準拠率find docs/_internal -name '*.md' | xargs grep -rL '^---' | wc -l0本
命名規約違反（pipeline と workflow の混在）find docs/_internal -name '*pipeline*workflow*' | wc -l0本
_config.json nav 登録率scripts/adr-lint.mjs で未登録ファイル数0本
旧パス参照漏れgrep -r 'docs/_internal/[a-z]' docs/ CLAUDE.md | grep -v '/0[0-6]_|biz/|daily_log'0件
Rule of Three 警告find docs/_internal/{dir} -maxdepth 1 -name "*.md" | wc -l が PR で 2→3 になる場合に CI 警告警告時にサブディレクトリ作成

検証手段:

  • 自動: GitHub Actions の frontmatter-lint ジョブ（PR 単位、マージブロック）。scripts/adr-lint.mjs を _internal/ 対応に拡張。
  • 自動: Rule of Three 自動カウント（CI スクリプト、PR コメントで警告）。
  • 手動: 移行完了後72時間は旧パス参照チェックコマンドを毎日実行。
  • 手動: Review After 2026-08-15 にチェック項目を全件確認。

実行頻度:

  • CI lint: 全 PR で実行（マージブロック）。
  • 旧パス参照チェック: 移行後72時間は毎日、以降は PR 単位で CI 実行。
  • Review After 評価: 2026-08-15（3ヶ月後）に1回。以降は半年毎。

違反時の対応:

  • CI lint 失敗: マージブロック。PR 作者が修正してから再 push。
  • Rule of Three 警告: PR 作者が同 PR 内でサブディレクトリ作成＋既存2本を移動。frontmatter lint 通過確認後にマージ。
  • 旧パス参照漏れ検出: 移行漏れとして CI 失敗扱い、即時修正。
  • Review After で目標未達: 本 ADR を amend するか、サブディレクトリ内の2階層化を検討する別 ADR を起案。

運用上の罠への対策（fitness function に組み込み済み）:

  1. AIエージェント旧パスキャッシュ: grep -r 'docs/_internal/' /Users/ts_kuma/.claude/projects/ | grep -v '/0[0-6]_' を移行後に手動実行。
  2. 移行期間中のリンク切れ: CI で旧パス参照チェックを自動化。
  3. daily_log/ アーカイブ化: 6ヶ月超の weekly ログは 02_project/daily_log/archive/ に移動するルールを 06_ops/ 配下に文書化。
  4. frontmatter 未準拠ファイル流入: CI lint でマージブロック、CLAUDE.md に「新規 _internal/ ファイル作成時は frontmatter 必須」を追記。

参照 (References)

  • 関連 ADR:
    • ADR-0028: docs/adr/0028-adopt-6-stage-workflow-uc-slice-dev-cd-gas-mvp.md（ステージ番号の整合性根拠）
    • ADR-0039: docs/adr/0039-adopt-arc42-for-architecture-documentation.md（arc42 スコープ外明言）
  • 関連 PR/Issue: RQ-045（3モデル合意調査）
  • 内部資料: docs/_internal/research_prompts/RQ-045_internal_docs_organization_synthesis.md（line 46 に Rule of Three 合意事項）
  • 外部資料: