Documentation

ドキュメンテーション

目的

「コードで分からないこと」を伝える。実装の背景・設計判断の理由・制約・運用手順など、コードを読んでも分からない情報を文書化し、チームの認知負荷を下げる。コードで分かることは書かない。

使うタイミング

• 新機能・新サービスを作ったのにREADMEが追いついていない
• 新規参加者がセットアップに詰まっている
• エージェントがプロジェクト固有の規約を把握できていない(CLAUDE.md未整備)
• 設計判断の理由が誰も分からなくなっている(ADR未記録)
• 障害対応手順が口頭伝承になっている
• 四半期棚卸しで陳腐化した文書を発見した

ドキュメントの種類と置き場所

種類	対象読者	置き場所	更新タイミング	関連スキル
README	新規参加者・外部利用者	リポジトリルート	機能追加・破壊的変更時	—
CLAUDE.md	AIエージェント	リポジトリルート・各サブディレクトリ	規約・コマンド変更時	—
ADR(Architecture Decision Record)	設計者・将来の自分	docs/adr/	重要な設計判断時	[[architecture-design]]
API文書	API利用者	docs/api/ またはスキーマから自動生成	スキーマ変更時	[[api-design]]
ランブック	運用者・オンコール担当	docs/runbook/	障害対応後・手順変更時	[[monitoring-operations]]
CHANGELOG	利用者・リリース管理者	リポジトリルート	リリース時	[[cicd-deployment]]
設計書・詳細設計	開発者	docs/design/	設計変更時	[[detailed-design]]

正本はリポジトリに置く。 WikiやNotionを正本にするとコード変更と文書更新が乖離する。

進め方

1. 読者を決める: 誰のために書くかを最初に明記する。新規参加者・運用者・API利用者・未来の自分——読者が曖昧なドキュメントは書けない
2. 書くべき内容を絞る: コードを読めば分かることは書かない。「なぜその設計にしたか」「どの制約があるか」「何をやってはいけないか」を優先する
3. 既存の文書を確認する: 重複・矛盾・正本の所在を整理してから書き始める
4. テキストベースで書く: 図はMermaid等のテキスト形式を使う。diffが見え、エージェントが編集でき、レビューができる
5. セットアップ手順を検証する: 新人または新しい環境で実際に手順通りに動かして確認する。動かない手順書は害になる
6. コードの近くに置く: 関連するコードと同一リポジトリ・同一PRで更新する運用を徹底する
7. 陳腐化したものは「直すか消す」: 間違ったドキュメントはゼロより害。四半期に一度の棚卸しで削除も選択肢に入れる

成果物テンプレート

READMEテンプレート

# プロジェクト名

一言で何ができるか。誰のどんな問題を解決するか。（3行以内）

## セットアップ

