アンチパターン集 — やってはいけないCLAUDE.md

よくある失敗パターンとその対策をまとめます。

1. Linterの仕事を書く

問題: ESLintやPrettierで強制できるルールをCLAUDE.mdに書くと、二重管理になり矛盾が生まれます。

<!-- NG -->
- インデントはスペース2つ
- セミコロンは必ずつける
- 末尾カンマを使う

対策: フォーマット系のルールはLinter設定に任せる。CLAUDE.mdにはLinterでカバーできない設計方針を書く。

問題: CLAUDE.mdにコード例を直接書くと、ソースコードの更新に追従できず、すぐに情報が古くなります。

対策: コードの代わりにファイルパスを示す。src/lib/errors.ts を参照 のように書けば常に最新を参照できる。

問題:

<!-- NG -->
- きれいなコードを書いて
- パフォーマンスに気をつけて
- セキュリティを意識して

対策: 具体的なルールに変換する。

<!-- OK -->
- 関数は30行以内。超える場合は分割する
- N+1クエリを避ける。一覧取得はeager loadingを使用
- ユーザー入力は必ずZodでバリデーションしてからDBに渡す

問題: 500行超のCLAUDE.mdは、すべてのルールの優先度が等しくなり、重要な指示が埋もれます。コンテキストウィンドウも圧迫します。

対策: 200行以内に収める。詳細はrulesファイルや@インポートに分離する。

問題: 「リサーチして、分析して、記事も書いて」と一つのエージェントに詰め込むと、どの作業も中途半端になります。

対策: 1エージェント=1タスクの原則。リサーチエージェント、分析エージェント、執筆エージェントを分ける。

問題: AIの出力をそのまま採用すると、事実誤認やコードのバグを見逃します。

対策: CLAUDE.mdにレビュー工程を明記する。成果物は必ずCodexでセカンドオピニオンを取得する のように。

各アンチパターンに共通するのは、具体性の欠如とスコープの曖昧さです。CLAUDE.mdは「誰が読んでも同じ行動を取れる」レベルの具体性を目指しましょう。