agents-md

AGENTS.md 生成器

生成工作区根目录指令和按需规则；可选择根据本地 Compose 证据同步现有项目运行时区块。

输入

• 目标根目录必须包含一个 *.code-workspace 文件（多文件夹或单文件夹）。如果没有，则停止且不要生成文件——项目矩阵根据其 folders 列表构建；告知用户从包含此类文件的文件夹重新运行。如果存在多个，请在扫描前询问要使用哪一个。
• 绝不读取或复制 Agent 自己的全局或用户指令文件（~/.claude/CLAUDE.md、~/.codex/、全局 AGENTS.md、个人记忆/规则）。根据随附模板和工作区证据生成规则。零署名：从生成的文件和所有输出中省略共同作者、AI 和工具署名。

规则

• 工作区根目录的 AGENTS.md 是 Codex CLI、Claude CLI、Antigravity CLI、Cursor CLI、Opencode CLI 和 GitHub Copilot CLI 的唯一事实来源；共享操作指令——上下文、记忆策略、问题路由、技能使用——均放在其中。
• 绝不创建或编辑 CLAUDE.md 或 GEMINI.md，也不从中提取规则；将已有文件报告为冲突指令文件。
• 只创建一个根目录 AGENTS.md，以及文件映射中的 rules/ 文件。项目同步仅编辑现有 AGENTS.md 文件；绝不创建项目指令文件。

模式

默认模式：生成或刷新根目录文件及其按需文件。如果存在 .devcontainer/compose.yml，则阅读项目运行时同步并同步现有项目运行时区块；否则报告已跳过同步，不加载该参考文档。

仅提及项目运行时同步的请求选择仅运行时模式：遵循该参考文档和现有技术栈检测；跳过根目录生成、迁移和设置建议。此模式下，绝不创建或编辑工作区根目录的 AGENTS.md 或 rules/。以下根目录生成规则和完成检查仅适用于默认模式。

工作区扫描

先扫描每个工作区文件夹：记录工作区或项目根目录中的任何 VISION.md/vision.md（供 North star 使用），并检测每个技术栈。存在多个技术栈时 → 简介栏要说明这一点，并提醒不要在项目之间混用约定或代码。

技术栈检测

Stack 单元格中的事实必须从应用根目录的清单文件和锁定文件读取——绝不根据文件夹名称、根目录级清单文件或文件是否存在来猜测。先找到实际应用根目录——通常位于嵌套路径（application/、app/、src/）中——再读取其中的清单文件。各生态系统的清单文件读取方式见：references/stack-detection.md。

项目矩阵格式

每个 .code-workspace 文件夹占一行，顺序与 folders 一致——绝不臆造或遗漏项目。列必须严格为 | Project | Path | Stack |：

• Project：使用文件夹 name 中的 PROJECT-CODE——去掉表情符号，转为大写，将连续标点/空格折叠为单个连字符，并去掉首尾连字符（Payments API → PAYMENTS-API）；缺少 name 时使用路径 basename；非应用文件夹添加类型前缀（PACKAGE-QUEUE、DB）。在所有地方都使用项目矩阵中的完整 PROJECT-CODE；绝不将一个项目的约定、令牌或组件混入另一个项目。
• Path：相对于工作区根目录的文件夹 path；. 表示元数据/工作区行。
• Stack：简洁的一行——语言、所有主要框架、构建工具、包管理器；仅当清单文件固定了版本时才列出版本；非应用文件夹说明其用途。单元格中不得有说明性文字。

如果规范化后得到空的或重复的 PROJECT-CODE，则停止并要求提供唯一代码，再输出矩阵。也要检查 . 文件夹中的清单文件；它可能是应用根目录。

示例：

| Project      | Path             | Stack |
| :---         | :---             | :---  |
| PAYMENTS-API | ../payments-api  | PHP 8.3 / Laravel 13 / Vite / Composer + npm (application/) |
| DB           | ../db-migrations | MySQL / raw SQL migrations |

Vite 本身绝不意味着使用了某个包管理器。

生成的骨架

将 assets/agents-md-template.md 作为 AGENTS.md 输出，并将每个 assets/rules/ 文件按字节原样输出为 rules/<name>，只填入 文件映射 指定的方括号占位项；Versioning and regeneration 中保留的自定义内容除外。默认骨架受以下三条规则约束：

• 仅当已安装 Matt Pocock 的技能时，才在 skills.md 中输出 ## Matt skill routing：在工作区根目录或用户主目录的 .agents/skills/ 或 .claude/skills/ 下，存在 ask-matt、grill-with-docs 或 to-spec 的 SKILL.md。否则删除该节。如果此检查结果与运行时的技能列表不一致，请询问。无论哪种情况，渐变表都会列出外部技能。
• 仅当扫描发现愿景文件时，才输出 #### North star，并列出每个文件的作用范围；绝不虚构文件或复述其内容——该小节只指向文件。未发现文件 → 删除该小节。
• issues.md 必须保持与资源文件一样简洁——路由/标签流程放在 issue 技能中，不在此处说明——并且不要填写 Context & native memory 中的两个占位项。

