ドキュメント記述ルール（Writing Guide）

このリポジトリの docs/ 配下に新規ファイルを作成する際に守るルールを定めます。 Claude Code・人間の両方が迷わず書けることを目的とします。

1. ファイル共通ルール

2. 見出しルール

2.1 レベル定義

2.2 項番ルール

• H2 は ## N. 形式（## 1. ## 2. ...）
• H3 は ### N.M 形式（### 1.1 ### 1.2 ...）
• H4 以下は項番不要
• セクションを削除・追加しても他の番号を振り直さない（参照リンクが壊れるため）

# ページタイトル

## 1. 概要
## 2. スコープ
### 2.1 含む
### 2.2 含まない
## 3. 処理フロー

3. 本文記述ルール

3.1 文体

3.2 情報密度

• 概要セクションは 3 行以内（Claude Code が最初に読む）
• 詳細は H3 以下または detail/ サブディレクトリに分離する
• 「なぜ」が非自明な場合のみコメントを書く（CLAUDE.md コーディング規約と同じ方針）

3.3 テーブル

データ・仕様・一覧は原則テーブルで表現する:

| フィールド名 | 型 | 説明 | 制約 |
|---|---|---|---|
| invoice_id | string | INV ID（SSOT） | NOT NULL |

3.4 コードブロック

言語を必ず指定する:

