| name | coding-standards |
| description | コードの品質問題、アンチパターン、可読性を検査。機能実装、コードレビュー、リファクタリング時に使用。 |
普遍的コーディング規約
技術的アンチパターン（赤信号パターン）
以下のパターンを検出したら即座に停止し、設計を見直すこと：
コード品質のアンチパターン
- 同じようなコードを3回以上書いた - Rule of Threeに違反
- 単一ファイルに複数の責務が混在 - 単一責任原則（SRP）違反
- 同じ内容を複数ファイルで定義 - DRY原則違反
- 依存関係を確認せずに変更 - 予期しない影響の可能性
- コメントアウトでコード無効化 - バージョン管理を活用すべき
- エラーの握りつぶし - 問題の隠蔽は技術的負債
- 型アサーション（as）の多用 - 型安全性の放棄
設計のアンチパターン
- 「一旦動くように」という思考 - 技術的負債の蓄積
- 継ぎ足し実装 - 既存コードへの無計画な追加
- 不確実技術の楽観的実装 - 未知要素を「たぶん動く」前提で設計
- 対処療法的修正 - 根本原因を解決しない表面的な修正
- 無計画な大規模変更 - 段階的アプローチの欠如
基本原則
- 積極的なリファクタリング - 技術的負債を防ぎ、健全性を維持
- 使われない「念のため」のコード禁止 - YAGNI原則（Kent Beck）に反する
- Minimum Surface for Required Coverage - 保守対象の要素（永続状態、公開コントラクト要素または境界を越えるフィールド/Props、振る舞いモード/フラグ/バリアント、再利用可能な抽象、コンポーネント分割）を導入する場合、現在のユーザー観察可能な要件と受容済み技術制約（監査、データ整合性、互換性、セキュリティ、パフォーマンス、アクセシビリティ）をカバーする最小の設計面を選ぶ。採用の正当化は「より小さい代替案では満たせない現要件・制約を明記する」形で行い、価値ベースの議論（再利用可能、将来対応、実装が楽）はタイブレーカーのみに用いる。YAGNI との違い: YAGNI は時間軸の判断（将来のためだけの作業はしない）、本原則は固定されたカバレッジ点での設計面を制約する。
コメント記述ルール
- コードファースト: 命名・型・構造を第一の表現手段とし、コードで表現できない情報を持つときだけコメントを書く。迷ったらコメントを足す前に命名を見直す
- 「なぜ」を説明し「何を」は書かない: 判断の理由、トレードオフ、制約・エッジケース、公開APIの契約を説明する
- 履歴情報禁止: 開発履歴は記載しない
- タイムレス: いつ読んでも有効な内容のみ記述
- 簡潔性: 必要最小限の説明にとどめる
エラーハンドリングの基本原則
Fail-Fast原則
エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ。エラーの握りつぶしは禁止。
詳細な実装方法（Result型、カスタムエラークラス、層別エラー処理など）は各言語・フレームワークのルールを参照。
Rule of Three - コード重複の判断基準
Martin Fowler「Refactoring」に基づく重複コードの扱い方：
| 重複回数 | 対応 | 理由 |
|---|
| 1回目 | インライン実装 | 将来の変化が予測できない |
| 2回目 | 将来の統合を意識 | パターンが見え始める |
| 3回目 | 共通化実施 | パターンが確立された |
共通化の判断基準
共通化すべきケース
- ビジネスロジックの重複
- 複雑な処理アルゴリズム
- 一括変更が必要になる可能性が高い箇所
- バリデーションルール
共通化を避けるべきケース
- 偶然の一致（たまたま同じコード）
- 将来異なる方向に進化する可能性
- 共通化により可読性が著しく低下
- テストコード内の簡単なヘルパー
参照の代表性
失敗パターン: 近隣2-3ファイルのパターンや依存バージョンをリポジトリ全体での使用状況を確認せずに採用すると、古いパターン、バージョン不一致、アーキテクチャ不整合が発生する。
採用前の確認
既存コードからパターン、API、依存を採用する場合:
- IF 参照が近隣2-3ファイルのみ → THEN Grepでリポジトリ全体を検索し、異なるディレクトリの3ファイル以上で同じパターンが使われている場合に採用可能
- IF Grepで参照元以外に1-2件のみ検出 → THEN それが正規の実装かレガシーの残存か調査してから採用を判断
- IF Grepで参照元以外に0件 → THEN ローカル規約として扱い、明示的な理由がある場合のみ採用（例: 周辺コードとの整合性、破壊的変更の回避）
- IF リポジトリ内に複数のアプローチが共存 → THEN 多数派パターン（最多ファイル数）を特定して採用。少数派を選ぶ場合は理由を明記
- IF 外部依存（ライブラリ、プラグイン、SDK）を採用 → THEN 同じ依存のリポジトリ全体での使用分布を確認。リポジトリの状態だけでは適切なバージョンが判断できない場合はエスカレーション
- IF 既存パターンに従う → THEN 代替が存在する場合はその理由を明記（例: 周辺コードとの整合性、破壊的変更の回避、統一的なアップデートを予定）
原則
近隣コードは調査の起点。採用の根拠にするにはリポジトリ全体での使用状況（異なるディレクトリの3ファイル以上）を確認すること。
よくある失敗パターンと回避方法
パターン1: エラー修正の連鎖
症状: エラーを修正すると新しいエラーが発生
原因: 根本原因を理解せずに表面的な修正
回避方法: 5 Whysで根本原因を特定してから修正
パターン2: 型安全性の放棄
症状: any型やasの多用
原因: 型エラーを回避したい衝動
回避方法: unknown型と型ガードで安全に処理
パターン3: テスト不足での実装
症状: 実装後にバグ多発
原因: Red-Green-Refactorプロセスの無視
回避方法: 必ず失敗するテストから開始
パターン4: 技術的不確実性の無視
症状: 新技術導入時の想定外エラー多発
原因: 事前調査なしで「公式ドキュメント通りなら動くはず」
回避方法:
- タスクファイル冒頭に確実性評価を記載
- 確実性lowの場合、最初に最小限の動作確認コードを作成
パターン5: 既存コード調査不足
症状: 重複実装、アーキテクチャ不整合、結合時の障害、古いパターンの採用
原因: 実装前の既存コード理解不足、近隣ファイルのみ参照し代表性を確認していない
回避方法:
- 実装前に類似機能の存在を必ず検索（同じドメイン、責務、設定パターンをキーワードに）
- 類似機能を発見 → その実装を使用する（新規実装は行わない）
- 類似機能が技術的負債 → ADRで改善提案を作成してから実装
- 類似機能が存在しない → 既存の設計思想に沿って新規実装
- すべての判断と根拠をDesign Docの「既存コードベース分析」セクションに記録
- 参照の代表性チェック: 上記「参照の代表性」セクションのIF-THEN閾値を参照
デバッグ手法
1. エラー分析手順
- エラーメッセージ（最初の行）を正確に読む
- スタックトレースの最初と最後に注目
- 自分のコードが現れる最初の行を特定
2. 5 Whys - 根本原因分析
症状: TypeScriptのビルドエラー
Why1: 型定義が一致しない → Why2: インターフェースが更新された
Why3: 依存関係の変更 → Why4: パッケージ更新の影響
Why5: 破壊的変更を含むメジャーバージョンアップ
根本原因: package.jsonでのバージョン指定が不適切
3. 最小再現コード
問題を切り分けるため、最小限のコードで再現を試みる：
- 関連のない部分を削除
- モックで外部依存を置き換え
- 問題が再現する最小構成を作成
型安全性の基礎
型安全の原則: unknown型と型ガードを使用する。any型は型チェックを無効化し、実行時エラーの原因となる。
any型の代替手段（優先順位順）
- unknown型 + 型ガード: 外部入力の検証に使用
- ジェネリクス: 型の柔軟性が必要な場合
- ユニオン型・インターセクション型: 複数の型の組み合わせ
- 型アサーション（最終手段）: 型が確実な場合のみ
型ガードの実装パターン
function isUser(value: unknown): value is User {
return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
}
型の複雑性管理
- フィールド数: 20個まで（超えたら責務で分割、外部API型は例外）
- オプショナル率: 30%まで（超えたら必須/任意で分離）
- ネスト深さ: 3階層まで（超えたらフラット化）
- 型アサーション: 3回以上使用したら設計見直し
- 外部API型の扱い: 制約を緩和し、実態に合わせて定義（内部では適切に変換）
リファクタリング手法
基本方針
- 小さなステップ: 段階的改善により、常に動作する状態を維持
- 安全な変更: 一度に変更する範囲を最小限に抑制
- 動作保証: 既存の動作を変えないことを確認しながら進める
実施手順: 現状把握 → 段階的変更 → 動作確認 → 最終検証
優先順位: 重複コード削除 > 長大な関数分割 > 複雑な条件分岐簡素化 > 型安全性向上
実装作業の完全性担保
影響範囲調査の必須手順
完了定義: 以下3段階すべての完了
1. 検索（Discovery）
Grep -n "TargetClass\|TargetMethod" -o content
Grep -n "DependencyClass" -o content
Grep -n "targetData\|SetData\|UpdateData" -o content
2. 読解（Understanding）
必須: 発見した全ファイルを読み込み、作業に必要な部分をコンテキストに含める：
- 呼び出し元の目的と文脈
- 依存関係の方向
- データフロー: 生成→変更→参照
3. 特定（Identification）
影響範囲の構造化報告（必須）：
## 影響範囲分析
### 直接影響: ClassA、ClassB（理由明記）
### 間接影響: SystemX、PrefabY（連携経路明記）
### 処理フロー: 入力→処理1→処理2→出力
重要: 検索のみで完了とせず、3段階すべてを実行すること
未使用コード削除ルール
未使用コード検出時 → 使用予定？
- Yes → 即実装（保留禁止）
- No → 即削除（Git履歴に残る）
対象: コード・ドキュメント・設定ファイル
Red-Green-Refactorプロセス（テストファースト開発）
推奨原則: コード変更は必ずテストから始める
開発ステップ:
- Red: 期待する動作のテストを書く（失敗する）
- Green: 最小限の実装でテストを通す
- Refactor: テストが通る状態を維持しながらコード改善
NGケース（テストファースト不要）:
- 純粋な設定ファイル変更（.env、config等）
- ドキュメントのみの更新（README、コメント等）
- 緊急本番障害対応（ただし事後テスト必須）
テスト設計原則
テストケースの構造
- テストは「準備（Arrange）」「実行（Act）」「検証（Assert）」の3段階で構成
- 各テストの目的が明確に分かる命名
- 1つのテストケースでは1つの振る舞いのみを検証
テストデータ管理
- テストデータは専用ディレクトリで管理
- 環境変数はテスト用の値を定義
- 機密情報は必ずモック化
- テストデータは最小限に保ち、テストケースの検証目的に直接関連するデータのみ使用
モックとスタブの使用方針
推奨: 単体テストでの外部依存モック化
- メリット: テストの独立性と再現性を確保
- 実践: DB、API、ファイルシステム等の外部依存をモック化
避けるべき: 単体テストでの実際の外部接続
- 理由: テスト速度が遅くなり、環境依存の問題が発生するため
テスト失敗時の対応判断基準
テストを修正: 間違った期待値、存在しない機能参照、実装詳細への依存、テストのためだけの実装
実装を修正: 妥当な仕様、ビジネスロジック、重要なエッジケース
判断に迷ったら: ユーザーに確認
テストの粒度原則
原則：観測可能な振る舞いのみ
テスト対象：公開API、戻り値、例外、外部呼び出し、永続化された状態
テスト対象外：privateメソッド、内部状態、アルゴリズム詳細
Security Principles
Secure Defaults
- 認証情報とシークレットは環境変数または専用のシークレットマネージャーで管理
- すべてのデータベースアクセスにパラメータ化クエリ（プリペアドステートメント）を使用
- 言語またはフレームワークが提供する確立された暗号ライブラリを使用
- セキュリティ上重要な値（トークン、ID、nonce）は暗号学的に安全な乱数生成器で生成
- 機密データは標準プロトコルを使用して保存時・転送時に暗号化
Input and Output Boundaries
- システムのエントリポイントで、期待される形式・型・長さについてすべての外部入力を検証
- 出力をレンダリングコンテキスト（HTML、SQL、シェル、URL）に応じて適切にエンコード
- エラーレスポンスには呼び出し元に必要な情報のみを返却し、詳細な診断情報はサーバーサイドでログに記録
Access Control
- ユーザーデータを扱うまたは状態変更をトリガーするすべてのエントリポイントに認証を適用
- エントリポイントだけでなく、各リソースアクセスで認可を検証
- 操作に必要な権限のみを付与（ファイル、データベース接続、APIスコープ）
Knowledge Cutoff Supplement (2026-03)
- OWASP Top 10:2025は症状から根本原因へと視点を移し、「Software Supply Chain Failures」(A03)と「Mishandling of Exceptional Conditions」(A10)が追加された
- 最近の研究ではAI生成コードがAccess Controlの欠落を高い発生率で示しているため、認証と認可を高優先度のレビュー対象として扱う
- OpenSSFが「Security-Focused Guide for AI Code Assistant Instructions」を公開した。汎用的なアドバイスより、言語固有で実行可能な制約を推奨している
- 詳細な検出パターンは
references/security-checks.mdを参照