使用技能

根据 references/skills-manifest.md 生成渐变表及配套内容——它是唯一事实来源；绝不要在此处硬编码表格行。phase: companion 的 Kit 条目仅在配套内容中呈现。

输出目录或说明前，应用该文件中的说明排除规则、单元格和启动行格式，以及安装检查。

根据 references/tool-calling.md 填写 [RUNTIME TOOL-CALLING …] 占位项，严格遵循其中的 Emitting into AGENTS.md 格式；仅当单元格缺失或不明确时，才打开各运行时的表格（claude、codex、copilot、cursor、opencode、antigravity）。仅在用户要求时设置原生记忆：memory defaults。绝不要链接参考文件（它们不会随项目发布），也不要复述 Local orchestration 规则。

版本控制与重新生成

技能版本为 v58。每个生成的文件都以标记 `` 作为首行。每当这些规则发生变化时，在此处以及所有资源文件中同时更新该标记。旧版 v6 之前的标记：regeneration。

运行时，检查每个目标——根目录中的 AGENTS.md 以及所有按需文件：

• 均不存在 — 全新生成。
• 存在标记 — 覆写前，按章节展示完整差异——绝不截断或概述——并单独标出自定义内容，然后征求确认。如果用户未回复，则停止，不写入，并说明原因。
• 没有标记（手写文件） — 不要重写；展示生成会新增或修改的内容，仅合并用户批准的章节，其余部分以现有文件为准。
• 保持 PROJECT-CODE 稳定 — 按 Path 匹配，保留每一行已有的代码。如果代码因目录重命名等原因而需要重新推导，则将其作为单独的差异项，需获得明确批准；绝不静默更改。新目录使用推导出的代码。
• 保留用户编辑 — 按照 regeneration 保留用户填写的占位值（尤其是 GLOSSARY.md 和 specs/adr 路径）、自定义规则正文以及外部章节。
• 单文件布局（标记版本低于 v50）：布局迁移。
• 安全写入 — 写入前重新读取每个目标；如果自获批后文件已发生变化，则重新计算差异并再次展示。任何写入或移动操作失败时，立即停止并报告已写入和未写入的内容。

迁移（请先征求同意）

列出每项迁移，以及链接会被改写的每个文件，并先征求同意。仅在产物根目录中移动和改写；项目仓库只读，并在报告中说明。若对方拒绝或未回复 → 保留现有路径；绝不在未征得同意时重命名。

• 仍位于 docs/ 下的产物子文件夹（v7 之前）：将 docs 迁移到 specs。
• 仍在使用的 CONTEXT.md 或 CONTEXT-MAP.md（v47 之前）：重命名为 glossary。

输出

在对话中提供写入前的差异、迁移移动清单和报告、Project Matrix 每一行所读取的清单文件、规则链接检查结果、相互冲突的指令文件，以及生成的字节大小——若超过 32768，则添加 Codex 大小说明。

结束时建议使用 /setup-matt-pocock-skills、为每个 UI 项目使用 /design-system，并在提及主机时使用 env-guard hooks——只建议，绝不运行。

完成标准

• 请求的项目同步满足对应参考文档中的匹配、审批和保留检查
• 每个文件的章节均按素材顺序排列；仅当 Matt 的技能解析成功时才包含 Matt 技能路由；仅当找到愿景文件时才包含 #### North star
• AGENTS.md 指定的每个 rules/ 路径在运行后都存在——在对话中报告检查结果；省略可选章节时，必须保留所有编号规则和 Runtime 工具调用
• 重新生成：外来章节、用户填写的值和规则正文自定义内容均得以保留；替换任何自定义规则前都已获得明确批准——否则停止运行，不写入任何内容
• 生成的目录和启动说明不包含清单排除的条目；工具包配套项仅出现在配套项列表中，且每项均通过安装检查
• 即使省略 Matt 路由，工作区路由仍得以保留；若生成 Matt 路由，则必须将已验证的检出路径传递给任务技能
• Project Matrix 行数等于 folders 计数；对话中指出每个 Stack 单元格所对应的清单文件；除非变更已获批准，否则现有 PROJECT-CODE 保持不变
• 每个生成的文件均以当前版本标记开头；Context 和原生记忆占位符保持完整，或沿用已有内容
• 未创建或编辑任何 CLAUDE.md 或 GEMINI.md；对话中说明生成的字节大小，超过 32768 时附上上述 Codex 说明
• 经批准迁移后，已移动的产物不再包含过时的 docs/<sub>/ 链接或旧 glossary 名称；仅改写清单中列出的文件，其他无关的 docs/ 内容和被拒绝的迁移保持不变
• 对生成文件进行搜索，确认其中不含会话数据：日期、对话引用、机器本地绝对路径