agents-md-generator

AGENTS.md 生成能力

此技能可让 Agent 生成 AGENTS.md 文件，作为代码库中 AI Agent 的贡献指南。

核心能力

• 功能：分析仓库边界，并生成或更新标准化的 AGENTS.md 文档
• 输出格式：包含结构化章节的 Markdown 文件
• 写作目标：依据 ISO 24495-1:2023 的浅白语言原则，以读者为中心提供指导：贡献者能够找到相关指导、理解经核实的约定，并将其用于下一次更改
• 字符数限制：根据仓库 LOC（代码行数）动态调整
• Monorepo 支持：自动检测 monorepo 结构并生成分层文档（根目录 + 软件包）
• 更新支持：仅刷新带有管理标记的 AGENTS.md 中的标准章节，同时保留用户自定义章节。未标记的文件需要先提供具体的更改预览并获得一次性采纳确认；不包含匹配标准标题的文件则需要明确请求完整重新生成

输出章节

单仓库 / 软件包文档（4-5 个章节）

适用于单个仓库或 monorepo 中的单个软件包：

• 概览：用 1-2 句话描述项目（抽象描述，不列出工具或框架）
• 所有权地图：可选，基于证据绘制的地图，分为稳定的所有权边界和活跃的更改路径——入口点、状态所有者、行为决策点、外部接口、约定/副作用、验证依据，以及参考近期历史确定的路径。如果仓库没有值得记录的稳定边界或活跃路径，则省略此章节；切勿为了填满模板而虚构所有权。
• 核心行为与模式：通过完整流程追踪跨领域模式——错误传播链、状态生命周期转换、跨边界连接机制、弹性/恢复策略、共享资源管理。通过多阶段分析发现：先检测表层惯用模式，再跨层深入追踪。
• 约定：命名、代码风格、API/接口设计约定（回调命名、返回值形式、方法职责划分）、配置/注册结构、边界约定（错误扁平化、架构漂移吸收、隔离规则）、组件组合模式。
• 协作约定：Agent 的行为和沟通规则

Monorepo 根目录文档（2-3 个章节）

适用于 monorepo 结构的根目录：

• 概览：用 1-2 句话描述 monorepo 的用途
• 所有权地图：可选地图，分为稳定的软件包级职责边界和活跃的跨软件包更改路径。在 monorepo 根目录中，软件包名称及其清单、公共导出、README 文本、依赖方向和近期已确认的更改集群，可构成充分证据；如果根目录仅提供没有说明价值的软件包列表，则省略此章节。
• 协作约定：适用于所有软件包的通用协作约定

操作模式

生成与更新

• 生成：从头创建新的 AGENTS.md（不存在 AGENTS.md 时的默认模式）
• 更新：刷新现有受管理 AGENTS.md 中的标准章节，同时保留自定义章节。有效的管理标记表示文件已纳入此工作流；匹配的标题仅用于识别替换候选项，不代表作者身份。未标记的文件需要在提供具体预览后获得一次性采纳确认；没有匹配标题则需要明确请求完整重新生成。有关标记约定和采纳工作流，请参阅 ./references/update_strategy.md。

Agent 会根据目标位置是否已存在 AGENTS.md 文件，自动选择相应模式。

生成模式（Monorepo）

支持三种模式：全部（根目录 + 所有软件包，默认）、仅根目录和单个软件包。详细策略和模式选择标准请参阅 ./references/monorepo_strategy.md。

执行工作流

按顺序执行以下步骤。每一步都有固定输出，供下一步使用；跳过步骤会导致字符预算错误、更新章节不匹配或遗漏 Monorepo 软件包。./scripts/ 下附带的脚本可确保确定性步骤可重复执行——每次都应调用脚本，而不是重新推导逻辑。

步骤 1 — 确定模式

1. 检查目标位置是否存在 AGENTS.md。存在 → 更新候选项（需通过下方的管理状态检查）。不存在 → 生成。

