CLAUDE.md

AI Agent 実行ガイドライン

最重要：自律的に判断・実行。確認は最小限に。

コア原則

• 即座実行 — 既存ファイルの編集は迷わず着手
• 大規模変更のみ確認 — 影響範囲が広い場合に限定
• 品質と一貫性の維持 — 自動チェックを徹底
• 事実確認 — 情報源を自ら確認し、憶測を事実として述べない
• 既存優先 — 新規作成より既存ファイルの編集を優先

基本設定

• 言語：日本語（技術用語は英語）
• スペース：日本語と半角英数字間に半角スペース
• 文体：ですます調、句読点は「。」「、」
• 絵文字：過度な絵文字の利用は避ける
• Cursor では .windsurf/ を除外
• Windsurf では .cursor/ を除外

略語解釈

• y = はい（Yes）
• n = いいえ（No）
• c = 続ける（Continue）
• r = 確認（Review）
• u = 元に戻す（Undo）

実行ルール

即座実行（確認不要）

• コード操作：バグ修正、リファクタリング、パフォーマンス改善
• ファイル編集：既存ファイルの修正・更新
• ドキュメント：README、仕様書の更新（新規作成は要求時のみ）
• 依存関係：パッケージ追加・更新・削除
• テスト：単体・統合テストの実装（TDD サイクルに従う）
• 設定：設定値変更、フォーマット適用

確認必須

• 新規ファイル作成：必要性を説明して確認
• ファイル削除：重要ファイルの削除
• 構造変更：アーキテクチャ、フォルダ構造の大規模変更
• 外部連携：新 API、外部ライブラリ導入
• セキュリティ：認証・認可機能の実装
• データベース：スキーマ変更、マイグレーション
• 本番環境：デプロイ設定、環境変数変更

実行フロー

1. タスク受信
   ↓
2. 即座実行 or 確認要求を判定
   ↓
3. 実行（既存パターン準拠）
   ↓
4. 完了報告

作業完了報告のルール

完了報告の種類

1. 完全完了時の合い言葉

作業が完全に完了し、これ以上継続するタスクがない場合は一語一句違えずに以下を報告する：

May the Force be with you.

使用条件（すべて満たす必要あり）：

• ✅ 全てのタスクが 100% 完了
• ✅ TODO 項目が全て完了（TodoWrite ツールで管理している TODO リストが空であること）
• ✅ エラーがゼロ
• ✅ これ以上新しい指示がない限り続けられるタスクがない

禁止事項：

• ❌ TODO リストに未完了タスクがある場合
• ❌ 「次のステップ」「残っているタスク」「現在残っている主なタスクは：」など継続予定の記述をした場合
• ❌ Phase や Step など段階的な作業で未完了の段階が残っている場合
• ❌ 自分の回答に具体的な残作業リストを明記した場合

2. 部分完了時の報告

作業が部分的に完了し、続きのタスクがある場合は以下のテンプレートを使用：

## 実行完了

### 変更内容

- [具体的な変更点]

### 次のステップ

- [推奨される次の作業]

継続必要時の動作

合い言葉の条件を満たさない場合：

• 合い言葉は使用しない
• 進捗状況と次のアクションを明示
• 残タスクがある場合は明確に伝える

開発手法

TDD サイクル

開発時は Test-Driven Development (TDD) のサイクルに従います：

1. Red（失敗）

   • 最もシンプルな失敗するテストを書く
   • テスト名は動作を明確に記述
   • 失敗メッセージが分かりやすいことを確認

2. Green（成功）

   • テストを通す最小限のコードを実装
   • この段階では最適化や美しさは考慮しない
   • とにかくテストを通すことに集中

3. Refactor（改善）

   • テストが通った後でのみリファクタリング
   • 重複を排除し、意図を明確に
   • 各リファクタリング後にテスト実行

変更管理

変更は以下の 2 種類に明確に分離します：

• 構造変更（Structural Changes）

  • コードの配置・整理・フォーマット
  • 動作は一切変更しない
  • 例：メソッドの並び替え、インポート整理、変数名変更

• 動作変更（Behavioral Changes）

  • 機能の追加・修正・削除
  • テスト結果が変わる変更
  • 例：新機能追加、バグ修正、ロジック変更

重要：構造変更と動作変更を同一コミットに含めない

コミット規律

コミットは以下の条件をすべて満たした時のみ実行：

• ✅ すべてのテストがパス
• ✅ コンパイラ/リンターの警告がゼロ
• ✅ 単一の論理的作業単位を表現
• ✅ コミットメッセージが変更内容を明確に説明

推奨事項：

• 小さく頻繁なコミット
• 各コミットは独立して意味を持つ
• 後から履歴を追いやすい粒度

リファクタリングルール

リファクタリング時の厳格なルール：

1. 前提条件

   • すべてのテストが通っている状態でのみ開始
   • 動作変更とリファクタリングを混在させない

2. 実行手順

   • 確立されたリファクタリングパターンを使用
   • 一度に一つの変更のみ
   • 各ステップ後に必ずテスト実行
   • 失敗したら即座に元に戻す

3. よく使うパターン

   • Extract Method（メソッド抽出）
   • Rename（名前変更）
   • Move Method（メソッド移動）
   • Extract Variable（変数抽出）

実装アプローチ

効率的な実装のための優先順位：

1. 最初のステップ

   • 最もシンプルなケースから着手
   • 「動くこと」を最優先
   • 完璧さより進捗を重視

2. コード品質の原則

   • 重複を見つけたら即座に排除
   • 意図が明確なコードを書く
   • 依存関係を明示的に
   • メソッドは小さく、単一責任に

3. 段階的な改善

   • まず動くものを作る
   • テストでカバー
   • その後で最適化

4. エッジケースの扱い

   • 基本ケースが動いてから考慮
   • 各エッジケースに対応するテスト追加
   • 段階的に堅牢性を向上

品質保証

設計原則

• 単一責任の原則を遵守
• インターフェースによる疎結合
• 早期リターンで可読性向上
• 過度な抽象化は避ける

効率性最適化

• 重複作業の自動排除
• バッチ処理の積極活用
• コンテキストスイッチ最小化

一貫性維持

• 既存コードスタイルの自動継承
• プロジェクト規約の自動適用
• 命名規則統一の自動実行

自動品質管理

• 変更前後の動作確認実行
• エッジケース考慮の実装
• ドキュメント同期更新

冗長性の排除

• 繰り返し処理は必ず関数化
• 共通エラーハンドリングの統一
• ユーティリティ関数の積極活用
• 重複ロジックの即座の抽象化

ハードコーディング禁止

• マジックナンバーは定数化
• URL、パスは設定ファイルへ
• 環境依存値は環境変数で管理
• ビジネスロジックと設定値の分離

エラーハンドリング

• 実行不可能時：代替案 3 つ提示
• 部分実行可能時：可能部分を先行実行、残課題を明示

実行例

• バグ修正：TypeError 発見 → 即座に型エラー修正
• リファクタリング：重複コード検出 → 共通関数化
• DB 変更：スキーマ更新が必要 → 確認要求「テーブル構造を変更しますか？」

継続改善

• 新パターン検出 → 即座に学習・適用
• フィードバック → 次回実行に自動反映
• ベストプラクティス → 随時更新

制約事項

Web 検索の制約

• WebSearch ツールは使用禁止 — 利用することは禁止です
• 代替手段：gemini --prompt "WebSearch: <検索クエリ> — Gemini 経由の検索