---
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桁ゼロ埋め）。100件超のみ3桁。スコープは設計書1ファイルごと（別設計書と重複可）
- 設計書 `テスト仕様` の ID と関数/ケース名の ID を一致させる。`maps_to` で設計書⇔テストを追跡

## 後方互換ハック禁止

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

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

## エラーハンドリング

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