code-quality

コード品質

一般的な技術スタック全体で、体系的なコードレビューと品質の徹底を行います。コードベースを健全に保つためのチェックリスト、リンティング戦略、メトリクスを紹介します。

クイックスタート

コード品質チェックを実行する

1. 静的解析を実行する： リンター、型チェッカー、フォーマッター
2. チェックリストに照らしてレビューする： 以下の言語別項目を確認します
3. 複雑度メトリクスを確認する： 循環的複雑度 < 25、データフロー複雑度 < 25
4. 結果を報告する： 重要度と推奨事項を含む構造化された出力

---

リンティングの設定

Rust — Clippy の設定

標準的な Clippy の設定（Cargo.toml または .clippy.toml に記述）：

[lints.clippy]
cognitive_complexity = "warn"
pedantic = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
unwrap_used = "deny"

標準コマンド：

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo check
cargo test -- --test-threads=1

適用する主なルール：

• テスト以外のコードでは .unwrap() を使わない（? または .expect("reason") を使用します）
• すべての公開アイテムに rustdoc を付ける（#[warn(missing_docs)]）
• 確認が必要な値を返す関数には #[must_use] を付ける
• #[allow(...)] を使う場合は、必ず理由を説明するコメントを追加する
• #[allow(...)] に妥当な理由を説明できない場合は、代わりに問題を修正する

TypeScript — ESLint + Strict モード

推奨する tsconfig.json の厳格さ：

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

適用する主なルール：

• any は使わず、代わりに unknown と型ガードを使う
• // @ts-ignore は使わず、型の問題を修正するか、説明を添えて // @ts-expect-error を使う
• let より const を優先し、var は使わない
• 状態のモデリングには判別可能なユニオン型を使う
• エクスポートする関数には明示的な戻り値の型を付ける

Python — Ruff + Mypy

推奨する pyproject.toml：

[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "ANN", "B", "A", "C4", "DTZ", "ISC", "PIE", "PT", "RET", "SIM", "TCH", "ARG", "PTH", "ERA"]

[tool.mypy]
strict = true
warn_return_any = true
warn_unreachable = true

適用する主なルール：

• すべての公開関数とメソッドに型ヒントを付ける
• すべての公開クラス、関数、メソッドに docstring を付ける
• os.path より pathlib.Path を使う
• パッケージマネージャーとして uv を使う
• 裸の except: は使わず、必ず具体的な例外を捕捉する

---

コードレビューチェックリスト

共通チェックリスト（すべての言語）

正確性：

• コードは説明どおりに動作しますか？
• エッジケース（空のコレクション、null/None、ゼロ、負の値）は処理されていますか？
• エラー発生時の処理は適切ですか？
• オフバイワンエラーはありませんか？

明瞭さ：

• PR の説明を読まなくてもコードを理解できますか？
• 変数名や関数名は説明的で、一貫性がありますか？
• 複雑な箇所には「何を」ではなく「なぜ」を説明するコメントがありますか？
• 可能な限り、コード自体で内容が分かるようになっていますか？

アーキテクチャ：

• この変更は既存のモジュール境界を尊重していますか？
• 変更の抽象化レベルは適切ですか？
• 依存関係は妥当ですか（1つの関数のために巨大なライブラリを追加していませんか）？

テスト：

• 新しい関数やメソッドはテストで網羅されていますか？
• エッジケースやエラー発生時の処理をテストしていますか？
• テストは読みやすく、保守しやすいですか？

セキュリティ（懸念事項が見つかった場合は、セキュリティ担当者によるフォローアップを依頼してください）：

• ハードコードされたシークレットや認証情報がない
• ユーザー入力は使用前に検証されている
• SQL インジェクション、XSS、パストラバーサルにつながる要素がない

Rust 固有のチェックリスト

• cargo fmt を適用している
• cargo clippy が警告なしで完了する（pedantic + nursery）
• テスト以外で .unwrap() を使っていない
• エラー処理では、適切なエラー型とともに ? を使用している
• 公開アイテムに rustdoc コメントがある
• #[allow(...)] に説明コメントが付いている
• 新しい関数に単体テストがある
• 関数ごとの循環的複雑度が 25 未満である
• 関数ごとのデータフロー複雑度が 25 未満である

TypeScript/React 固有のチェックリスト

• any 型を使っていない
• Strict モードに準拠している
• コンポーネントの props 型が明確である
• フックがフックのルールに従っている
• 不要な再レンダリングがない（メモ化やコールバックの使い方を確認する）
• 新しい依存関係がバンドルに与える影響を考慮している

Django/Python 固有のチェックリスト

• 公開インターフェースに型ヒントがある
• Ruff + mypy のチェックで問題がない
• N+1 クエリがない（select_related/prefetch_related を使用する）
• マイグレーションをレビューし、元に戻せることを確認している
• ビューにビジネスロジックがない（サービスレイヤーを使用する）

---

複雑度メトリクス

循環的複雑度

コード内の独立した経路の数を測定します。推奨しきい値：< 25。

複雑度	リスクレベル	対応
1-10	低	シンプルで適切に構成されたコードです
11-20	中程度	複雑さが増している場合は簡素化を検討してください
21-24	高	リファクタリングを推奨します
25+	違反	マージ前に必ずリファクタリングしてください

削減方法：

• 各分岐のヘルパー関数を抽出します
• 早期リターン／ガード節を使用します
• 複雑な条件分岐をルックアップテーブルまたはパターンマッチングに置き換えます
• バリアントに応じて動作が変わる場合は、ストラテジーパターンを使用します

データフローの複雑度

関数内で相互に関わる変数の数を測定します。推奨しきい値：< 25。

削減方法：

• 引数の数が少ない純粋関数を抽出します
• 関連する引数を構造体／オブジェクトにまとめます
• データを複数の段階で変換する関数を分割します

測定ツール

言語	ツール	コマンド
Rust	cargo clippy (cognitive_complexity)	clippy の設定に組み込まれています
TypeScript	eslint-plugin-sonarjs	complexity ルールを設定します
Python	radon	radon cc <file> -s -a
Python	ruff	ルール C901（mccabe の複雑度）

---

レビュー結果の形式

コードレビューを提出する際：

## Code Review: [PR/File/Module]

**Date:** YYYY-MM-DD

### Summary
[1-2 sentences: overall quality assessment]

### Findings

| # | Severity | File | Line(s) | Finding | Suggestion |
|---|---|---|---|---|---|
| 1 | High | src/app.rs | 45-67 | Cyclomatic complexity 28 (limit: 25) | Extract match arms into helper functions |
| 2 | Medium | src/ui.rs | 120 | Unwrap without context | Use `.expect("reason")` or `?` |

### Positive Observations
[What's well-written — acknowledge good code]

### Metrics
- Linter: [clean / N warnings]
- Tests: [pass / fail]
- Complexity: [within limits / violations noted above]

### Security Notes
[Items to flag for follow-up, if any]

---

統合

• プロジェクトの AGENTS.md／CLAUDE.md の実行ポリシーに従い、確認を求めずにリンター、フォーマッター、型チェッカーを実行できます。
• 関連項目：範囲を絞った変更セットを敵対的にレビューするには、このパックの code-reviewer スキルを、より適切な構成で複雑度違反を修正するには design-patterns を参照してください。