PRテンプレートへの組み込み

ドキュメントをコードと同じリポジトリで管理する（Docs as Code）と、PRテンプレートに「ドキュメント更新の確認」を組み込むことができます。これにより「ドキュメントの更新が必要かどうか」を毎回意識させる仕組みになります。

Markdown — .github/PULL_REQUEST_TEMPLATE.md 
## 変更内容
（このPRで何を変えるかを簡潔に記述）

## 変更の種類
- [ ] バグ修正
- [ ] 新機能
- [ ] リファクタリング
- [ ] ドキュメント更新

## PRチェックリスト

### 設計・実装
- [ ] 設計標準ドキュメントへの影響を確認した
  - [ ] 影響なし
  - [ ] 影響あり → `docs/` 以下のドキュメントを同時に更新した
- [ ] テストを追加または更新した
- [ ] セルフレビューを実施した

### ドキュメント
- [ ] READMEの更新が必要な変更ではないか確認した
- [ ] APIの変更がある場合、OpenAPI仕様を更新した
- [ ] 新しいコンポーネントがある場合、Storybookを追加した

チェックボックス「影響あり → docs/ を更新した」を設けることで、コードの変更とドキュメントの更新を同一PRで完結させる文化が根付きます。レビュアーがこのチェックを確認することで「このコードの変更はドキュメントの更新も必要では？」という気づきを促せます。

LinterでルールをAuto化する

ドキュメントに書いたルールを、可能な限り自動チェックに変換します。「書かれているが守られない」ルールは自動化によって解消しましょう。

ドキュメントのルール自動化の方法
TypeScriptで any 型を使わないESLintの @typescript-eslint/no-explicit-any ルール
コミットメッセージはConventional Commitsに従うcommitlint のCIチェック
APIのレスポンスはOpenAPIスキーマに準拠するopenapi-generator のバリデーション
コンポーネントにアクセシビリティ属性を付与するeslint-plugin-jsx-a11y
SQLのインデックス追加は CONCURRENTLY で行うSQLマイグレーションのlintツール（独自スクリプト）
インポートの順序（標準→外部→内部）eslint-plugin-import の order ルール

自動化できないルールこそ人間がレビューする

自動化できるルールはLinterに任せ、人間のレビューは「設計の意図が適切か」「例外の判断が正しいか」という判断を要するものに集中させます。これにより、レビューの質が向上し、レビュアーの時間も有効活用できます。

オンボーディングへの組み込み

新メンバーが入社した際の最初のタスクに「設計標準ドキュメントを読んで、不明点や古い情報をフィードバックする」を組み込みます。これには2つのメリットがあります。

1つ目は新メンバーがドキュメントの存在を早期に認識することです。入社直後に「このチームはドキュメントを大切にしている」という文化を伝えられます。2つ目はドキュメントの問題を発見できることです。新鮮な目で読んでもらうことで、陳腐化した記述・説明不足の箇所・前提知識が足りない箇所が明確になります。

実例：新メンバーが読んでわかること

実際に「新メンバーに読んでもらったら、3つのセクションが実態と違うことが判明した」という経験をしているチームは多くあります。「新メンバーに説明できる状態にある」ということが、ドキュメントの最低限の品質基準とも言えます。

検索しやすいタイトル・見出し設計

どんなに内容が良くても、見つけられないドキュメントは存在しないも同然です。タイトルは「検索したときに見つかるか」を意識して付けます。

Text — タイトル設計 Good / Bad 
❌ 悪いタイトル例（曖昧・検索されない）:
- 「設計について」
- 「開発ガイド」
- 「規約」
- 「ルールまとめ」

✅ 良いタイトル例（具体的・検索でヒットする）:
- 「TypeScript コーディング規約 2025年版」
- 「REST API エンドポイント命名ガイドライン」
- 「React コンポーネント命名・ファイル構成規約」
- 「PostgreSQL マイグレーション安全実行ガイド」

見出しにも検索キーワードを含めると、Notionやリポジトリ内検索でヒットしやすくなります。「エラーハンドリング」について知りたい人が検索したときに、「4.2 エラー処理の方針」より「4.2 TypeScript エラーハンドリング規約」の方が見つけやすいです。

エントリーポイントを整備する

