Kamoneです！

皆さん、Claude Code使ってますか？最近はマルチエージェント機能が実装されて、ますます人間不在で仕事をこなせる力に磨きがかかっていますね。

彼らに仕事を任せるにあたって重要になるのがCLAUDE.mdの作り込みです。
これはいわばルールブックで、ここに書かれている規則に従ってエージェントが働いてくれるわけです。
エージェント達に期待する振る舞いをCLAUDE.mdに盛り込めば、ただやって欲しいことを伝えるだけよりもずっと精度の高い仕事をしてくれるようになります。

しかし、このCLAUDE.mdの作り込みには明確な正解がありません。やらせたいことによっても変わってくるし、AI自体も日々進化・変化しているので同じテクニックがいつまでも通用するとは限りません。
ネット上でも「これを書いておいた方がいい」、「これは意味ない」などユーザーたちの間で熱い議論が飛び交っていますね。

そんな中、2/22にXで投稿されたあるポストに注目が集まっています。

投稿者はClaude Codeの開発者Boris Cherny（ボリス・チェミー）氏で、Claude Codeのエンジニア力を10倍にするCLAUDE.mdを紹介するという内容でした。

## Workflow Orchestration

### 1. Plan Mode Default
- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) 
- If something goes sideways, STOP and re-plan immediately – don't keep pushing 
- Use plan mode for verification steps, not just building 
- Write detailed specs upfront to reduce ambiguity 

### 2. Subagent Strategy 
- Use subagents liberally to keep main context window clean 
- Offload research, exploration, and parallel analysis to subagents 
- For complex problems, throw more compute at it via subagents 
- One task per subagent for focused execution 

### 3. Self-Improvement Loop 
- After ANY correction from the user: update tasks/lessons.md with the pattern 
- Write rules for yourself that prevent the same mistake 
- Ruthlessly iterate on these lessons until mistake rate drops 
- Review lessons at session start for relevant project 

### 4. Verification Before Done 
- Never mark a task complete without proving it works 
- Diff behavior between main and your changes when relevant 
- Ask yourself: "Would a staff engineer approve this?" 
- Run tests, check logs, demonstrate correctness 

### 5. Demand Elegance (Balanced) 
- For non-trivial changes: pause and ask "is there a more elegant way?" 
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" 
- Skip this for simple, obvious fixes – don't over-engineer 
- Challenge your own work before presenting it 

### 6. Autonomous Bug Fixing 
- When given a bug report: just fix it. Don't ask for hand-holding 
- Point at logs, errors, failing tests – then resolve them 
- Zero context switching required from the user - Go fix failing CI tests without being told how 

## Task Management 
1. **Plan First**: Write plan to tasks/todo.md with checkable items 
2. **Verify Plan**: Check in before starting implementation 
3. **Track Progress**: Mark items complete as you go 
4. **Explain Changes**: High-level summary at each step 
5. **Document Results**: Add review section to tasks/todo.md 
6. **Capture Lessons**: Update tasks/lessons.md after corrections 

## Core Principles 
- **Simplicity First**: Make every change as simple as possible. Impact minimal code. 
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. 
- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.

Claude Codeの開発者自身が実際に使っているMDファイルなら権威性はバッチリですし、同じ内容をコピーするだけで使えて考える必要がないので有難～い！

…と思考停止で使ってもいいのですが、せっかくなので1つ1つの項目についてなぜそれを書くべきなのか、一歩掘り下げてみましょう。

AIにスムーズに仕事を進めてもらうための基本的な考え方を理解すれば、巷の最新プロンプトテクニックを追いかけてコピーしなくても自分の用途に合った設定を編み出せるようになるはずです！

Claude Code ベストプラクティス（解説付き・日本語）

Workflow Orchestration（ワークフロー統括）

1. Planモードをデフォルトにする（Plan Mode Default ）

ここでは、「基本的にPlanモードを使う」ことを定めています。Planモードというのは、実際の作業に入る前に計画を立てるモードのことです。通常は「～を作って欲しい」と依頼すると、いきなりコードを書き始めてしまうのですが、Planモードではまず実装計画を立て、計画が承認されてから作業を行うようになります。どんなタスクがあるのか、何から手をつければいいのか、何が終わっていて何がまだなのか、といった全体像を確認できるようになるので、AIエージェントが迷いにくくなるんですね。Claude Codeを最大限活用するならこのプランモードが使われるように設定しておいた方がいいでしょう。

