ワークスペース指示

AGENTS.mdとAgent Skills

場所に応じて自動適用されるリポジトリ指示には AGENTS.md を使います。作業に関係するときだけ検索・読み込みする再利用可能なガイダンスには Agent Skills を使います。

ワークスペースルートの AGENTS.md は q ワークスペース全体に適用されます。入れ子のファイルはそのディレクトリと子孫に適用されます。

読み込みと優先順位

q はセッション開始時に <workspace>/AGENTS.md を読み込みます。ルートのガイダンスは通常チャット、ACP セッション、サブエージェントのモデルリクエストに提供されます。

構造化されたツール呼び出しがパスを示すと、q はルートから対象へ各ディレクトリを調べます。新しく適用されるファイルはルートから下へ追加され、配下で指示が競合するときは深い AGENTS.md が優先されます。

ツールバッチの直前に新しいファイルを発見すると、q はそのバッチを停止して指示を加え、モデルに確認を求めるツールエラーを返します。モデルは適切な呼び出しだけを再試行できます。読み込んだ指示はコンテキスト圧縮後も先頭の指示ブロックに残ります。

リポジトリのガイダンスはシステム契約、q の組み込み開発者指示、ユーザーの明示的な依頼より下位です。

パス検出

q は path、paths、file、directory、source、destination、root、workdir、working_directory などの構造化 JSON フィールドを認識します。

シェルコマンドの文字列からパスを推測しません。隠れたシェルコマンドだけで入れ子のディレクトリに到達する場合、そのコマンドの実行前に AGENTS.md は自動検出されません。

指示の安全性

各 AGENTS.md は 64 KiB 以内で、NUL バイトを含まない UTF-8 テキストである必要があります。大きすぎる有効なテキストは印を付けて切り詰めます。読めないファイル、通常ファイルでないもの、不正なテキスト、ワークスペース外へ解決されるシンボリックリンクは無視します。

この検証は指示入力を制限しますが、シェルコマンドのサンドボックス化や、リポジトリ指示をユーザー・システムポリシーより信頼することはありません。

.qignoreによる探索

ルートの .qignore はディレクトリ探索とルート一覧をフィルタリングします。コメント、否定パターン、ルートアンカー、ディレクトリ接尾辞、*、**、? に対応します。q の .q/ メタデータは常に探索から除外されます。

.qignore はアクセス制御ではありません。ワークスペース内の明示的なパスはモデルのツールが引き続き読めます。アクセス自体を防ぐには OS 権限や隔離を使ってください。