Antigravityのinstructions.mdを作り直した話
最近、Google のエージェンティックAIプラットフォーム「Antigravity」を少しずつ触り始めています。とはいえ、まだまだ経験不足で、毎回試行錯誤しながら進めている段階です。そんな中で、「これは自分の備忘録として残しておいた方がいいな」と思う瞬間が増えてきました。特に、プロジェクトの基本理念やルールをまとめる **instructions.md** は、エージェントとのコミュニケーションの土台になる大事なファイルです。
今回、私なりに考えた標語 *****な・ど・し・り・さ***** を中心に、instructions.md をブラッシュアップしてみました。これは完全に自分のための整理ですが、せっかくなのでブログにも残しておきます。
「な・ど・し・り・さ」という独自標語
私が勝手に作った標語であり、全てを網羅しているわけではありませんが、私の悪い頭でもなんとか覚えておけるかなぁと。- **な**：なぜ作るのか
- **ど**：どう作るのか
- **し**：書式はどうするのか
- **り**：履歴はどう残すのか
- **さ**：ここは触らないで（触ってはいけない領域）
AI と協力して開発を進めるとき、どうしても「意図のすれ違い」が起きやすいので、こういう“自分なりの軸”があると安心できます。
特に Antigravity は「skills」という仕組みが最近(2026年1月)実装されまして、プロジェクト固有のルールを細かく分けて管理できます。
AIにも確認してみたところ、「instructions.md は“憲法”」、「skills は“法律”」のようなイメージなんだそうです。
自分でプロジェクト固有の役割をもたせる仕組みを考えていたら「もうあるよ!!SKILLSだ!」って訳で、もうあるんかい!!となりました。
役割を分けるというのは今後のためにも素晴らしいですね。
試行錯誤して作ってみたinstructions.md（備忘録）
今回の instructions.md は、私が実際にAI先生(アイ先生?)とやり取りしながら、トライアンドエラーで取捨選択をしながら調整したものです。 特に、パス表記は `/` に統一した方が AI が誤解しにくいことや、skills の構造を明確に書くとエージェントの挙動が安定することなど、実際に試して気づいた点を反映しています。以下に全文を貼っておきます。 （自分用の備忘録ですが、同じように試行錯誤している方の参考になれば嬉しいです。）
# 開発基本ルール
---
## 行動の指針(判断優先順位)
- 本ファイルは、Antigravityエージェントが本プロジェクトで行動する際の最上位ルールです。
- プロジェクト個別のルールは、`.agent/skills/`フォルダに格納してあります。
- skills は、エージェントが必要に応じて自動的に参照する知識パッケージです。
- skill.md は単独で存在する場合もありますが、目的別にサブフォルダを作成し、複数の skill.md が存在する構成になる場合もあります。
- 例:
```
+---.agent
| \---skills
| coding-style/
| powershell5-output/
| naming-convention/
| ...
```
- 本ドキュメントや`.agent/skills`内で判断できない事項がある場合は、勝手に推測せず確認を求めてください。
- これは禁止ではなく、その際に`基本ルールに書き漏れがあるようだが、私はこう判断した`と分かりやすくアラートを発してもらいたいからです。
## 基本理念
- な・ど・し・り・さ(なぜ作るのか、どうやるのか、書式はどうする、履歴はどうする、ここはさわるなの五大要素を自分で決め、要素から一文字を取って標語にした独自の考え方です)
## 基本理念に基づく開発ルール
### なぜ作るのか
- 品質の高い成果物を作るため、AIと人間が協力するためのプロジェクトです。
- 人間だけでは工数の不足で手が回らない細部の丁寧な仕上げ、見落としがちな不具合、ロジックの矛盾を回避し、高品質のプログラムが欲しいです。
- 成果物はダミーではなく、実際に使用される前提です。
### どう作るのか
- プロジェクト全体で一つの処理ではないので、何をどう作るかは適宜指示いたします。
- パフォーマンス優先か、(人間の)可読性優先か、バランス優先か、こちらから方向性の依頼がなければどの方向性で作るのか明示して下さい。
- エージェントの判断が人間の意図と異なっていた場合、その理由を短く記録してください。
### 書式について
- 修正する場合は、元の書式を維持するようにして下さい。
- 命名規則ですが、外部ライブラリの継承クラスや、フレームワークで命名が強制されている場合を除き、生成するメイン実行モジュールファイルには mmm_ を付けて下さい。
- メイン実行モジュールとは、ユーザーが直接実行するスクリプトや、プロジェクトのエントリーポイントとなるファイルを指します。
- 迷った場合は、`mmm_` を付けるかどうかを必ず確認してください。
- テキストファイルを出力する場合、文字エンコードはUTF-8(BOMなし)にして下さい。(Shift_JISにはしないで下さい)
- 文字コードについて
- PowerShell 5.1のファイルは必ずShift_JISで出力します。
- PowerShell 7.x(7系)のファイルはBOMなしのUTF-8で出力します。
- VBA、Microsoft Access、Visual Basic 6.0も、Shift_JISで出力します。
- その他は、BOMなしUTF-8で出力します。
- 上記の知識が間違っていると判断した場合は、適切な(常識的な)文字コードで出力して下さい。
### 履歴・コメントについて
- コメントは人間が読んで理解できるように、日本語で詳しく説明するように入れてください。
- コメントの位置は、コードの直前に改行して入れてください。
- 例:
```
# これはコメント
function sample() {
...
}
```
- コメント、履歴は必ず日本語にしてください。専門用語も可能な限り日本語訳にして下さい。
- 日本語にする場合、無理な意訳で意味がボケると判断した場合は、英語のままか、カッコ書きで補足して下さい。
- 成果物には、技術者以外が見ても分かるような丁寧な説明を入れてください。
### 禁止事項(ここは触らないでという場所)
- 修正する場合は、無関係な処理を変更しないようにして下さい。必要ある時は確認して下さい。
- 一度完成した関数のシグネチャ(引数や戻り値)の数や型は変更しないで下さい。(もう運用している可能性があるため。)ただし、必要ある時はその旨を報告願います。
---
## 基本的なプロジェクトフォルダ構成(存在する時)
### Windows PowerShell 5.1(TREEコマンドによるツリー構造)
- 生成物は既存のフォルダに合うように作ってください。
- 生成物に存在しない場合、適切なフォルダを作ってください。
- その時の文字コードはファイルの種類に応じた一般的な文字コードにして下さい。
```
C:.
| .gitattributes
| .gitignore
| README.md
|
+---.agent
| \---skills
| skill.md
|
+---.antigravity
| instructions.md ※本ドキュメント
|
+---_ai ※開発依頼をした時のプロンプトの保存場所(必要時だけ参照して下さい)
| initial_001_mmm_ExcelToMarkdown.bas.md ※サンプル
|
|
+---_dev_bat ※Windowsコマンドプロンプトの*.batファイルの出力先
+---_dev_etc ※何にも該当しない成果物の出力先
+---_dev_js ※Java Scriptの出力先
+---_dev_powershell5 ※PowerShell5.1のコマンドファイルの出力先***文字コードは必ずShift_JISであること***
| mmm_capa.PS1 ※サンプル
| mmm_TEST.ps1 ※サンプル
|
+---_dev_powershell7 ※PowerShell7.x(7系)のコマンドファイルの出力先
+---_dev_python ※Pythonの出力先
+---_dev_vba ※Visual Basic、AccessやExcel等のVBAモジュールの出力先
| mmm_ExcelToMarkdown.bas ※サンプル
|
+---_setupdoc ※環境などをセットアップした時の人間用手順メモ(必要時だけ参照してください)
| Windows11へのpython導入から、markItdown導入まで.txt
|
\---_test ※テストの成果物や中間ファイルの出力先(必ずテスト関連はここに出力してください)
generate_evidence.ps1 ※サンプル
test_evidence.txt ※サンプル
test_mmm_capa.ps1 ※サンプル
test_report.html ※サンプル
```
今回の instructions.md は、私自身が Antigravity を理解するための“地図”のようなものです。 まだまだ勉強中ですが、こうして形にしていくことで、少しずつ AI との協働がスムーズになって行くといいな。
いかんせん、AIと人間との大協力時代は始まったばかりで、繰り返しになりますが私は圧倒的な経験不足。
自分の弱みを素直に認めて、もう一度ゼロから、いやマイナスかも知れないけど、何もないところから少しづつでも何かを積み上げて行きたいです。
それではまた次の記事でお会いしましょう!! --------------------------------------------
