Googleのリポジトリから学ぶAIコーディング運用：AIに任せる前に、リポジトリをAI対応にする

AIコーディングというと、どのAIツールを使うか、どんなプロンプトを書くかに注目しがちです。

もちろん、それも重要です。ただ、AIへ継続的に作業を任せようとすると、プロンプトだけでは足りません。

AIがリポジトリの構成を理解できるか。どのコマンドで検証すればよいか。どのファイルを触ってよいか。PRを作るときに何を書けばよいか。AIが古い実装パターンに引っ張られないように、どんな知識を渡すべきか。

こうした情報がリポジトリ側に用意されているかどうかで、AIコーディングの安定感はかなり変わります。

この記事では、Google ChromeのGitHub Organizationで公開されている GoogleChrome/webstatus.dev と GoogleChrome/modern-web-guidance-src を題材に、AIコーディング運用として何が学べるのかを整理します。

先に言うと、この記事で見るのは「AIがどれだけコードを書いたか」ではありません。外から見える範囲で重要なのは、AIに作業させやすいように、リポジトリ側へ文脈、ルール、検証導線、PR運用が組み込まれている点です。

今回見るのはGoogle Chromeの2つのリポジトリ

タイトルではわかりやすさのために「Googleのリポジトリ」と書いていますが、正確にはGoogle ChromeのGitHub Organizationで公開されている2つのリポジトリを見ます。

1つ目は GoogleChrome/webstatus.dev です。

これはGoogle検索やChrome本体のリポジトリではありません。webstatus.dev は、Web Platform features のブラウザ対応状況や、開発者による採用・利用状況などを追跡するためのWebサービスです。

webstatus.dev のREADME では、Browser Compat Data、Web Platform Tests、Web Featuresなどの公開データを取り込み、Goのbackend APIとTypeScriptのfrontend dashboardで提供する構成が説明されています。

2つ目は GoogleChrome/modern-web-guidance-src です。

これは GoogleChrome/modern-web-guidance のソースリポジトリです。Modern Web Guidanceは、AI coding agentへモダンなWeb開発の知識を渡すAgent Skillとして配布されています。source repo側では、guidanceの作成、調整、評価を扱います。

この記事では、この2つを同列には扱いません。

webstatus.dev は、個別プロダクトの開発リポジトリをAI対応にしている例です。一方、modern-web-guidance-src は、AIエージェント向けの知識そのものをSkillとして作り、配布し、評価している例です。

主役はあくまで webstatus.dev です。modern-web-guidance-src は、AI向けの文脈やSkillを設計する流れが特殊な事例ではないことを補強する材料として扱います。

見るべきなのはAIが作業しやすい設計

公開リポジトリを見ただけでは、どのコードをAIが書いたのかは断定できません。

しかし、AIに作業させるための準備は確認できます。

webstatus.dev には、たとえば次のような要素があります。

見るもの	何が分かるか
`GEMINI.md`	AI向けの入口とプロジェクト文脈
`.agent/skills`	作業領域ごとのルール分割
devcontainer	AI利用を含む開発環境の再現性
`make precommit`	AI作業後の検証導線
PR作成Skill	人間がレビューしやすいPR運用

この構成から見えるのは、AIに「いい感じに直して」と丸投げする運用ではありません。

むしろ、AIが迷わないように、必要な情報をリポジトリの中に置いています。どの作業では何を見ればよいか。変更後にどのコマンドを実行すればよいか。PRを作るときに何を説明すべきか。

こうした情報が整理されているため、AIの作業結果を人間が受け取りやすくなっています。

これはwebstatus.devだけの特殊な話ではない

webstatus.dev の構成は、Google Chrome関連のリポジトリだから特殊、というだけではありません。

現在のAIコーディングツール全体でも、リポジトリ側に文脈や作業ルールを置く流れが強くなっています。

たとえば Claude CodeのBest Practices では、CLAUDE.md にプロジェクト固有のコマンド、コードスタイル、ワークフロー、レビュー時の注意などを置く考え方が説明されています。同時に、常に必要ではないドメイン知識やワークフローはSkillsへ分け、CLAUDE.md を短く保つことも案内されています。

