【ITニュース解説】Everything Claude Codex: 11 Lessons From 11 Months in Claude Code

AIアシスタントをより有効に活用するための実践的な知見として、「Everything Claude Codex」（ECX）という独自のシステムを開発した経緯とその中で得られた11の教訓が解説されている。このシステムは、従来のAIアシスタントが抱える「記憶力の欠如」や「定型作業の繰り返し」といった課題を解決し、作業効率を飛躍的に向上させることを目的としている。

開発者は学生として複数の学位取得と並行して多くの課題を抱える中で、AIアシスタント「Claude Code」を利用し始めた。しかし、AIはセッションごとに以前の会話内容を忘れてしまうため、毎度自身の状況やプロジェクト内容、試したことなどを説明し直す必要があった。この非効率な状況を改善するため、ECXを開発した。これは、二つのAIエージェントが記憶を共有し、ノートや検索機能、システムの健全性チェック機能などを備えた総合的なアシスタントシステムである。

ECXの開発から得られた11の教訓は以下の通りだ。

第一に、エージェントはユーザーが入力する前の情報によって性能が大きく変わる。AIの応答品質を最も向上させたのは、高性能なモデルではなく、現在進行中のタスクや締め切り、プロジェクトの状況などを記した「hot.md」というファイルだった。このファイルをセッション開始前にAIに読み込ませることで、AIは常に最新の文脈を把握し、開発者の状況を理解した上で応答するようになった。

第二に、同じプロンプトを三回入力したら、それは「スキル」として定義すべきだ。特定の支援（例えばインターンシップ情報の検索）を依頼する際に、毎回同じ内容のプロンプトを貼り付けていた作業を、「/opps」のような短いカスタムコマンド（スキル）に置き換えることで、作業を自動化し、時間を節約できるようになった。これにより、繰り返しの作業がインフラの一部として機能する。

第三に、AIへの指示は単なる「提案」に過ぎず、確実に実行させたいことは「フック」として実装する必要がある。AIに特定の記述スタイル（例：emダッシュを使わない）を指示しても、AIはそれを無視することがあった。しかし、下書き保存時にスタイル違反をチェックする16行のフック（特定のイベント発生時に自動実行されるコード）を導入することで、指示が確実に守られるようになった。フックは、モデルの判断に委ねるのではなく、システムとして動作を強制する仕組みだ。

第四に、セキュリティのための「ガード」機能は、実際に想定される入力（ペイロード）でテストすることが重要だ。危険なコマンド（例：rm -rf ~のようなファイル削除）を防ぐためのガードが、テスト環境変数を読み込むように設計されていたため、実際のAI環境では機能していなかった事例がある。ガードの有効性を確認するには、AIが実際に送信するデータ形式でテストする必要がある。

第五に、エラーを報告しない「サイレント障害」は真の敵だ。夜間の検索インデックス更新が120日間も失敗し続けていたにもかかわらず、何の通知もなかったため、検索結果が古い情報に基づいていたことがあった。問題が明確に報告されるシステムはすぐに修正されるが、静かに壊れるシステムは放置されがちである。ECXの「doctor」機能は、フックやインデックス、定期実行ジョブなどの健全性を常時チェックし、問題があれば修正コマンドを提示する。

第六に、連携しているツールがダウンしている場合、そのツールを呼び出すことは時間の無駄であり、誤った判断につながる。AIエージェントは、連携しているツール（例えば、ローカルAIモデルを実行するOllamaのようなバックエンドサーバー）が応答しないと、役立たない情報に基づいて自信満々に推論してしまう。ECXでは、ツールを呼び出す前にその依存関係の健全性をチェックし、二回連続で失敗した場合はそのツールをブロックして理由を伝えるようにした。

第七に、「完了」の定義は明確な証拠を伴うべきだ。AIがタスクが「完了した」と報告しても、実際にはコードがコミットされていなかったり、プッシュされていなかったりすることがあった。ECXでは、テストの出力、公開URL、コミットハッシュなどの具体的な「証明」なしにはタスク完了と認めない。カスタムコマンド「/ship」は、コミット、プッシュ、証拠報告までを一貫して行う。

第八に、脳を共有するならば、二つのエージェントは一つよりも優れている。ChatGPTアプリの音声AI「Codex」と「Claude」という異なるAIを併用する場合、それぞれのAIが個別の記憶しか持たないことが課題だった。ECXでは、「AGENTS.md」というファイルを共有させ、さらに「agent-sync」というフックを用いて、各AIのチャット履歴をリアルタイムに同期させることで、両者が同じ情報に基づいて応答できるようにした。

第九に、ノートパソコンの電源が入っていないと機能しないアシスタントは真のアシスタントではない。以前に構築したローカルで動作するAIアシスタントは、ノートパソコンを閉じると使えなくなる問題があった。ECXでは、AIとの会話内容やノートのコピーをプライベートなGitHubリポジトリに同期させることで、スマートフォンからもアクセス可能にした。これにより、いつでもどこでも最新の情報に基づいてAIに質問したり、メモを取ったりできるようになった。

第十に、単語でしか検索できないノートは役に立たない。単なるキーワード検索（grep）では、「レイテンシに関するノート」のように意味で情報を探し出すことはできない。ECXのノートは、意味、関連性（知識グラフをたどる）、画像内容で検索できるようにした。これにより、より高度な情報探索が可能になり、すべてのノートは毎晩再インデックスされる。

第十一に、生のリソース（例：チャット履歴）を直接同期してはならない。スマートフォンからもすべての情報にアクセスできるようにするため、最初は完全なチャット履歴をGitHubに同期することを検討した。しかし、チャット履歴にはAPIキーなどの機密情報が含まれており、一度Gitの履歴に記録されると完全に削除することが非常に困難だ。そのため、ECXではチャット履歴のサマリーと記憶だけをスマートフォンに同期するようにした。これで十分な情報が得られ、セキュリティリスクも回避できる。

これらの教訓は、AIを単なるチャットボットとしてではなく、個人の高度なアシスタントとして活用するための具体的な手法と、システム開発における実践的な課題解決のヒントを示している。AIの能力を最大限に引き出すためには、AIに適切な情報を提供し、動作を保証する仕組みを構築し、システム全体の健全性を維持することが不可欠であることが分かる。システムエンジニアを目指す初心者にとって、AIの活用だけでなく、セキュリティやデータ管理、障害対応といった幅広い視点での開発経験が凝縮された事例と言えるだろう。