バイブコーディング時代、リポジトリ規則と個人の好みの境界

AGENTS.mdの役割は開発者を複製することではなく、事故を防ぐべき境界だけを固定することにある。

バイブコーディングを導入したチームは、まもなく似たような問いに直面します。リポジトリごとにAGENTS.mdやCLAUDE.mdを置いてAIエージェントに規則を伝え始めると、どこまでを共通規則として固定し、どこからを個人の好みとして残しておくべきなのかが曖昧になるからです。この境界を誤ると、二つの問題が同時に生じます。必ず守るべき安全規則は緩くなり、逆に好みに近い選択は不必要に硬直化するのです。

最近のバイブコーディング論議で頻繁に登場する観点も似ています。人間はシステムアーキテクチャや好みのような高次の判断に集中し、実装やボイラープレート、反復的なリファクタリングはエージェントに任せよ、というものです。これを実務的に翻訳すれば単純です。リポジトリには「誰が作業しても同じでなければならないもの」を残し、人によって違ってもよい領域はあえて強制しないことです。

この問いは理論にとどまりません。先に整理した[OpenClaw事例分析]¹と[OpenClawのAGENTS.md解剖]²を見ると、実際に生産性を生んだ規則は好みの統一ではなく、境界の明示性でした。Steinbergerもまた、最近はコードをすべて読むわけではないが、システム構造と設計はずっと握り続けていると説明しています。³⁴ OpenClawが強く固定したのもタブとスペースではなく、import boundary、ビルドゲート、マルチエージェントの安全規則、そして不可逆な作業の承認境界です。⁵

肝心なのは多く書くことではなく、何を閉じて何を開いておくかを設計することです。

TL;DR

• リポジトリ規則はチームの好みを複製する文書ではなく、事故のコストが大きい境界を固定する文書であるべきです。
• ビルド、テスト、セキュリティ、Gitの安全規則、アーキテクチャ境界はリポジトリとともに管理しなければなりません。
• 命名のニュアンスやコメントスタイルのような好みは、formatter、linter、テンプレート、個人プロンプトで扱うほうが適しています。

なぜこの区分が重要なのか

AIエージェントは規則を素早く守ります。問題は、規則の性格を自分では区別できないという点にあります。リポジトリの指針にビルドコマンド、シークレットの扱い、ブランチの安全規則のように必ず守らなければならない制約と、「私ならこう書く」という水準の好みが混ざっていると、エージェントは両者を同じ重さで扱います。すると重要な規則は埋もれ、さほど重要でない規則は過度に増幅されます。

たとえばpnpm testを通さずにマージすればバグが出ます。実際のシークレットをコミットすれば事故になります。認証フローや決済の権限ロジックを十分な検討なしに変えれば運用リスクが生じます。こうしたものは議論の余地のない運用契約です。一方、関数名をfindUserにするかgetUserByIdにするか、テストファイルをソースの隣に置くか__tests__にまとめるか、importをどの順序で並べるかは、結果に影響を与えることはあっても、たいていは正解が一つに固定されるわけではありません。

この違いを区別しなければ、リポジトリの文書はすぐに肥大化します。あらゆる選好を中央の規則に引き上げれば、エージェントは文書を読むことにより多くのコンテキストを使い、チームは些細なスタイル合意に不要なエネルギーを費やします。逆に客観的な制約を好みの水準で扱えば、マルチエージェント環境で衝突と手戻りが繰り返されます。

結局、良いAGENTS.mdはチームの好みの辞書を作る文書ではなく、事故のコストが大きい領域の境界を明確に引いておく文書であるべきです。

OpenClawが実際に示したもの

以前の記事で整理したとおり、OpenClawのAGENTS.mdは単なるスタイルガイドではなく運用契約です。² 興味深いのは、その文書が「開発者をどう複製するか」よりも「エージェントがどこで事故を起こしうるか」にはるかに強く集中している点です。実際の指針を見ると、ビルド成果物やモジュール境界に影響を与えうる変更にはpnpm buildの通過をハードゲートとして要求し、@ts-nocheckのような典型的な回避パターンも明示的に禁止しています。⁵

