instruction-writing

name	instruction-writing
description	.instructions.mdファイルを作成・編集する。frontmatter（applyTo）の設計、repo-wide vs path-specific の使い分け、glob パターンの書き方を支援。instructions.md作成、.instructions.md編集、.agent/instructions、.github/instructions、applyTo、globパターン、path-specific、repo-wideなどの言及時に使用。
user-invokable	false

instruction-writing

VS Code Copilot 用の .instructions.md ファイルを作成・編集するためのガイド。ファイル編集時に自動適用される指示を定義する。

記述原則: 短く強く

instructions は常時読み込み。特に圧縮重要。

• ユーザー内容をそのまま転記せず、意図を最小記述に圧縮
• 人間の読みやすさ < エージェントの機能性
• 一般常識・推測可能な情報は省略

作成・編集後は必ず圧縮レビュー実施（Reviewer モード・圧縮レビュー実施中は除く）:

1. ファイル作成・編集完了
2. Reviewer サブエージェントに「短く強く」観点でレビュー依頼
3. 指摘に基づき圧縮実施
4. ユーザーに提示

ファイルパスのリンク化: 必須参照は [path](path)、補足情報は path のみ。詳細は copilot-instructions-maintenance

よくある致命的なミス

• ❌ applyTo を指定しない

  • 自動適用されず、手動で添付しないと機能しない
  • applyTo: "**" で全ファイル、applyTo: "**/*.rb" でRubyファイルのみ

• ❌ applyTo が広すぎる

  • 無関係なファイルにも適用されてコンテキストを圧迫
  • 対象を絞る: app/**/*.rb など

• ❌ 追跡対象（.github/instructions/）を直接編集

  • チームに影響するため、提案のみ行う
  • ローカル用は .agent/instructions/ に配置

• ✅ 正しいやり方

  • 目的に応じて種類を選択（repo-wide / path-specific）
  • applyTo を適切に設定して自動適用
  • ローカル用は .agent/instructions/ に配置

種類と使い分け

種類	ファイル	いつ使う	編集可否
repo-wide	.github/copilot-instructions.md	全チャットに常時適用したい全体ルール	提案のみ
path-specific (shared)	.github/instructions/*.instructions.md	チームで共有したいファイル種別ごとのルール	提案のみ
path-specific (local)	.agent/instructions/*.instructions.md	個人用のファイル種別ごとのルール	直接編集OK

frontmatter の書き方

---
applyTo: "**/*.rb"           # 必須: 自動適用する glob パターン
name: Ruby Coding Guidelines # 任意: 表示名（省略時はファイル名）
description: Rubyコーディング規約  # 任意: 短い説明
---

applyTo の glob パターン例

パターン	対象
**	全ファイル
**/*.rb	全Rubyファイル
app/**/*.rb	app/配下のRubyファイル
spec/**/*_spec.rb	specファイルのみ
*.{js,ts,jsx,tsx}	JS/TSファイル
app/frontend/**	フロントエンドディレクトリ配下

雛形作成

テンプレートからファイルを生成:

.agents/skills/99_instruction-writing/scripts/init_instruction.sh {instruction-name}

生成先: .agent/instructions/{instruction-name}.instructions.md

ファイル名の付け方

ファイル名にはプレフィックス（00_, 10_, 20_, 30_, 99_）を付けて分類します。

詳細: プレフィックス命名規則

絶対守るルール

• ❌ Bad: 追跡対象（.github/instructions/）を直接編集

  • チーム共有ファイルを勝手に変更すると影響が大きい

• ❌ Bad: applyTo を省略して「手動で添付すればいい」と考える

  • 毎回添付は非現実的、自動適用が基本

• ✅ Good: ローカル用は .agent/instructions/ に配置

  • gitignore対象なので自由に編集可能

• ✅ Good: 追跡対象の変更は提案のみ

  • 変更方針・差分案を提示し、ユーザーの判断を仰ぐ

prompt / skill との使い分け

種類	いつ使う
instructions	常に自動適用される（コーディング規約、安全策、禁止事項）
prompts	明示的に呼び出す（PR作成、Issue作成などの定型作業）
skills	キーワードで自動発火する知識（判断基準、ルール、落とし穴）

参考資料

• VS Code Custom Instructions 公式ドキュメント
• copilot-instructions-maintenance スキル

---

applyTo を必ず設定し、対象を適切に絞って自動適用する。ローカル用は .agent/instructions/ に配置。