2. 在仓库根目录运行 Monorepo 检测：

   python ./scripts/detect_monorepo.py <repo_root>
   

   输出：{is_monorepo, markers}。结果为 true 时仅表示初步判定：请根据 ./references/monorepo_detection.md 发现实际软件包。如果发现的软件包少于 2 个，即使存在标记，也应将仓库视为单个文档。否则，根据 ./references/monorepo_strategy.md 选择 全部 / 仅根目录 / 单个软件包。如果 is_monorepo 为 false，则将仓库视为单个文档。

3. 在测量 LOC 或深入分析之前，对每个现有目标运行 python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type <single_repo|monorepo_root>。management_status 为 managed、unmarked 或 invalid；generated_doc_type 记录有效标记的原始文档类型，或为 null。无效标记会阻止自动更新。请在应用标题计数门槛前，于下一项中确定原始类型：未标记文件若包含匹配的标准标题，可以继续准备采纳预览，但不能写入；按原始类型匹配到的标题数为 0 时，必须明确请求完整重新生成。单个匹配的标题绝不构成写入授权。

4. 将有效的 generated_doc_type 与当前目标类型进行比较。若两者不同，则使用原始类型重新运行解析器，以识别原始的受管理章节和自定义章节，然后再准备完整重新生成。对于未标记文件，根据独特的标准标题推断其原始类型（## 3. Working Agreements 与 ## 3. Core Behaviors & Patterns / ## 5. Working Agreements）；若这些标题相互冲突或不足以判断，则询问应使用哪种原始类型。保留原始自定义章节，并在覆盖前获得对具体类型转换预览的确认。

5. 对于软件包文档，检查仓库根目录是否存在 AGENTS.md。若存在，则引用其实际相对路径。若不存在，则在软件包文档中直接加入通用工作约定，以及发现的任何软件包本地验证命令。对于单个软件包请求，不要创建根目录文件。在全部模式下，处理完根目录后再次检查。

步骤 2 — 测量 LOC 并分配预算

对每个目标文档（单个仓库，或根目录 + 每个软件包）运行：

python ./scripts/loc_to_limit.py <target_directory>

输出：{loc, scale, character_limit}。如果脚本报告缺少 tokei，请显示其安装提示并停止——不要手动估算 LOC。将 ./references/loc_measurement.md 中的比例用作各章节的初始分配，然后根据已核实的内容重新分配容量。只有前言和受管理章节的合计字符数受硬性上限限制；各章节的比例并非独立上限。

步骤 3 — 构建技术栈上下文

在分析模式和约定之前，根据 ./references/read_only_commands.md > Dependency Discovery，读取文档范围内（根目录或每个软件包）的软件包清单。跳过锁文件。使用这些技术栈上下文，在步骤 4 中聚焦相关框架，而不是盲目搜索。

步骤 4 — 分析仓库

在分析前阅读 ./references/content_quality.md。精简记录与决策相关的事实、当前来源证据及其预期去向。在 Generate 模式下，从源代码中发现这些事实。在 Update 模式下，还要从旧的、基于分析生成的受管理部分中提取重要事实，作为检查线索，对照当前源代码重新确认，并发现旧文档遗漏的内容。旧文档不能作为当前行为的证据，工作记录也不是新的输出章节。

针对选定的重要行为，检查直接实现这些行为的辅助函数，直到确认适用的选择条件、保护／绕过路径、恢复结果、状态生命周期、所有权／清理条件以及实际接收方。起草前，将这份精简的关系记录保存到目标仓库之外的临时暂存文件中。仅记录功能或辅助函数名称并不代表完成了源代码追踪。近期历史会影响活动路由的分类，但不会影响是否保留当前已验证的安全约束。

在依据历史确定优先级前，先根据文档记载的功能以及权威注册项／公开接口建立覆盖表。在 Update 模式下，还要纳入旧文档中所有受管理的 Stable 边界、Active 路由和核心流程。确认每一行当前的所有者／使用方，并进行选择或基于证据的排除。使用实际实现文件和符号追踪选定行，从 open 到 closed，包括管道中每个会改变行为的阶段。没有变更的历史窗口不能作为排除仍在运行的钩子、迁移或安全条件的依据。

