はじめに
project-scaffold は、AGENTS.md や docs/ などのAIエージェント向け運用ルールを Org Standard として管理し、複数のプロジェクトへ適用するためのSkillです。
この記事では、導入から日常運用までに必要な手順だけをまとめます。
設計意図や、なぜこの仕組みにしたのかについては別の記事にまとめています。
インストール
まず project-scaffold と project-scaffold-audit をインストールします。
gh skill install bracelabs/agent-skills project-scaffold
gh skill install bracelabs/agent-skills project-scaffold-audit
役割は次の通りです。
| Skill | 役割 |
|---|---|
project-scaffold |
Org Standardの作成とProjectへの適用 |
project-scaffold-audit |
ProjectとOrg Standardの差分確認、Org Standardへの改善反映 |
1. Org Standardを作る
最初に、組織やチームで共通して使う Org Standard を作ります。
作り方は主に3つあります。
Built-in Starterから作る
一番簡単な方法です。
project-scaffold に同梱されているBuilt-in StarterをベースにOrg Standardを作ります。
CodexやClaude Codeから、例えば次のように依頼します。
/project-scaffold Built-in StarterからOrg Standardを作成してください。
Built-in Starterには、AGENTS.md、docs/、.gitignore などの基本的な構成が含まれています。
自分たちの運用に合わせて変更してください。
既存プロジェクトを参考に作る
すでにAIエージェントを運用しているプロジェクトがある場合は、そのプロジェクトを指定して作ることもできます。
/project-scaffold 以下のプロジェクトを参考に、Org Standardを作成してください。
- /path/to/project-a
- /path/to/project-b
既存プロジェクトの運用から、共通化できそうな内容をOrg Standardの初期状態として作成します。
既存のOrg Standardを使う
すでに組織内でOrg StandardをGit管理している場合は、そのリポジトリを指定して利用できます。
2. Org StandardをGitで管理する
Org Standardができたら、Gitリポジトリとして管理しておくと複数人で共有できます。
/project-scaffold Org StandardをGit管理したいです。
リモートリポジトリは <repository> を使用してください。
以降は、このリポジトリを組織の共通ルールとして管理します。
3. Projectへ適用する
Org Standardを作成したら、各プロジェクトへ適用します。
既存プロジェクトの場合は、対象リポジトリで次のように依頼します。
/project-scaffold このプロジェクトにOrg Standardを適用してください。
project-scaffold は既存のファイルを無条件に上書きするのではなく、変更内容を先に提示します。
内容を確認してから反映します。
新しいプロジェクトを作る場合も同様にOrg Standardを利用できます。
4. 定期的にauditする
各プロジェクトで開発を続けていると、Org Standardとの差分が生まれます。
定期的に project-scaffold-audit を実行して、ProjectとOrg Standardの差分を確認します。
/project-scaffold-audit
見つかった差分は、次の4種類に分類されます。
| 分類 | 意味 |
|---|---|
Local |
そのプロジェクトの技術、ドメイン、開発方法などの事情から必要な差分。そのプロジェクトに残す |
Promote |
特定の技術やプロジェクトに依存せず、他のプロジェクトでも継続的に使えそうなルール。Org Standardへ取り込む候補 |
Remove-Migrate |
古くなっている、重複している、現在のOrg Standardと矛盾しているなど、整理や移行を検討する差分 |
Needs-decision |
意図的な差分なのか判断する材料が足りないもの。何を確認すれば判断できるかも合わせて出す |
Org Standardとの差分があるからといって、すべて修正するわけではありません。
例えば、auditの結果は次のような形で確認できます。
| 分類 | 根拠 | 影響範囲 | メリット | 互換性リスク | 最小の変更案 |
|---|---|---|---|---|---|
Promote |
AGENTS.md にレビュー前の確認手順が追加されている |
全プロジェクト | レビュー前の確認方法を統一できる | 低 | Org Standardの AGENTS.md に同じルールを追加する |
Local |
app/AGENTS.md にSwift固有のビルド手順がある |
このプロジェクトのみ | このプロジェクトの実装時に必要 | なし | 変更せずProject側に残す |
Remove-Migrate |
docs/README.md に古いドキュメント配置ルールが残っている |
このプロジェクト | 現在のOrg Standardとの重複をなくせる | 中 | 新しい配置へ移行して古い記述を削除する |
Needs-decision |
docs/ にOrg Standardにはないディレクトリが追加されている |
このプロジェクト、または全体 | 用途次第 | 不明 | 追加した理由を確認してから判断する |
AIが分類した結果を確認し、Org Standardへ取り込みたい項目だけ承認します。
5. 改善をOrg Standardへ戻す
Promote と判断されたもののうち、組織全体で使いたいものを承認します。
Org StandardをGit管理している場合は、変更用のブランチとPRを作成できます。
Promoteのうち以下をOrg Standardへ反映してください。
- ○○
- △△
PRを作成してください。
PRをレビューして、問題なければOrg Standardを更新します。
6. 更新したOrg Standardを各Projectへ反映する
Org Standardを更新したら、各プロジェクトでも project-scaffold を再実行します。
/project-scaffold
変更内容を確認し、必要ならPRとしてレビューしてから取り込みます。
基本的な運用はこれの繰り返しです。
組織で運用する場合
小規模な組織であれば、CTOやテックリードなどが定期的に各プロジェクトをauditする方法がシンプルです。
プロジェクト数が多い場合は、例えば、
月に1回
project-scaffold-auditを実行してレポートを提出する
というルールを各プロジェクトに持たせてもいいと思います。
集まった結果から必要なものだけOrg Standardへ反映します。
Built-in Starterについて
Built-in Starterは、Org Standardを作るための初期構成です。
project-scaffold の正解として固定されているものではありません。
自分たちの運用に合わせて変更し、その後 project-scaffold-audit を使いながら育てていくことを想定しています。
Built-in Starter自体を変更する project-scaffold-maintain というSkillもありますが、こちらは agent-skills リポジトリのメンテナー向けです。
組織内のOrg Standardを更新する場合は project-scaffold-audit を使用してください。
まとめ
基本的には次の流れだけ覚えておけば使えます。
-
project-scaffoldでOrg Standardを作る - Gitで管理する
- 各Projectへ適用する
-
project-scaffold-auditで差分を確認する - 必要な改善をOrg Standardへ戻す
- 更新したOrg Standardを各Projectへ再適用する
リポジトリはこちらです。
興味が湧いたら、以下の記事も読んでいただけるとありがたいです。