Claude Codeで良い結果を得る

• ここ数か月、さまざまな LLMプログラミングエージェント を試した結果、Claude Codeが最も満足度の高いツールだった
• Claude Codeのおかげで、短期間に約 12本のプログラムとプロジェクト を作成でき、普段なら時間の都合で着手しなかった作業にも取り組めるようになった
• 成功裏に活用するには、明確な仕様書の作成、プロジェクト構造・ビルド・lintの実行方法をまとめた文書の提供、AI自身へのコードレビュー依頼、そして個人用の グローバルエージェントガイド の運用が鍵となる
• AIが書いたコードはしばしば 不正確または非効率 になりうるため、すべてのコードとテストケースを必ず自分で確認し、不足しているテストは自分で追加するか、AIに作成させたうえで再レビューする
• 付録として公開されたグローバルエージェントガイドには、段階的な実装計画、テスト駆動開発、シンプルさ・明確さ・実用性を重視する哲学、品質基準、問題解決プロセスなどの 詳細な開発指針 が含まれている

---

Claude Code活用の経験と効果

• ここ数か月、さまざまな LLMプログラミングエージェント を試し、とくにClaude Codeの使用体験が最も優れていた
• まったく問題がないわけではないが、短期間で12本以上のプログラムやプロジェクトを完成させることができた
• Claude Codeなしで、同じ期間内にこれらすべての作業をこなすのはほぼ不可能だっただろう
• 多くは、時間がかかるという理由で、そもそも試すことさえしなかったはずのプロジェクトだった

Claude Code活用戦略

• 明確な仕様書を作成する
  • プロジェクト開始前に、要件と文脈を明確に文書化してエージェントに渡す
  • これにより、コード作成の方向性と範囲を明確にする
• プロジェクト構造を文書化する
  • ビルド、lint、テストの実行方法を含む文書を用意する
  • エージェントがコードベースをより効果的に探索し、作業できるようになる
• エージェントにコードレビューを依頼する
  • Claude Codeに自分が生成したコードを直接レビューさせ、想定外の改善点やバグを見つける
• 個人用グローバルガイドを活用する
  • 問題解決のアプローチ、TDDの適用、シンプルさ・明確さの維持、試行回数の制限（3回）など、個人ルールを記した ~/.claude/CLAUDE.md により、一貫した開発プロセスを維持する

LLMが書いたコードの検証

• AI生成コードにはしばしば 論理エラー、性能低下、不完全なテスト などの問題がある
• 著者はすべてのコードを 手動でレビュー し、動作を確認する
  • 欠けているテストケースは自分で追加する
  • あるいはAIに作成を依頼し、その後コードとテストを再確認する
• プロフェッショナルな環境では、PRに自分の名前が入る以上、最終的な品質責任は自分にある と強調している

個人用「グローバル」エージェントガイドの主な内容

このガイドは ~/.claude/CLAUDE.md ファイルで管理している

• 哲学と中核原則

  • 段階的に進める: 小さな単位で変更し、常にコンパイルとテストを通す
  • 既存コードを学ぶ: 実装前にコードのパターンを分析し、計画を立てる
  • 実用性優先: プロジェクトの状況に応じた柔軟なアプローチ
  • 明確さ優先: 読みやすく意図が明白なコードを重視し、不要なトリックを避ける

• シンプルさの定義

  • 関数・クラスは単一責任
  • 早すぎる抽象化は避ける
  • 複雑さを減らし、説明を必要としないコードを目指す

• 作業プロセス

  • 1. 企画と段階設定:
    • 複雑な作業は3〜5段階に分けて IMPLEMENTATION_PLAN.md に記録する
    • 各段階の目標、成功基準、テストケース、進捗状況を明記する
  • 2. 実装フロー:
    • 理解 → テスト作成（赤） → 最小実装（緑） → リファクタリング → コミット
  • 3. 3回試してだめなら再評価:
    • 失敗時は試行内容とエラー、原因を記録する
    • 代替案を探る（2〜3通りのアプローチ）
    • 根本的な設計や問題分解を見直す
    • 別のパターンや機能を試す

• 技術標準

  • コンポジション優先、依存性注入を活用する
  • インターフェースを使う、テストしやすさを確保する
  • 明示的なデータフロー
  • TDDを推奨し、テストの無効化は禁止

• コード品質ルール

  • すべてのコミットでコンパイル成功、テスト通過、新機能のテスト追加、コードスタイル遵守を満たす
  • コミット前にフォーマッタ・リンターを実行し、変更点をセルフレビューし、「なぜ」を説明するコミットメッセージを書く

• エラー処理

  • 早期失敗と具体的なメッセージ
  • デバッグに必要なコンテキストを提供
  • 適切なレベルで例外処理し、例外の隠蔽は禁止

• 意思決定基準

  • 1. テストしやすさ
  • 2. 6か月後でも理解できる可読性
  • 3. プロジェクトのパターンとの一貫性
  • 4. シンプルさ
  • 5. 変更しやすさ

• プロジェクト統合

  • 類似機能を3つ以上分析する
  • 既存のパターン・ライブラリを再利用する
  • 同じテストユーティリティを使う
  • 新しいツールの導入には強い理由が必要

• 品質ゲート

  • すべてのテストに合格
  • プロジェクトのルールを順守
  • リンター警告なし
  • コミットメッセージが明確
  • 実装が計画と一致している
  • TODOにはissue番号を含める

• テスト指針

  • 実装ではなく 振る舞い 中心のテスト
  • 可能ならテストごとにアサーションは1つ
  • シナリオを説明する明確な名前
  • 既存のテストユーティリティを再利用する
  • テストは決定論的であるべき

• 絶対禁止

  • --no-verify でフックを回避する
  • テストを無効化する
  • コンパイルできないコードをコミットする
  • 検証のない推測

• 必ず実施すること

  • 段階的なコミット
  • 文書を継続的に更新する
  • 既存実装から学ぶ
  • 3回失敗したらアプローチを再評価する

Claude Codeで制作したオープンソースプロジェクト

• HTML/XML認識リバースプロキシ (cdzombak/xrp)
• VS Code Solarizedテーマ（ライト/ダーク） (cdzombak/dzsolarized-vscode)
• FlickrフォトストリームRSSジェネレーター (cdzombak/flickr-rss)
• Lychee写真ライブラリ用メタデータツール (cdzombak/lychee-meta-tool)
• macOSスクリーンロック状態のMQTTレポート (cdzombak/macos-screenlock-mqtt)
• Lychee Bird Buddy写真タイトル自動設定 (cdzombak/lychee-birb-title)
• ローカルLLMベースの写真自動分類 (cdzombak/lychee-ai-organizer)
• macOS向けソフトウェア一括インストール自動化 (cdzombak/mac-install)
• RSSサービスプロジェクト (cdzombak/rss.church)
• Flickr写真の全件/選択的エクスポートとメタデータ保持 (cdzombak/flickr-exporter)
• 静的HTMLギャラリージェネレーター (cdzombak/gallerygen)