clean-code

クリーンコードとクリーンアーキテクチャ

最初に編集する前に：コンテキストを読み込む

セッション間で情報はすべて失われます。scripts/ と references/ は、このファイルがあるフォルダーを基準に解決されます。次の順に読み進めてください。些細な編集（誤字やコメント）の場合、この手順とレビュー用チェックリストは省略できます。

1. スタック。 .clean/context.json を確認します。ない場合は scripts/detect_stack.py を実行するか、マニフェストとファイル拡張子を確認します。
2. パック。 packs 内、または「次に読む」にある各パックをファイル読み込みツールで開きます（パック名を挙げるだけでは読み込んだことになりません）。ただし、pack_scopes が作業対象を除外しているフレームワークパックは除きます。手動で確認する場合：references/framework-map.md の clean-packs インデックスを参照します。該当するものがない場合は、適用に関する質問に回答します。
3. レイヤー。 .clean/architecture.md を確認します。「レイヤールール」を参照してください。
4. 決定事項。 .clean/decisions.md と .clean/ledger.md を確認します。記録された決定事項は確定済みです。進行中の取り組みは再開し、最初からやり直さないでください。
5. 構造。 作業対象領域の .clean/structure.md の行（パスで grep）を確認するか、scripts/map_structure.py --path <area> を実行します。手動で確認する場合は、フォルダーを一覧表示し、最も類似するファイルを2、3個開きます。
6. プロジェクトの指示。 AGENTS.md、CLAUDE.md、CONTRIBUTING.md、ARCHITECTURE.md、README.md を確認します。

競合がある場合は、優先順位の高いものを適用します：プロジェクトの指示、記録された決定事項、宣言済みのレイヤー、ローカルの規約、フレームワークパック、言語パック、このスキル。.clean/ を作成するのは init、audit、new-project のみです。通常のセッションでは既存の内容を読み込み、最後に保存するかどうかを提案します。

作業サイクル

1. 枠組みを定める：動作の変更、前提、最小限の対象範囲、成功の確認方法を明確にします。曖昧さが実装に影響する場合に限り、質問します。
2. 読む：周辺のコード、命名、テスト、エラー処理のスタイル、フレームワークの慣習を確認し、まず既存の実装を検索します。
3. 配置する：担当する単位と、どの境界のどちら側に置くかを決めます。
4. 必要な箇所だけ編集する：変更するすべての行が依頼に沿っていることを確認します。対象を絞って編集し、ファイル全体を再生成しないでください。変更によって不要になったものは削除します。
5. 検証する：最も範囲を絞った有意義なチェックを行い、次にリスクレベルに応じて必要な確認を実施します（review-checklist.md）。バグの場合は、まず再現テストを作成します。リファクタリングの場合は、変更前と変更後にテストを行います。何かを実行せずに成功を主張してはいけません。
6. 差分をレビューする：references/review-checklist.md を使い、自分で確認する項目も含めてレビューします。

常に適用するルール

配置。 役割に応じてフォルダーを決めます。パックの役割とプロジェクトの構成に従い、類似ファイルの配置を踏襲します。一貫した配置場所がない場合に限って新しいファイルを作成し、その場合はインポート、エクスポート、登録、ルート、DI、ビルド設定まで完全に組み込みます。参照されていないファイルはデッドコードです。リポジトリのルートや現在のディレクトリを既定の配置場所にしないでください。兄弟ファイルの派生版（_v2、_new、_final、_copy）を作成したり、雑多なファイル置き場（utils、helpers、common）を増やしたりせず、概念に合った名前を付けます。アクセス修飾子は必要最小限にします。

どの規模でも、1つの単位には1つの役割だけを持たせます。 説明するのに「および」が必要ですか？ それなら分割します。解析、ドメインルール、永続化、外部呼び出し、プレゼンテーション、配線は、それぞれ別の配置場所に分けます。オーケストレーターは協力要素を順序立てて実行し、ビジネスルールは持ちません。新しい振る舞いは、開いているファイルではなく、それを担う単位に追加します。現時点で同一であっても、異なる担当者のコードは分離します。

コードは最小限にします。 コードを書く前に、最初に「はい」と答えた時点で止めます。不要ですか（YAGNI）？ 何も書きません。コードベースにすでにありますか？ 再利用します。標準ライブラリ、プラットフォーム、またはインストール済みの依存関係で実現できますか？ それを使います。1行で済みますか？ その1行を書きます。それ以外の場合も、必要最小限だけを書きます。検証、エラー処理、セキュリティ、アクセシビリティを削ってはいけません。

コード。 名前はプロジェクトの用語に沿って意図を明確にし、1つの概念に1つの名前を使います。関数は1つのことだけを、1つの抽象化レベルで行い、引数は少なくし、フラグ引数は使いません。コメントには理由を簡潔に記します。エラーを握りつぶしてはいけません。判断できる場所で処理し、原因を保持し、想定される結果は値としてモデル化します。テストではTDDの三原則とF.I.R.S.T.に従い、失敗するテストを弱めたり、スキップしたり、削除したりしてはいけません。すべてのAPIについて、記憶に頼らず、インストール済みバージョンを.clean/context.jsonで確認します。重複をなくすのは、一緒に変更する必要があるコピーに限ります（DRY）。フォーマッターに書式設定を任せます。設計の優先順位は、テストが成功すること、知識が重複していないこと、意図が表現されていること、要素が最小限であることです。