\`\`\`javascript
// GAS コード
\`\`\`

\`\`\`bash
# シェルコマンド
\`\`\`

\`\`\`
# 言語不明な場合は空（markdown として扱われない）
\`\`\`

3.5 リンク

<!-- 同リポジトリ内：相対パス・.md 拡張子を使う -->
[銀行照合仕様](../../domains/bank-reconciliation/current-spec.md)

<!-- 外部リンク：絶対 URL -->
[arc42](https://arc42.org/)

<!-- ADR への参照 -->
[ADR-0039](../../adr/0039-adopt-arc42-c4-madr-feature-folder-for-document-structure.md)

3.6 用語: 3 階層分類と原語温存・初出グロス (ADR-0105)

専門語は 3 階層に分け、噛み砕く対象を Tier 1/2 に限定する。Tier 0 は崩さない・Tier 1/2 は原語を残して初出グロスを足すのが原則:

ルール:

• 原語温存: Tier 1/2 の専門語・略語・固有名詞は日本語に置換しない (LLM の意味解像度・glossary 突合・コード参照を保つため)。地の文 (説明) は日本語で書く。
• 初出グロス記法: 原語〔和訳＝一句〕。例: SSoT〔Single Source of Truth＝唯一の正データ〕 / DLQ〔Dead Letter Queue＝処理失敗メッセージの退避先〕。全角 （） も可。同一文書で初出 1 回のみ。
• 冒頭エレベーターピッチ（旧称 TL;DR）: 主要ページは、冒頭に業界用語なしの要約を置く。ADR 本文はこの方式でなく「決定の早わかり」に一本化済み（ADR-0138 で必須化・ADR-0139 で旧 TL;DR 箇条を廃止）。書式: セクション見出し ## エレベーターピッチ（括弧補足は付けない）の直下に引用ブロック >（サイト上で枠表示される）を置き、中身は問いラベルの箇条書き 5 行（- **ラベル**　: 本文・最長ラベル幅まで全角スペースを足して「:」を縦に揃える・各 1 文）: ①これは何？（ページ/仕組みの正体を一言。唐突感の防止）→ ②だれのため？ → ③なにが起きる？（時系列は → の一行フローで。機能やゲートの列挙はしない）→ ④譲れない一線（一番誤解されたくないこと）→ ⑤だから（読み手への約束）。語りかけのため、ここのみ「です・ます」可。模範例: docs/_internal/03_decisions/decision_pipeline/README.md 冒頭。既存の「TL;DR（このページは何か・専門語ゼロ）」表記は grandfather（そのページを触るときに順次改名）。
• 用語定義の SSoT: docs/architecture/glossary.md。新語はまず glossary に追加する。
• 検証: node scripts/adr-lint.mjs --check-terminology docs/adr/ で glossary 未登録 + 初出グロスなしの略語を warn 検出 (filenum ≥ 105 限定・warn のみ)。

4. current-spec.md 固有ルール

domains/<feature>/current-spec.md に固有の記述基準:

5. research.md 固有ルール

6. itgc.md 固有ルール

7. システム概要ページ（README / landing）固有ルール (ADR-0114 / ADR-0128)

システム・パイプライン・機能ドメインの全体像を説明する概要ページの冒頭構造を定める。正規形（模範例）は docs/_internal/03_decisions/decision_pipeline/README.md の §1-§2。サイト入口の 2 階層 landing 構造（L0 全社ポータル → L1 各軸入口） と新類型 Tier P は §7.3 を参照。

本則の階層: 本セクションのうち「§1§2 の形式・Tier A 必須 7 ページ・Tier 判定基準・Tier B 禁止条項・Tier A 上限 10 ページ・Tier P 定義と L0/L1 landing 階層（ADR-0128）」は核心決定（変更には ADR 改訂が必要。Tier B 禁止条項は緩和不可・強化のみ可）。状態 Enum の更新トリガー詳細・staleness 検知の閾値・棚卸しサイクル運用・検証手順詳細は実施細則（本ページ単独で調整可）。

7.1 冒頭構造（§1 基本情報 → §2 エレベーターピッチ・順序固定）

• §1 基本情報: H1 直下に ## 1. 基本情報。引用ブロック > 形式・- **ラベル**　: 値（コロン縦揃え）。
  • 必須 4 項目: 状態 / コード（コード位置）/ 基盤決定（よりどころの ADR リンク）/ 変更履歴（GitHub commits リンク）
  • 任意 3 項目: 英語名 / 本番（本番 URL）/ ドメインオーナー（状態フィールド更新の責任者）
  • 状態は Enum 5 値で固定: Planned / Development / Production / Deprecated / Archived
  • 状態の更新トリガー（実施細則）: 本番リリース・非推奨化・退役・アーカイブの各イベント時に変更を入れた PR と同一 PR で更新 + 半年毎の Tier 棚卸しで検認。自動検知は 実装済み (2026-06-04): scripts/tier-a-header-lint.mjs が「状態 = Production かつ最終 commit が 183 日以上前」で CI 警告 (T1)、あわせて Tier A の部分ビルド HTML に必須 4 項目の存在をアサート (T2 = ADR-0114 §決定 5 のスモークテスト)。docs-nav-lint workflow で毎 PR 実行。
• §2 エレベーターピッチ: ## 2. エレベーターピッチ。書式は §3.6 の問いラベル 5 行形式。
• 順序は §1 基本情報 → §2 ピッチで固定（模範例と一致させ移行コストを抑える。順序の実証比較は ADR-0114 Confirmation のウォークスルーで記録）。
• 免責: 冒頭ブロック（基本情報・エレベーターピッチ）は内部開発ドキュメントの理解導入であり、監査証跡・法令対応の正式記述ではない。会計業務ドメインの README に展開する際も、電帳法等の訂正削除履歴要件を担う文書としては扱わない。
• 会計業務ドメイン（corporate-tax / project-accounting）の追加注記（必須）: ファクトボックス直下に 1 行注記を置く — 「※本ブロックは開発理解導入用であり、法務・監査対応の正式記録ではない（正式記録は該当の運用文書を参照）」。なお両ドメインへの展開は、顧問税理士または法務担当者から「ファクトボックスが電帳法・会計指針上の記録文書に該当しない」旨の見解取得が前提条件（取得困難な場合は変更履歴フィールドの除外または別ファイル分離に設計変更。ADR-0114 §決定 1）。

7.2 適用範囲（3 Tier・完全リスト）

• Tier A 必須（7 ページ・上限 10 ページ）: §1 基本情報 + §2 ピッチの両方を冒頭に持つ。
  1. _internal/03_decisions/decision_pipeline/README.md（準拠済・模範）
  2. domains/corporate-tax/README.md ※税理士見解取得まで適用保留
  3. domains/data-ingest/README.md
  4. domains/order-management/README.md
  5. domains/project-accounting/README.md ※税理士見解取得まで適用保留
  6. domains/rpa-automation/README.md
  7. architecture/product_overview.md
• Tier A 判定基準: (a) 単一のシステム・パイプライン・機能ドメインの全体像を説明する landing、または複数ドメインをまたぐ製品全体 landing である、かつ (b) 対応する実装（コード位置）が存在する。判定プロセス: ページ作成 PR のレビュー時にレビュアーが Tier 判定をコメントで明示し、Tier A 該当なら同一 PR で本リストを更新する。
• Tier B ピッチのみ任意（完全リスト 15 ページ・「等」を使わない）: docs/README.md、adr/README.md、architecture/README.md、data/README.md、data/data-definitions/README.md、data/master-definitions/README.md、domains/README.md、domains/_shared/README.md、implementation/README.md、implementation/legacy-dev/README.md、operations/README.md、operations/itgc/README.md、operations/testing/README.md、_internal/01_discovery/research_prompts/README.md、_internal/biz/README.md。ナビゲーション目的の TOC ページにファクトボックスは不適用。
  • 運用禁止条項（核心決定）: レビュアーは Tier B ページのピッチ不在を理由に差し戻してはならない（任意規約の解釈分裂による差し戻し増加を防ぐ）。
• Tier C 適用外: spec_*.md（spec 型「基本情報」は別物 — 関数仕様テーブル。guidelines_spec_template.md 準拠で共存）、データ定義リファレンス本体、ADR 本体、RQ 調査結果（TL;DR grandfather 維持）、index.md（flat TOC）、_meta / _nav。SUMMARY.md は Tier C から外し Tier P（§7.3・ADR-0128）へ移した（全社の顔 = L0 ポータルの役割を担うため）。
• Tier 分類の棚卸しは半年毎（担当者明記の issue テンプレートから起票・カレンダー登録と組）。次回 Review After: 2026-12 月初（ADR-0114）。テンプレ整備済 (2026-06-18): .github/ISSUE_TEMPLATE/tier-inventory.md（手動起票可・cron 自動起票は main 領分で実装予定）。

7.3 Tier P（ポータル landing）と L0/L1 landing 階層 (ADR-0128)

サイトは「管理会計ERP 単体ドキュメント」から BizLP コーポレート社内サイト（事業軸 Corp / MAS / DRP） へ再ポジショニングされた。入口を 2 階層の landing 構造として規約化し、コードを持たない landing にシステム前提のファクトボックス（§7.1）を誤適用しないために新類型 Tier P を設ける。ADR-0114 を Refine（核心は温存・Supersede ではない）。

L0 / L1 landing 階層:

• L0 = 全社ポータル: SUMMARY.md。全 3 軸を横断する「全社の顔」。Tier P。
• L1 = 各軸入口: 軸ごとの概要/入口ページ。コードを持つ軸（MAS / DRP）= Tier A、持たない軸（Corp）= Tier P。
  • MAS: architecture/product_overview.md（Tier A）
  • DRP: _internal/03_decisions/decision_pipeline/README.md（Tier A・模範）
  • Corp: corp/README.md（Tier P・稼働中）

Tier P（ポータル landing）の必須形式:

• H1 直下に 軽量ヘッダー（引用ブロック >・コロン縦揃え）。必須 4 項目: 運営（運営主体）/ 対象（読者）/ 更新ポリシー（更新の頻度・契機）/ 索引リンク（全ページ一覧 = index.md への導線）。
• 続けて エレベーターピッチ（§3.6 の問いラベル 5 行形式）。
• システム前提のファクトボックス（状態 / コード / 基盤決定 / 変更履歴）は課さない（ポータルには実装コードや状態 Enum が無く形骸化するため）。tier-a-header-lint.mjs の必須 4 項目（REQUIRED_LABELS）は Tier P に適用せず、Tier P 専用検査（運営/対象/更新ポリシー/索引リンク）を別途行う。

Tier 判定基準の軸分岐:

• 「コードを持つ」の境界定義: リポジトリ上に実行可能な成果物（スクリプト / アプリ / Worker）が存在し CI でアサート可能な軸を「コードを持つ」とする。単なる仕様文書・調査記録のみの軸はコードを持たない。
• Tier P → Tier A 格上げトリガー: コードを持たない軸（Tier P）に後から実行可能な成果物が生まれ CI アサート可能になった時点で、当該軸の L1 入口を Tier A へ格上げし §7.2 Tier A リスト + tier-a-header-lint.mjs の TIER_A 配列へ追加する。

flowchart TD
    P["概要/入口ページ"] --> Q1{"ナビ専用 TOC か？
(index / _meta / _nav)"}
    Q1 -->|Yes| C["Tier C（適用外）"]
    Q1 -->|No| Q2{"対応する実行可能コードが
リポジトリにあり CI で
アサート可能か？"}
    Q2 -->|Yes| A["Tier A
（§1 基本情報 + §2 ピッチ）"]
    Q2 -->|No| PP["Tier P
（軽量ヘッダー + ピッチ）"]

判定プロセス: ページ作成 PR のレビュー時にレビュアーが本フローチャートで Tier を判定しコメントで明示する。Tier A / Tier P 該当なら同一 PR で §7.2 リストまたは Tier P 対象を更新する。Tier 4 分類（A/B/C/P）の判定で例外が 5 件を超えたら分類設計を見直す（ADR-0128 撤退条件）。

8. 禁止事項

• 個人名 (例: 達希) をドキュメント・コメントに書かない (代表取締役指示 2026-06-04)。職位が適切な箇所 (指示・判断・観測・レビューの主体) は「代表取締役」、アカウントが適切な箇所 (起案者・Deciders・owner・author 等のメタデータ欄) はログイン中のアドレス [email protected] を使う。例外: 実データの値を説明する記述 (銀行摘要・振込先名など実在文字列の引用) は実データと一致させる
• 「TODO」「後で書く」「TBD」を本文に残したままコミット（frontmatter の status: active と矛盾）
• 200 行を超えるファイルを 1 ファイルに詰め込む（detail/ に分割すること）
• docs/dev/ docs/arch/ docs/spec/ への新規ファイル作成（AGENTS.md 参照）
• 列番号のハードコード（data[3] 等）をデータ仕様テーブルに記載することは禁止ではないが、実装コードでは禁止