init-or-refactor-agents-md

初始化或重构 AGENTS.md

编写一份简短、信息密度高且规范统一的 AGENTS.md。

工作流

1. 阅读 AGENTS.md、CLAUDE.md、CODEX.md、.cursorrules 以及类似的仓库本地指令文件。
2. 列出相互冲突的指令及其来源，并询问以哪条为准。标出与以下目标政策冲突的内容，尤其是推测性、实现细节或依赖大量测试固件的测试矩阵、未经批准的依赖项、盲目沿用本地模式，以及拒绝合理重写的要求。
3. 起草前按以下顺序精简：遵循 write-for-agents 中的精简规则；移除工具封装噪声和未来仪式性要求；移除推测性、私有、分支矩阵、依赖大量测试固件或虚饰性的测试，以及维护不良结构的规则；保留仓库特有、安全关键或屡次被违反的规则。优先使用一条项目符号，而不是新增章节。将移除项归类为 delete、yagni、tool-noise、test-theater 或 structure。完成后，确保每条来源规则都已保留，或归入上述某一类别并移除。
4. 总结现有的分支、提交、PR、评审、发布和部署规则。请用户确认采用直接在默认分支上工作（在 main 或 trunk 上工作）、分支/PR 工作流（使用专注的分支并创建或更新其 PR），还是其他工作流；并推荐明确的仓库规范。对于直接在默认分支上工作或分支/PR 工作流，要求提交范围明确、逻辑清晰，并尽早且频繁地推送；对于分支/PR 工作流，在完成第一个有用的工作切片后，立即创建或更新 PR。未经批准，绝不重写共享历史。对于其他工作流，只保留用户提供的要求。
5. 起草 AGENTS.md，仅包含一行项目描述、非显而易见的命令、已确认的 Git 工作流、目标政策（除非全局指令已对仓库中的所有 Agent 作出规定）、关键安全或审批规则，以及仅在部分任务中需要查阅的现有文档的一行指引。使用简洁的项目符号。只有在用户要求时才创建新文档。
6. 展示来源、冲突、Git 方案、拟议的 AGENTS.md 和带标签的移除项。写入前先征求确认。
7. 写入 AGENTS.md，然后删除合并保留内容后不再需要的其他指令文件。除非明确提出要求，否则不要创建特定工具的指令文件。

目标策略

• 大多数测试都是负担。只有当测试能捕获其他手段无法发现的现实问题时，才保留或添加：已发布且可能再次出现的 bug、其他仓库、服务或用户依赖的契约，或关键不变量（安全、权限、兼容性、并发、迁移、协议、数据丢失）。如果 bug 已进入默认分支或到达用户，就算已发布。每个不变量只用一个测试覆盖，不要为每个强制执行该不变量的分支各写一个测试。
• 使用能证明改动有效的最低成本检查：运行程序、临时脚本或手动检查。实际可行时，修复 bug 前先复现它。
• 丢弃大多数这类检查。若某项检查达到上述标准，就将其提升为测试，而不是另写一个测试：通过公共接口执行一个确定性场景，并在适合的现有测试中添加。提升后的回归检查在没有修复时仍必须失败。
• 绝不测试私有辅助函数、框架或类型保证、等效场景，或只是把代码改写成断言的内容。只在系统边界使用 mock。
• 更改行为或触及测试时，删除未达到标准的测试，并说明原因。意图不明确时，查看历史记录。
• 绝不为了让改动通过而删除或削弱失败的测试。查明失败原因。
• 除非有人要求，否则不采用单元测试优先的 TDD、不设覆盖率目标、不添加仅供测试使用的 API、测试夹具脚手架或 BDD 工具。
• 添加代码前，按优先顺序采用可行的第一种方案：消除需求；使用仓库中现有的代码、配置、工具或工作流；使用标准库或原生功能；使用已安装的依赖；编写少量本地代码；最后才添加抽象、文件、服务、配置接口或依赖。到此为止；优先减少文件，代码应直白易懂。
• 绝不为了简化而牺牲安全性、信任边界验证、防止数据丢失、无障碍性、可观测性或仓库特定的保障措施。
• 添加依赖前，比较可信的替代方案，包括不添加依赖。使用当前来源评估适用性、许可证、维护状况和安全性，包括漏洞、来源可信度和传递依赖。考虑它将替代的代码以及新增的义务。提供简明建议，列出来源和风险，然后征求批准。
• 按纵向切片开展工作，确保改动便于审查。简化触及的代码。只有在本地模式合理且有明确意图时才遵循。优先采用正确的修复方案，而非最小补丁；解释权衡，并以便于审查的切片重写糟糕的结构。
• 高风险或破坏性改动前先征求同意，并在完成前运行相关检查。