AIエージェントの運用ノウハウを組織の資産にする — project-scaffoldを作った話

使い方や導入手順だけ知りたい場合は、以下の記事にまとめています。

project-scaffoldでAIエージェントの運用ルールを複数プロジェクトに展開する

はじめに

AIエージェントを個人で使うだけなら、AGENTS.md を自分が使いやすいように書き、必要に応じてSkillやドキュメントを追加していけば済みます。
ただ、これを複数のプロジェクト、さらに組織全体で運用しようとすると難しくなります。

プロジェクトごとに改善を続ければ、それぞれの環境に合わせて運用は変わっていきます。
それ自体は問題ではありません。

問題になるのは、

• どのルールを組織として共通化すべきなのか
• どこからがプロジェクト固有のルールなのか
• 新しいプロジェクトでは何を参考にすればいいのか
• あるプロジェクトで生まれた良い運用を、どう他へ展開するのか
• プロジェクトごとのAIエージェント活用方法を、どう比較するのか

が、だんだん分からなくなることです。

この問題を扱うために、agent-skills で project-scaffold と project-scaffold-audit を公開しました。
この記事ではSkillのコマンドや導入手順よりも、なぜこの仕組みにしたのかを中心に書きます。

project-scaffold では、組織共通の運用を Org Standard として管理し、各プロジェクトとの差分を project-scaffold-audit で拾い上げます。
各プロジェクトを同じ形に揃えるのではなく、現場で生まれた改善を組織側へ戻せるようにするのが目的です。

きっかけは、組織にAIをどう導入するかを考えたこと

最初にこの問題を考え始めたのは、以前PM/PLとして働いていた頃でした。
開発にAIを導入するとしても、Claude CodeやCodexを使える状態にすれば終わり、という話ではありません。

例えば、

• エージェントにはどこまで判断させるのか
• 要件や仕様をどこに残すのか
• AGENTS.md には何を書くのか
• 実装前に何を確認させるのか
• 意思決定をどう残すのか
• 作業途中のファイルをどう扱うのか
• 実装後に何を検証させるのか

といった運用も一緒に考える必要があります。

その後、個人開発でAIエージェントを使いながら、複数のプロジェクトでいろいろな運用を試すようになりました。
そこで、組織で運用したら起きそうだと考えていた問題を、自分自身でも経験することになりました。

プロジェクトごとに運用が独自進化する

最初は、あるプロジェクトで作った AGENTS.md や docs/ の構成を、新しいプロジェクトへコピーして使っていました。

そこから開発を進めるたびに、

「この情報は AGENTS.md ではなく docs/ に置いた方がいい」

「このルールは分割した方がエージェントが迷わない」

「作業中のファイルは別の場所へ置いた方が扱いやすい」

といった改善を加えていきました。

すると、しばらく経った頃には各プロジェクトの運用が別々に進化していました。

新しいプロジェクトを触っている間は、それほど困りません。
問題は、しばらくして以前のプロジェクトへ戻ったときでした。
他のプロジェクトではすでに改善していた運用が反映されていないので、以前は普通に使っていた構成がかなり使いづらく感じます。

かといって、最新のプロジェクトから全部コピーすればいいわけでもありません。

そこで追加したルールが、

• そのプロジェクトだから必要なのか
• 他のプロジェクトにも入れた方がいい改善なのか

を判断する必要があるからです。

AGENTS.md は単純にコピーできない

もう一つ困ったのが、プロジェクト固有の情報と、他のプロジェクトでも使える運用ルールが混ざっていたことでした。

例えば一つの AGENTS.md に、

• AIエージェント全般の運用
• 使用している技術
• アプリケーション固有の構成
• 要件や仕様に関するルール
• そのプロジェクトだけの作業手順

が全部書かれているとします。

これを新しいプロジェクトへコピーすると、当然ながら元のプロジェクトの前提も一緒についてきます。
実際、既存プロジェクトをベースにプロトタイプを作っていると、

AGENTS.md や docs/ に書かれている内容と、今の指示が矛盾している。どちらを優先すればいいのか。

という指摘をエージェントから受けることが何度もありました。
人間なら「これは前のプロジェクトの話だな」と読み飛ばせる内容でも、AIエージェントにとっては作業時のコンテキストになります。

