日本語: エージェント対応コードベース：否定ルール、正確な命名、ディレクトリのREADME

r/ClaudeAIの開発者が、Claude Codeが新しい機能をモノリシックなUserManagerクラス（認証、セッション、プロフィール、分析）に何度も詰め込んだ後、どのようにAndroidコードベースを適応させたかを詳述しました。重要な洞察：エージェントは毎回冷えた状態で現れ、まるで初日を迎えた新入社員のように、アーキテクチャ上の決定を覚えていません。その解決策は、リポジトリルートにCLAUDE.mdで明示的なルールを設定することでした。

最大の効果を発揮した3つのパターン

1. 否定ルールは肯定ルールより効果的

「良い設計に従う」の代わりに、開発者は次のような指示を書きます：

BaseActivityには触らないでください – 12の機能で共有されており、静かに壊れます。

エージェントはデフォルトで楽観的であり、最も抵抗の少ない道を選びます。危険な経路を明示的に遮断することで、漠然としたガイダンスよりも効果的に悪い決定を防げます。

2. 名前は思っている以上に重要

UserSessionExpiryHandlerという名前のクラスは契約です。単にHandlerと名付けるのはノイズです。エージェントは名前に強くパターンマッチします；良い名前は、ファイル読み込みの必要性を減らします。開発者は汎用的な接尾辞を避け、名前に目的を明示することを推奨しています。

3. 各ディレクトリには、そこに属さないものをリストしたREADMEを置く

「このフォルダはUI用です」の代わりに、READMEは次のように言います：

presentation/にビジネスロジックを置かないでください

この否定的な枠組みはエージェントに「より強く響く」ようで、肯定的なガイダンスよりも悪い配置を防ぎます。

CLAUDE.mdの実践的なルール

• ファイルは小さく保つ。1クラス1役割。
• 古いファイルを拡張するのではなく、新しいファイルを作成する。
• モノリスを作らない – 早期に責務を分割する。

開発者によると、これらのルールを適用した後、エージェントが600行のファイルを1セッションで3回読み直すパターンはほぼ消えました。トークンコストが大幅に削減されたと考えられるが、適切に計測はしていないとのことです。

対象読者

AIコーディングエージェント（Claude Code、Copilotなど）を使用していて、トークンの無駄を減らし、エージェントによる悪いアーキテクチャ上の決定を防ぎたい開発者向け。