• 英：Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
• 日：複雑なタスク（3ステップ以上、または設計判断が必要）では必ずPlanモードに入る
  • 意味：無計画に実装を始めて手戻りが発生することを防ぐルールです。
  • 解説：複雑なタスクでは、実装を先に始めると、途中で前提が崩れて「手戻り」が発生するリスクがあります。Planモードは実装に入る前に設計を行い、作業計画を立てるのでこうした失敗を防ぐのに役立ちます。
• 英：If something goes sideways, STOP and re-plan immediately – don’t keep pushing
• 日：何かが想定外になったら、その場で止めて再計画する（惰性で進めない）
  • 意味：最初の計画に固執して軌道修正ができなくなることを防止するルールです。
  • 解説：Planモードで立てた計画も100％完璧ではありません。むしろ、計画通りに進まないことがほとんどでしょう。この時、計画の見直しを行わずに試行錯誤すると、場当たり的な局所最適の継ぎ足しになってしまい、全体の整合性が取れなくなるリスクがあります。”急がば回れ”の言葉通り、詰まったら一旦手を止めて計画を練り直すことが問題解決の近道です。
• 英：Use plan mode for verification steps, not just building
• 日：Planモードは「作る」だけでなく「検証手順」にも使う
  • 意味：Planモードで実装計画だけでなく、検証計画も立ててもらうルールです。
  • 解説：アプリもツールも作って終わり、では不安が残ります。実際に問題なく動くところまで確認しないと安心はできません。検証計画を立てるということは、期待する動作や確認方法まで決めておくということ。検証項目と手順が定義されていれば、テストをクリアできるように実装できるようになります。
• 英：Write detailed specs upfront to reduce ambiguity
• 日：曖昧さを減らすために、最初に詳細な仕様を書き切る
  • 意味：仕様の中に曖昧な記述が含まれないようにするルールです。
  • 解説：仕様の中に曖昧な記述があると、解釈の余地が生まれ、解釈の違いによって実装がブレてしまう懸念があります。ここでいう曖昧な記述というのは、可能な限り粒度を細かくして、定量化して、解釈の余地を狭めることが品質のブレを防ぎます。

2. サブエージェント戦略（Subagent Strategy）

ここでは、サブエージェントを活用するための方針を定義しています。サブエージェントとは、Claude Codeのエージェントチームを構成する機能で、メインのエージェントの配下で指示を受けて作業を実行するエージェントです。役割分担やタスクへの取り組み方などを明確に定義しておくことで、品質を安定させることができます。

• 英：Use subagents liberally to keep main context window clean
• 日：メインのコンテキストをクリーンに保つために、サブエージェントのライブラリを積極的に使う
  • 意味：タスクに関する細かい情報は、サブエージェントのライブラリに記録させるルールです。
  • 解説：メインエージェントのコンテキストに雑多なログが混ざると、重要な情報が埋もれて判断精度が落ちてしまう懸念があります。サブエージェントにこれらの雑多な情報を残すようにすれば、メインエージェントのコンテキストが汚れるのを防げます。
• 英：Offload research, exploration, and parallel analysis to subagents
• 日：調査・探索・並列分析はサブエージェントにオフロードする
  • 意味：タスクごとにサブエージェントを作り、実行させるようにするルールです。
  • 解説：1つのエージェント、スレッドで複数のタスクを実行すると、精度が下がる懸念があります。調査、探索、並列分析などそれぞれのタスクに専用のエージェントを立ち上げ、集中的にタスクに取り組んでもらうのがベターです。
• 英：For complex problems, throw more compute at it via subagents
• 日：複雑な問題には、サブエージェントを介してより多くの計算リソースを投入する
  • 意味：複雑なタスクに対しては、複数のサブエージェントを立ち上げて処理させるルールです。
  • 解説：タスクが複雑になると、単体のサブエージェントだけでは計算能力が足りなくなる懸念があります。このような場合には、複数のサブエージェントを起動してアサインすることで、不足をカバーすることができます。
• 英：One task per subagent for focused execution
• 日：サブエージェントごとに1つのタスクを集中的に実行する
  • 意味：1つのサブエージェントに割り当てられるタスクを1つに限定するルールです。
  • 解説：1つのサブエージェントに複数のタスクを渡すと、優先順位の判断を間違えたり、複数のタスクの情報を混線させたりして破綻しやすくなります。AIも人間と同様、マルチタスクをさせるより1つのことに集中させた方が能率が上がり、品質も上がります。

3. 自己改善ループ（Self-Improvement Loop）

ここでは、同じミスをしないように教訓を蓄積するルールを定めています。

