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

Thu, 26 Mar 2026 17:26:21 +0900

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

チョン・ドヒョン - ROBOCO首席コンサルタント

バイブコーディングを導入したチームは、まもなく似たような問いに直面します。リポジトリごとに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、テンプレート、サンプルコード、個人プロンプト、チームプレイブックのような軽い装置で扱うほうが適しています。そうしてこそ、好みは維持しつつリポジトリの指針が過度に重くならずに済みます。

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