software-clean-code-standard

クリーンコード標準

このスキルは、このリポジトリで共有するスキルに適用される、正式なクリーンコード標準です。安定したルール ID（CC-*）、レビューでの適用方法、言語別オーバーレイと明示的な例外を通じて安全に拡張する方法を定めています。

独断ではなく判断を重視：この標準の CC-* ルールは、結合度と凝集度、命名、小さなインターフェース、明示的なエラーといった長く通用する原則です。一方、関数の長さに厳格な上限を設ける、「コメントはコードの臭い」とする、DRY を絶対視するといった、根拠が曖昧な通説はそうではありません。Robert C. Martin の Clean Code（第 2 版、2025 年）と John Ousterhout の A Philosophy of Software Design は、関数のサイズとコメントについて、公開された議論の中で意見が対立しています（references/code-quality-operational-playbook.md § 14 を参照）。書籍の具体的な数値基準ではなく、ルール ID の意図を適用し、リファクタリングすべきでない場合を把握してください（同じ参考資料の § 14.3）。

---

クイックリファレンス

タスク	ツール／フレームワーク	コマンド	使用する場面
標準を引用する	CC-* ルール ID	N/A	PR レビューコメント、設計に関する議論、事後分析
フィードバックを分類する	CC-NAM、CC-ERR、CC-SEC など	N/A	「スタイル論争」を避け、フィードバックの一貫性を保つ
スタック固有の詳細を加える	言語別オーバーレイ	N/A	基本ルールが言語／フレームワークに対して一般的すぎる場合
例外を認める	免除記録	N/A	明示的なリスクを伴い、ルールに違反せざるを得ない場合
共有チェックリストを再利用する	assets/checklists/	N/A	製品に依存しないレビュー／リリース用チェックリストが必要な場合
ユーティリティパターンを再利用する	references/*-utilities.md	N/A	認証／ロギング／エラー／レジリエンス／テスト用の共有ユーティリティを抽出する場合

このスキルを使用する場面

• チームや言語をまたいでクリーンコードのルールを定義または適用する場合。
• 具体的なレビュー指摘やスキャナーの検出結果を CC-* ID に対応付ける場合。レビューのワークフローには software-code-review を使用してください。
• 自動化を構築する場合：リンター／CI ゲートを CC-* ID に対応付けます。
• 繰り返し発生するレビュー上の議論を解決する場合：ルール ID、適用範囲、例外について認識を合わせます。

このスキルを使用しない場面

• 詳細なセキュリティ監査 → CC-SEC-* の基本範囲を超える OWASP／SAST の詳細分析には、software-security-appsec を使用してください。
• レビューのワークフローの仕組み → PR のワークフロー、レビュアーの割り当て、フィードバックのパターンには、software-code-review を使用してください。
• リファクタリングの実行 → 段階的なリファクタリングパターンと品質ゲートには、qa-refactoring を使用してください。
• アーキテクチャ上の意思決定 → コードレベルのルールを超えるシステムレベルのトレードオフには、software-architecture-design を使用してください。

ワークフロー

1. 依頼が基本ルール、オーバーレイ、例外のどれに関するものかを判断します。
2. セキュリティ、レビュープロセス、リファクタリングの仕組みが実際の問題であれば、関連するスキルに案内します。
3. 新しい文言や自動化を提案する前に、既存の CC-* ルールを根拠として示します。ツールの検出結果は、ツールの重大度だけでなく、失敗の仕方に基づいて対応付けます。
4. 適用範囲と根拠を明示したうえで、該当する標準、オーバーレイ、または免除のパターンを適用します。
5. 長期的に有効な標準を追加または改訂する前に、ナビゲーション用の参考資料と照合します。

ルール適用チェックリスト

レビューで CC-* ルールを引用または適用する場合：

• ルール ID を明示的に引用している（言い換えではない）— 例：CC-SEC-01、CC-ERR-03（2 桁の CC-<CAT>-<NN>。カタログに存在する ID のみ対象 — python3 scripts/check_cc_ids.py [paths] は不明な ID があると失敗します）
• 適用範囲を明記している：ファイル、モジュール、サービス、またはリポジトリ全体
• リポジトリで特定の言語を使用しており、基本ルールが曖昧な場合、言語別オーバーレイを適用している
• ブロッキングか助言かを明記している：正確性／セキュリティに関する指摘はマージをブロックし、スタイルに関する指摘は助言とする
• アーキテクチャを変更しないと本当にルールを満たせない場合、免除の手順を記録している

意思決定ツリー：基本ルール、オーバーレイ、例外の選択

Feedback needed: [What kind of guidance is this?]
    ├─ Universal, cross-language rule? → Add/modify `CC-*` in `references/clean-code-standard.md`
    │
    ├─ Language/framework-specific nuance? → Add overlay entry referencing existing `CC-*`
    │
    └─ One-off constraint or temporary tradeoff?
        ├─ Timeboxed? → Add waiver with expiry + tracking issue
        └─ Permanent? → Propose a new rule or revise scope/exception criteria

---

任意：AI／自動化

リファクタリングの根拠ゲート。

コードが時代遅れに見えるという理由だけで、ルール違反を指摘してはいけません。コードが引き起こす保守上の問題を明示してください。たとえば、変更の重複、隠れた副作用、安全でない結合、読みにくい制御フロー、または測定された複雑性のホットスポットです。提案された書き換えに、動作を維持するテストも、変更リスクを具体的に低減する根拠もない場合は、安定しているものの扱いにくいコードをそのまま維持し、変更を増やすのではなく、範囲を絞った例外を記録してください。

• 自動化による検出結果はルールレベルの例に照らして整理し、優先度を割り当てる前にコードを確認してください。
• AI による提案は助言として扱い、人間のレビュアーがルールへの言及を添えて承認または却下してください（https://conventionalcomments.org/）。
• 新たなブロッキング対象の違反はリポジトリのベースラインと照合して判定してください。劣化や冗長性は、普遍的なしきい値ではなく、レビュー対象となる推移として追跡してください（メトリクスのガイダンス）。

AI 生成コードのレビュー

AI 生成コードには、同じ CC-* 標準を適用するとともに、次のパターンに特に注意してください。

パターン	CC-* との対応	検出方法
存在しないインポート	CC-SEC-05	npm info／pip index／型チェックが失敗する
古い API または非推奨の API	CC-DEP-01	コンパイラーの警告、変更履歴の確認
エラーパスの欠落	CC-ERR-01, CC-ERR-04	catch／finally がない、null ガードがない、タイムアウトがない
早すぎる抽象化	CC-FUN-06	呼び出し箇所が 1 つだけのラッパー、未使用のジェネリクス
自信満々だが誤ったコメント	CC-DOC-01, CC-DOC-02	実装と一致しない docstring
セキュリティ上のアンチパターン	CC-SEC-08, CC-SEC-03	クエリ内での文字列連結、トークンのハードコード
暗黙のフォールバックまたは空の catch	CC-ERR-01	エラーパスが、呼び出し元から失敗が見えないまま、もっともらしいデフォルト値を返す
アサーションの弱体化または削除	CC-TST-01, CC-TST-03	要件を逆にしてもテストが失敗しなくなっている
ヘルパーの重複またはスコープの拡大	CC-FUN-05, CC-FUN-06	既存の動作に並行するヘルパーが追加されている、または抽象化に 2 つ目の用途がない

エージェントの変更規律とリグレッションを検出するテストについては、coding-behavior.mdを参照してください。ハルシネーションの詳細な確認方法については、references/code-quality-operational-playbook.md § 11.3を参照してください。

---

ナビゲーション

リソース

• references/clean-code-standard.md — CC-* ルールの定義です。ルール ID を探したり引用したりする際は、最初に開いてください
• references/code-quality-operational-playbook.md — 運用プレイブック：LLM が生成したコードのレビュー、複雑さの管理、ピアレビューの統制、独断的なルール適用よりも判断を重視する方法（従来の RULE-01–13 は廃止済みです。§ 1 で CC-* への対応を示しています）
• references/working-effectively-with-legacy-code-operational-checklist.md — テストがない、または不十分なコードを安全に変更する方法（Feathers）
• references/refactoring-operational-checklist.md — 動作を維持するリファクタリングの手法と前提条件（Fowler）
• references/design-patterns-operational-checklist.md — GoF パターンが複雑さに見合う場合と、過剰設計になる場合
• references/functional-programming-patterns.md — Result/Either 型、pipe/compose、不変性、純粋関数、レール指向プログラミング、CC-* ルールとの対応
• references/code-complexity-metrics.md — 循環的複雑度／認知的複雑度、Halstead 指標、ネストの深さ、ツール（ESLint、Biome、Oxlint、SonarQube、Ruff）、リファクタリングのトリガー
• data/sources.json — レビュー、セキュリティ・バイ・デザイン、オブザーバビリティ、最新のツールに関する現在の外部参照（公式ドキュメントを優先）

テンプレート

• assets/checklists/backend-api-review-checklist.md
• assets/checklists/secure-code-review-checklist.md
• assets/checklists/frontend-performance-a11y-checklist.md
• assets/checklists/mobile-release-checklist.md
• assets/checklists/ux-design-review-checklist.md

ユーティリティパターン

• references/utility-patterns.md — 下記の具体的なユーティリティを使う前に、コードを重複させずユーティリティを切り出すべきか、またその方法を判断するためのガイド
• references/auth-utilities.md
• references/error-handling.md
• references/config-validation.md
• references/resilience-utilities.md
• references/logging-utilities.md
• references/observability-utilities.md
• references/testing-utilities.md
• references/llm-utilities.md

関連スキル

• ../software-code-review/SKILL.md — レビューワークフローと判断。CC-* ID を引用してください
• ../software-security-appsec/SKILL.md — 基本的な CC-SEC-* の範囲を超える、セキュリティの詳細な解説
• ../qa-refactoring/SKILL.md — リファクタリングの実行パターンと品質ゲート
• ../software-architecture-design/SKILL.md — システムレベルのトレードオフと境界

---

最新情報の確認手順

• 名前が指定されたリンターやスキャナーについては、検出事項を CC-* に対応付ける前に、公式のルール説明とプロジェクトで解決されるバージョンを確認してください。
• CI ゲートを提案する場合は、スキャナーが現在のベースラインと新規コードをサポートしているか確認し、ルールのカバレッジをリポジトリの既存チェックと比較してください。
• 選択したルールの対応付け、サポートされていないルールや移行リスク、および検証に使用した情報源を報告してください。

既知の落とし穴

• 「クリーンコード」をスタイル上の好みだけとして扱い、正確性、可観測性、セキュリティ、変更の安全性を無視すること。
• クリーンさを名目に、一律の抽象化ルールを強制し、間接性を高めて実行時の明瞭さを損なうこと。
• 安定した CC ルールの意図を維持せずに、言語固有のフォーマッターやリンターの見解を普遍的なガイダンスに混ぜること。
• 明示されたリポジトリのルール ID が別の指示を示しているのに、ツールのデフォルトによってチーム標準が暗黙に再定義されること。
• 静的なスタイルチェックの出力だけでコードを監査し、障害モード、データ境界、運用上のリスクを見落とすこと。

よくあるアンチパターン

• クリーンさの美学を満たすためだけに、具体的で理解しやすいコードを階層化された抽象化に置き換えること。
• 短い関数、DRY、命名規則を絶対視し、凝集性、局所性、ドメインの明瞭さを損なう場合でも適用すること。
• 境界を保ったり、時期尚早なフレームワーク化を避けたりするための現実的な重複を、「クリーンコード」を理由に阻止すること。
• ルールが保守性や安全性にとって重要な理由を説明せず、ルール ID を形だけのチェックリストにすること。
• ツール、ランタイム、チームのワークフローに合わせて調整せず、ある言語エコシステムの慣習を別のエコシステムにそのまま適用すること。

学びのループ

過去の決定や落とし穴が関連する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認するとき、または利用可能な代替ファイルとしてのみ learnings.md を使ってください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶しておく価値のあるパターン、防ぐべきミス、または意外だったドメイン知識に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを 1 つ追加してください。SKILL.md 自体は変更しないでください。