Claude.mdの育て方

Transcript

1. CLAUDE.mdの育て方 CLAUDE.mdの育て方 Jamboカンファレンス@渋谷 徳永 悠 2025/01/12
2. 自己紹介 徳永 悠 Yu Tokunaga 新卒 シェアサイクル「ダイチャリ」 バックオフィス部門 👉 システム開発に触れる エンジニアへ転身 SES企業にて1年間経験 2025年1月〜現在 現職  Swift / Flutter (CtoCアプリ開発)  インフラ
3. 本日の流れ チームが直面する課題 CLAUDE.mdという解決策 開発サイクルでの育て方（4段階） 運用のポイントと効果 今後の展望
4. チームが直面する課題 🔴課題①：アーキテクト決定者への負 荷集中 • アーキテクチャを決めたエンジニアにレビュー が集中 • ボトルネックになる • スケールしない ⚠️課題②：負荷分散のジレンマ レビュアーを増やす ↓ コード品質にばらつき ↓ 保守性が低下 ↓ 徐々に生産性が低下 ❓ どうすれば品質を保ちながらスケールできるか？
5. CLAUDE.mdという解決策 コンセプト：開発サイクルで気づきを得て改善し続ける 改善サイクル  CLAUDE.md (Single Source of Truth)  開発サイクルで使用 ①コード生成 ②仕様書レビュー ③ローカルレビュー ④GitHub Actions  各サイクルで 気づきを得る  CLAUDE.mdに反映 (ルール追加・修正)
6. 育て方① コード生成時  どんなAIでもOK: Claude ChatGPT Gemini  やること 1 コード生成 ルールに基づいた実装をリクエスト 2 生成コード確認 意図通りかチェック。ここで違和感に気づく   改善アクション 気づいたルールの不足や曖昧さを CLAUDE.mdに反映  この工程で得られる気づき 「このAIは依存方向を間違えやすい」 → ルールをもっと明確に書こう 「エラーハンドリングのパターンが不統一」 → 実装例を追加しよう 「命名規則が曖昧で解釈がブレる」 → 具体例を増やそう
7. 育て方② 仕様書レビュー  対象: 仕様書そのもの $ /spec-review  仕様レビューで見つかった パターンをCLAUDE.mdに反映  「既存実装チェックで毎回同じ指摘が...」 → 『既存コード調査必須』をルー ル化  「仕様段階で防げるバグパターン発見」 → チェック項目に追加  この工程で得られる気づき 改善アクション カスタムコマンドのチェック項目  ルール準拠チェック CLAUDE.mdのルールに従っているか  既存実装との整合性チェック 再利用可能性（定数、Utils等） 重複実装の防止 $ /spec-review Analyzing specifications... ✅ ルール準拠: OK ⚠️ 提案: 既存のUserUtilsが使えそうです ❌ エラー: 依存方向が逆です (Domain -> Infra) Terminal
8. 育て方③ ローカルレビュー  対象: 生成されたコード（仕様参照）  /local-diff-review  この工程で得られる気づき 「実装中に『あれ、これどう書くんだっけ？』 → その場でCLAUDE.md に実装例を追加」 「ローカルで試して分かった非効率なルール → ルールを削除・緩和」 改善アクション  実装中の気づきを CLAUDE.mdに反映  pre-commit  Claude Hooks 問題：硬直的 • 毎回走ると時間がかかる • 結果：逆に生産性が落ちる • 問題：必ずしもやる必要がない時がある • すべての変更に対して柔軟性に欠ける •  Claude Code カスタムコ マンド 推 奨 ✅ 任意実行なので自由度がある • 不要であれば叩く必要なし • エンジニアの判断に委ねる •
9. 育て方④ GitHub Actionsでの自動レビュー 自動レビューフロー  仕組み 🔄 PR作成時に自動実行 🤖 CLAUDE.md基準で自動レビュー 💬 指摘事項をPRに直接コメント  人間の役割 👤 他の人のPRを見て、ルールが採用されているか確認  改善アクション: チーム全体の傾向からCLAUDE.mdを改善  この工程で得られる気づき 「他の人のPRで同じ指摘が繰り返される → チーム全体で必要なルールとして追加」 「自動レビューで誤検知が多い → ルールの表現を改善」      PR作成  Actions自動実行  指摘事項をコメント  人間が確認  CLAUDE.md更新
10. 実際に効果があったルール  アーキテクチャ  構造関連  コーディング  実装パターン  ビジネス関連 アーキテクチャの依存方向 • 各レイヤーの責務定義 • ディレクトリ構造の統一 • ファイル配置ルールの明確化 • コメント規則の標準化 • 命名規則（変数・関数） • 各レイヤーごとの実装例 • エラーハンドリングの統一 • ドメイン固有ルールの定義 • 業務制約の明文化 •
11. 運用上のポイント 【従来】 人  人  Dev   Rev  指摘  指摘が属人的になり、同じ指摘が繰り返される 【導入後】 人  CLAUDE.md  人    RULE   Auto    指摘をルール化し、次回から自動適用  人格ではなくルールを議論できる  ポイント①：ドキュメントの同期 CLAUDE.md = AGENTS.md = GEMINI.md  AI間で出力がばらつかないよう、同期指示を明記する  ポイント②：レビューフローの変化
12. 導入後の変化（体感ベース）  レビュー負荷の分散 課題①の解決 ✔ CLAUDE.mdが共通基準として機能 ✔ アーキテクト以外もレビュー可能に ✔ ボトルネックが解消 ✔  保守性の下振れ抑制 課題②の解決 ✔ コード品質の最低ラインが保証 ✔ 開発サイクルでチェックが入る ✔ レビュアーが増えても品質が安定 ✔  ビジネスインパクトに集中 New Value 副次的効果 ✔ 実装の細部に時間を取られない ✔ 可処分時間が増える ✔ 本質的な価値創造に投下できる ✔
13. 現在の課題と対策  課題① ルールの目的を明確化 ルール毎に「なぜ必要なのか」とい う目的と、削除条件を明記します。 例：「テスト独立性確保のため」 戦略が変われば見直し対象とする  課題② メンテナーの育成 CLAUDE.mdを継続的に育てられる 人材を増やし、定期的なリファクタ リングを実施します。 不要ルールの削除 矛盾の解消・新パターン追加  課題③ 継続的な改善 属人化を防ぎ、チーム全体でレビュ ー文化を醸成するフローを確立しま す。 メンテナンスフローの定着 レビューを通じたルールの改善
14. 活用方法  0 → 1（新規プロジェクト） 1 まずCLAUDE.mdを書く アーキテクチャ、構成、責務、実装例 2 いきなりプロジェクトを開始しない 3 CLAUDE.mdを書いてから実装開始 4 開発サイクルで使いながら育てる  1 → 10（既存プロジェクト） 1 PRのコメントをMCPで取得 2 パターン化 → コード規約にする 3 CLAUDE.mdに追加 4 開発サイクルで検証・改善  具体例: ・変数名が曖昧 → 命名規則として明文化 ・エラー処理不統一 → パターン追加  まとめ 開発サイクルで気づきを得て、CLAUDE.mdに反映し続ける 🎯 品質を保ちながら、チームをスケールさせる
15. 🙏 ご清聴ありがとうございました