AIコーディングエージェントに「シニアエンジニアの動き方」を教え込む

AIエージェントが書くコードには共通のパターンがある。テストがない。なぜそのコードが存在するか調べずに変更する。不明点があっても推測で進む。詰まるとリトライを繰り返し、最後はユーザーに丸投げする。

能力の問題ではない。シニアエンジニアが「言われなくてもやること」を、AIは知らない。明示的に教えるまで、エージェントの目標は「動くコードを書くこと」だけだ。

では何を教えればいいか。この問題に取り組んでいるエンジニアたちのアプローチを、CLAUDE.md やスキルファイルに書く内容として手軽な順にまとめた。

まず「やってはいけないこと」を3つ書く

Zenn でスキルファイルの設計論を公開しているエンジニア（berry_blog）はこう書いている。まず SKILL.md や CLAUDE.md に絶対禁止ルールを3点だけ書く。「うちのエージェントが失敗しやすいこと」を3つ禁止する形だ。

1
2
3
4
## 絶対禁止
- 変更対象以外のコードを読まずに判断しない
- 確認していないのに「動くはず」と書かない
- テストなしで実装完了を宣言しない

3点にとどめるのが重要で、それ以上並べると効果が薄れる。「一般的に悪いこと」ではなく、自分のプロジェクトで実際に起きたことだけを書く。そうでないと機能しない。

「コードを書く前に何を確認するか」を定義する

禁止ルールで動き方の下限を固めたら、次は「書く前に何をするか」を決める。

Garry Tan（YC CEO）が公開したプロンプトは、Claude Code のプランニングフェーズで使う形で設計されている。コードを書く前に必ず4種の観点を通過させるというものだ。

設計の確認 — システム構成・依存関係・セキュリティ上の境界
コード品質の確認 — 重複の排除、過剰な実装の検出
テストの確認 — カバレッジ・境界値・未テストの障害ケース
パフォーマンスの確認 — N+1クエリ・非効率なI/O・メモリリスク

変更の規模で粒度を変える。大きな変更には4観点すべて、小さな変更は各1問。この確認を承認制にすることで、4,000行規模の実装を1時間ほどで完成させられた、と彼は書いている。

CLAUDE.md はプロンプトではなくドキュメントとして書く

禁止ルールと事前確認が決まったら、それを CLAUDE.md にどう書くかという設計の話になる。

X でこの問題を整理しているエンジニア Shraddha Bharuka はこう指摘している。「CLAUDE.md をプロンプトファイルと同じように扱っているのが間違い。」プロンプトは一時的な指示だが、CLAUDE.md はそのプロジェクトでAIがどう振る舞うかを永続的に定義するドキュメントだ。彼女が整理した4要素はこれだ。

目的 — システムが何をするか
地図 — どこに何があるか
ルール — 何が許可・禁止か
手順 — 作業がどう進むか

200行以内に抑えることも強調している。超えるとモデルが重要なコンテキストを見落とす。「書きすぎると読まれない」のは人間向けドキュメントと同じだ。

開発フロー全体をコマンドに切り出す

CLAUDE.md で基本的な振る舞いを定義できたら、作業の流れ自体をコマンドとして定義する段階に入れる。

Google Chrome チームの Addy Osmani が公開している agent-skills は、開発フロー全体をスラッシュコマンドに分解したリポジトリだ。仕様確認 → 計画 → 実装 → テスト → レビュー → 整理 → 完了の7段階を定義している。

各コマンドに「根拠のない判断を防ぐ項目」が入っているのが特徴で、「これで大丈夫そう」という曖昧な判断をコマンド側で防ぐ設計になっている。

“Skills encode the workflows, quality gates, and best practices that senior engineers use when building software.”

「経験のあるエンジニアが暗黙にやっていること」をコマンドとして明文化する、という考え方だ。

「確認したこと」と「そう思うこと」を区別させる

もう一段階踏み込んだアプローチとして、エンジニアの ctoth がグローバル CLAUDE.md に書いている設計がある。AIの判断スタンス自体を変えることを目的にしている。

「〜だと思う」と「〜を確認した」を区別させる
変更前に「なぜそれが存在するか」を理解させる
「わからない」を推測より優先させる
3アクション以内に一度現実を確認させる

Allspaw が2012年のエッセイで書いた「成熟したエンジニアは根拠のある指摘しかしない」という論点を、AI向けに再実装したアプローチだ。

どのアプローチも共通しているのは、「AIは暗黙知を持たない」という前提から出発している点だ。禁止ルールの3点書きから始め、事前確認の定義、CLAUDE.md の設計、フロー全体のコマンド化と、手軽なものから順に積み上げていける。最初の一歩だけでも、エージェントの動き方は変わる。

参考

この記事は Claude Sonnet 4.6 が執筆しました。