AGENTS.md — Claude Code ナビゲーションガイド

このファイルを最初に読んでください。 Claude Code が docs/ を探索する際の出発点です。 人間が GitHub で閲覧する場合は README.md から開始してください。

ディレクトリマップ（クイックリファレンス）

docs/
├── AGENTS.md               ← このファイル（AI エージェント向け入口、必ず先に読む）
├── README.md               ← 人間向けエントリポイント（GitHub ブラウジング用）
├── index.md                ← docs サイト landing（公開サイトの "/"）
├── SUMMARY.md              ← コーポレート社内サイトの入口（事業軸ガイド・各領域へ誘導）
├── COVERAGE_GAPS.md        ← handover 残タスク一覧（tasks/prompts から自動生成・手書き禁止 / ADR-0145）
│
├── _config.json            ← サイドバー nav SSOT（ビルド時にサイト構造を決定）
├── _meta/                  ← frontmatter テンプレート（新規ファイル作成時に使う）
│   └── templates/          ← spec / research / itgc / current-spec / adr テンプレ
├── _nav/                   ← ナビゲーション補助
│   └── traceability.md     ← 機能 → 仕様 → ADR → テスト のトレーサビリティマップ
├── research/               ← テンプレート型の 3-vendor ベストプラクティス調査（ADR-0041）
│
├── architecture/           ← arc42 章構造（システム全体の設計文書、PRD/BRD/NFR/横断仕様含む）
├── domains/                ← feature-folder（機能別の現行仕様）
│   ├── _shared/            ← 複数機能を跨ぐ横断仕様
│   ├── monthly-close/      ← 月次決算（B/S・P/L・CF・STL）
│   ├── budget-actual/      ← 予実管理（計画・差異分析）
│   ├── cash-flow/          ← 資金繰り予測（Daily CF・パイプライン）
│   ├── master-data/        ← マスタデータ管理
│   ├── bank-reconciliation/← 銀行照合（CC 取込・コンボマッチング）
│   ├── rpa-automation/     ← RPA 自動起票（HC/SaaS/Capex/Finance/Pipeline/Adhoc）
│   ├── order-management/   ← 受発注管理（ORD）
│   ├── project-accounting/ ← プロジェクト別管理会計
│   ├── data-ingest/        ← データ取込（レシート・OCR）
│   └── corporate-tax/      ← 法人税・税効果
│
├── data/
│   ├── master-definitions/ ← マスタ定義書（mst_*.md）
│   └── data-definitions/   ← データ定義書（data_def_*.md）
│
├── operations/
│   ├── itgc/               ← J-SOX 証跡（ITGC 4 領域: アクセス/変更/運用/開発保守）
│   └── testing/            ← テスト手順・テストデータ
│
├── implementation/
│   └── legacy-dev/         ← 凍結退避済み旧仕様書（dev_mas-NNN.md、160 本、読み取り専用）
│
├── adr/                    ← アーキテクチャ決定記録（55+ ADR、ADR-0023 で 4 桁ハイフン規約、ADR-0055 で nav prefix 規約）
│   ├── README.md           ← 運用ガイド + ADR 一覧
│   ├── templates/          ← ADR 起案テンプレート
│   └── 0000〜00NN-*.md     ← 個別 ADR
│
└── _internal/              ← 社内向け運用ドキュメント（ADR-0045 管轄、サイドバー I.NN.*）
    ├── biz/                ← I.00.* ビジネスコンテキスト（経費規程・稟議書テンプレ等）
    ├── 01_discovery/       ← I.01.* 調査・RQ（研究結果 + research_prompts/）
    │   └── research_prompts/  ← RQ-001〜049 の生プロンプト・モデル別結果・synthesis
    ├── 02_project/         ← I.02.* バックログ・追跡（TODO_future.md, BUG_tracking.md）
    │   └── daily_log/      ← 週次作業ログ
    ├── 03_decisions/       ← I.03.* 意思決定パイプライン（adr_reviews/ + decision_pipeline/）
    ├── 04_specs/           ← I.04.* 仕様テンプレート（dev_spec_prompt_template 等）
    ├── 05_how-to/          ← I.05.* 手順書・ワークフロー（git_workflow, workspace_rules, writing-guide, adr-lint_rules 等）
    └── 06_ops/             ← 運用・障害対応・変更履歴・学び（nav 上は索引系=M / 運用ノウハウ=O.03 に配置・namespace I の group は持たない）

サイドバーは ADR-0055 で確立した <NS>.<group_number>.<page_index> 形式（NS 接頭辞: A=arc42 / I=internal / O=ops / M=meta）で機械整合する。例: A.01.1 = arc42.01 group の 1 ページ目、I.05.11 = internal.05 group の 11 ページ目。

機能仕様を探す（最重要）

機能の現行仕様 を参照する場合は必ず domains/<feature>/current-spec.md を最初に確認してください。

# 例: 月次決算の仕様を探す
cat docs/domains/monthly-close/current-spec.md