GitHub Copilot coding agentのbest practices でも、AIに任せるIssueのスコープ、背景、期待する変更、受け入れ条件、検証方法を明確にすることが重視されています。

また、CodexのSkills では、必要なときに必要なSkillだけを読む progressive disclosure の考え方が説明されています。巨大な指示ファイルを毎回読むのではなく、作業に応じて必要な文脈だけを読む設計です。

同じGoogle Chrome Organizationの modern-web-guidance-src も、この流れを補強します。webstatus.dev が個別リポジトリをAI対応にする例だとすれば、modern-web-guidance-src はAIエージェント向けの知識そのものをSkill化し、その効果を評価する例です。

GEMINI.mdはAI向けの入口になっている

webstatus.dev には GEMINI.md があります。

これはGemini Code Assist向けのプロジェクト文脈ファイルです。中には、プロジェクト概要、ローカル開発ワークフロー、主要なMakefileコマンド、Specialized Skills、知識ベース更新の手順などが整理されています。

重要なのは、GEMINI.md が巨大な全部入り説明書になっていないことです。

もちろん、プロジェクトの全体像は書かれています。しかし、細かい作業ルールは GEMINI.md にすべて詰め込むのではなく、.agent/skills 側に分けています。

つまり、GEMINI.md はAIに毎回すべてを説明するための長文プロンプトではなく、プロジェクト全体を把握し、必要な作業ルールへ進むための入口として使われています。

この考え方は、Gemini CLIに限らず、Codex、Claude Code、Cursor、GitHub Copilot coding agentなどでも応用できます。

個人開発のリポジトリでも、まず AGENTS.md や GEMINI.md のような入口ファイルを置き、そこに以下を書くだけでも効果があります。

プロジェクト概要
よく使うコマンド
編集してよい範囲
テスト、lint、build方法
PR作成時の注意
参照すべき設計ドキュメント

AIに毎回説明するのではなく、リポジトリに説明を置く。これが最初の一歩です。

Skill分割はクレジット節約だけが目的ではない

このリポジトリで特におもしろいのが、.agent/skills による分割です。

GEMINI.md には、backend、frontend、E2E、ingestion、workers、search grammar、PR作成などのSkillがあることが書かれています。

また、webstatus.dev のPR #2278 では、大きな GEMINI.md の文脈を modular Gemini CLI Skills へ移行したことが説明されています。理由として、Progressive Disclosureによるtoken overhead削減、domain-specific instructionsによる信頼性向上、専門ドキュメントの保守性向上が挙げられています。

ここで大事なのは、Skill分割を単なるクレジット節約として見ないことです。

たしかに、毎回すべてのルールを読ませなければ、トークンやクレジットの消費は減ります。しかし、それは副次的な効果に近いです。

本質は、AIが今の作業に必要な情報だけを参照しやすくすることです。

frontendの修正をしているときに、backend、E2E、データ取り込み、PR作成の細かいルールまで常に意識する必要はありません。逆に、PRを作る段階では、frontendの細かい実装ルールよりも、差分確認、検証、コミットメッセージ、PR本文のルールが重要になります。

このように作業ごとに必要な情報は違います。

分割する理由	内容
作業範囲を絞る	frontend作業中にbackendの細かいルールまで意識しなくてよい
指示の混線を防ぐ	関係ない制約が混ざりにくい
必要な文脈だけ渡す	今の作業で見るべき情報に集中しやすい
保守しやすい	frontendルールだけ、PRルールだけを個別に更新できる
差分知識を残しやすい	AIが見落としやすい注意点を領域ごとに管理できる

全部入りの巨大なルールファイルを毎回読ませるよりも、作業領域ごとに分けておいた方が、AIにとっても人間にとっても扱いやすくなります。

AI向け文脈は、多ければよいわけではありません。今の作業に関係ない情報を減らすことで、AIが見るべきものをはっきりさせる方が効く場面があります。

modern-web-guidance-srcに見る、差分知識を渡す設計

modern-web-guidance-src は、今回の話をさらに一段広げてくれます。

modern-web-guidance のREADME では、Modern Web GuidanceはAI coding agentsへmodern web platformの知識、best practices、modern API patternsを渡すAgent Skillとして説明されています。

