コーディングエージェントにCMS改修を任せる前に、規約ファイルを1枚書いた話

うちの会社では、自社製のPHPのCMSを何年も育てています。
去年からその改修作業の一部を、AIのコーディングエージェントに任せるようになりました。

最初の数週間は、正直ひどかった。
コードは書ける。むしろ書けすぎる。頼んでいない「改善」までやってくれる。
CSSを直接直してSCSSと食い違わせる。既存の命名規則を無視して、自分の流儀のキャメルケースを持ち込む。
一つひとつは些細でも、レビューのたびに同じ指摘を繰り返すのは、人間相手でもAI相手でも消耗します。

エージェントは「優秀な新人」ではなく「初日の派遣さん」

途中で気づいたのは、例える相手を間違えていたことです。
優秀な新人なら、周りのコードを読んで空気を察してくれます。
でもエージェントは毎回が「初日」。前回の指摘を覚えていない前提で設計しないといけない。

初日の人に渡すべきなのは、分厚い仕様書ではありません。
「これだけはやらないでください」という貼り紙です。

仕様書より先に、「事故る場所」を書いた

それで書いたのが、リポジトリ直下に置く規約ファイル1枚。
ポイントは、べき論ではなく「過去に実際に事故った操作」だけを並べたことです。

# コーディング規約（エージェント向け・抜粋）

## 触ってはいけないもの
- .css を直接編集しない。正本は .scss。変更は必ず SCSS 側で行い、
  コンパイルして両方を同時に更新する
- DB スキーマの変更は SQL ファイルとして起こす。DB へ直接実行しない
- 本番用の設定ファイル（config.php）への変更を提案しない

## 必ずやること
- 既存の命名規則（スネークケース）に合わせる。新しい流儀を持ち込まない
- 変更したファイルは、作業報告の末尾に全件列挙する
- 仕様が曖昧なときは実装前に質問する。良かれと思って補完しない

## 判断に迷ったら
- 「動くけど既存の書き方と違う」なら、既存の書き方が正

見てのとおり、技術的にすごいことは何ひとつ書いてありません。
でもこれを渡すようになってから、レビューで同じ指摘を書く回数が目に見えて減りました。
特に効いたのは「CSSを直接編集しない」で、SCSSとの食い違い事故はこの1行でほぼ根絶できています。

運用して分かったこと：規約は「育てる」もの

半年運用して、いくつか学びがありました。

まず、規約は書いた瞬間から古くなります。
エージェントが新しいタイプの事故を起こすたびに、その場で1行追記する。これを習慣にしてから、規約が「生きた文書」になりました。
逆に、しばらく発動していないルールは消します。長い規約は読み飛ばされるのは、人間もAIも同じらしい。

次に、「なぜ」を1行添えると精度が上がること。
「CSSを直接編集しない」単体より、「正本はSCSS」という理由をセットにしたほうが、周辺ケースでの判断がまともになります。
ルールの丸暗記ではなく原則で判断してくれる感じは、ちょっと人間くさくて面白いところです。

最後に、規約があってもレビューは省けません。
規約は事故の種類を減らす道具であって、品質を保証する道具ではない。
最終的にマージボタンを押す責任は、いまのところ人間の側にあります。

教育コストの前払い、という考え方

新人教育に時間を使うのは、将来のレビュー時間を先に買っているからです。
エージェント相手には教育が蓄積しないぶん、規約ファイルという形で「前払い」しておく。
1枚書くのにかかった時間は30分。回収はたぶん、最初の1週間で終わっています。

CMSにプラグイン機構を後付けした話（設計メモはこちら）でも、エージェントとの分業が前提になっていて、この規約ファイルはその土台でもあります。

エンジニアがキャンプ場で何をしているかはサイトについてで白状しています。