セキュリティ。 信頼境界ごとに入力を検証してエンコードし、クエリはパラメーター化します。認可は保護対象の操作のそばに置き、シークレットをコード、コミット対象の設定、ログに含めてはいけません。

レイヤーを宣言している場合のレイヤールール

.clean/architecture.mdでレイヤーが宣言されている場合は厳守します。scripts/check_boundaries.pyで確認するか、変更したファイルのインポートを読み、各レイヤーの名前を確認します。宣言されていない場合は、フレームワークパックの標準的な構成に従います。これらのルールは判断の指針です。

• 依存関係ルール：ソースコードの依存関係は、内側、つまりより上位のポリシーのみを参照します。内側の要素は、外側の要素（クラス、関数、変数、注釈、データ形式）の名前を一切参照しません。
• ビジネスルールを最上位に置きます。データベース、Web、UI、フレームワーク、デリバリー機構は、ポリシーが所有するインターフェースの背後にある詳細です。
• SQLはデータアクセス層に置きます。行データ、ORM型、フレームワークのリクエスト／レスポンスオブジェクトを内側に渡してはいけません。内側に合わせた単純な構造を渡します。
• ビジネスオブジェクトをフレームワークの基底クラスから派生させたり、フレームワークの型を注釈に使ったりしてはいけません。依存性注入の配線はmainに置きます。
• コンポーネントグラフは非循環にし、安定性の高い方向へ依存させます。テストしにくいものとテストしやすいものを分離し、先回りした境界設定はしません。

コマンド

/clean-code <argument>（または$clean-code、@clean-code、/skill:clean-code）と自然言語の指示は、いずれも同じように処理されます。

引数	従う内容
init（別名questions、"interview me"）	references/init.md
audit	references/audit-report.md。コードは変更しません
clean-up	.clean/ledger.mdとともにreferences/project-refactor.mdに従います。台帳がない場合は監査（ファイル数）を提案し、同意を待ちます
new-project <description>	references/new-project.md
plan <task>	references/plan.md。何も編集しません
review [files]	references/review-checklist.mdとThe review Commandに従います。何も編集しません
compress [files]	references/compress.mdに従います。管理対象のブロックには触れません
（なし）	このファイル。複数ステップまたは再開可能な作業ではreferences/session-protocol.mdに従います

読み込む資料

タスクに必要なものだけを、references/から読み込みます。長いファイルは「目次」を参照してください。

タスク	読む資料
レビュー、エージェントのにおい A1～A10	review-checklist.md
リスクレベル：LOW、MEDIUM、HIGH	review-checklist.mdの「Risk Levels」
コメントの整理（C1～C5、G12）	comments.md
アーキテクチャスタイル、デザインパターン、データアクセス	patterns.md
新しい依存関係	framework-map.md、「Dependencies And Package Idioms」
新しい境界、レイヤー、フレームワーク、データベース	architecture.md
テスト	tests.md
並行処理	concurrency.md
セキュリティ、信頼境界、データとオブジェクト、パフォーマンス	principles.md
においの命名またはトリアージ	smell-triage.md；ID（G17、N7、T5など）はchapter-map.md
名前が付いたルールをそのまま確認	canon.md
次のセッションに引き継ぐ状態	memory-protocol.md
実例、テンプレート	examples.md
ホストフック、コマンド、インストール先	host-matrix.md
スクリプトdetect_stack.py、scan_repo.py、map_structure.py、check_boundaries.py、check_compression.py：フラグ、検出結果、終了コード。出力は証拠であり、判定ではありません	tools.md

対応範囲モード

外科的対応（デフォルト）：変更範囲を最小限にします。無関係なにおいは報告し、依頼された結果に必要な場合（「テストスイートを通す」など）を除き、修正しません。修正は最小限にとどめ、テストを弱めず、別途報告します。 キャンペーン対応（明示的な依頼がある場合のみ）：references/project-refactor.mdを参照します。リファクタリングの一括作業中に動作を変更してはいけません。

完了チェックリスト

• 最初の編集を行う前に、必要な資料を読み込みます。
• タスクを解決し、変更した各行がタスクに対応し、上記のルールに従っていることを確認します。
• 新しいファイルは役割に応じた場所に配置し、適切に接続します。同種の別ファイル、重複、未使用コード、一時ファイル、デバッグ出力を追加しません。
• 変更をテストでカバーします。テストを弱めません。
• 検証結果を正直に報告します。リスクレベル、結果、実行できなかった内容、残るリスクを含めます。
• 長期的な決定事項を.clean/decisions.mdに記録します。ファイルを追加または移動し、.clean/が存在する場合は、scripts/map_structure.py --writeを実行します。