ドキュメントへのエントリーポイントを複数の場所に設けることで、「存在は知っているが、URLを覚えていないので毎回Slackで聞いている」状態を解消します。

エントリーポイント設置方法
GitHubリポジトリのREADMEdocs/へのリンクセクションを追加
Confluenceのプロジェクトトップ「設計標準ドキュメント一覧」セクションを固定
Slackのチャンネルブックマーク・ピン留めにドキュメントのリンクを追加
オンボーディングドキュメント「まず読むべきドキュメントリスト」として掲載
PRテンプレート「関連ドキュメント」セクションにリンクを記載

参照文化の醸成

「〇〇の実装方針については、コーディング規約のセクション4.2に記載されているエラーハンドリングの原則に従いました」というコメントをPRやSlackで積極的に書きましょう。このような参照コメントには3つの効果があります。

1. ドキュメントの存在が可視化される：ドキュメントを知らないメンバーが「こういうドキュメントがあるのか」と気づきます。2. 意思決定の根拠が明確になる：「なぜこう実装したのか」が後から追跡できます。3. 文化の波及：1人がやり始めると、他のメンバーも真似するようになります。

上から「読め」では根付かない

ドキュメントを参照する文化は、上から「読め」と言っても根付きません。テックリードや先輩メンバーが率先して参照することで、自然に広がっていきます。最初の「参照コメント」の投稿を習慣化することが最も効果的です。

まとめ：6つのPARTで学んだこと

設計標準ドキュメントは、チームの集合知を記録し、品質を継続的に担保するための重要な資産です。多くのチームで「作ったが使われない」「古くなってしまった」という状態に陥りますが、仕組みと文化の両輪で対策できます。

6PARTで学んだアプローチを整理します。

ドキュメントを「作る」フェーズでは、全種類を一度に作ろうとせず、チームの課題から最も優先度の高い1つを選ぶことが重要です。テンプレートを使って箇条書きから始め、完璧を目指しません。「ルール」だけでなく「なぜそのルールがあるのか」を必ず書き、Good/Bad例・アンチパターン集を充実させます。チェックリストを末尾に付けてレビューの拠り所にします。

ドキュメントを「生かす」フェーズでは、オーナー制度を設けて各ドキュメントに維持管理責任者を明記します。四半期ごとの定期レビューをカレンダーに固定し、変更はPRベースで行ってSlackに自動通知する仕組みを作ります。ドキュメントのルールをできる限り自動チェックに変換し、PRテンプレートに「ドキュメント更新の確認」を組み込みます。オンボーディングに組み込み、新メンバーが最初に触れる文化を作ることも重要です。

PARTテーマキーポイント
01はじめに・コーディング規約属人化の防止・「なぜ」の重要性・Linter連携
02アーキテクチャ・API設計Clean Architectureのレイヤー・ADRの書き方・レスポンス形式統一
03UI/UX・データモデル・基本原則デザイントークン・SQL標準・優先度の考え方
04実践：書き方テンプレート・なぜを書く・Good/Bad例・チェックリスト
05ツール・腐る理由・定期レビューDocs as Code・12ヶ月シナリオ・GitHub Actions通知
06乖離防止・使われるドキュメントPRテンプレート・Linter自動化・オンボーディング・参照文化

次のアクション

読んだだけで終わらせないために、今すぐできるアクションを1つ提案します。

今すぐできる最初のアクション（所要時間：30分）

直近のコードレビューで繰り返し出た指摘を3つ書き出してください。それがそのままコーディング規約の「Bad例」になります。次に、それぞれに「なぜそれが問題か」を1行添えると、最初のドキュメントの骨格が完成します。

例：「any型を使わない → 型安全性が失われ、実行時エラーが検出できなくなるため」

これを3つ揃えたら、PART 04のテンプレートに当てはめてMarkdownとして保存し、チームのリポジトリに docs/coding-standards.md として追加するPRを出す — それが第一歩です。

設計標準ドキュメントは一度作れば終わりではなく、チームとともに育てていくものです。最初は3つのルールだったドキュメントが、半年後には30のルールに育ち、1年後にはチームの新人が「このドキュメントのおかげで迷わなかった」と言う資産になります。

小さく始めて、継続的に改善していきましょう。