ドキュメント標準

配置先の決定

docs/ 直下に新規ファイルを作らない（README.md と各サブディレクトリのみ）。

audience による分岐

同じ機能でも、想定読者によって配置先と書き方が異なる:

両方が必要な機能では、両方のディレクトリに作成し相互参照リンクを置く。

顧客向け資料での開発用語禁止例

迷ったら「読み手が IT 部門ではない現場担当者」と仮定し、技術用語を平易な業務用語に置き換える。判断に迷う用語が出たら人間に確認する。

命名規則

ファイル名・ディレクトリ名

• kebab-case 必須（例: api-specification.md, transfer-instruction/）
• 拡張子は .md のみ（.markdown 禁止）
• 日本語ファイル名禁止
• 日付を含む場合は ISO 8601 形式を先頭: 2026-05-08-{内容}.md

ADR 専用ルール

• ファイル名: {4桁連番}-{kebab-case-title}.md（ファイル名は英語 kebab-case で統一。本文タイトル・内容はプロジェクトの言語で書いてよい）
• 例: 0001-adopt-feature-flags.md, 0042-introduce-event-sourcing.md
• 連番は配置先ディレクトリ（docs/adr/ または knowledge/D19/）内の最大値+1（既存を確認してから採番）
• 配置先・フォーマット・ステータス値・作成手順は「## ADR（Architecture Decision Record）」を参照

リリースノート専用ルール

• ファイル名: {ISO日付}.md（例: 2026-05-08.md）
• バージョン番号運用をしないプロジェクト向け。SemVer 等を採用しているなら v1.2.3.md 形式に変えて運用する

禁止する命名

• temp.md, tmp.md, new_*.md, *-old.md, *-backup.md（残骸化）
• untitled.md, memo.md（内容を表さない）
• snake_case.md（例: api_specification.md）
• 末尾に日付のみ（spec_20260508.md）

ADR（Architecture Decision Record）

設計上の意思決定を MADR 形式で記録する。ファイル名・採番は「命名規則 → ADR 専用ルール」に従う。

配置先

• 複数リポジトリに跨る共通ポリシー → 共通ポリシー用の中央リポジトリの docs/adr/
• 特定リポジトリのみに適用 → そのリポジトリの docs/adr/
• knowledge 運用（D01〜D21 の文書クラス）を導入したリポジトリ → knowledge/D19/ （ADR は D19「ソフトウェアアーキテクチャ・ADR パック」に属するため。索引は knowledge/D19-*.md）

いずれの配置先でも様式（MADR の章立て・ファイル名・採番・ステータス値）は本標準に従う。

ステータスの値

テンプレート

# [タイトル]

## ステータス

[Proposed | Accepted | Deprecated | Superseded by {4桁連番}-{kebab-case-title} | Partially superseded by {4桁連番}-{kebab-case-title}] — YYYY-MM-DD

## 背景と課題

問題の背景と、解決すべき問いを記載する。

## 意思決定の要因

- 意思決定に影響する制約・要件

## 検討した選択肢

- 選択肢1
- 選択肢2

## 決定内容

選択した選択肢: **選択肢名**、採用理由を記載。

### 結果（Consequences）

- 良い結果: 採用により得られる利点・解消される課題
- 悪い結果: 採用に伴うコスト・新たに生じる制約やリスク

## 選択肢の評価（Pros and Cons）

### 選択肢1

選択肢の概要説明。

#### メリット

- ...

#### デメリット

- ...

### 選択肢2

選択肢の概要説明。

#### メリット

- ...

#### デメリット

- ...

## 関連リンク

- Extends: [{4桁連番}-{kebab-case-title}](リンク)
- Supersedes: [{4桁連番}-{kebab-case-title}](リンク)
- Related: [チケット等](リンク)

作成手順

1. 配置先ディレクトリ（docs/adr/ または knowledge/D19/）内の既存 ADR を確認して次の連番を決定する（命名規則を参照）
2. 上記テンプレートでファイルを作成する。ステータス行は表の値から1つ選んで角括弧とパイプを外し、日付は date +%Y-%m-%d で確定した値を入れる（学習データの日付に頼らない）。Superseded by {4桁連番}-{kebab-case-title} を選んだ場合はプレースホルダを置き換えた ADR の実 ID に置換する
3. 既存 ADR を置き換える場合は双方向に更新する。新 ADR の「関連リンク」に Supersedes: を記載し、かつ旧 ADR のステータスを Superseded by {新 ADR の ID} に更新する（片側更新漏れを防ぐ）
4. 一覧表に追記する（存在する場合）。docs/adr/README.md、knowledge 運用なら knowledge/D19-*.md の ADR 索引

内容ルール

技術情報の最新性

• 「最新版」ではなく具体的なバージョン番号を記載
• 確認日時を本文冒頭に明記（例: > 確認日: 2026-05-08）
• 公式サイトでの確認を経てから記載
• 読者向けに「最新情報を別途確認すること」の注意書きを追加

重複の禁止

• 同じ内容を別ファイルに重複させない
• 該当機能の仕様書が docs/features/{機能名}/ に既にあるなら、 そこに追記するか参照する。再調査・再記述しない

README.md の役割

• 各サブディレクトリの最初に読まれるべきインデックス
• そのディレクトリの目的、主要ファイルへの導線、関連リンクを提供
• 機能ディレクトリの README.md は 1 ページサマリー的な内容にする

顧客向け資料の PDF 生成

docs/business/ 配下のドキュメントは、編集後に PDF を生成して配布する。

生成手順

/pdf skill を使用する。代表的なトリガー:

• 「<file>.md の PDF を再生成して」
• 「docs/business/ 配下の資料を最新化して」

詳細手順は ~/.claude/skills/pdf/SKILL.md を参照。

drawio 図が含まれる場合

drawio 図が更新されているなら PDF 生成の前に ~/.claude/hooks/run-drawio-export.sh で SVG を最新化する。

制約

• PDF はローカル保存されるが git には含めない（docs/**/*.pdf を .gitignore 推奨）

配布先（任意）

Google Drive 等のドラフト管理サービスへ自動同期したい場合は、自プロジェクト 側で skill を追加し、本 skill から呼び出す形にする（pdf-gdrive-sync の ような skill を独自に作る運用が想定される）。

一時ファイルの扱い

ユーザーから一時的に渡されたファイル（CSV、ログ、画像、参考資料等）は inbox/ （リポジトリルート、git 管理外）から読む。

処理後の選択肢:

1. 不要なら削除
2. 永続化が必要なら docs/ の適切なサブディレクトリへ kebab-case 命名で移動
3. 顧客フィードバック等の参照価値があるなら docs/features/{機能名}/{ISO日付}-{内容}.md で保存

docs/temp/ は使用しない（廃止済み）。