🍊

いい機会なのでCLAUE.mdのベストプラクティスを探ってみる

に公開
生成 AI
Claude Code
tech

みなさま、Claude Codeは使っているだろうか。
私は掛け値なしに生身の人間と関わるよりもずっと多い時間をClaude Codeとともに過ごしている。
そんな私だが、しばらくユーザースコープのCLAUDE.mdに手をつけていないことを思い出したため、昨今のSkillsブームに合わせて再検討することとした。
この記事が今後Claude Codeを触るみなさまの役に立てば嬉しい。

CLAUDE.mdのベストプラクティス

いくつかの記事を参考にして、自分なりに腑に落ちた内容をまとめてみる。

簡潔に保つ

HumanLayerの記事によると、最先端の思考型LLMでも確実に従える指示は150〜200程度が限界らしい。Claude Codeのシステムプロンプトには約50の指示が含まれているそうなので、ユーザースコープのCLAUDE.mdには本当に必要なものだけを書くのがよさそうだ。

CLAUDE.md file should contain as few instructions as possible - ideally only ones which are universally applicable to your task.

https://www.humanlayer.dev/blog/writing-a-good-claude-md

コードスタイルはLinterに任せる

コードスタイルのルールをCLAUDE.mdに書くのは非効率だし、コンテキスト量を圧迫したくない。
LLMより従来のLinterやFormatterの方が高速で確実だ。代わりにHooksを設定して、ファイル編集後に自動でフォーマッタを実行させるのがよさそう。

完全に受け売りだが、尊敬している先輩エンジニアがBiomeを激推ししていたこともあり、自分はBiomeを好んで使っている。create-next-appでBiomeが選べるようになっているあたり、彼の考えは正しかったみたいだ。

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "editFile",
        "command": "bunx biome check --write $FILE"
      }
    ]
  }
}

プロンプトの言語について

正直CLAUDE.mdを日本語で書くか英語で書くかは悩みどころだった。調べてみると、プロンプトとコンテンツの言語は一致させた方が精度が上がるという研究がある。ただし機械翻訳したプロンプトは精度が落ちるらしいので、自分で書くか、ネイティブにレビューしてもらうのが無難だろう。

一方、コード生成や論理推論のようなタスクは言語に依存しにくいとも言われている。結局、以下のようなハイブリッドに落ち着いた。

  • 会話の指示やワークフロー → 日本語（日本語で出力させたいので）
  • コマンド → 英語のまま
  • Plan Mode → 英語のまま（元々英語で効果が検証されている）

そもそもClaudeは日本語の理解力がかなり高い気がしているので、英語と日本語を細切れに織り交ぜる某大柴のような記法をしない限りは致命的な問題は出ない気がしている。
もしこれがいいよ！という意見があればぜひ教えていただきたい。

https://ryanstenhouse.dev/why-your-llm-prompts-should-match-your-content-language/

参考リンク

Discussion