- Claude Codeは、使いやすさの面で非常に優れたAIエージェント/ワークフローである
- アーキテクチャの単純さと明確な制御ループにより、デバッグや保守がしやすい体験を提供する
- RAGの導入を最小限に抑え、高度なプロンプトとコンテキストファイルを積極的に活用することで、LLMの強みを最大化している
- 多様なツールと明確なガイドラインを通じて、作業の明確性と一貫性を維持している
- 複雑さではなくわかりやすい構造とプロンプト設計により、自分自身のLLMエージェントも同様に実装しやすい利点がある
概要
- Claude Code（以下、CC）は、現在利用可能なAIエージェント/コーディングワークフローの中でも、もっとも満足度の高い体験を提供する
- CCの強みは、対象に合ったコード編集、不要な妨害の削減、ユーザーの制御権を保った快適なUXにある
- Claude 4モデルと独自のInterleaved Thinkingが中核を担っているが、CursorやGithub Copilotなど、同じモデルを基盤とする他ツールよりも不便さが少ない
- この記事では、CCの実装原理を分解し、近い体験を提供する独自のLLMエージェントを実装するための実践ガイドを提供する
Claude Codeの中核的な美徳: 単純さ
- 最大の教訓は「単純に保つこと（Keep Things Simple, Dummy）」である
- LLMエージェントは、複雑な構造（マルチエージェント、複雑なRAG、検証体系など）を導入すると、デバッグや改善が極めて難しくなる
- CCは、単一のメインループ、シンプルなツールセット、一目で把握できる構造を採用し、すべての中核ロジックを1つのファイルに収めることで、不要なボイラープレートや複雑さを排している
なぜ単純さが重要なのか
- マルチエージェント構造の代わりに、1本のメインスレッドでほとんどの作業を処理する
- 履歴の要約やUXのためのメッセージ統合などは補助的に適用
- 複雑な作業が必要なときは自分自身を複製してサブエージェントとして分岐する（再帰的分岐はなく、1段階までのみ許可）
- ToDoリストを積極的に活用
- 複雑な問題はサブエージェントで分割処理し、その結果をメインのメッセージ履歴に統合
- 抽象度が高すぎる多層構造（マルチエージェント、グラフナビゲーション）は、かえってシステムの安定性や拡張性を損なうおそれがある
軽量モデルを積極活用
- claude-3-5-haikuなどの軽量LLMモデルを大半のリクエストで使用
- 大きなファイルの読み込み、Webページの解析、git履歴の要約など、多くの作業を効率よく処理
- 軽量モデルを使うことで、コストを最大70〜80%削減できる
- すべての主要機能呼び出しで最適化されたモデルの組み合わせを活用することを推奨
精緻なプロンプト設計
- CCのシステムプロンプトは、**膨大な分量（約2800 tokens）**と多様なセクション（トーン&スタイル、作業管理、ツール使用ポリシー、OS/ディレクトリ情報など）で構成される
- claude.mdなどのコンテキストファイル全体を常に含め、コンテキストの豊かさを最大化
- システムプロンプトでは、ポリシー上のルール、例示、注意点、ツールを使うタイミングなどを非常に詳細に案内している
XMLとMarkdownの同時活用
- プロンプト内でXMLタグとMarkdown構造を同時に使用
<system-reminder>, <good-example>, <bad-example> などにより、詳細かつ条件分岐可能な情報伝達を実現- Markdownの見出しでセクションを明確に区切る
コンテキストファイルの重要性
- claude.mdの有無によって、CCの性能差がはっきり現れる
- コードベースからは推論しづらい追加ルール（フォルダ/ライブラリの除外、推奨ポリシーなど）を伝えるうえで必須
- MinusXもminusx.mdによって、チームやユーザーの嗜好を体系化している
RAGを最小化し、LLM検索を活用
- CCはRAG（Retrieval Augmented Generation）の代わりに、実際の開発者のように
ripgrep, jq, find コマンドなどを用いた直接的なコード検索ベースの構造を好む
- これは、複雑なRAG構成に伴う隠れた失敗可能性（例: 類似度関数、再ランカー、チャンク分割）に対する代替策となる
- LLMが実際のコードコンテキストを直接探索・理解する構造により、可動部品の数が減り、RL学習の効率向上まで期待できる
ツール設計と階層構造
- CCは、**低レベル（Bash, Read, Write）、中レベル（Edit, Grep, Glob）、高レベル（Task, WebFetchなど）**のツールをすべてサポートしている
- 使用頻度や正確性などを考慮し、必要なツールを個別に分離
- ツールの説明、例、使用タイミングなどをシステムプロンプトで明確に提示
- 複雑な作業は
Taskや高レベルツールを通じて一貫して管理する
Explicit Todo管理によるコンテキスト喪失の防止
- 長時間実行されるLLMエージェントの代表的な問題（コンテキスト喪失、方向性の喪失）を解決するため、CCは明示的に維持されるToDoリストで状態を管理する
- マルチエージェント体系の代わりに、モデルが自律的にToDoを更新しながら、作業の方向性と柔軟性の両方を確保する
エージェントのトーン、スタイル、親和性の制御
- トーン、スタイル、積極性などを別セクションで管理
- 不要な説明を控える、絵文字は明示的に求められた場合のみ許可するなど、一貫したユーザー体験を設計
- 「非常に重要（IMPORTANT）」、「絶対に〜しない（NEVER）」、「常に（ALWAYS）」などの強い修飾語で注意点を伝える
判断アルゴリズムとフロー設計
- LLMが従うべき主要なアルゴリズムを明確に記述し、例示する
- Do/Don'tリストを並べるよりも、フローチャートや段階的チェックリストのほうが、アルゴリズムの安定性維持に効果的
- 複数の指針や例が衝突する可能性を考慮し、役割範囲やポリシーを構造的に明示する
デザインパターンと適用の実践ヒント
- 強いオピニオンと構造は、独自エージェントを設計する際にそのままベンチマークにできる
- 頭が混乱するようなフレームワークの乱用ではなく、シンプルで効果的な構造の設計が重要
- 実際にMinusXでも多くの原則を適用しており、今後さらに拡大していく計画である
結論
- Claude Codeの最大の教訓: 「単純さこそが最高の力」
- 構造的な明確さ、意味のあるプロンプト設計、軽量ツールの組み合わせが、強力なLLMエージェントを可能にする
- 独自のLLMエージェントを開発する際には、CCの設計哲学とガイドを積極的に参考にする価値が高い
2件のコメント
すごく好き、幸せ、最高、甘くて、このまま続けたい
Hacker Newsの意見
KISSのような単純さはいつも勝つという考えで、この記事がそれをうまく整理していて参考になったという感想
Claude Codeがオープンソースではないのは残念だが、内部動作をよりよく把握できるツールがあるとの紹介で、本当にどう動くのか興味があるならClaude Traceがおすすめとのこと
https://github.com/badlogic/lemmy/tree/main/apps/claude-trace
このツールは、セッションで使われたすべてのツールとプロンプトを表示するJSONファイルと、見やすく整形されたHTMLファイルを作ってくれる
https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file
システムプロンプトも確認できる
モデルは基本的に作業を複数の段階に分解して根気強く解決するよう学習されており、失敗ケースにもある程度強い
最近マルチエージェントシステムが注目される中で、LLM中心の組織がどうアプローチしているか分かって有益だったという意見で、自分も日常的にいろいろな設計観点を試しているので共感したとのこと
主なインサイトは
(1) プロンプトは長くてもよく、ツールの目的やどう役立つかなどの基本説明を必ず含めるべき
(2) ツール呼び出しは非常に基礎的な部分なので、文脈をもっと反映すべきである（いつ使うか、いつ使わないかなど）
(3) システムの状態をメッセージとして管理するのは悪くない。凝った方法（データフレーム保存、変数パースなど）も考えたが、コンテキストウィンドウが長くなるならメッセージだけでも十分だと思う
OpenAIやGoogle Geminiなどのモデルも試したが、Anthropicのモデルほどはうまくいかず、速度も遅いと感じた。プロンプトが長くなるほど、ツールのことを忘れたり、間違った形式で結果を出したりする現象を経験した
明確さと単純さが最優先である
Google Gemini（特にPro版）がClaudeと比べてどうなのか気になるという質問で、Googleの多くの製品は好きだが、製品終了の多さや企業統制（Chromeなど）への強引さ、検閲の問題が気になるとのこと
自分なりの戦略としては、Geminiでプロジェクト要約と高レベル設計プランを作り、その後gpt5に改善と詳細なワークフロー設計（例: XML文書）までさせ、それを再びClaudeに渡す。これだけでもClaudeの右往左往する挙動をほぼ避けられる
https://www.tbench.ai/leaderboard
自分は、ベースモデル自体が実際のコーディング業務に強いのでユーザーの評価が高いのだと思う（一般的なベンチマーク用問題とは違う）。GitHub Copilotを使ってみると、ClaudeはOpenAIやGoogleのモデルより圧倒的に優れており、その差が大きすぎて他のモデルは実質的に使い物にならないと感じるレベルだという意見
今、Claude CodeでSecurity Onion上のElastic関連の問題をデバッグしようとしているが、数分すると難解なJSコードが大量に出てきて、
Error: kill EPERMというエラーが出るログを見るとNode.jsプロセスを殺してしまい、そのせいでClaude自体も落ちているのではないかと思うし、あるいは問題を解けずにClaudeが自分で終了しているようにも感じる
とにかく、プロセスが生きているならもう少し助けてほしい
今後はLLMが最も得意な言語・プラットフォーム・アーキテクチャがますます主流になるだろうという考えで、たとえばnodejsをLLMが10倍うまく扱えるなら、最初からElixirやGoではなくnodejsを使うのが合理的だという見方。ジュニア開発者でもLLMの助けでミドル級・シニア級のように活用できる
sudoを使ってスーパーユーザー権限でプロセスを実行しようとした際、タイムアウトしてそのようなエラーが出る場合がある自分はスタートアップの最初のMVP全体をClaude Codeで作り、今では有料顧客まで獲得している。もちろん、SEV（サービス停止）事故が起きたら一瞬で崩れかねないという根本的な不安はあるが、セキュリティ脆弱性の修正、テスト駆動開発、長期ロードマップに沿ったソフトウェアアーキテクチャ設計のために、今もClaudeを積極的に活用している
こういうストーリーが今後ますます普通になってほしい
「Keep things simple」という主張が正しいなら、むしろやや複雑な構成に感じられるという意見
自分はいつも、必要なことをその都度ワンプロンプトで尋ねる単純なやり方で十分多くの作業をしてきた
議論されていた複雑な構造が、本当に練り込まれたプロンプトと比べてどんな追加価値をもたらすのか確信が持てない
たとえば「新しく学ぶ言語でwhileループを作る方法」のような一文プロンプトのほうが、むしろ効率的ではないかという考え
コントロールフローはむしろ不明瞭に感じられるし、LLMがappendix（ツールやシステムプロンプト）の部分をきちんと使っているのかも疑問で、要求が複雑すぎると一部が無視されたりトークンの無駄になったりするのではと思う
断片ごとに個別のプロンプトを投げる形でプログラミングするほうが、自分にはずっと自然に感じられる
別のやり方を使っている事例やプロンプトを一度見てみたい
実際にLLMを使って全体的なプログラムを人々がどう作っているのか気になるし、プロンプトごとに分けて作る事例を探してみたい
参考までに、記事の最後にあるminusx.comへのリンクは、セキュリティ証明書が553日前に失効している状態だという指摘で、サイトは有効ではないので注意してほしいとの案内