对于 Update 模式，在深入追踪源代码前，将 git 历史作为发现所有权的信号：

1. 优先检查自上次由技能更新目标文档中的 AGENTS.md 以来的变更。如果没有可靠的更新锚点，则默认查看最近约 3 个月的记录，并根据仓库活跃度调整范围。

2. 手动展开 git 历史前，先运行附带的高变更率信号辅助工具：

   python ./scripts/git_ownership_signals.py <target_directory>
   

   如果存在可靠的更新锚点，请使用 --anchor <commit-ish> 传入。该脚本会输出精简的 Markdown-KV，以减少上下文用量。

3. 先只查看提交元数据和变更路径。默认不要阅读范围广泛的差异内容。

4. 留意变更路径的聚类、反复共同变更的模式、重命名／移动、已删除路径，以及高变更率的边界文件。

5. 使用历史决定下一步检查的方向，而不是决定要记录什么。只有当前代码或文档约定能够确认时，才添加 Ownership Map 边界。

6. 不要在 AGENTS.md 中保留“先前重点”或“当前重点”等时间线摘要。仅在面向用户的摘要中报告，除非代码当前明确体现了这一转变，例如仍在运行的迁移或兼容性边界。

有关令牌安全的 git 命令和展开规则，请参见 ./references/read_only_commands.md#git-history-signals-update-mode。

运行 ./references/agents_md_template.md 中定义的多阶段分析：

1. 阶段 1 — 技术栈与接口发现（出现在 3 个以上文件中的重复惯用模式、项目特有的抽象）。
2. 阶段 2 — 跨层深入追踪（错误传播、接线、状态生命周期、失败路径、集中式委派）。
3. 阶段 3 — 验证（优先采用出现在 3 个以上位置的模式，同时考虑跨层流程；还应保留一个已验证、对安全工作至关重要的边界，即使它只出现于一处）。

如果 Serena MCP 可用，优先使用其只读符号工具（find_symbol、find_referencing_symbols、get_symbols_overview 等），而不是 rg / grep / find——符号查询在调用方追踪和跨层流程方面更准确。请参见 ./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp。 仅在当前上下文中运行此分析。不要委派给子 Agent——第 3 阶段的跨模式验证和分节预算跟踪需要统一视图（参见范围边界 > 单上下文执行）。

仅记录实际观察到的模式／惯例。保留必要的入口点、会改变行为的替代方案、异常／回退条件、生命周期义务和兼容性影响。如果某个分节需要超出初始分配的篇幅，应在总限额内重新分配未用篇幅，而不是删去这些事实。按照内容质量参考中的压缩顺序处理。

如果可选的 ## 2. Ownership Map 没有基于证据的内容，则省略该分节，并保持后续分节编号不变。分节编号是更新模式标识符；切勿为了填补编号空缺而重排 Core Behaviors & Patterns、Conventions 或 Working Agreements 的编号。有证据时，将 Ownership Map 的内容拆分为 Stable Ownership Boundaries，用于说明原先单列表格 Ownership Map 会记录的持久安全边界；以及 Active Change Routes，用于说明依据近期历史并经当前代码确认的变更路径。将 Active Change Routes 视为增补性的更新模式上下文，而不是稳定边界的替代项或筛选条件。稳定边界项目应是完整的变更路由规则；活动项目应是关联上级边界或跨边界的增量路由。不要在 Active 中重述父级 Stable 边界的宽泛所有者、契约或验证方式。若移除继承自 Stable 的细节后不再有实质性增量，则省略该 Active 路由。除分节字符预算外，不要设置项目数量上限。

步骤 5 — 组装（生成）或拼接（更新）

起草前，请阅读 ./references/plain_language.md。撰写生成的章节正文时，应面向熟悉项目编程语言、但尚不了解项目本地负责人、术语或契约的贡献者。更新模式下新撰写的受管理正文也应遵循同一写作指南；根据更新契约保留自定义章节和现有序言的原始字节。这是一次输出编写流程，不是新增章节，也不是对未来 Agent 回复新增长期规则。