背景にあるのは、AIが古いlegacy codeに引っ張られ、現在ならnative APIで書ける処理を、重いJavaScriptや古いworkaroundで書くことがある、という問題意識です。

Modern Web Guidanceは、この問題に対して、modern browser APIs、performance、accessibility、responsible fallbacksを使えるように、targeted guidanceをAIのcontext windowへ入れる設計になっています。

さらに、guidesがtoken-efficientであることも重視されています。

project-discipline-guides/SKILL.md では、Gemini、Claude、Codexが共通して知っている一般論をmirrorとして生成し、Target guideから不要なcommon knowledgeを削るワークフローが説明されています。

これは、AI向けの文脈は多ければよいわけではない、という今回の記事の主張とよく合います。

必要なのは、AIがすでに知っている一般論を増やすことではありません。AIが見落としやすい差分知識、プロジェクト固有の判断、実務上の落とし穴を渡すことです。

また、Modern Web Guidanceは、guidanceを置いて終わりではありません。

modern-web-guidance-src のREADME や CONTEXT.md では、realistic developer prompts、browser-based assertions、gold-standard demo、negative demo、guided / unguidedの比較によって、AIエージェントがguidanceに従えるかを測る評価基盤も説明されています。

この記事ではeval結果の数値までは扱いません。重要なのは、AI向け知識を「置いて終わり」にせず、効果を測る設計まで含めて考えている点です。

devcontainerと検証コマンドがAI作業の土台になる

AIに作業を任せるなら、AIがどの環境でコマンドを実行するのかも重要です。

webstatus.dev のREADMEでは、devcontainerを使って開発を始める流れが説明されています。また、devcontainerにはGemini CLIが含まれることも書かれています。

これは単に「便利な開発環境」というだけではありません。

AIコーディングでは、環境差がそのまま失敗につながります。

依存関係が入っていない
コマンドが手元と違う
テストが動かない
ローカルでだけ通る
AIが実行した環境と人間が確認する環境が違う

こうしたズレがあると、AIに作業を任せても最後は人間が全部直すことになります。

devcontainerのような仕組みで環境を揃えておくと、人間とAIが同じ前提で作業しやすくなります。

さらに、GEMINI.md では make precommit が主要コマンドとして説明されています。これはテスト、lint、ライセンスヘッダー確認などを含む、PR前の包括的な検証コマンドとして位置づけられています。

AIはコードを書けます。しかし、そのコードが正しいとは限りません。

だからこそ、AI作業を受け止める検証導線が必要です。

検証導線	効果
test	動作の破壊を検出する
lint	コード品質のばらつきを抑える
format	差分を読みやすくする
typecheck	型の破壊を検出する
content check	ブログやMDXの破損を検出する

小規模なリポジトリなら、make precommit ほど大きな仕組みは不要です。

たとえば、以下のようなコマンドを1つ用意するだけでも十分です。

pnpm verify

中身は、プロジェクトに合わせて次のようにできます。

pnpm lint
pnpm typecheck
pnpm test
pnpm build

大事なのは、AIに「最後にこれを実行して」と言える状態にしておくことです。

検証コマンドがない場合、AIの作業結果を人間が目視で確認し続けることになります。それではAIの速度を活かしにくくなります。

PR作成Skillから学べるレビューしやすいAI運用

webstatus.dev には、webstatus-pr-creation というPR作成用のSkillもあります。

このSkillでは、AIがPRを作るときの手順が具体的に書かれています。

git status を確認する
git diff を確認する
lintやtestを実行する
main に直接commitしない
branchを作る
Conventional Commits形式でcommit messageを書く
PR本文に What、Why、How、Corrected Assumptions / Learnings を書く

PR本文に「何を変えたか」だけでなく、「なぜ変えたか」「どう実装したか」「間違えた前提や学び」まで書くことを求めている点が重要です。

AIにPRを作らせるなら、コードだけでなく、レビューしやすい説明まで出させる必要があります。

AIが作った差分は、人間がレビューします。そのときにPR本文が「fixed bug」だけでは、レビューする側は結局すべての差分を読み解かなければいけません。

一方で、PR本文に以下が整理されていれば、レビューの負担は下がります。

PR本文に必要な要素	役割
What	何を変えたか
Why	なぜ変えたか
How	どう実装したか
Corrected Assumptions / Learnings	作業中に分かった誤解や学び