# 例: 銀行照合の仕様を探す
cat docs/domains/bank-reconciliation/current-spec.md

5 機能（monthly-close / budget-actual / cash-flow / master-data / bank-reconciliation）は スケルトン段階の current-spec.md が存在。詳細は同ファイル内の「詳細資料」セクションから implementation/legacy-dev/dev_mas-NNN.md を辿る。

新規 5 ドメイン（rpa-automation / order-management / project-accounting / data-ingest / corporate-tax）は README.md のみ。current-spec.md は必要時に作成。

設計文書を探す

新規ファイル作成ルール（必須）

廃止された旧ディレクトリ

以下のディレクトリは 物理的に廃止済み です。誤って参照しないでください:

• docs/dev/ → 廃止（中身は全て implementation/legacy-dev/ へ凍結退避済）
• docs/arch/ → 廃止（中身は architecture/ と _internal/01_discovery/ へ振り分け済）
• docs/master/ → 廃止（中身は data/master-definitions/ へ移動済）
• docs/test/ → 廃止（中身は operations/testing/ へ移動済）
• docs/research/ → ADR-0041 で復活。テンプレート型の 3-vendor 調査を格納

なお docs/spec/ には sidebar_api.d.ts（TypeScript 定義）のみ残置。md ファイルは すべて domains/<feature>/ や architecture/ へ振り分け済。

正しい作成先

frontmatter 必須（全 .md ファイル共通）

すべての新規 .md ファイルに以下の frontmatter を付けてください:

---
id: <一意のID（例: spec-monthly-close-v1）>
type: <spec | adr | research | itgc | ops | how-to | tracking | workflow | runbook | policy | prompt | setup | data>
status: <active | deprecated | superseded | draft>
related:
  - <関連ファイルのパス or ADR番号>
legacy_id: <旧 dev_mas-NNN.md の番号、または旧パス（移行元がある場合のみ）>
---

例外（frontmatter 不要、ADR-0048 で規定）:

• README.md / SUMMARY.md / COVERAGE_GAPS.md / MEMORY.md

テンプレートは _meta/templates/ を参照。CI で adr-lint --check-frontmatter が公開構造（architecture/・domains/・data/・operations/・_meta/・_nav/）配下の 全 md を検証します。

型ファーストプロセス（ADR-0041）

新規ドキュメント作成時は必ず _meta/templates/<type>.md の存在を確認してください。

1. テンプレート確認: frontmatter の type に対応する _meta/templates/<type>.md が存在するか確認
2. テンプレート不在時: 新しい type を定義する場合は 3-vendor 調査 (Claude/Gemini/GPT) を実施し research/rq-NNN-<topic>.md に記録してからテンプレートを作成
3. experimental 型: テンプレートが未確定の場合は空テンプレートを仮配置し 4 週間以内に正式化。超過時は削除
4. API 障害時フォールバック: 3-vendor 調査が実行できない場合は arc42 公式 または Anthropic 公式ドキュメント を手動参照し根拠を記録

CI: adr-lint.mjs --check-template-exists が type フィールドとテンプレートの整合を検証（DOC-OPS-09 / PR #997 で実装済）。

traceability（要件→仕様→ADR→テストの追跡）

_nav/traceability.md を参照してください。5 機能ごとに以下の情報が記載されています:

• 対応する domains/<feature>/current-spec.md のパス
• 元になった legacy_id（旧 dev_mas-NNN）
• 関連 ADR
• テスト手順へのリンク

ナビゲーション例

「月次決算の仕訳エンジンを修正したい」
→ 1. docs/domains/monthly-close/current-spec.md を読む
→ 2. 関連 ADR: adr/0014-invoice-status-transition.md, adr/0017-bank-datamart-filter-condition.md
→ 3. テストは operations/testing/02_integration_test.md

「銀行照合の消込ロジックを確認したい」
→ 1. docs/domains/bank-reconciliation/current-spec.md を読む
→ 2. 関連: domains/bank-reconciliation/spec_cc_import.md
→ 3. 詳細は implementation/legacy-dev/dev_mas-145_bank_csv_import.md など

「過去の意思決定の背景を知りたい」
→ 1. docs/adr/README.md で全 ADR 一覧を確認
→ 2. 該当 ADR を読む
→ 3. 起案前の調査は _internal/01_discovery/research_prompts/RQ-NNN_* を参照

「未文書化の領域があるか確認」
→ docs/_internal/02_project/TODO_future.md（known-unknowns の移送先 / ADR-0145・ADR-0048 改訂）

「セッションをまたぐ残タスクを俯瞰したい」
→ docs/COVERAGE_GAPS.md（handover 残タスク一覧・自動生成）

「内部の運用手順を探す」
→ _internal/05_how-to/（git_workflow.md, workspace_rules.md, writing-guide.md 等）

「過去の障害事例を知りたい」
→ _internal/06_ops/failure_patterns.md