为智能体提供有用的代码仓库上下文

从当前检出的代码开始

智能体需要知道正在修改哪个代码仓库和分支，也需要知道工作目录是否包含无关修改。这些事实决定哪些文件可以安全编辑，也影响如何理解最终 diff。

实现前，要求智能体检查项目指令和软件包配置。从其他代码仓库记住的命令，在这里可能不适用。熟悉的框架名称不能证明已安装版本或项目约定。

对于小修改，提供相关模块、调用方、测试和架构决策。调查发现具体需要时，再补充信息。

指令文件可以说明受支持的命令、模块边界、审查要求，以及哪些操作需要负责人决定。AGENTS.md 约定让编程工具有一个容易识别的位置来查找这些信息。工具支持情况和指令优先级可能不同，应检查所用工具的行为。

把稳定的项目规则保存在代码仓库中，把当前任务写在任务说明中。不要把指令文件变成全部对话的历史记录，或临时计划清单。

有效的指令是：“路由修改了访问行为时，运行授权集成测试。”模糊的指令是：“始终注意安全。”前者明确了触发条件和审查者能够验证的操作。

命令、目录或架构改变后，指令可能过时。如果指南提到的脚本不存在，检查软件包配置。如果文档声称某服务只读，先检查权限，再依赖该说法。

记录冲突。用当前版本的直接证据了解实现行为。不要因为旧代码违反某项有意制定的策略，就悄悄弃用策略。策略与当前行为回答的是不同问题。

例如，指南可能禁止直接写入共享分支，但旧脚本仍在这样做。正确做法是保留策略并修正脚本。现有代码不构成重复违规操作的许可。

完整代码仓库可能包含凭据、含私密信息的测试夹具、客户导出文件和旧支持日志。能够访问代码仓库，不代表其中每个文件都适合交给模型服务。

使用获准工具，并遵守数据处理规则。从上下文中排除秘密信息。尽可能用虚构数据替代客户示例。除了上传文件，也要检查已连接工具：搜索连接器可能获取初始提示词中从未包含的信息。

代码仓库中的“不要读取秘密信息”指令是有用的指导，但不能替代对秘密信息存储系统和敏感目录的访问限制。

完成后，在 pull request 中记录行为变化、验证情况和尚未解决的限制。受支持的工作流改变时，更新长期维护的项目文档。不要把完整智能体对话复制进代码仓库。

记录应帮助后续维护者重复这项工作，而无需重建一段长对话。链接到权威文档，每项稳定规则只保留一份权威说明。

良好的上下文减少重复调查，也让错误更容易被发现，因为预期行为和可用命令已经明确。