agents-md

Agents.md

维护一份简洁的项目简介，帮助 Agent 了解项目的目标、作者的思路，以及在工作中必须避免的反复错误。

流程

1. 确定范围。 明确项目根目录、创建、审计或更新意图、目标语言，以及实际涉及的各类工具环境。阅读适用的说明文件，并依据本地行为或当前官方文档厘清发现机制和优先级。将根目录下的 AGENTS.md 作为规范默认来源，但保留已确立的可移植源文件。不要假定各工具环境对文件名、嵌套结构、导入或符号链接的支持情况。
2. 检查维护中的证据。 只需阅读足够的 README、产品愿景、术语表、ADR、贡献指南、配置、代码和现有说明，以找出权威负责人、相互矛盾之处，以及不应要求人类另行提供的事实。当前实现只能证明已有的内容，不能确定项目应发展成什么样。
3. 明确项目指南针。 简洁确认项目的目的、目标用户、期望方向、需要保护的特质、重要的权衡，以及作者的决策启发原则或期望与 Agent 建立的关系。优先采用权威的维护中资料或用户已提供的意图。如果仍有重要且由人类决定的空缺，且 grilling 可用，则仅针对这些空缺使用它；否则直接提出最少量且聚焦的问题。如果项目指南针已足够清晰，就不要再次访谈；进行常规的定向审计或更新时，不要调用 grilling。
4. 找出实际工作中的问题。 只保留有现有已接受说明、人类明确决定或反复出现且已证实的 Agent 错误作为依据的具体指导。只有在用户授权相关来源和范围时，才检查对话或工具环境历史。一次性错误或假设性风险不足以作为依据。
5. 选择合适的归属位置。 仅当项目指南针说明和操作指导应在主动工作期间影响 Agent 时，才将其保留在此处。对其他内容只指明归属，不要修改：
   • 可由机器检查的行为应放在可执行配置或 CI 中；
   • 由审阅者判断的项目规则应放在规范编码标准来源中；
   • 功能需求和实现状态应放在临时工作文档中；
   • 架构、领域含义和持久的决策理由应放在各自维护的来源中；只有当 Agent 必须查阅时，才在此处添加简短的条件性指引。
6. 提出最小化的文档或改动。 说明每段保留的内容会如何改变 Agent 的行为，以及为什么此文件最适合作为归属位置。项目指南针宜采用简短自然的项目说明信，操作问题宜采用直接指令并提供安全替代方案。删除过时、重复、泛泛、推测性或现已由机制强制执行的指导。不要模仿其他作者的文风，也不要强行套用模板。
7. 取得认可。 展示完整的拟议内容或精确改动、规范路径、目标语言、覆盖的工具环境以及可移植性限制。只有获得人类明确认可后才能写入。只有在说明修改对草案的影响明确后，才算接受了修正。
8. 写入并验证。 保留无关说明，只应用已认可的改动。仅当指定的工具环境无法直接使用规范来源时，才创建最小且经过验证的适配器、导入文件或链接。重新阅读每个生成的文件，确认其引用指向有效，并验证差异中没有矛盾的重复内容或无关改动。

内容筛选

有用的内容可能包括：

• 简要说明项目旨在实现什么、面向谁，以及这为何应影响实现选择；
• 当多个解决方案都看似合理时，Agent 必须保留的产品特性与取舍；
• 作者长期遵循的决策原则和协作预期；
• 反复出现的风险，以及触发条件和明确的安全处理方式；
• 几乎每项相关任务都需要遵守的跨界面要求或术语；
• 有条件的指引，指出受维护的资料来源，并说明何时应阅读。

排除：

• 可通过检查代码仓库获取的脚本、依赖项、框架、目录或文件清单；
• 可从软件包、构建、任务或 CI 配置中查到的开发命令；
• 由可执行工具或编码规范管理的格式化、代码检查、类型、测试或审查规则；
• 功能规格、实现片段、当前进度、临时例外情况和详尽的架构摘要；
• 当有条件指引已足够时，重复的术语表或 ADR 历史；
• 通用工程建议、Agent 能力描述、与本项目无关的个人偏好，以及未经认可的指令；
• 为用户未纳入范围的测试框架提供的兼容文件。

结果

• No instructions needed：没有值得纳入始终加载上下文的长期项目准则或操作差异，因此不创建文件。
• No changes needed：现有指令链条内容准确、简洁、归属正确，且适用于所请求的测试框架。
• Agree-ready：一份完整文档或最小改动已可供人工确认；尚未更改任何文件。
• Updated：已写入并验证获认可的改动，路径如报告所示。
• Inconclusive：明确指出具体的意图、权威性、归属或测试框架发现冲突，以及解除阻碍的条件。

完成标准

每条最终指令都必须传达实现无法自行确定的、已获认可的项目意图，或防止已证实的重复性操作失败。人工已认可其含义、语言、路径和测试框架范围；未重复更高优先级的规范；并且每个指定的测试框架都能通过已验证的发现机制获取一致的规范指令集。