---
applyTo: "**"
---

# コーディング規約（共通）

## コメント

人間レビューと1年後の追跡を前提に書く。

- 配置はコードの上。短い定数の補足のみ行末可
- ビジネス判断・制約・ワークアラウンドは必ず「なぜ」を書く
- 命名で分かることでも1〜2行の目印コメントは可（自明コメント違反としない）
- 禁止: 逐語訳・超詳細解説・セクション区切り（`# === ===`）・ファイル先頭コメント
- TODO / FIXME は原則残さない。残すなら必要事項を1行明記
- docstring / JSDoc は公開 IF（UC・ドメインサービス・Repository・カスタムフック・ユーティリティ）のみ必須

## テスト記述

- 設計書 `テスト仕様` の `T-XX` を関数名・ケース名に埋め込む
  - Python: `def test_T_01_refresh_false時は...():`（`-` は `_`）
  - TypeScript: `test("T-01: refresh=false時は...", () => {})`
- コメント・docstring で ID/テスト名を重複説明しない
- 全テストで `# 準備 - ...` / `# 実行 - ...` / `# 検証 - ...` マーカー必須。行数による免除なし。英語（Arrange/Act/Assert）禁止
- このマーカーは規約由来。「自明コメント」違反として指摘・削除しない

### ID 採番

- `T-XX`（2桁ゼロ埋め。枝番英小文字1字可・100件超のみ3桁）。スコープは設計書1ファイルごと（別設計書と重複可）
- 設計書 `テスト仕様` の ID と関数/ケース名の ID を一致させる。`maps_to` で設計書⇔テストを追跡

## 後方互換ハック禁止

使われないコードは完全削除。禁止:

- 未使用の引数・変数の残置 / 削除した型・関数の再公開
- `# removed` / `# deprecated` / `# 旧実装` 付き残置
- 後方互換ラッパー・エイリアス / 新旧両対応の `if-elif`

## エラーハンドリング

- 同じ抽出・型定義・変換ロジックを2箇所以上に書きそうになったら共通モジュールへ（ローカル util 量産禁止）
- `ValueError`/`RuntimeError` のキャッチオールでステータスコード変換禁止。UC で意味のある例外にラップ
- 設計記録番号・設計書名への直接参照（`# ADR-XXX 参照` 等）をコード・テスト・docs 本文に書かない

### try-catch / try-except ルール

- 握り潰し禁止: `except: pass` / `catch(e) {}` は書かない。最低限ログ出力か再送出する
- broad catch は境界のみ: `except Exception` / `catch (e: unknown)` はシステム境界（router・API handler）にのみ使う。内部ロジックでは具体的な例外型を捕捉する
- 例外連鎖必須: ラップするときはオリジナルを連鎖させる（Python: `raise DomainError(...) from e` / TypeScript: `throw new AppError(msg, { cause: e })`）
- 設計書の `例外` と一対一: catch する例外型は設計書の `例外[].例外型` に対応させる。設計書にない例外を握り潰さない