• 英：After ANY correction from the user: update tasks/lessons.md with the pattern
• 日：ユーザーから何らかの修正指摘を受けたら、必ず tasks/lessons.md にパターンを追記する
  • 意味：ユーザーがエージェントに対して修正を依頼したり間違いを指摘したら、指定したMDファイルに記録することを徹底させるルールです
  • 解説：何度も同じミスを繰り返されるとストレスが溜まるものです。できれば同じ失敗を繰り返さないで欲しい。AIエージェントはファイルを参照できるので、過去のミスや受けた指摘を記録しておくことができます。必ず記録を残しておくようにルール化しておけば、同じミスをして同じ指摘を受けることを防止できます。
• 英：Write rules for yourself that prevent the same mistake
• 日：同じミスを繰り返さないための「自分向けルール」を書く
  • 意味：同じミスを繰り返さないための再発防止ルールをエージェント自身に作成させるルールです。
  • 解説：ミスをしやすい仕事の進め方をしているなら改善しなければミスは減りません。そこで、エージェント自身に同じミスをしないためにどうすればよいかを考えて書かせるわけです。これを繰り返せばミスをしにくいエージェントチームに成長することが期待できます。
• 英：Ruthlessly iterate on these lessons until mistake rate drops
• 日：これらの教訓を容赦なく反復し、ミス率が低下するまで続ける
  • 意味：tasks/lessons.mdを繰り返し読み込んで学習することでミス率を低下させるルールです
  • 解説：ミス率を下げるには、反復が効果的です。人間の場合はその場で同じ事象を反復することが難しいですが、AIエージェントは疑似的に同じミス、同じ指摘、同じ対処を何度も繰り返して経験を強化できるということなのでしょう。「容赦なく」という強調もポイントかもしれません。
• 英：Review lessons at session start for relevant project
• 日：セッション開始時に、そのプロジェクトに関係する教訓を見直す
  • 意味：セッション開始時にtasks/lessons.mdを読み込んで内容を把握するように徹底させるルールです
  • 解説：せっかくtasks/lessons.mdに知見を書き溜めても、見なかったら意味がありません。セッション開始と同時に一点これまでの知見を確認してから仕事を進めるようにすれば、同じミスをする確率を大幅に減らすことができるはずです。

4. Doneの前に検証する（Verification Before Done）

ここでは、「何を以て完了とするか」と「完了に持っていくために何をすべきか」を定義しています。

• 英：Never mark a task complete without proving it works
• 日：動作することを証明するまで「完了」にしない
  • 意味：タスクを完了する条件として「動作確認」を必須とするルールです
  • 解説：AIは意外と動作確認をサボりがちです。コードを書くだけで完成させた気になっていることが多いので、実際に動かしてみたら初歩的なミスでエラーを吐く、なんてことはしょっちゅうです。動作確認せずに完了にしてはいけないとルール化することで、ちょっと動かせば分かるレベルのミスは減らせるはずです。
• 英：Diff behavior between main and your changes when relevant
• 日：必要に応じて、変更前後の挙動差分（diff）を確認する
  • 意味：変更が発生したら、挙動に変化がないか確認させるルールです
  • 解説：AIは修正を提案して実行してくれますが、やっぱり動作確認をサボります。依頼したユーザーとしては修正したことで挙動がどうなったのかを確認してもらわなければ安心できませんよね。
• 英：Ask yourself: “Would a staff engineer approve this?”
• 日：「スタッフエンジニアがレビューしてOK出す内容か？」と自問する
  • 意味：成果物を提出する前に、レビュアーがOKを出す内容になっているかセルフチェックさせるルールです
  • 解説：「これ、レビューに出す前に自分でチェックしたの？」人間の仕事でもよく言われるヤツですね。「とりあえず出して指摘受けたら修正すればいいや」というやっつけ仕事はできればAIエージェントにはしてほしくないですよね。そこで、提出前にセルフチェックを義務付けるわけです。人間はモチベーションやコンディションにも左右されますが、AIエージェントは書いてあればとりあえず守ろうとはとしてくれるので書いておいた方がいいですね。
• 英：Run tests, check logs, demonstrate correctness
• 日：テストを実行し、ログを確認し、正しさを実証する
  • 意味：成果物の確かさを、テストの実行とログの確認によって担保させるルールです
  • 解説：これは1番目のルールを補完するルールだと思われます。『動作することを証明するまで「完了」にはしない。』『動作の証明とは、テストの実行とログの確認である。』という組み立てになっているのでしょう。

5. 美しさを求める（バランス重視）（Demand Elegance (Balanced)）

ここでは、実装や修正に美しさを追究するように定めています。ここでいう美しさとは、単に動けばいいだろうというような短絡的な実装ではなく、将来的な拡張性やメンテナンス性、コードの可読性なども含めた総合的な優位性のことを指しています。