首先将封闭且与决策相关的契约写入 Ownership Map/Core Behaviors，避免在多个章节中重复。将剩余篇幅用于特定于仓库的约定；不要以牺牲已覆盖的契约为代价，罗列通用命名、角色、日志或资源清单。移除 Active 标签或合并章节时，确保每一行覆盖项都有归属。

• 生成：使用 ./references/agents_md_template.md 中的结构输出文档（单仓库／包为 4-5 个章节，monorepo 根目录为 2-3 个章节，具体取决于 Ownership Map 是否有证据支持的内容）。在序言中、首个 ## 标题之前，单独添加且仅添加一行 ``；monorepo 根目录使用 monorepo_root。Working Agreements 章节及其根目录不存在时的回退处理，请使用 ./references/working_agreements.md。

• 更新：对现有文件运行章节解析器：

  python ./scripts/parse_sections.py <path/to/AGENTS.md> --doc-type single_repo
  

  （monorepo 根目录请使用 --doc-type monorepo_root；准备类型转换时，请使用步骤 1 中的原始类型。）输出会将每个 ## 标题标记为 is_standard（可替换候选项，须通过管理门槛）或非标准（保留）；在 optional_standard 中标记须经证据门槛确认的标题，并通过 is_optional_standard 标记匹配到的可选章节。旧版 ## 2. Folder Structure 章节会报告 canonical_title: "## 2. Ownership Map"，以便获批的更新可以迁移这些章节。只替换标准章节的正文；保留自定义章节、文件标题和序言不变，但可按批准插入标记或替换类型。按编号位置插入缺失的必需标题；仅当新分析得出有证据支持的内容时，才插入缺失的可选标题。完整的重新组装规则见：./references/update_strategy.md。

  管理门槛：依据步骤 1 的管理结果，而非仅依据 is_standard。对于未标记文件，先完成具体的预览，列出替换、插入、删除和标记插入内容，然后取得一次性采纳确认。获批后，同时写入采纳内容和标记；如被拒绝，则保持原文件不变。一般性的更新请求不构成采纳确认。保留所有非标准内容及现有序言，唯一例外是明确获批的标记插入。无效标记必须报告，不得静默修复。详情请参阅更新策略。

  如果现有文档类型不再符合仓库情况（例如，单仓库变成了 monorepo），则强制完整重新生成，而非更新：将所有自定义章节原样移入重新生成的文档（保持原有顺序），并在覆盖前取得用户确认。

步骤 6 — 验证并写入

写入前，请确认：

