← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:32
commonid: adr-0039type: adrstatus: accepted
pagemode: Standardkruchten: Existence/Propertyscope: platformimplementation_status: Done (Phase 1-4 完了 + 構造補完: itgc/ + ban…proposed_at: 2026-05-14 19:29approved_at: 2026-05-15deciders: [email protected] (単独)business: meta
型付き辺: 出 14 / 入 2
関連: ADR-0000 ADR-0030 ADR-0045 ADR-0049 ADR-0098 ADR-0114 ADR-0115 ADR-0023 ADR-0036 ADR-0046 ADR-0048 ADR-0058 ADR-0079 ADR-0041 細分化された: ADR-0054 ADR-0117全体は INDEX →

ADR-0039: ドキュメント構造を arc42+C4+MADR+feature-folder に刷新する

  • Status: Accepted
  • Mode: Standard
  • Kruchten Type: Existence/Property
  • Scope: platform
  • Implementation Status: Done (Phase 1-4 完了 + 構造補完: itgc/ + bank-reconciliation/ + 5 新ドメイン + spec_*.md 全 27 本振り分け完了)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-14 19:29
  • 承認日時 (JST): 2026-05-15
  • Deciders: [email protected] (単独)

決定の早わかり（Y-statement）

本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

  • 文脈: docs/dev/ に dev_mas-NNN.md 形式のファイルが 150+ 本あり、docs/arch/ には設計文書と外部調査資料が混在する。3 者並列レビューで、既存構造が Claude Code の自律実装の障壁と判明した。Jr エンジニア入社 (D-180) も控える。
  • 問題: Claude Code は機能仕様の参照に全ファイル探索が必要で、1 機能あたり平均 7.4 回のツール呼び出しが発生している (実測 15 サンプル)。「現在の設計」と「過去の調査メモ」を機械判別できず、誤った文書を参照するリスクがある。
  • 問題点と課題（直せる原因 → 発生を止めるためにやること）:
    • 機能単位で spec を辿れる構造がない → feature-folder (domains/<feature>/current-spec.md) で機能単位の参照点を作る。
    • 文書の type / status を機械判別できない → 全ファイルに id / type / status / related / legacy_id の frontmatter を必須化する。
    • 設計文書・外部調査・証跡が同一ディレクトリに混在 → 6 軸 (architecture / domains / research / data / operations/itgc / implementation/legacy-dev) でディレクトリを分離する。
  • 前提（解決を課題に立てない与件）:
    • dev_mas-NNN.md の連番は git blame と外部リンク (PR description 269 件) があり一括リネーム不可。
    • SSG は自作 docs-build.mjs + Cloudflare Pages を維持する。
    • J-SOX 対応の変更管理・アクセス管理の証跡を docs 体系に組み込む。
  • 決定（対応策）: 現状維持 (案 A)・Diátaxis 全面採用 (案 B)・g3doc スタイル (案 D) でなく、arc42 サブセット + C4 L1/L2 + MADR + feature-folder のハイブリッド構造 (案 C) に刷新する。既存 150+ ファイルは implementation/legacy-dev/ に凍結退避し、新規ファイルは新構造にのみ作成する。移行は Phase 1〜4 の段階実行で、各 Phase に数値化された撤退条件を設ける。
  • 目的: Claude Code が「機能名」から spec → detail → ADR → テスト を辿れる状態にする。探索ツール呼び出しを平均 7.4 回から目標平均 2 回以内に削減し、J-SOX 証跡の提示構造も事前整備する。
  • 代償: 総工数 80〜128 h (約 6〜10 週、業務並行) と新旧構造の混在期間。2 軸構造の学習コスト、frontmatter 記述の手間、Phase 3 未完遂時の legacy-dev/ 長期負債化リスクを受け入れる。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

1.1 背景 (Background)

2026-05 に実施したドキュメント体系の現状調査(Gemini / Claude / GPT の 3 者並列レビュー)により、既存構造が Claude Code による自律実装の障壁になっていることが判明した。Jr エンジニア入社(D-180)を前に、AI + 人間の両方が迷わずナビゲートできる構造への刷新が必要なタイミングである。

1.2 現状 (Current State / As-Is)

docs/dev/ に dev_mas-NNN.md 形式のファイルが 150+ 本存在し、docs/arch/ には設計文書(FRD/NFRD/データモデル等)と外部調査資料(ref_*.md)が混在している。ディレクトリ間の関係を示す index や feature 単位のナビゲーションは存在しない。

1.3 課題 (Problem)

Claude Code が特定機能の仕様を参照する際、docs/dev/ の全 150+ ファイルを grep/read で探索しなければ関連ファイルを特定できず、1 機能あたり平均 7.4 回のツール呼び出しが発生している(実測: 2026-05、5 機能 × 3 クエリ = 15 サンプル)。docs/arch/ では「現在の設計」と「過去の調査メモ」が同一ディレクトリに混在し、type / status の機械判別ができないため Claude Code が誤った文書を参照するリスクがある。

計測条件(後任が再現可能な形で記録):

  • 対象機能: 月次決算(dev_mas-030〜035)・予実管理(dev_mas-060〜070)・資金繰り予測(dev_mas-080〜085)・勘定科目マスタ(dev_mas-010〜015)・銀行照合(dev_mas-045〜050)
  • 計測方法: Claude Code の JSONL トランスクリプト(~/.claude/projects/<hash>/*.jsonl)から Read/Bash(grep)/Bash(find) ツール呼び出しを集計
  • 結果: 最小 5 回・最大 13 回・平均 7.4 回
#!/usr/bin/env bash
# count-doc-tool-calls.sh: Claude Code transcript から docs 探索ツール呼び出し数を集計
# Usage: ./count-doc-tool-calls.sh <session.jsonl> <feature-keyword>
TRANSCRIPT="$1"; KEYWORD="$2"
echo "=== '$KEYWORD' に関連するツール呼び出し ==="
grep -o '"name":"[^"]*"' "$TRANSCRIPT" \
  | grep -E 'Read|Bash|Grep' | wc -l
echo "=== 参照されたファイルパス ==="
grep -o '"file_path":"[^"]*docs[^"]*"' "$TRANSCRIPT" | sort -u

再計測タイミング: Phase 1 完了後と Phase 3 完了後に同一クエリで再計測し、削減効果(目標: 平均 2 回以内)を検証する。

1.4 制約・要件 (Constraints & Requirements)

  • dev_mas-NNN.md の連番は git blame と外部リンク(PR description / commit message 269 件確認済)があるため一括リネームは不可
  • SSG は自作 docs-build.mjs + Cloudflare Pages を維持(乗り換えコストが現時点では ROI 不足)
  • ソロ開発 + 日常業務並行のため、大規模一括移行は困難
  • J-SOX 対応として変更管理・アクセス管理の証跡を docs 体系に組み込む必要がある
  • docs/_config.json の nav 配列への登録が必要(CLAUDE.md 制約)

1.5 目標 (Goals / To-Be)

Claude Code が「機能名」から spec → detail → ADR → テスト を辿れる feature-folder 構造を実現し、設計文書・外部調査・運用手順・ITGC 証跡がそれぞれ独立したディレクトリに収まる状態にする。既存 150+ ファイルは implementation/legacy-dev/ に凍結退避し、新規ファイルは新構造にのみ作成するルールで移行リスクを最小化する。

2. 判断基準 (Decision Drivers)

  • AI 最適化: Claude Code が単独で機能を再実装するために必要十分な情報密度が確保できるか(1 ファイル 200 行以内・type/status の機械判別)
  • 移行リスク最小: 150+ 既存ファイルの git blame・外部リンクを破壊しない
  • J-SOX 対応: 変更管理証跡(ADR + Git 履歴)が監査人に提示できる構造か
  • ソロ運用の持続可能性: 日常業務並行で継続的にメンテナンスできる複雑度か
  • AI + 人間の両立: frontmatter で AI が機械判別、index.md で人間がスキャン

関連 ADR 整合性

  • ADR-0000(ADR を記録する): 本 ADR はその方針に沿った運用であり Conflict なし
  • ADR-0023(ADR 構造業界標準化・MADR 採用): 本 ADR が採用する MADR 形式は ADR-0023 の延長であり Supersede 不要・整合
  • ADR-0019(Decision Pipeline LangGraph 移行): docs 構造変更は Pipeline の動作に影響しない。Conflict なし
  • ADR-0030(Kruchten 3 分類)/ ADR-0036(Confirmation セクション必須): 本 ADR はこれらを遵守して起案。Conflict なし
  • Supersede 対象: なし(既存 ADR にドキュメント構造を定めたものが存在しないため)

決定

ドキュメント構造を arc42 サブセット + C4 L1/L2 + MADR + feature-folder ハイブリッド構造に刷新する。architecture/ (arc42 章構造)・domains/<feature>/current-spec.md (feature-folder)・research/ (外部調査)・data/ (マスタ・データ定義)・operations/itgc/ (J-SOX 証跡)・implementation/legacy-dev/ (既存 150+ ファイル凍結退避) の 6 軸でディレクトリを分離し、全ファイルに id / type / status / related / legacy_id を含む frontmatter を必須化する。既存 dev_mas-NNN.md は連番・git blame・外部リンクを保護するため一括リネームせず legacy-dev/ にそのまま移動し、新規ファイルは新構造にのみ作成する。移行は Phase 1〜4 の段階実行とし、各 Phase に数値化された撤退条件を設ける。

検討した代替案 (Alternatives Considered)

判断基準案 A(現状維持)案 B(Diátaxis)案 C(arc42+C4、推奨)案 D(g3doc)
AI 最適化✕ 全探索継続△ 4 区分では spec 判別不可◎ frontmatter + feature-folder△ README のみでは密度不足
移行リスク◎ ゼロ△ 設計成果物の分類が崩れる○ 凍結退避で既存リンク保護◎ ほぼゼロ
J-SOX 対応✕ 証跡体系なし△ how-to はあるが証跡構造なし◎ itgc/ + ADR + Git 履歴△ 証跡構造なし
ソロ運用持続可能性◎ 変更なし△ 全面移行で一時悪化○ 段階移行・Phase 単位◎ 変更少ない
AI + 人間両立✕△◎ frontmatter(AI) + index.md(人間)○

  • 案 A: 現状維持(変更しない)

    • Good, because 移行コストがゼロ
    • Bad, because Claude Code が機能仕様を辿るために 150+ ファイルを全探索し続ける問題が解消されない(1 機能あたり平均 5〜10 回のツール呼び出し継続)
    • Bad, because Jr エンジニア入社時のオンボーディングコストが高いまま
    • Bad, because J-SOX 証跡体系が構築されないまま監査対応が必要になった場合に後追い対応となる

  • 案 B: Diátaxis 全面採用(Tutorial/How-to/Reference/Explanation の 4 区分)

    • Good, because Cloudflare・Canonical が採用する実績ある手法で読者の利用意図を強制的に明示できる
    • Bad, because 本プロジェクトは PRD/FRD/spec/ADR という「設計成果物」中心であり、4 区分のどこにも収まらないファイルが大量発生する(Canonical 自身が「導入直後はドキュメントが悪化して見える」と認めている)
    • Bad, because トップレベル分類が設計成果物に合わないため、移行後に再構造化が必要になるリスクがある

  • 案 C: arc42 サブセット + C4 L1/L2 + MADR + feature-folder(推奨)

    • Good, because arc42 の「戸棚」思想で既存の PRD/BRD/FRD/ADR/arch_* がそのままセクションにマッピングでき、移行コストが低い
    • Good, because C4 L1/L2 を Mermaid で Git 管理でき、GAS+Sheets の小規模構成では L2 で全体像を表現できる
    • Good, because feature-folder(domains/<feature>/current-spec.md)により Claude Code が機能単位で spec を参照でき、ツール呼び出しを 1〜2 回に削減できる(推定)
    • Good, because legacy_id: dev_mas-NNN を frontmatter に保持することで既存リンクを壊さず移行できる
    • Good, because operations/itgc/ に ITGC 4 領域(経産省「システム管理基準追補版 R6.12 改訂」対応)を常設し ADR と Git 履歴を証跡として活用できる
    • Bad, because arc42 の章構造と feature-folder の 2 軸が初見では分かりにくく、Jr エンジニアの学習コストがある(AGENTS.md に構造説明を記載して緩和)
    • Bad, because frontmatter 必須化により新規ファイル作成時に YAML 記述の手間が増える(テンプレートで緩和可能)
    • Bad, because Phase 3(domains/ 抽出)が長期化すると legacy-dev/ が事実上の現行仕様置き場になる長期負債化リスクがある

  • 案 D: Google g3doc スタイル(コードと並走する README 中心)

    • Good, because「docs alongside code」の文化は GAS 実装ファイルと近くなる
    • Good, because 移行コストが最小
    • Bad, because 会計ドメインの複雑な業務ロジックを README だけで表現するには情報密度が不足し、spec/ADR 体系を補完できない
    • Bad, because J-SOX 証跡体系を組み込む構造的な場所がない

移行計画 (Migration Plan)

移行工数見積(数値)

Phase内容所要日数累積時間(業務並行)
Phase 1骨格構築・AGENTS.md・_meta テンプレ1〜2 日8〜16 h
Phase 2低リスク再配置(adr/・arch/・test/・master/ の移動)2〜4 日16〜32 h
Phase 3domains/ 段階抽出(優先 5 機能分)5〜7 日40〜56 h
Phase 4-alychee + markdownlint(既存ツール・設定のみ)0.5 日4 h
Phase 4-b--check-frontmatter(id/type/status/related 必須キー + 値域チェック)1 日8 h
Phase 4-c--check-legacy-dirs(docs/dev/・docs/arch/・docs/spec/ への新規作成禁止チェック)0.5 日4 h
Phase 4-d--count-domains(domains/*/current-spec.md カウント、完了条件 3 の CI 実装)0.5 日4 h
Phase 4 小計2.5 日20 h
合計10〜16 日80〜128 h(約 6〜10 週)

長期負債化リスク: Phase 3 を着手せず Phase 1/2 のみ完了した状態で放置すると、legacy-dev/ が永続化し「凍結のつもりが事実上の現行仕様置き場」になるリスクがある。Phase 3 完了目標を 2026-08-31 とし、超過時は月次レビューで継続判断する。

移行対象 150+ ファイルの主要カテゴリ

  • docs/dev/dev_mas-NNN.md(〜150 本) → implementation/legacy-dev/ 凍結退避後、機能別に domains/<feature>/current-spec.md へ段階抽出
  • docs/arch/ref_*.md(外部調査 10+ 本) → research/ へ移動
  • docs/arch/frd_*.md / nfrd.md / arch_*.md(設計 5 本) → architecture/ へ移動
  • docs/master/mst_*.md(マスタ定義 10+ 本) → data/master-definitions/ へ移動
  • docs/spec/data_def_*.md(データ定義 5+ 本) → data/data-definitions/ へ移動
  • docs/test/*(テスト 10+ 本) → operations/testing/ へ移動
  • 外部リンク棚卸: ADR-0023 時の調査で PR description 内参照 269 件を確認済。dev_mas-NNN への直接参照は legacy-dev/ 移動後も git 追跡可能(git log --follow)

運用上の罠(詳細)

  • 複数機能を跨ぐ仕様の置き場所: _shared/ ディレクトリを domains/ 配下に設け、横断仕様はそこに集約する
  • legacy_id 衝突: 同一機能の dev_mas-NNN が複数存在する場合(例: 改訂版が別連番で存在)、frontmatter に legacy_id: [dev_mas-042, dev_mas-067] と配列で記録する
  • status 陳腐化: 月次レビューで status: deprecated になっていない active ファイルを adr-lint.mjs の --check-frontmatter で検出する
  • 新旧混在期の参照ミス: AGENTS.md に「docs/dev/ docs/spec/ docs/arch/ への新規ファイル作成禁止」を明記し、Claude Code が誤ったディレクトリに作成するのを防ぐ

移行完了条件(独立定義)

以下の全てを満たした時点を「移行完了」とする(撤退条件と独立して定義):

  1. docs/dev/ が空、または全ファイルが legacy-dev/ に移動済み
  2. docs/arch/ に ref_*.md(外部調査)が存在しない
  3. domains/ に月次決算・予実管理・資金繰り・マスタデータの 4 機能の current-spec.md が存在する
  4. lychee・markdownlint・frontmatter linter が CI で全件パス
  5. _nav/traceability.md に 5 機能以上の要件→spec→ADR リンクが記載されている

影響 (Consequences)

5.1 正の影響 (Good)

  • Claude Code のドキュメント探索ツール呼び出しが現状平均 7.4 回から目標平均 2 回以内に削減され、機能あたりの自律実装速度が向上する
  • frontmatter の type / status / legacy_id により AI が機械判別でき、設計文書と外部調査メモの誤参照リスクが解消される
  • operations/itgc/ に J-SOX 証跡(ITGC 4 領域)を常設することで監査人への提示構造が事前に整備される
  • arc42 章構造に既存 PRD/BRD/FRD/ADR がそのままマッピングでき、Jr エンジニア(D-180 入社)のオンボーディングが構造化される
  • 既存 dev_mas-NNN.md の連番・git blame・PR description 269 件の外部リンクが legacy-dev/ 移動後も git log --follow で追跡可能

5.2 負の影響 (Bad)

  • 総工数 80〜128 h(約 6〜10 週、業務並行)が必要で、その間は新旧構造が混在する
  • arc42 章構造と feature-folder の 2 軸構造は初見で分かりにくく、Jr エンジニアおよび Claude Code の学習コストが発生する(AGENTS.md で緩和)
  • frontmatter 必須化により新規ファイル作成時に YAML 記述の手間が増える(テンプレートで緩和)
  • Phase 3(domains/ 抽出)を完遂しないと legacy-dev/ が事実上の現行仕様置き場として永続化する長期負債化リスクがある
  • frontmatter linter の誤検知(false positive)で開発フローが阻害される可能性があり、Phase 4-b のチューニング工数を要する

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

  • SSG は自作 docs-build.mjs + Cloudflare Pages を維持し、Docusaurus/MkDocs 等への乗り換えは行わない(ROI 不足のため将来再評価)
  • _shared/ ディレクトリで横断仕様を吸収するが、どこまでを「横断」とみなすかは運用で判断する必要がある
  • 既存 150+ ファイルを一括リネームしないため、新旧の命名規則が永続的に共存する

撤退条件 (Rollback Plan)

Phase 別撤退条件(数値化)

  • Phase 2 撤退: lychee で内部リンク切れが移行前比 10 件/週を超えて 2 週連続増加した場合
  • Phase 3 撤退: 2026-08-31 時点で domains/ 配下の current-spec.md が 2 ファイル未満(優先 5 機能の 40% 未満)の場合、または移行済み機能の Claude Code ツール呼び出し回数が 平均 5 回以上のまま改善なしの場合
  • Phase 4 撤退: frontmatter linter の誤検知率(false positive)が PR あたり 3 件超 が 3 週連続した場合はルール縮退(必須キー削減)

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

Phase 3 中間ロールバック手順(抽出済みファイルが存在する場合)

Phase 3 撤退判定が発動した時点で domains/ に一部 current-spec.md が存在する場合は以下の順で差し戻す:

  1. git mv domains/<feature>/current-spec.md implementation/legacy-dev/<feature>-current-spec.md で legacy-dev/ へ移動
  2. 移動先ファイルの frontmatter を status: active(legacy-dev/ での現行仕様扱い)に戻し、legacy_id: 行は保持
  3. 元の legacy-dev/dev_mas-NNN.md に付与した status: superseded を status: active に戻す
  4. domains/<feature>/ ディレクトリが空になったら削除(git rm -r)
  5. AGENTS.md の「新規ファイルを domains/ 以外に作らない」制約を legacy-dev/ 経由アクセス許可に緩和
  6. _nav/traceability.md の該当機能行のリンクを legacy-dev/ パスに更新

各ステップは独立した git commit で実施し、1 機能単位でロールバック可能にする(全機能一括 revert 禁止)。

Review After

Review After: 2027-02-14(起案から 9 ヶ月後): 新構造全体の再評価。Claude Code ツール呼び出し削減効果・frontmatter 陳腐化率・Jr エンジニアのナビゲーション実態を総合評価し、必要なら新 ADR で Supersede する。

6.5 Confirmation (準拠確認 / Fitness Function)

本 ADR の決定が実装で守られているかを以下 3 種の fitness function で継続検証する。

  1. 検証手段:

    • scripts/adr-lint.mjs --check-frontmatter: 全 docs 配下 .md の frontmatter に id / type / status / related / legacy_id 必須キーと値域(type ∈ {spec, adr, research, itgc, ...}、status ∈ {active, deprecated, superseded})が存在するかを検証
    • scripts/adr-lint.mjs --check-legacy-dirs: docs/dev/ docs/arch/ docs/spec/ への新規ファイル作成を git diff 経由で検出しエラー化
    • scripts/adr-lint.mjs --count-domains: domains/*/current-spec.md の存在ファイル数を集計し、移行完了条件 3(優先 4 機能の current-spec.md 存在)の進捗を可視化
    • lychee + markdownlint: 内部リンク切れ・Markdown 構文を CI で全件チェック(既存設定流用)
    • AI ツール呼び出し計測: count-doc-tool-calls.sh を Phase 1 完了後・Phase 3 完了後に同一 15 サンプルで再実行(目標: 平均 2 回以内)

  2. 実行頻度:

    • adr-lint.mjs 3 サブコマンド + lychee + markdownlint: PR ごとに CI で自動実行(GitHub Actions)
    • 月次レビュー: status: deprecated 化されていない陳腐化候補の手動レビュー(毎月第 1 月曜)
    • ツール呼び出し計測: Phase 1 完了時・Phase 3 完了時の 2 回、および Review After (2027-02-14) の総合評価時

  3. 違反時の対応:

    • CI 失敗 → PR マージ不可。起案者が frontmatter 補完または legacy-dirs 違反ファイルを正規ディレクトリへ移動して再 push
    • frontmatter linter の誤検知率が PR あたり 3 件超 × 3 週連続 → Phase 4 撤退条件発動、必須キー縮退を新 PR で実施
    • ツール呼び出し計測で目標未達(平均 5 回以上) → Phase 3 撤退条件発動、中間ロールバック手順に従い差し戻し
    • 月次レビューで陳腐化候補が放置された場合 → 起案者が status: deprecated 付与または該当ファイル削除

参照 (References)

  • 関連 ADR:
    • ADR-0000(ADR を記録する) — 整合
    • ADR-0023(ADR 構造業界標準化・MADR 採用) — 延長・整合
    • ADR-0019(Decision Pipeline LangGraph 移行) — 影響なし
    • ADR-0030(Kruchten 3 分類) — 遵守
    • ADR-0036(Confirmation セクション必須) — 遵守
  • 関連 PR/Issue: (要追記)
  • 外部資料:
    • arc42 Documentation Template (https://arc42.org/)
    • C4 Model (https://c4model.com/)
    • MADR (Markdown Any Decision Records)
    • Diátaxis Framework (Cloudflare / Canonical 採用事例)
    • Google g3doc スタイル
    • 経産省「システム管理基準追補版 R6.12 改訂」(ITGC 4 領域)