工作区指引

AGENTS.md 与代理技能

需要按位置自动生效的仓库指令请使用 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 字段。

它不会解析 Shell 命令字符串来猜测路径。如果只通过不透明的 Shell 命令进入嵌套目录，则不会在该命令执行前自动发现其中的 AGENTS.md。

指令安全

每份 AGENTS.md 限制为 64 KiB，必须是无 NUL 字节的 UTF-8 文本。超长的有效文本会被截断并附上标记。不可读取、不是普通文件、文本无效，或解析到工作区外的符号链接都会被忽略，以限制仓库控制的提示输入。

这些检查只约束指令加载，不会对 Shell 命令进行沙箱隔离，也不会让仓库指令的可信级别高于用户和系统策略。

使用 .qignore 控制发现

工作区根目录的 .qignore 过滤目录发现和根目录列表。它支持注释、否定规则、根目录锚定、目录后缀及 *、**、? 通配符。q 自身的 .q/ 元数据始终不参与发现。

.qignore 不是访问控制边界。只要明确指定的路径仍在工作区内，模型工具依然可以读取。若必须禁止访问某个路径，请使用操作系统权限或隔离环境。