特に Corrected Assumptions / Learnings はAI運用らしい項目です。

AIは途中で間違えた前提を置くことがあります。リポジトリ構成を誤解したり、既存ルールを見落としたり、不要な実装をしようとしたりします。

その誤解をPR本文や作業ログに残せば、次回以降の作業で同じ失敗を減らせます。

これは、AIの作業を単発で終わらせず、リポジトリの運用改善につなげる考え方です。

すぐ真似できること、真似しなくてよいこと

webstatus.dev や modern-web-guidance-src の構成を、そのまま個人開発や小規模リポジトリに持ち込む必要はありません。

むしろ、最初から全部真似しようとすると重くなります。

すぐ真似するなら、まずは以下で十分です。

AGENTS.md
docs/ai/
  pr.md
  verify.md
  frontend.md
  content.md

それぞれの役割はシンプルです。

真似すること	小規模リポジトリでの形
AI向け入口を作る	`AGENTS.md`
検証コマンドをまとめる	`pnpm verify`
PR作成ルールを書く	`docs/ai/pr.md`
UI実装ルールを書く	`docs/ai/frontend.md`
記事制作ルールを書く	`docs/ai/content.md`

もしAIに守らせたい実装パターンがあるなら、次のようなファイルを追加してもよいです。

docs/ai/
  guidance.md
  eval-checklist.md

guidance.md には、AIに守らせたい実装パターンや避けたい古い実装を書きます。eval-checklist.md には、AIの出力をどう確認するかを書きます。

個人ブログなら、特に content.md は有効です。

たとえば、以下のようなルールを置いておくと、AIに記事を書かせるときのブレを減らせます。

断定しすぎない
未確認情報は未確認と書く
SEOより内容品質を優先する
MDXとして壊れない形式にする
コードブロックには言語名を付ける
引用元を本文作成時に再確認する

一方で、すぐ真似しなくてよいものもあります。

Google Cloud前提の構成
Spanner、Cloud Run、Valkeyなどのインフラ
Gemini CLIへの過度な依存
最初から細かすぎるSkill分割
MCP連携
大規模チーム前提のeval harness

大事なのは、Googleと同じ道具を使うことではありません。

AIが迷わないように、文脈と検証の置き場所を作ることです。

最初は、入口ファイル、検証コマンド、PRルールの3つだけでも効果があります。

向いているリポジトリ、向いていないリポジトリ

AI向けのリポジトリ設計は、すべてのリポジトリで同じ重さにする必要はありません。

向いている	向いていない
テストやlintがある	検証コマンドがない
PRレビューをする	直接mainに反映する
何度もAIに作業させる	単発作業だけ
領域ごとの作業がある	まだ構成が固まっていない
AIに守らせたい実装パターンがある	ルールを保守できない
AIの出力を評価する観点がある	AIの出力をレビューしない

まだ構成が固まっていないリポジトリなら、細かいSkill分割よりも、まずは検証コマンドと作業範囲を整える方が先です。

一方で、同じ種類の作業を何度もAIに任せるなら、入口ファイル、領域ごとのルール、PR作成ルールを整える価値は上がります。

まとめ：AIに任せる前に、リポジトリをAI対応にする

GoogleChrome/webstatus.dev から学べるのは、AIにすべてを任せる方法ではありません。

むしろ逆です。

AIに任せる前に、リポジトリ側を整える。AIが読む入口を用意する。作業領域ごとにルールを分ける。検証コマンドを用意する。PR作成の手順を明文化する。人間がレビューしやすい成果物を出させる。

さらに modern-web-guidance-src を見ると、AI向けの知識そのものをSkillとして作り、配布し、評価する流れも見えます。

AI向け文脈は、多ければよいわけではありません。AIがすでに知っている一般論を増やすより、AIが見落としやすい差分知識、プロジェクト固有の判断、実務上の落とし穴を渡すことが重要です。

AIコーディングの品質は、AIの性能だけで決まりません。リポジトリに文脈、ルール、検証、PR運用があるかどうかでも大きく変わります。

AIに任せる前に、まずリポジトリをAI対応にする。

webstatus.dev と modern-web-guidance-src から学べるのは、そのための実践的な設計です。