AGENTS.md 全局代理规则配置指南

本文档记录 AI Agent（如 Antigravity / Claude Code）的全局代理规则配置规范。AGENTS.md 是 AI 编码助手识别并遵循的项目级/全局级行为约束文件，用于统一规范 Agent 在代码分析、修改和验证过程中的行为模式。

---

1. 回复语言

• 优先使用中文回复，除非用户明确要求其他语言。

---

2. 指令优先级与规则作用域

AGENTS.md 遵循就近优先原则，多级规则按如下优先级执行：

用户当前任务的明确要求 > 目标文件所在目录的 AGENTS.md > 上级目录的 AGENTS.md > 全局 AGENTS.md

核心原则

• 系统约束最高：始终遵循当前运行环境中的系统、安全和工具约束。
• 用户优先：用户在当前任务中的明确要求优先于 AGENTS.md；如有冲突，应说明原因并遵循更高优先级约束。
• 就近覆盖：项目级 AGENTS.md 优先于全局文件；目标文件所在目录越近的 AGENTS.md，对其子树越优先。
• 合并执行：不冲突的上层与下层规则应合并执行。
• 风险决策：不同选择会对接口兼容性、数据结构、依赖版本、公共行为或大量文件产生实质影响，且无法从现有上下文判断时，应向用户说明差异并请求确认；低风险实现细节可选择最小改动方案继续执行。

作用域检查

• 开始仓库内的分析、修改或验证前，应确定每个目标文件适用的规则。从仓库根目录沿目标文件的父目录链检查 AGENTS.md。
• 一个任务涉及多个目录或仓库时，应分别判断规则作用域，不要把某一目录的局部规则套用到其他目录。
• 如果不存在项目级 AGENTS.md，继续使用全局规则，不要擅自创建规则文件。

---

3. 工具选择与后备方案

原则	说明
优先本机工具	Windows 环境下优先使用当前会话可用的本机工具，不假定任何命令必然存在
延迟检查	命令无法解析或行为异常时，再通过 Get-Command <命令> -ErrorAction SilentlyContinue 检查
按需版本检查	只有工具版本会影响任务结果时，才执行版本检查
禁止擅自变更	工具不可用时采用等价的本机后备方案；未经用户明确允许，不得安装、升级、降级、卸载或重新配置工具

---

4. 代码搜索与探索

4.1 语义与调用关系

• 需要理解符号、依赖或调用链时，先确定目标文件所属的仓库根目录，检查是否存在 .codegraph/。
• CodeGraph 可用时：优先使用 codegraph_explore、codegraph_node 或相应 CLI 发现候选位置和关系。
• 复核原则：涉及当前源码事实、刚修改的文件时，应通过直接读取源码或 rg 复核。
• CodeGraph 默认自动同步，无需例行手动同步；不存在索引时使用常规搜索，不擅自创建索引。

4.2 文件定位、内容搜索与阅读

工具优先级链：

查找文件路径: fd → rg --files → PowerShell 文件查找
搜索文本内容: rg → Select-String → 其他系统工具
阅读文件内容: bat --paging=never → Get-Content

搜索规范

• 搜索前尽量限定仓库、目录、文件类型或 glob。
• 结果较多时先评估数量，再逐步缩小范围，不根据宽泛结果或终端截断直接下结论。
• 默认排除无关依赖、构建产物、生成文件、缓存和大型日志。
• 读取未知的大型文件前先检查大小，只读取与任务相关的范围。

---

5. 代码修改规范

• 最小改动：只修改完成任务所需的内容，避免无关的重构、格式化和整文件覆盖。
• 验证先行：不猜测文件路径、符号位置、数据结构或调用关系。修改前应通过 CodeGraph、rg、fd 或源码阅读验证目标位置。
• 基于证据：基于已验证的源码上下文进行修改；证据不足时继续搜索。
• 保护现有工作：保留用户已有和无关的工作区变更；存在重叠且无法安全处理时，先向用户说明。

---

6. 验证与结果汇报

验证要求

• 发生修改时，重新读取变更位置，确认内容正确且范围符合任务要求。
• 根据修改范围和风险执行直接相关、尽量轻量的检查；不默认运行完整编译或全量测试。

汇报规范

场景	要求
验证通过	只有实际执行并成功完成的检查，才能表述为"已通过"或"验证成功"
未执行验证	会影响交付可信度的验证，应明确说明
验证失败	说明执行的命令、关键错误和影响；区分原有问题与本次修改引入的问题
最终回复	按任务实际情况简要说明结论、修改内容、已执行的验证以及仍存在的限制或风险