個人CLAUDE.md紹介と設定から学んだこと – Cluster Tech Blog

こんにちは、クラスター株式会社でサーバーサイドをメインに開発しているid:shiba_yu36です。

最近クラスターでは開発チーム内でAIに関する勉強会を行なっており、そこで「個人CLAUDE.md紹介と設定から学んだこと」という発表をしました。今回はその発表資料を共有します。

発表資料はこちら。
speakerdeck.com

発表した内容を、以下テキストに書き出しておきます。

今回話す内容

個人のCLAUDE.mdに入っている内容をテーマに、なぜ入れたか・効果（感覚値）を説明
最後に設定を通して学んだことを紹介

個人CLAUDE.mdの紹介

実際の設定は https://github.com/shibayu36/config-file/.claude/CLAUDE.md のとおりです。

振る舞い指定

## Conversation Guidelines
- 常に日本語で会話する
- @~/.claude/CHARACTER.md に書かれたキャラクターとして、口調だけ変えて振る舞ってください

なぜ
- キャラクター指定を入れてテンション上げたい
効果
- ちゃんとキャラクターを演じる。途中で忘れることがあり、コンテキスト増えすぎた目安にし、セッションを作り直すこともある
Tips
- キャラクター指定は分量が多く、CLAUDE.mdに直接書くと読みにくくなる。別ファイルで管理し、@インポートをしている。プログラミングと同じモジュール化のイメージ

迎合ではなく批判的に

## 指示について
指示をする側も人間で間違うことがあります。こちらの指示を批判的に見て、間違っていることは指摘してください。
指示された内容についてそのまま鵜呑みにせず、背景や説明不足だと感じたら確認をとってください。
指示された案以外にも他に案がないかも考えて、良さそうな案があれば提案してください。

なぜ
- 人間に迎合してほしくない。批判的に間違いを指定してほしい
効果
- 全然聞いてくれない…どうしたらいいんや。知見募集

正しい現在日時

## 最近・直近など、現在日時を取り扱う場合
- 必ず `date` コマンドを使って、現在日時を取得すること

なぜ
- 「今日の話をまとめて」と言うと、LLMの学習最終日付を使いがちだった。今のClaude 4 Opus/Sonnetだと2025/01を出すことがあった。
効果
- かなり効果的。謎日付を使うことが減った

複数案での設計指針検討

## 設計指針
実装する時は、初めからコードを書き始めるのではなく、まずはどのような設計で実装するかを提案して欲しい。
考える時は次の指針に従ってほしい。

- いろんな軸から複数案を考え、その案のメリットデメリットを併記する
- その複数案から、今達成したいことを実現するシンプルかつメンテナンス性に優れた案を1つ選び提案する
- 選んだ案を採用する時、未来でどういう変更が加わったらその案が破綻するかも一緒に提案して欲しい

なぜ
- 設計を考えさせるとただ一つの回答を出し、自分のアイデアが広がらない
- ただ一つだと自分がLLMを無意識に誘導していることがある
- より自分の思考が広がりやすい返答を返してほしい
効果
- かなり従ってくれる
- 複数案出すと極端な例も含め気づきになる。自分の思考を短絡的にしないためにかなり役立っている

この設定を入れた時の設計の様子

  案1: Repository パターン with インターフェース（推奨）

  // user_repository.go
  type UserRepository interface {
      GetAllUsers(ctx context.Context) ([]slack.User, error)
      FindByDisplayName(ctx context.Context, displayName string) ([]slack.User, error)
  }

  type userRepository struct {
      client      *slack.Client
      cache       []slack.User
      cacheExpiry time.Time
      cacheTTL    time.Duration
      mu          sync.RWMutex
  }
  メリット: テスタブル、責務が明確、キャッシュロジックを隠蔽
  デメリット: 初期実装にはやや大げさかも

  案2: シンプルな構造体直接実装

  type UserCache struct {
      client *slack.Client
      users  []slack.User
      expiry time.Time
  }
  メリット: シンプル、実装が速い
  デメリット: テストしづらい、拡張性が低い

  案3: Handler内に直接実装

  メリット: ファイル数が増えない
  デメリット: Handlerが肥大化、責務が不明確、テストしづらい

  推奨案の詳細設計

  案1のRepository パターンを推奨するよ！理由：
  - users.listの結果をキャッシュして効率化できる
  - 将来のreal_name検索追加が容易
  - Handlerから Slack API の詳細を隠蔽できる
  - モックを使ったテストが書きやすい

  // 15分程度のTTLでキャッシュ
  // users.listは全ユーザー取得なのでAPIコール削減効果が高い
  // ページネーション対応（大規模ワークスペース用）

  この設計が破綻するケース：
  - リアルタイムでのユーザー情報更新が必須になった場合
  - メモリ使用量が問題になるほど大規模なワークスペース（数万ユーザー）

  どう思う？😊

