Claude Codeを開発チームの一員にする実運用設計

Claude Codeはリポジトリ直下のCLAUDE.mdを毎セッション読み込みます。ここに何を書くかで、エージェントの働きの質が決まります。私たちの原則は「人間の新人に渡して恥ずかしくない資料にする」です。

書くべき内容は4種類です。第一に、プロジェクトの構成。第二に、コマンド一覧。開発サーバーの起動、テスト実行、リント、ビルドのコマンドを正確に書きます。エージェントが間違ったコマンドを試行錯誤する時間は純粋な無駄です。第三に、規約。コミットメッセージの形式、命名規則、「このディレクトリは触らない」という境界。第四に、ドメイン知識。LMSの「受講者」「組織」「コース」といった用語の定義と関係です。

逆に書くべきでないものは、頻繁に変わる情報と長大な設計文書です。CLAUDE.mdは毎セッションのコンテキストを消費するため、長いほど他の情報を圧迫します。目安は200行以内。詳細はdocs/以下に置き、CLAUDE.mdからはパスを参照させます。

もう一つ重要な運用は、エージェントが間違えたときにCLAUDE.mdを更新することです。同じ間違いを2回見たら、それは指示の不備です。1行追記するだけで、以後のセッション全てで同じ間違いが消えます。人間の新人教育における「手順書の改訂」と同じ構造です。

.claude/commands/ディレクトリにMarkdownファイルを置くと、スラッシュコマンドとして呼び出せる定型プロンプトになります。実際に使っているパターンを3つ紹介します。

1つ目は、レビューコマンドです。変更差分をセキュリティ、パフォーマンス、規約違反の3観点でレビューさせる指示を定型化しています。人間がレビューする前の一次フィルタとして機能します。2つ目は、記事作成コマンドです。コラム記事のデータ構造に準拠した記事データの生成と内部リンク設定を定型化しています。3つ目は、デプロイ前チェックです。ビルド、テスト、環境変数の差分確認、マイグレーションの有無確認をコマンド一発で実行させます。

設計のコツは「手順が3回以上繰り返されたら定型化する」というシンプルな基準です。最初から網羅的に作ろうとすると、使われないコマンドが増えて管理が濁ります。

Claude Codeには許可設定があり、ファイル編集、コマンド実行、外部通信をどこまで自動承認するかを制御できます。

境界の考え方は「取り消せる操作は任せ、取り消せない操作は人が握る」です。ローカルのコード変更はgitでいくらでも巻き戻せますが、本番への反映と外部への公開は巻き戻せません。AIの精度の問題ではなく、操作の可逆性で線を引くのがポイントです。

AIのコードは文法ミスやタイポがほぼない代わりに、「もっともらしいが要件とズレている」「存在しないAPIを自信満々に呼ぶ」「テストが実装をなぞっただけ」という種類の問題を起こします。

私たちのレビュー手順は3段階です。まず、差分を通読する前に、エージェント自身に変更の意図と影響範囲を要約させます。この要約と実際の差分がズレていたら、それ自体が危険信号です。次に、テストコードを実装より先に読みます。テストが要件を正しく表現していれば、実装の細部は信頼できます。最後に、rsyncのドライランやステージング環境での動作確認という実物での検証を挟みます。

コードレビューだけで本番に出さない、という原則は、AI時代にはむしろ重要度が増しています。

これからClaude Codeをチームに導入する場合の初期整備項目を挙げます。

この体制で運用した結果、定型的な実装は従来の数分の一の時間で完了するようになりました。一方で、要件そのものが曖昧なタスク、部門をまたぐ仕様決定、「そもそも作るべきか」という判断は、エージェントには任せられません。

CLAUDE.mdという「教育資料」、カスタムコマンドという「業務手順書」、権限設計という「職務権限規程」、レビュー体制という「品質管理」。人間の組織で当たり前にやってきたことを、AIに対しても丁寧にやる。それが、AIを開発チームの一員にする実務の中身です。