◉ANTIGRAVITY LABEN
記事一覧/Agents & Manager
◈ Agents & Manager/2026-06-28中級

組み込み Guide スキルを使い捨てにせず、設計資産として育てる

Antigravity v2.2.1 で加わった組み込み Guide スキルを、一度きりの指示で終わらせず、バージョン管理されたチーム共有の設計資産として運用するための具体的な構成と判断基準を整理します。

Antigravity419エージェント81スキル設計15運用14

✦ プレミアム記事

エージェントに同じ前提を毎回説明している、という感覚に心当たりはないでしょうか。プロジェクトのディレクトリ規約、コミットメッセージの書き方、レビューで必ず見る観点。会話を始めるたびにこれらを貼り付け直していると、本来集中したい作業の手前で時間が溶けていきます。

Antigravity v2.2.1 で組み込みの Guide スキルが入り、この繰り返しをスキルとして固定できるようになりました。ただ、ここで一度きりの便利機能として消費してしまうのか、それともチームと自分の知見を蓄積する場所として育てるのかで、半年後の効きが大きく変わってきます。

私自身、個人開発で複数のブログとアプリを並行して回しているので、エージェントに渡す前提知識は放っておくと際限なく増えていきます。Guide スキルをその場しのぎで書き捨てるたびに、似た内容を三度も四度も書き直していました。そこで運用の型を決めたところ、エージェントの初動が安定し、説明のやり直しがはっきり減りました。その型を共有します。

Guide スキルは「会話の外」に知識を逃がす仕組み

Guide スキルの本質は、会話コンテキストに毎回載せていた前提を、参照可能な外部知識として切り出すことにあります。プロンプトに直接書く方式と比べると、性質がかなり違います。

観点毎回プロンプトに記述Guide スキル化
更新会話ごとに手で貼り直す1ファイルを直せば全会話に反映
履歴残らない・追えないGit の差分で意図まで追える
共有個人のメモに閉じるリポジトリ経由でチーム全員へ
コンテキスト消費毎回トークンを食う必要時のみ読み込まれる

特に効くのが履歴です。「なぜこの規約にしたのか」をスキルの変更履歴に残しておくと、半年後の自分が同じ議論を蒸し返さずに済みます。私はこの一点だけでも Git 管理に乗せる価値があると考えています。

3層に分けて、スキルを肥大化させない

最初にやりがちな失敗が、1つのスキルにすべてを詰め込むことです。規約も手順もトラブル対処も全部入りにすると、エージェントが文脈に応じて必要な箇所を選べず、かえって精度が落ちます。

私はスキルを役割で3層に分けています。

第1層: 不変の前提(foundation)

プロジェクトの普遍的な約束事を置きます。変更頻度が低く、ほぼ全タスクで参照される内容です。

.antigravity/guides/
├── foundation/
│   ├── repo-conventions.md      # ディレクトリ・命名規約
│   ├── commit-style.md          # コミットメッセージの型
│   └── review-checklist.md      # レビュー必須観点

第2層: タスク種別ごとの手順(workflows)

「記事を1本追加する」「依存を更新する」のような、繰り返す作業の段取りです。手順そのものなので、ステップを番号で明示します。

├── workflows/
│   ├── add-article.md           # 記事追加の手順
│   ├── dependency-bump.md       # 依存更新と動作確認
│   └── release-checklist.md     # リリース前の確認項目

第3層: 落とし穴と対処(pitfalls)

過去に踏んだ罠を、症状と対処のペアで記録します。エージェントが似た状況に入ったとき、ここを参照させると同じ失敗を繰り返しません。

└── pitfalls/
    ├── edge-cache-stale.md      # キャッシュ起因の不整合
    └── i18n-count-mismatch.md   # 日英件数ずれの検出と修正

分割の目安は、1ファイル 200〜400 行です。これを超えたら、内部で扱っている関心事が複数あるサインなので、切り出しを検討します。逆に 50 行に満たないものは、関連スキルへの統合を考えます。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦Guide スキルを Git 管理し、3層のディレクトリ構成で育てる具体的なファイル設計
✦1つのスキルに詰め込みすぎて精度が落ちる失敗と、200〜400行で分割する判断基準
✦スキルの効果を測るための簡単な回帰チェックスクリプトと、月次で陳腐化を検出する運用
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

◈ Agents & Manager2026-04-26
Antigravity エージェントに「失敗の理由が一発で分かる」トレースを設計する — 可観測性の実践
自前のエージェント実行ループに OpenTelemetry のスパンを入れ、失敗の理由を数行で読めるようにするための設計です。スパン構造、属性の線引き、failure_class の分類、リトライ表、ダッシュボード、コスト属性、PII の扱いまでを、動くコードと一緒に整理します。
◈ Agents & Manager2026-11-19
Issue の本文をエージェントに読ませる前に、GitHub Actions を「読む係」と「書く係」に分けて secrets を遠ざける
Issue の本文は誰でも書ける入力です。それをエージェントに読ませる GitHub Actions を、権限のない「読む係」と、エージェントを動かさない「書く係」の2ジョブに分け、本文をシェルに展開させない書き方と、提案を検める小さな Python スクリプトまでを動くコードつきでまとめました。
◈ Agents & Manager2026-10-22
引き継ぎ文書の古い参照は 17 件に見えて実際は 2 ファイルでした。本当に危なかったのは、別のサイトの手順書が混ざっていたことでした
エージェントに読ませるリポジトリ直下の .md を点検する Python スクリプトの全文です。素朴な版は壊れた参照を 17 件と数え、直すと 7 件、実体は 2 ファイル。別の問題が見つかるまでの過程を残します。