PART 04 — 実践：設計標準ドキュメントの書き方
テンプレート・なぜを書く・Good/Bad例・例外・チェックリスト・コツ

# [ドキュメント名]

---
owner: @username
last_reviewed: YYYY-MM-DD
next_review: YYYY-MM-DD
---

## 概要
このドキュメントは〇〇チームの△△エンジニアを対象に、
〜〜に関するルールと判断基準を定めます。

**スコープ**: このドキュメントが対象とする範囲
**対象外**: このドキュメントがカバーしない範囲
**関連ドキュメント**: [リンク]

## 用語定義（Glossary）
| 用語 | 定義 |
|------|------|
| 〇〇 | △△のこと。〜〜と混同されやすいが、違いは〜〜 |

## 背景・このドキュメントを作った理由
（なぜこのルールが必要になったか。過去の課題・インシデントなど）

## 原則・ルール

### [ルール1のタイトル]
**なぜ**: ～という理由から
**ルール**: ～すること
**例外**: ～の場合は除く（理由：〇〇）

## 具体例

### Good ✅
```code
（良い例のコード）
```
↑ これが良い理由: ～

### Bad ❌
```code
（悪い例のコード）
```
↑ これが悪い理由: ～という問題が生じる

## アンチパターン
| アンチパターン | 何が問題か | 代わりにすべきこと |
|----------------|------------|-------------------|
| 〇〇する | △△という問題が発生する | □□すること |

## チェックリスト
- [ ] ～を確認したか
- [ ] ～を満たしているか

## 参考資料
- [公式ドキュメント](URL)

── ❌ Bad: なぜが書かれていない ──
グローバル変数を使用しないこと。


── ✅ Good: なぜと例外が書かれている ──
グローバル変数を使用しないこと。

理由:
グローバル変数はどこからでも変更可能なため、予期しない副作用が発生しやすく、
テストが困難になります。2023年Q3のリファクタリングで、グローバル状態への
依存が原因でバグが多発し、修正に2週間かかりました（インシデント #INC-234参照）。

例外:
設定値（環境変数・フィーチャーフラグ）は、モジュールトップレベルの定数として
定義することを許可します。この場合も変更不可（const/readonly）にしてください。

// ❌ Bad: エラーを握りつぶしている
async function fetchUser(id: number) {
  try {
    const user = await api.getUser(id);
    return user;
  } catch (e) {
    console.log(e);  // ログだけ出してundefinedを返す
    // → 呼び出し元はエラーが起きたかどうか判断できない
  }
}

// ❌ Bad: エラー型が不明確
async function fetchUser(id: number) {
  try {
    return await api.getUser(id);
  } catch (e: any) {  // any型は使わない
    throw e;
  }
}

// ✅ Good: 型安全かつ呼び出し元で処理を委ねる
class UserNotFoundError extends Error {
  constructor(userId: number) {
    super(`User not found: ${userId}`);
    this.name = 'UserNotFoundError';
  }
}

async function fetchUser(id: number): Promise<User> {
  const user = await api.getUser(id);
  if (!user) {
    throw new UserNotFoundError(id);
  }
  return user;
}

// 呼び出し元での型安全な catch
try {
  const user = await fetchUser(123);
} catch (e) {
  if (e instanceof UserNotFoundError) {
    // 404ページへリダイレクト
  } else {
    throw e; // 未知のエラーは再throwする
  }
}

原則: SQLクエリはORMを使用すること

理由:
生SQLは可読性が低く、SQLインジェクションのリスクが高まります。
ORMを使うことでパラメータのエスケープが自動化されます。

例外（以下の場合は生SQLを使用してよい）:
1. ORMで表現できないパフォーマンスクリティカルなクエリ
   → 例: 数百万件のデータを対象にした複雑なJOINと集計
2. ORMでは利用できないDB固有機能
   → 例: PostgreSQLのFULL TEXT SEARCH、LATERAL JOIN等

例外使用時のルール（濫用防止）:
- コメントに「なぜORMを使わないか」を必ず記載すること
- コードレビューで2名以上のApproveを必須とする
- パフォーマンステストの結果（ORMとの比較）をPRに添付する

# アンチパターン集: React コンポーネント設計

## AP-001: Propsのバケツリレー（Props Drilling）

### 何が問題か
コンポーネントA → B → C → D とPropsを渡し続けるパターン。
途中のB・Cは使わないPropsを受け取り続けるため、
コンポーネントの結合度が上がり、リファクタリングが困難になる。

### 見分け方
同じprops名が3層以上のコンポーネントに存在する場合。

### 代わりにすべきこと
- 3層以上またがる場合はContext APIまたはZustand等の状態管理ライブラリを使う
- コンポーネントの責務を見直し、データを必要とするコンポーネントの近くに状態を置く

### 参考インシデント
2024-05のリリースで、テーマカラーの変更が10コンポーネントに波及し、
修正に丸1日かかった（PR #891）。Context移行後は1ファイルの変更で済んだ。

## PRセルフレビューチェックリスト

### API設計
- [ ] エンドポイントはRESTful命名規則に従っているか（名詞・複数形）
- [ ] エラーレスポンスは統一フォーマットを使用しているか
- [ ] 新規エンドポイントのOpenAPIドキュメントを追加したか

### セキュリティ
- [ ] ユーザー入力を直接SQLに渡していないか（SQLインジェクション対策）
- [ ] 認証・認可のチェックが適切に実装されているか
- [ ] 機密情報（パスワード・トークン）がログに出力されていないか
- [ ] レート制限が必要なエンドポイントに設定されているか

### パフォーマンス
- [ ] N+1クエリが発生していないか（SQLのログで確認）
- [ ] 外部APIへの同期呼び出しがタイムアウト設定されているか

### テスト
- [ ] 正常系・異常系（バリデーションエラー、認証エラー）のテストがあるか
- [ ] 境界値（空文字、最大長、0件）のテストがあるか

Step 1: 箇条書きでアウトラインを作る（30分）
  - ルール1: 関数は1つの責務のみ持つ
  - ルール2: 関数名は動詞で始める
  - ルール3: 引数は3つ以下にする

Step 2: 各項目に「なぜ」を1行追加する（30分）
  - ルール1: 関数は1つの責務のみ持つ
    なぜ: テストが単純になり、変更の影響範囲が明確になるため

Step 3: Good/Bad例を1つずつ追加する（1時間）

Step 4: チームにドラフトレビューを依頼する
  → フィードバックをもとに修正（完璧でなくてOK）