この経験から、他のプロジェクトにも適用できる標準的な運用はルートの AGENTS.md に置くようになりました。
技術・要件・仕様などの固有情報は docs/ や app/AGENTS.md に置き、再利用したい運用とプロジェクト固有の情報を意識して分離しています。

もちろん、このディレクトリ構成自体を正解にしたいわけではありません。
組織によって docs/ を使わないかもしれませんし、ルートの AGENTS.md に持たせる責務も違います。
どこまでを共通ルールとして扱うのか、その組織なりの基準を決めておく必要があります。

組織では「良い運用があったら共有して」だけでは回らない

仮に10個のプロジェクトがあり、それぞれがAIエージェントの使い方を改善しているとします。
CTOやテックリードが、すべてのプロジェクトについて、

• AGENTS.md
• ドキュメント構成
• Skills
• 開発フロー
• レビュー方法
• 独自ルール

まで継続的に把握するのは現実的ではありません。

一方で、「良いやり方を見つけたら共有してください」というボトムアップの運用だけに頼るのも難しいところです。
日常的に使う側からすると、ちょっとした改善は、共通化を担当するチームへ報告するほどのものに見えないことも多いからです。

そこで考えたのが、

各プロジェクトには自由に改善してもらい、その結果を後から差分として拾い上げる

という方法でした。

Built-in Starter / Org Standard / Project

project-scaffold では、運用を3つのレイヤーに分けています。

Built-in Starter

Skillに同梱している汎用的な初期構成。
AGENTS.md、docs/、.gitignore など、AIエージェントを使ったプロジェクト運用を始めるための例を用意しています。

例えば冒頭に挙げた「作業途中のファイルをどう扱うのか」には、tmp/<work-item>/ を置き場所にして docs/ を正本と分ける、という答えを持たせています。
ルート直下の .gitignore にはアンカー付きの /tmp/ ルールを必ず残し、AGENTS.md にもその境界を書きます。
エージェントが作った一時ファイルがコミットに紛れ込んだり、逆に残すべき記録が消えたりするのを防ぐためです。

ただし、これをそのまま組織の標準にしてほしいわけではありません。
あくまで最初の材料の一つとして用意しています。

Org Standard

チームや組織が実際に管理する標準。
実体は $PROJECT_SCAFFOLD_HOME（既定は ~/.config/agent-skills/project-scaffold/）以下の scaffold/ ディレクトリで、Skillのインストール先とは別の場所に置いています。
gh skill update でSkillを更新しても、育てた標準が巻き込まれて消えないようにするためです。
チームや組織で共有するときは、このディレクトリをGitリポジトリにして配ります。

Built-in Starterから作ることもできるし、既存のプロジェクトやドキュメントを参照して作ることもできます。
そのため project-scaffold は、それぞれの組織が自分たちの運用をOrg Standardとして管理するための仕組みとして作っています。
特定のディレクトリ構成を配ることが目的ではありません。

Project

Org Standardを適用する個々のプロジェクト。
新規プロジェクトだけでなく、既存プロジェクトへの適用も想定しています。

既存プロジェクトでは、すでにあるルールをいったんそのまま尊重します。
変更内容を計画として提示し、承認を取ってから、必要なものだけを反映します。

最初のOrg Standardは完成品ではない

複数の既存プロジェクトを調べ、各チームの運用を把握して、最初から完璧なOrg Standardを作るのは現実的ではありません。
まずはBuilt-in Starterを使うか、参考にしたいプロジェクトをいくつか指定して、ざっくりと作れば十分です。

肝心なのは、実際のプロジェクトを見ながら育てることです。そのために作ったのが project-scaffold-audit です。

差分を消すのではなく、差分を評価する

project-scaffold-audit はProjectとOrg Standardを比較し、見つかった差分を4種類に分類します。

分類	意味
Local	そのプロジェクト固有の事情として残す
Promote	Org Standardへ取り込む候補
Remove-Migrate	古い・重複している・標準と矛盾しているなど、整理を検討する
Needs-decision	判断材料が足りず、人間による検討が必要

Org Standardとの差分は、違反として扱いません。 これがauditの前提になっています。

例えば特定の技術を使うプロジェクトだけに必要なルールなら、Local のままで構いません。
一方、そのプロジェクトで生まれたレビュー方法が他のプロジェクトでも使えそうなら、Promote の候補になります。
場合によってはOrg Standard側の方が古いこともあります。