たとえばOpenClawは、拡張が内部実装に直接手を出せないようにimport境界を規則としてロックしています。またgit stashの禁止、任意のブランチ切り替えの禁止、原子的なコミットの維持といったマルチエージェントの安全規則を置いています。ビルドとテストもハードゲートとソフトゲートに分け、いつ必ず検証しなければならないのかを明確に書いてあります。²⁵

逆にその文書は、「セミコロンを必ず使え」「関数名は必ずこういうトーンでつけろ」といった個人の好みを中心に設計されてはいません。つまりOpenClawが示した核心は単純です。リポジトリ文書が扱うべきなのは美的な統一感ではなく、構造的な安全性なのです。

リポジトリとともに管理すべき規則

以下はリポジトリとともにバージョン管理されるべき領域です。共通点は一つです。違反したときにバグ、衝突、セキュリティ事故、運用の混乱が発生するという点です。

• ビルドとテストのコマンド
• マルチエージェント環境におけるGitの安全規則
• 公開APIサーフェス、import boundary、パッケージ境界のようなアーキテクチャ制約
• シークレット、個人情報、運用設定値のようなセキュリティ境界
• 認証、決済、権限、DBスキーマのように手動レビューが必要な高リスク領域
• PR／コミットの単位のような変更管理の原則
• Research → Plan → Implementのように誤りのコストを下げる作業順序
• AI利用時の透明性要件
• チームがすでに検証済みの品質ゲートと自動化基準

これらの項目は「良さそうな推奨」ではなく、リポジトリの運用契約に近いものです。

たとえばビルドコマンドがnpm run buildなのかpnpm buildなのかを、人によって別々に解釈してはいけません。自動化パイプラインとローカル検証が同じコマンドを基準に動かなければならないからです。Gitの規則も同様です。マルチエージェントで同時に作業する環境では、任意のstash利用、要求されていないブランチ変更、広範囲の非原子的なコミットが実際の衝突を生みます。

セキュリティ境界については言うまでもありません。実際の電話番号、本番環境の環境変数、非公開鍵、顧客データのサンプルといったものは、チームのスタイル選好ではなく禁止リストです。こうした内容は個人プロンプトや暗黙知に置いてはならず、リポジトリの文書と自動スキャンの規則にともに残っていなければなりません。

ワークフローの順序も同じ文脈です。実装の前に既存コードを読み、計画を立て、それから変更させるという手順は、単なる形式主義ではありません。エージェントは質問を減らすほど速くなりますが、誤った仮定の上で速くなれば、後でより高くつきます。ですから探索と計画を先に要求する規則は、好みではなくコスト削減の装置です。

ここでもう一つ重要なポイントがあります。チームがすでに自動化に依存しているなら、その自動化が期待する形式もまた共通規則になります。たとえばConventional Commits形式がリリースノート、チェンジログ、CIルーティングに結びついているなら、それはもはや好みではありません。逆に単に「読みやすい」水準の形式選好であれば、チームレベルの合意であってよく、必ずしもリポジトリの中核規則に格上げする必要はありません。

反復手順をどこに置くかも同じ基準で見ることができます。OpenClawはリリースやセキュリティ点検のような複雑な反復業務をAGENTS.mdの本文に長く書くのではなく、別のスキルとして分離しています。²⁶ これもまた良い区分です。リポジトリの中核文書には原則と境界を残し、手続き的な詳細は再利用可能な実行面として分離するほうが長持ちします。

個人の好みとして残してよい領域

逆に次のような領域は、個人やチームの好みとして残しておくことができます。もちろんチームが一貫性のために標準化することはできますが、それがリポジトリの中核的な安全契約である必要はありません。

• セミコロンの使用有無、空白の数、trailing commaのようなフォーマットの細部
• 関数名や変数名の細かなニュアンス
• importの並べ方
• コメントをどの程度まで書くかというスタイル
• テストファイルの配置方法とテストの記述スタイル
• 抽象化を早く行うか遅く行うかという選好
• feature-based構造とlayer-based構造の間の選好
• エラー処理パターンの細かな選択
• プロンプトを長く書くか短く書くかといった個人の作業スタイル

