clean-code

Clean Code - 実践的な AI コーディング標準

重要スキル - 簡潔に、直接的に、解決策に集中してください。

---

基本原則

原則	ルール
SRP	単一責任 - 各関数/クラスは1つのことだけを行う
DRY	同じことを繰り返さない - 重複を抽出して再利用する
KISS	シンプルに保つ - 動作する最もシンプルな解決策を選ぶ
YAGNI	必要になるまで作らない - 使われない機能を作らない
Boy Scout	見つけたときよりもきれいにしてから離れる

---

命名ルール

要素	規約
変数	意図が分かる名前にする: n ではなく userCount
関数	動詞 + 名詞: user() ではなく getUserById()
真偽値	疑問形にする: isActive、hasPermission、canEdit
定数	SCREAMING_SNAKE: MAX_RETRY_COUNT

ルール: 名前を説明するためにコメントが必要なら、名前を変更してください。

---

関数のルール

ルール	説明
小さく	最大20行、理想は5〜10行
一つのこと	一つのことだけを行い、それをうまくこなす
一つの抽象度	関数内の抽象化レベルは1つにする
少ない引数	最大3つの引数、できれば0〜2個
副作用なし	入力を予期せず変更しない

---

コード構造

パターン	適用
ガード節	エッジケースは早期リターンで処理する
ネストより平坦	深いネストを避ける（最大2階層）
合成	小さな関数を組み合わせる
同置	関連するコードを近くに置く

---

AI コーディングのスタイル

状況	対応
ユーザーが機能を求める	そのまま直接書く
ユーザーがバグを報告する	説明せず、修正する
要件が不明確	推測せず、確認する

---

アンチパターン（やってはいけないこと）

❌ パターン	✅ 修正
すべての行にコメントを付ける	自明なコメントは削除する
一行のためのヘルパー	コードをインライン化する
2つのオブジェクトのためのファクトリー	直接インスタンス化する
関数1つだけの utils.ts	コードは使用する場所に置く
「まず import して…」	説明せず、コードを書く
深いネスト	ガード節
マジックナンバー	名前付き定数
神関数	責任ごとに分割する

---

🔴 いかなるファイルも編集する前に（まず考える！）

ファイルを変更する前に、次の点を自問してください:

質問	理由
このファイルをインポートしているのは何か？	壊れる可能性がある
このファイルは何をインポートしているか？	インターフェースの変更
このファイルをカバーしているテストは何か？	テストが失敗する可能性がある
これは共有コンポーネントか？	複数の箇所に影響する

クイックチェック:

File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures

🔴 ルール: ファイルと依存するすべてのファイルを、同じタスク内で編集してください。 🔴 壊れたインポートや更新漏れを残さないでください。

---

まとめ

やること	やらないこと
コードを直接書く	チュートリアルを書く
コードに自己文書化させる	自明なコメントを追加する
バグはすぐに修正する	修正の前に説明する
小さなものはインライン化する	不要なファイルを作る
名前は明確に付ける	略語を使う
関数は小さく保つ	100行以上の関数を書く

覚えておいてください: ユーザーが求めているのは、動作するコードであり、プログラミングの講義ではありません。

---

🔴 完了前のセルフチェック（必須）

「タスク完了」と言う前に、次を確認してください:

チェック	質問
✅ 目標を達成したか？	ユーザーが求めたことを正確に行ったか？
✅ ファイルを編集したか？	必要なすべてのファイルを変更したか？
✅ コードは動くか？	変更をテスト/検証したか？
✅ エラーはないか？	Lint と TypeScript は通っているか？
✅ 忘れていることはないか？	見落としたエッジケースはないか？

🔴 ルール: 1つでもチェックに失敗した場合は、完了する前に修正してください。

---

検証スクリプト（必須）

🔴 重要: 各エージェントは、作業完了後に自分のスキルのスクリプトだけを実行してください。

エージェントとスクリプトの対応表

エージェント	スクリプト	コマンド
frontend-specialist	UX Audit	python ~/.claude/skills/frontend-design/scripts/ux_audit.py .
frontend-specialist	A11y Check	python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialist	API Validator	python ~/.claude/skills/api-patterns/scripts/api_validator.py .
mobile-developer	Mobile Audit	python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .
database-architect	Schema Validate	python ~/.claude/skills/database-design/scripts/schema_validator.py .
security-auditor	Security Scan	python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialist	SEO Check	python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialist	GEO Check	python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizer	Lighthouse	python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineer	Test Runner	python ~/.claude/skills/testing-patterns/scripts/test_runner.py .
test-engineer	Playwright	python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>
任意のエージェント	Lint Check	python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .
任意のエージェント	Type Coverage	python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .
任意のエージェント	i18n Check	python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .

❌ 誤り: test-engineer が ux_audit.py を実行する ✅ 正しい: frontend-specialist が ux_audit.py を実行する

---

🔴 スクリプト出力の処理（読む → 要約する → 確認する）

検証スクリプトを実行する場合、必ず次の手順に従ってください:

1. スクリプトを実行し、すべての出力を取得する
2. 出力を解析し、エラー、警告、成功項目を特定する
3. 次の形式でユーザーに要約する:

## Script Results: [script_name.py]

### ❌ Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2

### ⚠️ Warnings (Y items)
- [File:Line] Warning description

### ✅ Passed (Z items)
- Check 1 passed
- Check 2 passed

**Should I fix the X errors?**

4. 修正する前にユーザーの確認を待つ
5. 修正後 → スクリプトを再実行して結果を確認する

🔴 違反: スクリプトを実行したのに出力を無視することは、タスク失敗とみなされます。 🔴 違反: 確認せずに自動修正することは許可されていません。 🔴 ルール: 必ず 出力を読む → 要約する → 確認する → その後で修正する、の順序を守ってください。