init

适用场景

创建或更新仓库的 AGENTS.md 时使用此技能。

尤其适用于以下情况：

• 当前的 AGENTS.md 冗长、泛泛而谈或已过时
• Agent 反复犯同样本可避免的错误
• 仓库工作流发生变化，需要精简 Agent 指引

说明

将 AGENTS.md 视为一份记录无法从仓库中直接发现的隐患和工作流注意事项的动态清单，而非代码库概览。

核心原则：可发现性筛选

添加任何内容前，先问：

Agent 能否通过阅读仓库（README、代码、配置、脚本、目录树）发现这条信息？

• 如果能：不要写入 AGENTS.md。
• 如果不能，且会实质影响任务成效、成本或安全：则写入。

哪些内容值得写入

仅纳入符合以下条件的指引：

1. 无法仅凭仓库文件发现
2. 具有实际操作意义（会改变命令、结果或安全性）
3. 可执行（足够具体，能够照着操作）

典型示例：

• 非标准工具选择（例如使用 uv 而不是 pip）
• 命令注意事项（例如因测试夹具的行为，测试必须使用 --no-cache 运行）
• 隐藏的约束或隐患（已弃用的目录仍在生产环境中导入）
• 未体现在 lint、测试或配置中的关键本地约定

应删除或避免的内容

不要纳入：

• 技术栈概述
• 目录结构概览
• Agent 能从代码中推断出的架构说明
• 通用最佳实践建议
• 工具已强制执行的规则（lint、类型检查、测试、CI）
• 除非仓库明确要求，否则不要添加必需的样板标题

建议结构

优先采用简短且重点明确的章节，例如：

• 范围与路由（哪些区域需要单独的或模块本地的 AGENTS 文件）
• 无法从仓库中发现的命令
• 隐患 / 禁止触碰的区域
• 特定任务约束

对于大型仓库，建议在相关模块附近使用分层的 AGENTS.md 文件，而不是创建一个庞大的根目录文件。

优先检查的源文件

• 现有的 AGENTS.md
• README.md
• PROJECT.md（如有）
• Cursor 规则（.cursor/rules/ 或 .cursorrules）
• Copilot 指令（.github/copilot-instructions.md）
• GEMINI.md
• CI/工作流文件和包管理器配置（用于发现命令或工具不一致）

如果 AGENTS.md 已存在，应在其基础上逐步改进，而不是不加判断地直接替换。

维护原则

AGENTS.md 是临时指引，而非永久配置。

出现反复发生的问题时：

1. 优先通过代码或工具修复根本原因（lint 规则、测试、脚本、结构）
2. 在根本原因解决前，仅保留最少量的必要说明
3. 积极清理过时指引

定稿前的质量检查

核实 AGENTS.md 中的每一条内容：

• 是否无法从仓库中发现？
• 现在是否仍然准确？
• 是否能实质减少错误、成本或耗时？

删除任何一项不符合上述检查的内容。