best-practices

ベストプラクティス

言語別リファレンス

各ファイル拡張子には、対応するリファレンスがあります。

• .ts、.js — references/typescript.md
• .tsx、.jsx — references/typescript.md + references/react/react.md
• .py — references/python.md + references/python/INDEX.md
• .go — references/go.md
• .swift — references/swift.md

共通の原則は references/universal.md に記載されています。

Next.js/React のリファレンス

Next.js プロジェクト向けに、references/react/ ディレクトリには以下が用意されています。

1. references/react/rules/INDEX.md — 影響度別のパターンインデックス
2. references/react/rules/_sections.md — 優先度とカテゴリ
3. 検出されたパターンに対応する個別のルールファイル

ルールの適用

• フレームワーク固有のルール（例：Next.js）は、そのフレームワークが検出された場合にのみ適用されます。
• CRITICAL ルールの優先度が最も高くなります。対象はウォーターフォール、バンドルサイズ、ハイドレーションです。
• すべてのリファクタリングでは、動作とパブリックインターフェースを必ず維持してください。

コード品質基準

• コメント：複雑なビジネスロジックにのみ記述します。コードの内容を言い換えるコメントは不要です。
• エラー処理：回復可能な場合にのみ try-catch を使用します。信頼できる経路に防御的なチェックは不要です。
• 型安全性：any は使用しません。適切な型、またはガード付きの unknown が必要です。
• スタイル：既存のコードスタイルと CLAUDE.md の規約を優先します。
• クリーンアップ：未使用のインポート、変数、関数、型は削除します。
• 互換性ハックなし：未使用の _vars と、削除済みコードの再エクスポートは削除します。
• 名前の変更：未使用としてマークするより、内容を表す名前を優先します。
• デッドコード：デッドコードは削除し、コメントアウトしたままにしません。
• ファイル構成：単一責任の原則はファイルレベルにも適用されます。複数の関心事を含むファイルは分割の候補です（references/universal.md を参照してください）。