\`\`\`bash
# コピペで動く手順のみ記載
git clone https://github.com/org/repo.git
cd repo
cp .env.example .env        # 環境変数の設定が必要な場合
npm install
npm run dev
\`\`\`

動作確認: http://localhost:3000 にアクセスして「〇〇」が表示されれば成功。

## 使い方

\`\`\`bash
# 基本的なコマンドや操作の例
npm run build
npm start
\`\`\`

詳細は [docs/](docs/) を参照。

## 開発参加

\`\`\`bash
npm test       # テスト実行
npm run lint   # リントチェック
\`\`\`

- ブランチ戦略: `main` は常にデプロイ可能。機能開発は `feature/xxx` ブランチで行う
- PRのサイズは400行以内を目安。コミットメッセージは [Conventional Commits](https://www.conventionalcommits.org/) に従う

## ライセンス
MIT

CLAUDE.mdテンプレート

# CLAUDE.md

このファイルはAIエージェントが毎回参照する前提で書いている。簡潔に。

## ビルド・テストコマンド

\`\`\`bash
npm run dev        # 開発サーバー起動
npm test           # 全テスト実行
npm run test:unit  # ユニットテストのみ
npm run lint && npm run build  # リント + 本番ビルド
\`\`\`

## ディレクトリ構成

\`\`\`
src/
  api/        # APIルート定義(Express)
  domain/     # ビジネスロジック。フレームワーク依存なし
  infra/      # DB・外部APIなどの実装詳細
  shared/     # 複数レイヤーで使う型・ユーティリティ
docs/
  adr/        # アーキテクチャ決定記録
  runbook/    # 障害対応手順
\`\`\`

## コード規約

- TypeScript strict モード。`any` は原則禁止
- テストファイルは対象ファイルと同ディレクトリに `*.test.ts` で置く
- 環境変数は `src/config.ts` 経由でのみアクセスする

## やってはいけないこと

- `main` ブランチへの直接pushは禁止
- 本番DBへの直接接続は禁止(ステージング環境を使う)
- シークレットをコードにハードコードしない

## 主要な設計判断(背景)

- ドメインレイヤーをフレームワーク非依存にした理由: テスト容易性とフレームワーク移行コストの低減
- ORMを使わずクエリビルダーを採用した理由: 複雑なクエリのパフォーマンスチューニングが必要なため

チェックリスト

• 読者(誰が読むか)を冒頭または自分のメモで明確にしたか
• コードを読めば分かる内容を省いたか
• セットアップ手順を実際の環境で動作確認したか
• 図はMermaid等のテキスト形式で書いたか
• コード変更と同じPRでドキュメントを更新したか
• 正本がリポジトリに存在し、WikiやNotionに分散していないか
• 陳腐化した記述を削除または修正したか
• CLAUDE.mdにビルド・テストコマンドと「やってはいけないこと」が揃っているか
• ADRに「なぜその設計を選んだか」と「検討したが選ばなかった代替案」が記載されているか

アンチパターン

• 書いた直後から更新されない設計書: コードと別のPRで管理すると乖離する。コード変更と文書更新を同一PRにする運用が必要
• Wiki・Notion・リポジトリに分散して正本不明: 「どれが最新か」の確認コストが発生する。正本はリポジトリに一本化する
• コードのコメントと同じ内容の説明文: 二重管理になり片方が腐る。READMEには「なぜ」だけ書く
• 動かない手順書: セットアップ手順を一度も検証しないまま放置する。動かないREADMEはゼロより害になる
• すべてを文書化しようとして力尽きる: 網羅性を目指すと更新が止まる。「新規参加者が詰まる箇所」に絞る
• 間違ったドキュメントを残す: 「後で直す」と放置した誤情報は混乱を招く。直せないなら削除する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	担当	具体的な使い方
司令塔(メインモデル)	何を文書化するかの判断・全体構成の設計	対象読者の確認、既存文書の重複・矛盾の洗い出し、各エージェントへの作業割り当てと最終レビュー
Opus相当	設計ドキュメント・ADRのレビューと品質担保	設計判断の妥当性・代替案の網羅性・背景情報の十分性を深く評価させる
Sonnet相当	ドキュメントのドラフト作成・更新・整形	READMEやCLAUDE.mdの初稿生成、既存文書への追記・修正、Mermaid図の生成
Haiku相当	陳腐化箇所の検出(コードとの突き合わせ)	コードとドキュメントを比較して「記述が古くなった箇所」「コマンドが変わった箇所」を高速にスキャンさせる

関連スキル

• [[orchestration]] — 多エージェント並列実行の共通原則
• [[architecture-design]] — ADR作成・設計判断の記録
• [[api-design]] — API文書の自動生成・スキーマ管理
• [[monitoring-operations]] — ランブック作成・障害対応手順
• [[cicd-deployment]] — CHANGELOGの管理・リリースノート
• [[detailed-design]] — 詳細設計書の作成
• [[code-review]] — ドキュメント更新をPRレビューに組み込む
• [[git-workflow]] — コード変更と文書更新を同一PRで管理する運用