ダブルチェックや学びをしやすいコード調査

## コード調査をお願いするときの指針
私からコード調査をお願いすることがある。その時はあなたに調査してもらいつつ、その妥当性を私も一緒にチェックしたい。
そこでコード調査をするときは結論だけを報告するのではなく、調査プロセスもリアルタイムに報告してほしい。
さらに結論をまとめるときは、結論に対する対する重要な証拠も一緒に提示して欲しい。

なぜ
- コード調査させると結論だけ短くまとめることが多く、正当性のダブルチェックができない
- プロセスを吐き出す、重要な証拠も一緒に提出させることで、正当性チェックや自分の学びに繋がりやすくなる
効果
- 従ってくれた時はかなり効果的。だが、従わないこともある
- 初回調査がうまくいかなかったら、調査自体でどういう出力を出して欲しいかを再検討し、調査自体のプロンプトを調整してやり直している

「暴走」「ついでに」をさせない実装指針

## 実装指針
- 段階的に進める: 一度に全てを変更せず、小さな変更を積み重ねる
- 複数のタスクを同時並行で進めない
- エラーは解決してから次へ進む
- エラーを無視して次のステップに進まない
- 指示にない機能を勝手に追加しない
- 周囲の似た実装を探し、それを参考にする

なぜ
- AIコーディングだと、なぜか全てを最初から実装しようとしたり、指示以外のことを「ついでに」やったり、「エラー出てるけど完成したよ」と言ってきたりしがち
- それを防ぐために、段階的に進め、指示以外のことをやめさせ、エラーは解決してから進んでと指示している
効果
- ちゃんと検証していないので、よく分からない
- 「ついでにやっておいたよ」「エラーは出てるけど完成しているよ」とは最近言ってこないので効いてるのかもしれない

テスト記述をましにしたい