こうした項目は、互いに異なる選択肢がいずれも合理的でありうるものです。たとえばあるチームはstrictな型設定を好み、あるチームはオンボーディングのコストを下げるために段階的に厳格度を上げます。あるチームはResultパターンを好み、あるチームは例外ベースのフローのほうが明確だと感じます。どちらであれ一貫して運用されるなら、十分に合理的でありえます。

重要なのは、こうした好みを完全に無視しようという意味ではないという点です。好みも生産性に影響します。ただし、それをどこに置くかが重要なのです。リポジトリの中核契約として扱うよりも、formatter、linter、テンプレート、サンプルコード、個人プロンプト、チームプレイブックのような軽い装置で扱うほうが適しています。そうしてこそ、好みは維持しつつリポジトリの指針が過度に重くならずに済みます。

とりわけバイブコーディングでは、この違いがいっそう重要になります。エージェントにあらゆる好みを強く注入すれば、コード生成はかえって硬直し、小さな変化でも規則の衝突が多く発生します。一方、好みは緩やかなガイドとして置き、安全と品質に直結する境界だけを強く固定すれば、エージェントははるかに安定して働きます。

この点でもOpenClawは良いヒントを与えてくれます。あのリポジトリのコーディングスタイル規則が本当に防いでいるのは、タブとスペースの選択ではなく、@ts-nocheckの乱用、動的importの混用、プロトタイプの変更といった構造的な欠陥です。²⁵ 表向きはスタイルのセクションに見えても、実際の内容は好みではなく時限爆弾の防止装置に近いのです。

一行の判別基準

実務では複雑に考える必要はありません。次の基準一つでほとんどが分類できます。

違反したときにバグ、衝突、セキュリティ事故、レビューの混乱が起きるならリポジトリ規則です。
違反したときに「私ならこうは書かない」という程度なら好みです。

この基準が良い理由は、技術スタックが変わっても有効だからです。ReactでもGoでも、モノレポでも単一サービスでも、人間とエージェントがともに働く限り、「事故を防ぐ規則」と「選好を表現する規則」は区別されなければなりません。

実践設計：四つの層に分けるとすっきりする

私はリポジトリの運用規則を次の四つの層に分ける方式をおすすめします。

第一に、AGENTS.mdにはハードガードレールだけを置きます。ビルド／テストのコマンド、禁止領域、レビュー必須条件、Gitの安全規則、高リスク変更の承認境界のように、間違えれば事故になるものです。

第二に、チーム共通のコンベンションはコードフォーマッターとリンター、テンプレート、サンプルコードに置きます。命名の選好、importの順序、ファイルの配置方法、コメントスタイルのように、一貫性は重要でも文書として長く読まれる必要はないものです。

第三に、繰り返される複雑な手順はスキルやプレイブックとして分離します。リリース、セキュリティ点検、PR運用のように段階の多い業務を本文に冗長に入れるのではなく、実行可能なワークフローとして切り出す方式です。

第四に、個人の作業スタイルはローカルのプロンプトとエディタ設定に残します。プロンプトの文体、並列エージェントの数、探索の習慣、一時的なチェックリストのようなものは、個人の生産性の領域として置くほうが適しています。

このように分ければリポジトリは軽くなり、チームの合意は自動化され、個人は自分に合った作業スタイルを維持できます。何よりも、エージェントが読む指針の優先順位が鮮明になります。

重要なのは開発者を複製することではない

バイブコーディングの核心は、AIに人間のようにコードを書かせることではありません。むしろ人間とまったく同じに書かなくてもよい領域を受け入れ、その代わり必ず同じでなければならない部分だけを明確に固定することにあります。

良いリポジトリの指針は、「私たちのチームはこういう好みを持つ人々だ」を長々と説明しません。代わりに「このリポジトリではこれだけは必ず守らなければならない」を短く明確に語ります。好みは開いておき、境界は閉じておくのです。

それが結局、AIエージェントをうまく使うチームと、AIを使いながらも疲弊し続けるチームを分ける違いである可能性が高いのです。