標準化というと、すべてのプロジェクトを同じ状態へ寄せるイメージを持ちやすいと思います。
ここでやりたいのは、違いをなくすのではなく、その違いが必要なのかを判断できる状態にすることです。
auditはそのために置いています。

AIが分類し、人間が決める

差分の検出や Local / Promote といった一次分類はAIエージェントに任せます。
ただし、AIが判断したものをそのまま自動でOrg Standardへ取り込むことはしません。

AIモデルは今後も変わるので、「このパターンなら必ずLocal」のようなルールを大量に持つのではなく、

• 他のプロジェクトでも使えるか
• 特定の技術やドメインだけに依存していないか
• 既存の標準とどういう関係にあるか

といった基本的な観点に留めました。最後は、その時点のAIと人間が判断します。

読む範囲を最初から絞っている

project-scaffold も project-scaffold-audit も、プロジェクトの中で読む範囲をあらかじめ制限しています。

見るのは、ルート直下の AGENTS.md / README.md / .gitignore、Org Standardで指定した運用ファイル、docs/ の浅い構成とその README.md / AGENTS.md、そして docs/00_templates/ のテンプレートまでです。
アプリケーションのソースコード、依存関係、生成物、シークレット、製品仕様は読みません。

運用ルールを見るだけなら、製品の中身まで読む必要はありません。読む範囲を限定することで、差分確認に不要なコンテキストを持たせずに済みます。
それに、読まれる範囲があらかじめ分かっていれば、顧客のコードを扱うプロジェクトでも、どこまでを確認対象にするか整理しやすくなります。

Projectで生まれたノウハウをOrg Standardへ戻す

全体の運用は、次のようなループになります。

あるプロジェクトで生まれた改善をOrg Standardへ戻し、それを別のプロジェクトへ展開します。
このサイクルを回すことで、Org Standardは組織のAIエージェント運用で得られたノウハウが溜まっていく場所へ育っていきます。
配った時点のテンプレートのまま止まることはありません。

auditを組織でどう回すか

CTO、テックリード、あるいはAIの共通化を担当するチーム（以下、共通化チーム）が定期的にauditを実行すると、

• プロジェクト間の判断基準を揃えやすい
• 他でも使えそうな改善を発見しやすい
• Org Standardから大きく外れているプロジェクトを把握できる

という利点があります。
ただ、プロジェクトが数十個あれば、共通化チームだけですべてを見るのは難しくなります。
その場合は例えば、

月に1回 project-scaffold-audit を実行し、レポートを提出する

というルールを各プロジェクトの仕事に組み込む方法も考えられます。

auditの既定の出力は読み取り専用のレポートで、差分を確認したプロジェクトのファイルには手を入れません。
承認したPromote項目がPRになるのも、Org Standard側のリポジトリに対してです。
つまり各プロジェクトに求めるのはレポートの提出までで、標準を変える判断は共通化チーム側に残ります。

集まったレポートから必要なものだけをOrg Standardへ反映します。
更新後は各プロジェクトで project-scaffold を再実行し、変更計画をPRの説明に使います。
その変更をチームでレビューするところまでが一つのサイクルです。
誰がauditと反映を担うかは、組織の規模や体制に合わせて決めます。

差分が見つかっても、すぐにファイルを修正すればよいとは限りません。
Org Standardの意図が伝わっていないなら、自動修正だけでは同じことがまた起きます。
必要に応じてルールの理由や他のプロジェクトでの使い方を共有し、勉強会を開く。
auditの結果は、組織全体でAIエージェントがどう使われているかを把握し、運用改善や教育につなげる材料にもなります。

AIエージェントの活用を比較できる状態にする

ここからは、まだ実際に運用して確かめたわけではない構想の話になります。
この仕組みを作ったもう一つの理由が、プロジェクトごとのAIエージェント活用を比較できる状態にしたかったことです。

例えば、少人数・短い納期・高い品質を維持できているプロジェクトがあるとします。

一方で、より多くの人数や時間を使っているのに、あまり成果が出ていないプロジェクトもあるかもしれません。
もちろん、その差がAIエージェントの使い方だけで決まるわけではありません。

ただ、Org Standardという共通基準があれば、

AIエージェントの運用方法にどんな違いがあるのか

を比較するための材料を作れます。