## TDDやテスト実装を行うときの指針
TDDやテスト実装を行うときは、t_wada(t-wada, twada, 和田卓人）の推奨する進め方に従って。

なぜ
- 「テスト」「TDD」という言葉が一般用語すぎて、ベストプラクティスに従ってくれない
- よりベストプラクティスに近づくようにしたい
効果
- 大きく効果を感じない
- そもそもLLMが「自動テストはなんのために行うか」「コスパの良い自動テストとは何か」の大前提を理解していないように感じている。あらゆる網羅的なケースを書きがち
- まず自分がテストコード上にテストケースの名前だけを書き、「今回は既存のこのテストを参考に、リストアップしたテストケースを完成させてね」と指示する方が作りやすかった
Tips
- 汎用的になってしまったワードでは、より限定すると効くことがある
  - TDD => t_wadaのTDD
  - リファクタリング => 「リファクタリング(第2版): 既存のコードを安全に改善する」に従ったリファクタリング
- 人名などを使うことでコンテキストを圧縮できる。ただしコンテキストを使って明示的に書くことで精度を上げることもできるので、トレードオフがある

エラーを深掘りさせる

## エラーなど期待とは違う現象が起きた時
- 必ず「なぜ期待とは違う現象が起きたか」について深掘りしてから、次の対処を考えること

なぜ
- 「このエラーが起きたのは多分こうだよ〜」と言って全然関係ない実装をしがち
- 一回深掘りして原因を明確にしてから、その原因に適切に対処してほしい
効果
- 効いているような効いていないような？
- しばらく様子見中

Bashコマンドの細かい制御

## Bashコマンド
- rmはインタラクティブにする設定をしているため、削除するときはrm -fを使うこと
- GitHubの情報を取得するときは、ghコマンドを用いる

なぜ
- 個人でaliasなどを貼っていると、デフォルトの挙動ではうまくいかないことがある。例えば自分はrmは必ずインタラクティブにする設定を入れているが、それだと毎回rmが一回失敗してからrm -fを使うようになってしまう
- 細かくBashコマンドを制御したい
効果
- rmは効いてる
- ghコマンドは使ってくれたり使ってくれなかったり
- 結局確率の問題なので、確率を上げることには成功していそう

一時ファイル場所の指定

## 一時ファイル
- 開発の過程で生成した一時ファイルはプロジェクト以下の `.claude/tmp` 以下に保存してください

なぜ
- 設計や調査内容、作業のためのスクリプトを一時ファイルに書き出す時、いろんなところに保存してgitを汚してしまう
- ある程度場所を限定し、gitignoreできるようにしたい
効果
- ちゃんと保存場所指示が効いてる

MCPのtool利用確率を増やす

## Serena利用について
- symbol検索を行うときは、symbol名を推測せずに、必ずget_symbols_overviewを実行して正しいsymbol名を取得すること

Serenaとは、LSPを使ってコード定義ジャンプなどをしてくれるMCPのこと
コード検索だと間違った関数呼び出しがヒットすることがあるが、LSPなら確実になる
なぜ
- コードジャンプする時symbol名を推測して適当なものを呼び出し、見つかりませんと言われることが多かった
- ちゃんと今見ている関数のsymbol名が何かを正確に取得してから、コードジャンプして欲しい
効果
- まあまあ効くが無視することも多い。確率は上がった
- このように指示によってMCPのtool利用確率を増やすこともできる

設定を通して学んだこと

プロンプトエンジニアリングの知識が結局大切

設定すればするほど、結局良い設定の基本はプロンプトエンジニアリングの知識と感じる
知識例
- 解釈の幅がない明確な表現
- 否定での指示を避け、できる限り肯定に書き直す
- 具体事例をいくつか入れる（Few-shotプロンプティング）
- なぜ必要か理由も一緒につける
自分は以下の資料を読んだ

今だとコンテキストエンジニアリングという考え方も出てきている。学ぶとMCPはどこに位置付けしているか、スラッシュコマンドを定義するとき何に気をつけるべきか、なども理解しやすくなる。

12-factor-agentsのfactor-03-own-your-context-windowより引用。

LLMは関係ないコンテキストにも無理やり追従する傾向にある

個人やプロジェクトのCLAUDE.mdの内容の全てに追従して結果を出そうとしがち
特定の時のみの内容をCLAUDE.mdに入れてしまうと、性能が劣化することも
- 例: ライブラリアップデート用の方法をCLAUDE.mdに入れると、その方法を全然関係ない時に使おうとしてしまう
- 似たような話で、IDE連携を常にONにしていると、変なコンテキストに引きづられる
いつも使う内容をCLAUDE.mdに入れ、特定の時のものはスラッシュコマンドや別ドキュメントに記載し、都度使うと良い

思考を広げるため、1つの最終結論ではなく、過程や複数案を出すように

1つの最終結論を出させると、ダブルチェックも出来ず、自分の学びにも繋がりにくい
設定によって、過程や複数案を出させれば、たとえ回答が間違っていたとしても、少なくともダブルチェックできる & 自分の学びに繋がる
できる限り思考を広げる方向に設定するのをオススメ

初手はうまくいかなくても、設定で大きく改善することがある

AIに何かのタスクをやらせる時、初手はあまり上手くいかないことが多い
上手くいかない理由を言語化し、設定を調整することで、大きく改善することがある
「うまくいかないからこのタスクはやらせない」より「うまくいかないから何か工夫をしてみる」を一度やってみることをオススメ
もちろんAIにも得意不得意があるので、色々試した結果、やっぱり無理そうと判断するのも良い

まとめ

今回は社内で「個人CLAUDE.md紹介と設定から学んだこと」という発表した内容を共有しました。参考に個人CLAUDE.mdやプロジェクトCLAUDE.mdを調整してみてください。

Source link

【初心者向け】ローカルLLMの色々な動かし方まとめ前の記事テスラの「完全自動運転」はなぜ他のメーカーと違って危険なのか？ - GIGAZINE 次の記事

この記事へのコメントはありません。