• 英：For non-trivial changes: pause and ask “is there a more elegant way?”
• 日：重要な変更を行う際には、立ち止まって「もっと洗練された方法はないか？」と自問する。
  • 意味：大きな変更を行う前に、その方法がベストか考えさせるルールです
  • 解説：AIに限らず、複雑な実装をしようとするほど、“とりあえず動けばいい”に寄せてしまいがちです。しかし、将来的な拡張性とか、メンテナンス性とか、現時点でベストを尽くした方がいいことも多々あります。そこで、「今やろうとしている実装は客観的に見て美しいか？」と自己批判させ、美しい実装を心がけるように仕向けます。
• 英：If a fix feels hacky: “Knowing everything I know now, implement the elegant solution”
• 日：もし修正がハックっぽいと感じたら：「今の知識を全て活かして、洗練された解決策を実装せよ」
  • 意味：とりあえず動けばいい、という短絡的な修正をやめて、より洗練された修正を行うようにするルールです
  • 解説：ここでいう「ハック」とは、目先の課題をクリアするためにやっつけ仕事をする、というニュアンスです。たとえば、根本的な原因を追究せずに例外処理を追加して回避したり、リトライやタイムアウトを増やしたりすることを指します。このような場当たり的な対処を通してしまうと、一見正しく動いているように見えて中身は時限爆弾だらけ、という状態になってしまいます。これもAIエージェント自身に自問自答させることで回避できる可能性が高まります。
• 英：Skip this for simple, obvious fixes – don’t over-engineer
• 日：単純で明らかな修正の場合はスキップしてください – 過剰設計は避ける
  • 意味：検討するまでもない修正の場合は検討をスキップさせるルールです
  • 解説：考えるまでもないタスクに実装の美しさを検討させるのは過剰で、コストの無駄になってしまいます。その辺は良い感じにバランスを取ってもらいましょう。
• 英：Challenge your own work before presenting it
• 日：提出前に、自分の仕事を自分で突っ込んで再評価する
  • 意味：提出前に自己批判・自己評価をさせるルールです
  • 解説：前項にも同じような項目がありましたが、提出前にセルフチェックさせることをルール化しています。「レビュー以前の指摘は自分で潰してから持ってこい」というヤツですね。

6. 自律的バグ修正（Autonomous Bug Fixing）

ここでは、バグ修正の方針を定めています。基本的には、指示を待たず自律的に修正を完結してもらう方針です。

• 英：When given a bug report: just fix it. Don’t ask for hand-holding
• 日：バグ報告を受けた場合：ただ修正する。手取り足取り教えを乞わない。
  • 意味：バグ報告に対して、逐一質問せず、ただ自律的に修正させるルールです。
  • 解説：ちょっとしたバグにまで「○○が原因だと思います。修正しましょうか？」みたいに確認を取られたら疲れてしまいますよね。「いちいち聞かなくていいからさっさと修正してくれ」と思うわけです。ルール化すれば確認地獄から解放されます。
• 英：Point at logs, errors, failing tests – then resolve them
• 日：ログ、エラー、失敗したテストを特定し、それらを解決する
  • 意味：バグ修正においては、まずログ・エラー・失敗したテストの結果を確認し、それらを解決するように徹底させるルールです。
  • 解説：ここではバグ修正において確認し、解決すべき対象を明示しています。何から手をつければいいかが明確になっていれば、変なところでつまづくことも少なくなるでしょう。
• 英：Zero context switching required from the user
• 日：ユーザーによるコンテキストスイッチングが一切不要
  • 意味：新しくセッションを開始するとき、これまでに与えたコンテキストが維持されるようにするルールです。
  • 解説：いちいちコンテキスト情報をまとめて渡さなくても自分からコンテキストを保存しておいて、新規セッション開始時に読み込んでくれるようになったらストレスフリーですよね。これを書いておくと、こちらが言わなくても次のセッションに渡すコンテキストをまとめておいて、次のセッション開始時に読み込んでくれるようになるのでしょう。
• 英：Go fix failing CI tests without being told how
• 日：指示されなくても、失敗しているCIテストを修正しなさい
  • 意味：CIテストが失敗したら、自律的に修正させるルールです
  • 解説：CI（Continuous Integration）テストとは、開発者がコード変更を頻繁に共有リポジトリに統合した際に、自動的にビルドやテストを実行するプロセスです。一番目の項目と似ていますが、とにかくあらゆるバグ・エラーは自律的に修正させようということです。

タスク管理（Task Management）

