複数の実プロジェクトを生き抜いたClaudeのコード構造

複数プロジェクトを経て有効だったこと

r/ClaudeAIで開発者が、2〜3件の実際のプロジェクトに実装しても壊れなかったClaude Codeの構造を共有しました。このセットアップは、複数のスキル、MCPサーバー、エージェントを追加した後も安定して機能し、単純なデモを超えた運用が可能になりました。

重要な構造上の決定

• CLAUDE MDを使用: 初期段階でCLAUDE MDをスキップすると、結果に一貫性がなくなりました。規約、テストルール、命名規則を定義した後、出力がより予測可能になりました。
• 意図によるスキルの分割: スキルをcode-review/、security-audit/、text-writer/のように整理することで、ロジックを一箇所にまとめるよりも効果的でした。これによりアクティベーションがより明確になりました。
• フックの実装: 最初にフックを使用しなかったのは誤りでした。PreToolUseおよびPostToolUseフックは、不正なコマンドや乱雑な出力を捕捉するのに役立ち、小規模な自動化にも有用でした。
• エージェントの分離: 単一エージェントのアプローチは拡張性に欠けました。専任のレビュワー、ライター、監査担当者のエージェントを設けることで、より予測可能な動作が実現しました。
• コンテキスト使用率の管理: コンテキスト使用率が高すぎると品質が低下します。約60%以下に抑えることで、顕著な違いが生まれました。
• 関心の分離: 設定、スキル、実行時ロジックを混在させるとデバッグが困難になりました。これらを分離することで、すべてが理解しやすくなりました。

MCP統合

GitHub、Postgres、ファイルシステムアクセスとのMCP（Model Context Protocol）統合は、Claudeの動作を完全に変えました。開発者によると、ここでセットアップは単なるおもちゃではなく、単なるプロンプト→出力ではなく、開発アシスタントのように振る舞い始めました。

開発者は、エージェントを構造化する最も明確な方法をまだ模索中ですが、このセットアップは現在、単純なデモを超えて成長するプロジェクトでうまく機能していると述べています。