• 前言与标准（受管理）章节的总长度不超过 character_limit。重新分配后可超出各章节的分配额度；应保留各章节的职责，不得添加填充内容。自定义章节不计入预算，且绝不能为了满足预算而删减。
• 文档的前言中恰好有一个有效的管理标记，且文档类型与输出相符。该标记计入前言预算。除经批准的标记插入或类型转换替换外，应保留前言。只有在批准具体的采用预览后，才可写入没有标记的文件。
• 不得出现反模式中的任何内容（不得包含常用命令、运行／测试／构建／部署说明、IDE／工具设置等）。例外：工作约定中必须包含已发现的类型检查命令，它不属于构建／运行说明。
• 对于更新模式：每个标准章节的正文都必须根据其受管理来源重新编写，不得因为旧措辞看起来可接受就直接沿用。
• 对于两种模式：最终压缩后，应依据./references/content_quality.md，将组装完成的文档与工作事实记录进行比较。每项重要的已验证事实都必须得到传达、修正以反映当前行为，或基于证据排除。即使结构和长度符合要求，未解释的遗漏或失真仍无法通过验证。重新确认的标识符和含义可以在新编写的章节中重复出现；内容新写不意味着必须删去有用事实。如果在重新分配篇幅并压缩后仍无法容纳重要事实，应完成一份可供审阅的候选稿，并在写入前询问范围或总长度限制。
• 压缩后，使用./references/plain_language.md中的读者任务检查来审阅生成的文案。贡献者应能找到变更、识别负责人和适用条件，并在无需解读简写的情况下了解约定和验证范围。应在保留已验证含义的同时，修改不清楚的受管理文案；此审阅不授权更改自定义章节、保留的前言、规范标题或字符限制。
• 将临时记录与最终输出一并阅读：为每项重要事实找到其在最终文档中的具体句子，并检查其适用关系字段。针对恢复、迁移、还原、复用、保护措施和资源所有权的宽泛主张，应反向核对其实现辅助函数。如果记录和文案都遗漏了某项条件，应重新检查辅助函数；两者一致并不代表通过审查。此审计应在 AGENTS.md 之外进行，只向用户报告实质性修正或限制。
• 既要检查深度，也要检查覆盖面：所有旧的受管理边界／路由／流程，以及已记录或已注册的能力候选项，都必须有当前的处置结论，且不得有任何选中的条目仍处于 open 状态。历史记录为空、笼统地称为“价值较低”或篇幅紧张，都不能成为排除当前安全约定的理由。通用的流水线阶段名称无法说明这些阶段的实际选择或恢复条件。
• 对于更新模式：只扫描受管理的标准章节，查找过时的常设工作约定措辞。如果受管理内容仍包含 Keep edits minimal、Minimal changes、preserve public APIs、existing plugin behavior 或 avoid unnecessary abstraction，则验证失败；自定义章节可保留用户编写的任何措辞。
• 对于更新模式：每个保留的自定义章节都必须与原文逐字节完全一致。
• 对于更新模式：在覆盖之前，应向用户报告受管理标准章节中将被删除的任何措辞；受管理章节中的用户补充内容不会保留，因此应列出将被删除的内容，并建议将用户自有内容移至自定义章节。
• 对于更新模式：如果因缺乏当前证据而打算省略现有的受管理 Ownership Map 或旧版 Folder Structure 章节，应报告整个章节将被删除，并在覆盖前征得确认。
• 对于单仓库文档：受管理的 Working Agreements 章节不得包含仅适用于 monorepo 的措辞，例如关于软件包级 AGENTS.md 的指导。
• 对于软件包文档：根目录引用必须指向现有文件；否则，软件包必须直接包含通用工作约定，且不得引用缺失的根目录文件。如果先前更新使用了回退方案，而现在根目录文档已存在，则应通过常规的受管理章节替换切换为继承，并报告将删除的措辞。 然后使用 Edit/Write 工具编写。对于 mode = All 的 Monorepo，处理完根目录后，对每个目标包重复步骤 2–6，并针对每个包重新执行步骤 1 的 Generate/Update 判定、管理检查和根目录存在性检查——即使根目录的操作是 Update，没有 AGENTS.md 的包仍应执行 Generate。

工具

此技能使用以下只读工具分析代码仓库。详细用法请参阅 ./references/read_only_commands.md。

• Serena MCP 符号工具（如可用，优先使用）：find_symbol、find_referencing_symbols、find_referencing_code_snippets、get_symbols_overview、search_for_pattern、list_dir、find_file、read_file。在查找符号、追踪调用方和进行结构分析时，优先使用这些工具，而非 rg / grep / find。仅使用列出的只读工具；不要调用写入/编辑符号工具或 execute_shell_command。请参阅 ./references/read_only_commands.md#symbol-level-analysis-optional-requires-serena-mcp。
• tokei：LOC 测量（必需）
• rg（ripgrep）：内容搜索（Serena MCP 不可用时的备用工具）
• grep / Select-String：内容搜索（按操作系统选择；Serena 和 rg 均不可用时的备用工具）
• sed -n / Get-Content \| Select-Object：按操作系统分页读取文件
• tree：可视化目录结构
• find：查找文件和目录（Linux / macOS；Serena 的 find_file 不可用时的备用工具）
• ls、pwd：基本目录导航
• git log、git show --stat、git show --name-only：Update 模式下用于发现文件归属的信号；先使用捆绑脚本，再查看元数据和变更路径，默认不要查看宽泛差异