ここでは、タスク管理の具体的なステップを定義しています。これまでの項目と重複する部分もありますが、重要なことは重複して記載した方が伝わりやすいという傾向があるという分析もあります。

1. 計画ファースト（Plan First）
   • 英：Write plan to tasks/todo.md with checkable items
   • 日：tasks/todo.md にチェックボックス付きで計画を書く
     • 意味：計画書はチェックボックス形式のToDoリストで作成させるルールです
     • 解説：チェックリスト化すると、作業が“可視化・分割”され、見積もりと進捗管理が可能になります。
2. 計画を検証する（Verify Plan）
   • 英：Check in before starting implementation
   • 日：実装開始前に一度、計画の妥当性を確認する
     • 意味：タスクの開始前に計画の妥当性を再確認させるルールです
     • 解説：思考停止で計画に固執して失敗のループに入ることを防止します。
3. 進捗を追跡する（Track Progress）
   • 英：Mark items complete as you go
   • 日：作業を進めながら完了した項目をマークする
     • 意味：完了した項目にチェックマークをつけることで、進捗を明確にするルールです。
     • 解説：完了＝チェックボックスにチェックが入っていること、と定義することで何が完了していて何が未完了なのか把握しやすくなります。
4. 変更点を説明する（Explain Changes）
   • 英：High-level summary at each step
   • 日：各ステップで変更点を高いレベルで要約して説明する
     • 意味：変更の意図がユーザーや他のエージェントにも理解できるように要約させるルールです
     • 解説：修正して動くようになっても、中身が分からなければブラックボックス化して理解負債になってしまいます。誰が見ても理解できるように要約を徹底させるようにします。
5. 結果を記録する（Document Results）
   • 英：Add review section to tasks/todo.md
   • 日：tasks/todo.md にレビュー（結果）セクションを追加する
     • 意味：タスクに対して必ずレビューを記録させるルールです
     • 解説：どのタスクがどう評価されたかを記録しておくことで、以降の類似のタスクに活かされることを期待します。
6. 教訓を残す（Capture Lessons）
   • 英：Update tasks/lessons.md after corrections
   • 日：修正後、tasks/lessons.mdを更新する
     • 意味：トラブルシューティングの履歴を記録させるルールです。
     • 解説：失敗と修正を記録して資産家することで、同じ失敗を繰り返さないように自己成長することを期待します。

基本原則（Core Principles）

ここでは、すべての項目に共通する基本的な原則を定義しています。

• 可能な限りシンプルに（Simplicity First）
  • 英：Make every change as simple as possible. Impact minimal code.
  • 日：変更は可能な限りシンプルに。影響範囲の小さいコード変更に留める。
    • 意味：いきなり大規模な変更に取り掛かることを防止するルールです。
    • 解説：一度に大量の修正をされてしまうと何が変更されたのかを追いかけるのも大変です。このルールは変更を小規模でシンプルにすることで、影響範囲を最小化しようとしています。
• 手抜き禁止（No Laziness）
  • 英：Find root causes. No temporary fixes. Senior developer standards.
  • 日：根本原因を特定する。場当たり的な暫定対応は禁止。シニア開発者基準でやる。
    • 意味：暫定的な対処は禁止し、根本原因を解決する恒久対処のみに限定するルールです。
    • 解説：人間の世界では「とりあえず暫定対処をして、後で恒久対処を考える」というケースはままありますが、AIに暫定対処を許可すると暫定対処が正解になってしまって根本解決がなされなくなってしまいます。初めから禁止しておきましょう。
• 影響を最小限に留める（Minimal Impact）
  • 英：Changes should only touch what’s necessary. Avoid introducing bugs.
  • 日：変更は必要な部分のみに留めるべきである。新たなバグの混入は避けること。
    • 意味：無関係な箇所まで手を付けることを防止するルールです。
    • 解説：AIにコード修正をさせると、突然何の関係もないコードも巻き添えに修正しちゃうことありますよね。そしてそれが原因で新たなエラーを発生させてしまう。一番目の項目とほぼ同じで、影響範囲を小さくさせる工夫です。

以上です！

短くまとめると次の6つです。

• まずはPlanモードで実装と検証の計画を立てる。
• サブエージェントを活用してシングルタスク化し、並列実行させる。
• 同じ失敗を繰り返さないように記録させる。
• 完了条件を明確にする。
• 美しい実装を心がける。
• 自律的にバグ修正させる。

このベストプラクティスのエッセンスは、Claude Codeだけでなく、AntigravityやCodexなど他のAIエージェントを活用したコーディングにも応用できるはずです。

ぜひ、活用してみてください！