例えば、成果の高い複数のプロジェクトで似た Local の運用が使われていれば、Promote 候補として再評価できます。
逆に、Org Standardとして共通化したルールが、実際にはあまり機能していない可能性も見えてきます。

project-scaffold 自体が生産性を測定するわけではありません。
リードタイムや品質、レビュー工数、人数などの指標と組み合わせて、初めて評価できます。
このSkillで作りたいのは、プロジェクトごとのAIエージェント運用を比較できる状態です。

開発会社では、AIの運用ノウハウ自体が資産になる

ここも今のところは構想で、この構成で実際に納品まで回したわけではありません。
ただ、AIエージェントを使った開発では、コード以外にもノウハウが蓄積されます。

例えば、

• どうAIへ仕様を伝えるか
• 要件や意思決定をどう管理するか
• どこまでAIに任せるか
• どのタイミングで人間がレビューするか
• Skillをどう使い分けるか
• 複数エージェントをどう連携させるか

といったものです。

受託開発やシステム開発会社では、こうした情報も開発ノウハウです。
そのため、顧客と共有するリポジトリと、社内のAIエージェント運用資産を分離する構成も考えられます。

例えば、

のように、社内向けの AGENTS.md や運用ドキュメントを親ディレクトリに置き、顧客へ共有・納品するコードは app/ 以下のGitリポジトリで管理します。
もちろん、何を納品対象にするか、どこまで顧客と共有するかは契約や会社の方針によります。

AIエージェントの運用が成熟するほど、

エージェントをどう働かせるかという情報自体が会社の開発ノウハウになる

という点は、今後意識する必要があります。
AGENTS.md やSkill、ドキュメント運用を社内ノウハウとして残す範囲を決める必要があります。

Org StandardにAIエージェントの運用ルールを蓄積する

project-scaffold が管理するのは、単なるプロジェクトテンプレートではありません。
具体的には、次のような領域です。

こうした領域をOrg Standardとして管理します。

現在のBuilt-in Starterでは主に AGENTS.md や docs/ を扱っていますが、組織によっては、

• 共通Skill
• Issue Template
• PR Template
• CI
• AIレビューの手順

などをOrg Standardに含めてもいいと思います。

既存プロジェクトや任意のディレクトリを参考に、自分たちのStandardを作れます。
project-scaffold が用意しているのは、組織が自分たちのAIエージェント運用を作り、適用し、継続的に見直すための仕組みです。
正解の運用そのものは配っていません。

まとめ：差分は残ってよい

技術も要件もチームも違う以上、プロジェクトごとの差分は当然発生します。
このSkillの目的は、すべてを同じ構成に揃えることではありません。

差分を見つけたときに、

• プロジェクト固有だから残すのか
• 他のプロジェクトにも広げるのか
• 古くなったので整理するのか
• まだ判断できないのか

を考えられる状態にしておきたいと考えています。

各プロジェクトには改善する自由を残し、そこで生まれたノウハウを必要に応じて組織全体へ戻す。
そのフィードバックループとして、project-scaffold と project-scaffold-audit を作りました。

公開リポジトリ

project-scaffold は以下で公開しています。

• GitHub: https://github.com/bracelabs/agent-skills
• 日本語README: https://github.com/bracelabs/agent-skills/blob/main/README.ja.md

GitHub CLIからインストールできます。

gh skill install bracelabs/agent-skills project-scaffold
gh skill install bracelabs/agent-skills project-scaffold-audit

Built-in Starterから試すこともできるので、複数プロジェクトでAIエージェントの運用を管理する方法の一例として使ってもらえればと思います。

なお、Built-in Starter自体を更新するのは project-scaffold-maintain という3つ目のSkillの役割です。
こちらは agent-skills リポジトリのメンテナー向けに用意しています。

project-scaffold-audit は、組織を問わず使えそうな改善を Global Promote candidate として報告することがあります。
実際にそのような改善が見つかった場合は、Issueなどでフィードバックをもらえるとうれしいです。

一方、 project-scaffold-maintain は Global Promote candidate を公開リポジトリのBuilt-in Starterへ反映し、PRを作成するためのSkillです。
組織内で管理しているOrg Standardを更新するためのものではありません。

組織で利用する場合は、社内の運用ルールやプロジェクト固有の情報を意図せず公開しないためにも、project-scaffold-maintain は利用せず、Org Standardの更新には project-scaffold-audit を使ってください。