捆绑脚本

确定性步骤已捆绑为 ./scripts/ 下的脚本，以便在不同调用和平台上保持一致。优先使用这些脚本，不要用自然语言重新推导逻辑。

• scripts/loc_to_limit.py：使用规定的排除项运行 tokei，解析 Total 行，并返回 {loc, scale, character_limit}。如果缺少 tokei，则显示安装提示并以非零状态退出。
• scripts/detect_monorepo.py：检查标记文件（pnpm-workspace.yaml、lerna.json、nx.json、turbo.json、rush.json、.moon/workspace.yml、go.work、Cargo.toml [workspace] members、package.json workspaces、Gradle settings.gradle*、Maven pom.xml <modules>、Bazel、Buck2、Pants、Hatch/uv/rye）。Gradle 匹配会读取完整的字面 include 声明（包括多行形式），忽略注释和字符串示例，并对项目路径去重；不会计算动态 Gradle 表达式。返回 {is_monorepo, markers}；若结果为 true，则仅为暂定结果，直到包发现步骤确认存在 2 个或更多包（步骤 1）。
• scripts/parse_sections.py：用于 Update 模式。返回一个章节映射，其中包含标准标题候选项、自定义章节和缺失标题，以及 management_status 和 generated_doc_type。现有 JSON 字段和 --doc-type 匹配方式保持不变；写入前，使用者必须先通过管理门槛检查。忽略围栏代码块中的标题和标记。解析器报告行范围，不会重写内容；应从原始字节中拼接保留的范围，并保留换行符和尾随空格。
• scripts/git_ownership_signals.py：用于 Update 模式。对目标目录运行令牌安全的 Git 历史聚合，并输出简洁的 Markdown-KV 高频变更路径信号。此输出仅用于发现线索；记录 Ownership Map 边界前，必须根据当前代码确认。

领域知识

• LOC 测量：测量仓库规模并确定字符数限制的能力。参见 ./references/loc_measurement.md
• 仓库分析：检查并了解代码库结构的能力。参见 ./references/read_only_commands.md
• 输出模板：标准化的 AGENTS.md 结构规范。参见 ./references/agents_md_template.md
• 内容质量：发现与决策相关的事实、基于证据进行保留或修正、压缩顺序，以及最终语义比较。参见 ./references/content_quality.md
• 通俗语言：了解读者需求、使用易于查找的标签、撰写清晰的技术文本，并依据 ISO 24495-1:2023 进行最终读者任务审查。参见 ./references/plain_language.md
• 工作约定：针对生成文档的 Agent 行为规则。参见 ./references/working_agreements.md
• Monorepo 检测：识别 Monorepo 结构的能力。参见 ./references/monorepo_detection.md
• Monorepo 策略：在 Monorepo 中生成文档的策略。参见 ./references/monorepo_strategy.md
• 更新策略：通过选择性刷新章节来更新现有 AGENTS.md 文件的策略。参见 ./references/update_strategy.md

范围边界

• 只读分析：支持用于检查仓库的非破坏性命令
• 输出范围：仅生成文档内容；不包含运行、测试、构建或部署说明。如果仓库分析未发现具体且稳定的内容，则省略可选章节。
• 排除的输入：锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock 等）不在分析范围内
• 单上下文执行（不使用子 Agent）：此技能在任何步骤中都不得启动子 Agent（例如 Agent / Task 工具、Explore、general-purpose 或任何委派的 Agent）。生成 AGENTS.md 需要对仓库有统一的整体认识：累积的技术栈上下文（第 3 步）、各章节的字符数预算（第 2 步）、跨 3 个或更多位置的第 3 阶段验证，以及更新模式下对自定义章节逐字节保留，这些都依赖单一上下文。将工作拆分给子 Agent 会丢失这些状态，并导致输出不一致或违反预算。父 Agent 调用此技能没有问题——技能的内部执行必须始终处于单一上下文中。