コミュニティコード簡略化ベストプラクティス

AI エージェントと LLM のための包括的なコード簡略化ガイド。8つのカテゴリにわたる47のルールが含まれており、重要度別に優先順位付けされています（コンテキスト発見と動作保存からいった重要な項目から、言語イディオムといった段階的な項目まで）。各ルールには詳細な説明、不正な実装と正しい実装を比較した実例、および具体的な影響指標が含まれています。

コア原則

1. コンテキストファースト: 変更を加える前に、プロジェクトの慣例を理解する
2. 動作保存: コードの書き方を変えるが、何をするかは変えない
3. スコープの厳格性: 最近変更されたコードに焦点を当て、差分を小さく保つ
4. 簡潔性より明確性: わかりやすく読みやすいコードが、巧妙なワンライナーに勝る

適用のタイミング

以下の場合にこれらのガイドラインを参照してください:

• 最近変更されたコードの簡略化またはクリーンアップ
• ネストの削減、複雑性の削減、または重複の除去
• 命名と可読性の向上
• 言語固有のイディオムパターンの適用
• 保守性の問題についてのコードレビュー

ルールカテゴリを優先度順に表示

優先度	カテゴリ	インパクト	プレフィックス	ルール数
1	コンテキスト発見	CRITICAL	ctx-	4
2	動作保存	CRITICAL	behave-	6
3	スコープ管理	HIGH	scope-	5
4	制御フロー簡略化	HIGH	flow-	9
5	命名と明確性	MEDIUM-HIGH	name-	6
6	重複削減	MEDIUM	dup-	5
7	デッドコード除去	MEDIUM	dead-	5
8	言語イディオム	LOW-MEDIUM	idiom-	7

クイックリファレンス

1. コンテキスト発見 (CRITICAL)

• ctx-read-claude-md - 簡略化する前に必ず CLAUDE.md を読む
• ctx-detect-lint-config - リンティングとフォーマット設定をチェック
• ctx-follow-existing-patterns - ファイルとプロジェクトの既存のコードスタイルに合わせる
• ctx-project-over-generic - プロジェクト慣例がジェネリックなベストプラクティスを上書きする

2. 動作保存 (CRITICAL)

• behave-preserve-outputs - すべての戻り値と出力を保存する
• behave-preserve-errors - エラーメッセージ、型、処理を保存する
• behave-preserve-api - パブリック関数署名と型を保存する
• behave-preserve-side-effects - 副作用（ログ、I/O、状態変更）を保存する
• behave-no-semantics-change - 微妙なセマンティック変更を禁止
• behave-verify-before-commit - 確定する前に動作保存を確認

3. スコープ管理 (HIGH)

• scope-recent-code-only - 最近変更されたコードのみに焦点を当てる
• scope-minimal-diff - 変更は小さくレビュー可能に保つ
• scope-no-unrelated-refactors - 無関係なリファクタリングなし
• scope-no-global-rewrites - グローバルな書き換えとアーキテクチャの変更を避ける
• scope-respect-boundaries - モジュールとコンポーネントの境界を尊重

4. 制御フロー簡略化 (HIGH)

• flow-early-return - アーリーリターンを使用してネストを削減
• flow-guard-clauses - 前提条件にガード句を使用
• flow-no-nested-ternaries - ネストされた三項演算子は絶対に使用しない
• flow-explicit-over-dense - 密集した式より明示的な制御フロー を好む
• flow-flatten-nesting - 深いネストを最大2～3レベルにフラット化
• flow-single-responsibility - 各コードブロックは1つのことだけを行う
• flow-positive-conditions - 二重否定より肯定的な条件を好む
• flow-optional-chaining - オプショナルチェーンと null合体を使用
• flow-boolean-simplification - ブール式を簡略化

5. 命名と明確性 (MEDIUM-HIGH)

• name-intention-revealing - 意図を明らかにする名前を使用
• name-nouns-for-data - データには名詞、アクションには動詞を使用
• name-avoid-abbreviations - 不可解な略語を避ける
• name-consistent-vocabulary - プロジェクト全体で一貫した用語を使用
• name-avoid-generic - ジェネリックな名前を避ける
• name-string-interpolation - 文字列連結より文字列補間を好む

6. 重複削減 (MEDIUM)

• dup-rule-of-three - 3つのルールを適用
• dup-no-single-use-helpers - 単一用途のヘルパー関数を避ける
• dup-extract-for-clarity - 明確性を向上させる場合のみ抽出
• dup-avoid-over-abstraction - 過度な抽象化より重複を好む
• dup-data-driven - 反復的な条件より データ駆動型パターンを使用

7. デッドコード除去 (MEDIUM)

• dead-remove-unused - 未使用のコード成果物を削除
• dead-delete-not-comment - コードは削除し、コメントアウトしない
• dead-remove-obvious-comments - 明らかなことを述べているコメントを削除
• dead-keep-why-comments - 「何」ではなく「なぜ」を説明するコメントを保持
• dead-remove-todo-fixme - 古い TODO/FIXME コメントを削除

8. 言語イディオム (LOW-MEDIUM)

• idiom-ts-strict-types - any より厳格な型を使用 (TypeScript)
• idiom-ts-const-assertions - const アサーションと readonly を使用 (TypeScript)
• idiom-rust-question-mark - エラー伝播に ? を使用 (Rust)
• idiom-rust-iterator-chains - より明確な場合はイテレータチェーンを使用 (Rust)
• idiom-python-comprehensions - 単純な変換に内包表記を使用 (Python)
• idiom-go-error-handling - エラーを即座に処理 (Go)
• idiom-prefer-language-builtins - 言語と stdlib の組み込み関数を好む

ワークフロー

1. コンテキスト発見: CLAUDE.md を読み、リント設定をチェック、既存パターンを確認
2. スコープ識別: 拡張を求められない限り、最近変更されたコードに焦点を当てる
3. 変換を適用: 優先度順にルールを使用 (CRITICAL が最初)
4. 動作を確認: 出力、エラー、副作用が同じままであることを確認
5. 差分を最小化: 小さく、焦点を絞った、レビューしやすい変更

使用方法

詳細な説明とコード例については、個別のリファレンスファイルをお読みください:

• セクション定義 - カテゴリ構造とインパクトレベル
• ルールテンプレート - 新しいルール追加用テンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリ定義と順序付け
assets/templates/_template.md	新しいルール追加用テンプレート
metadata.json	バージョンとリファレンス情報