# 编写 AGENTS.md ## 目标生成或更新人工智能编码代理的单一事实来源。 `CLAUDE.md` 与 `@AGENTS.md` 导入一起生成；根据要求提供其他代理文件。 **范围：**当前工作目录（CWD）。所有输出路径都是 POSIX 样式并且相对于 CWD。 ## 何时使用/何时不使用使用时： * 用户要求创建或更新 AGENTS.md、CLAUDE.md 或代理上下文文件（`.cursorrules`、`.windsurfrules`、`GEMINI.md`、`CODEX.md`、`.github/copilot-instructions.md`）。 * 用户想要将人工智能代理加入到项目中。请勿在以下情况下使用： * 单文件脚本、没有构建配置的一次性 PoC，或只有 README 的存储库。最小：一个至少包含一个可运行命令的构建配置文件。 * 用户想要审查（而不是编写）现有的 AGENTS.md — 使用审查技能。 ## 质量栏（默认）目标结果： * **没有规范违规**（格式/架构/验证检查），以及 * **评分标准≥ 4.5/5.0**（A-或更好），并且 * **评论家评论中没有 P1 发现** 标题：[references/agents-md-rubric.md]()（单一事实来源）。 ## 安全/约束（不可协商） * 切勿读取、请求或粘贴机密（示例：`.env`、API 密钥、令牌、私钥、凭据）。 * 除非用户明确请求，否则不要浏览网页或调用外部系统。 * 不要在分析/验证过程中运行破坏性命令（数据库重置、部署、发布）。 * 仅在用户明确批准后才写入文件（请参阅“用户审核”部分）。 ## 分析阶段执行这些步骤来收集事实。不要在最终文件中包含分析输出。 **优先级和分类：** 当上下文或时间有限时，请按以下顺序集中精力： * **P0（必须）：** 关键部分准确性、命令正确性、结构有效性 * **P1（应该）：** 领域和上下文、模式、测试策略、安全性、环境。 **如果检测到工作区配置**（turbo.json、nx.json、pnpm-workspace.yaml、package.json 中的工作区、Cargo.toml 中的“[workspace]”、go.work）：将 Monorepo 提升到 P1。 * **P2（必备）：** Monorepo（除非升级）、CI、工具首选项、搜索、Git、调试当输出超出行预算时，以相反的优先级删除部分：首先是 P2（调试 -> CI -> Git -> 搜索 -> 工具首选项 -> Monorepo），然后是 P1（环境 -> 安全 -> 测试策略 -> 模式 -> 域和上下文）。 P0 部分永远不会被丢弃。在优先级内，更喜欢保留内容更具体的部分。 **有针对性的更新：** 如果用户请求更新特定部分，则仅运行与这些部分相关的分析步骤。跳过完整的重新分析。仅验证更改的部分以及关键部分（始终重新验证）。 **文件和环境安全：** 安全/约束规则适用。另外在分析过程中： * 只读取 env_templates_ : `.env.example`, `.env.template`, `.env.sample`, `.env.local.example` * 跳过二进制锁文件（例如 `bun.lockb`）——通过 glob 检测是否存在，但不读取内容 * Env 部分值：使用描述占位符（例如，“DB_PASSWORD=<来自机密管理器>”）；切勿从“.env.example”或源代码复制实际默认值 * 例外：可以使用众所周知的本地开发默认值（`localhost`、`5432`、`postgres`） **简单的项目快捷方式：** 全部保留时应用：(1) 一个主要构建配置（调用 `uv run ...` 等辅助包装器等辅助包装器不算在内），(2) 一个主要源目录（测试/脚本/文档不算在内），(3) 无 monorepo 工作区配置。触发时：完全运行步骤0-3；对于步骤 4，仅读取主入口点。 **上下文预算：** 如果分析消耗过多上下文（许多大型配置文件），请停止扩展检测并继续使用迄今为止收集的数据进行生成。将 `` 添加到输出。更喜欢广度（浅层检测所有类别）而不是深度（读取一个类别中的每个文件）。 ### 0\.查看现有的 AGENTS.md 和代理上下文文件 **如果`AGENTS.md`存在**，请先阅读它。视为起点，而非权威。验证精选部分：部分|验证对照 ---|--- 领域和上下文|自述文件、包说明、源代码图案|实际目录布局、导入约定、代码风格测试策略|测试配置文件，测试目录结构安全| `.gitignore`，秘密管理器导入，环境变量模式 Git 约定 | `git log --oneline -20`，分支名称（如果不是 git 存储库则跳过）还要检查预先存在的代理上下文文件（`.cursorrules`、`.windsurfrules`、`GEMINI.md`、`CODEX.md`、`.github/copilot-instructions.md`）——如果找到，通知用户这些文件可以与 AGENTS.md 一起更新。 **部分更新政策：** 更新模式 |栏目|重新运行时的行为 ---|---|--- **自动检测**（始终重新生成）|关键、命令、结构、环境、执行上下文、数据和状态、搜索、Monorepo、CI、工具首选项、调试 |从项目文件覆盖 **策划**（如果有效则保留）|领域和上下文、安全 |保持现有；仅在可验证过时时更新（见下文） **混合**（检测+合并）|模式、测试策略、Git |从检测中重新生成碱基，合并手动添加 **过时标准：** 当自述文件目的/名称更改、项目类型更改或关键术语引用缺少标识符时，域和上下文已过时。当秘密加载机制发生变化、“.gitignore”模式出现分歧或新的环境模板具有未列出的敏感变量时，安全性就会过时。 **陈旧删除：** 自动检测部分：删除对不存在的工具/路径/命令的引用。混合部分：用 `` 标记已删除的项目。 **冲突：**更喜欢项目文件；如果不确定，请添加 ``。 **领域术语提取：** 扫描自述文件（标题、粗体/斜体术语、术语表部分）、入口点中的文档注释以及特定领域术语的配置描述（首字母缩略词、业务概念、项目特定术语）。包括出现在代码标识符中的术语，并且在没有上下文的情况下对于代理来说会产生歧义（例如，“工作区”表示“租户”而不是“IDE 工作区”）。省略普遍理解的术语（API、URL、JSON）。如果未找到域术语，请忽略关键术语字段。 **没有现有的 AGENTS.md：** 从项目文件中推断所有部分。仅填充有具体证据的部分。 **最小可行输出：** CRITICAL、领域和上下文以及命令都必须具有具体内容。如果命令为空，则不生成 - 通知用户该项目缺乏足够的结构。 ### 1\.检测堆栈并识别约束扫描项目根目录中的配置文件。如果构建配置仅存在于子目录中（例如，`backend/pyproject.toml` \+ `frontend/package.json`），也向下扫描一级。使用glob来检测；阅读以提取详细信息。对于大文件（>500 行），请改用 grep 依赖项部分。 **检测目标：** 扫描“references/detection-reference.md”中列出的以下类别的文件：构建和运行时、质量和挂钩、基础设施和部署、数据和 API、安全性和可观察性、文档和元。 **消歧规则：** * `template.yaml` -> SAM 仅当前 20 行包含 `AWSTemplateFormatVersion`/`Transform: AWS::Serverless` * `app.json` -> 仅当 deps 中有 `expo` 字段或 `react-native` 时才移动 * `package.json` 中的 `volta` -> 固定 Node/npm/yarn * `config.yaml`/`config.yml` -> Kubernetes 如果包含 `apiVersion` \+ `kind`;其他应用程序配置 * 仅当“*.cabal”或“stack.yaml”也存在时，“package.yaml”-> Haskell (hpack)；否则视为通用配置 * `Makefile` -> 如果目标调用 `npm`/`uv`/`cargo`/`go`/`mix` 则任务运行器包装器；否则构建系统 * 多服务存储库中的“Dockerfile” -> 记下 Structure 中的每个服务及其 Dockerfile 路径 **派生约束：** 锁定文件确定强制的包管理器。禁止同一生态系统中的竞争管理器（JS：npm/yarn/pnpm/bun；Python：pip/uv/poetry/pdm/pipenv）。跨生态系统锁文件不冲突。检测到 |授权|禁止 ---|---|--- 生态系统中的锁定文件 |那个包管理器|同一生态系统中的竞争管理者 `biome.json` | `生物群系` | `eslint`、`更漂亮` 部门中的“ruff” | `ruff` | `flake8`、`黑色`、`isort` `Cargo.toml` | `货物 fmt`、`货物 Clippy` | \-- `go.mod` \+ `.golangci.yml` | `golangci-lint` | \-- `deno.json` | `deno fmt`、`deno lint` | \-- `.editorconfig` |尊重缩进样式/大小 | \-- 预提交挂钩 | \-- | `--不验证` deps 中互斥的 lib |选择的图书馆 |替代方案 `pom.xml`（无`build.gradle*`）| `mvn` | `gradle` `build.gradle` 或 `build.gradle.kts`（无 `pom.xml`）| `./gradlew` （如果 `gradlew` 存在）否则 `gradle` | `mvn` `项目.clj` | `莱因` | `clj` `deps.edn`（无`project.clj`）| `clj` | `莱因` `build.sbt` | `sbt` | `磨坊` `build.mill` | `磨坊` | `sbt` `stack.yaml` | `堆栈` | `阴谋集团` `*.cabal` \+ `cabal.project` （无 `stack.yaml`）| `阴谋集团` | `堆栈` `.scalafmt.conf` | `scalafmt` | \-- `.clj-kondo/` | `clj-kondo` | \-- `checkstyle.xml` | `检查样式` | \-- **附加规则：** * **锁定文件冲突** -> 检查 CI 以确定哪个管理器；强制执行该命令。如果不清楚，``。 * **私人注册表** -> 注意 Env 中的 URL（无凭据）。 * **容器** -> 仅当应用程序在 Docker 中运行时才执行“docker compose run/exec”（不像数据库那样仅限于基础设施）。 * **Monorepo** -> `turbo.json` -> `turbo run`; `nx.json` -> `nx run`/`nx受影响`;注意根与包范围。 * **多语言（无工作区配置）** -> 每个堆栈的标签命令（例如，`# install (backend)`）。如果没有编排工具，请勿使用 Monorepo 部分。 * **Git 子模块** -> 注意结构中的路径。 * **无法识别的堆栈** -> 阅读自述文件并构建命令配置。不要猜测——省略没有证据的部分。 * **Java 共存** : 当 `pom.xml` 和 `build.gradle*` 都存在时，检查 CI 以确定主要；强制执行该命令。 * **Clojure 共存** ： `deps.edn` 和 `project.clj` 可以共存。更喜欢 CI 证据。如果 CI 不存在或不明确： `project.clj` 存在 → `lein`；否则`clj`。如果不确定，请添加 ``。 * **Gradle 包装器** ：存在 `gradlew` -> 使用 `./gradlew` 而不是 `gradle`。 * **Haskell 共存** : `stack.yaml` \+ `*.cabal` 是正常的 — Stack 管理工具链；使用“堆栈”。 ### 2\.地图入口点和数据找到主要入口点、测试运行器入口和固定装置位置、CI 配置。 **执行上下文：** **主机**（默认/仅限 Docker 基础设施）| **Docker**（撰写中的应用程序）| **开发容器** | **尼克斯** | **混合** | **无服务器**（Lambda/云函数/等） **项目类型** — 分类为：**库**（发布脚本，不部署）| **应用程序**（部署配置、Dockerfile、入口点）| **CLI/工具**（`bin`/`[project.scripts]` 条目，无部署）| **两者**（发布+部署）。消歧义：如果存在发布+部署，则首选两者；不确定时默认为应用程序。 **数据、基础设施和生成的代码** — 检测和路由： * DB/ORM/migrations/brokers/API schemas -> 数据和状态（仅路径和元数据；可运行的命令放在命令中以避免重复） * IaC/K8s/Helm -> 执行上下文+结构；秘密->安全；环境加载 + 模板 -> 环境 * 构建输出目录（`dist/`、`target/`、`.next/`）-> 结构（生成）； Codegen dirs -> 结构 `（生成 - 不编辑）` \+ CRITICAL NEVER * Codegen 工作流程（OpenAPI codegen、protobuf、GraphQL codegen）-> 命令中的注释生成命令、数据和状态中的源模式、结构中的输出 * 可观察性->模式； ADR/RFC -> 领域和上下文；部门扫描 -> 安全；调试工具->调试 * 虚拟环境 -> 从结构中排除，在 Env 中注明 ### 3\.提取命令从构建配置脚本、任务运行程序（“Makefile”、“Justfile”、“Taskfile.yml”）或工具约定中查找确切的命令。包括发布/发布、文档、部署/IaC、调试/REPL、codegen 命令（如果脚本存在）。反映来自 CI 或构建配置的固定工具版本。验证配置文件中是否存在命令 - 在分析期间不要执行任何命令（甚至只读命令）。 **工作目录：** 对于必须从子目录运行的命令（例如，特定包中的迁移），请在命令代码块中添加前缀“cd &&”，以便可以从存储库根目录复制粘贴该命令。 **恢复步骤：** 对于每个命令，确定 ON FAIL 恢复操作。来源：配套 `:fix` 脚本（例如，`lint` -> `lint:fix`）、缓存清除命令（例如，`rm -rf node_modules`）、单文件重新运行变体（例如，`vitest run `）或诊断步骤（例如，“检查输出是否存在类型错误”）。如果该工具有众所周知的修复命令，请使用它。如果不是，请指定诊断操作。 ### 4\.检测架构模式 **范围：** 仅检查步骤 1 中检测到的生态系统。 **方法：** 1. 使用 `references/framework-patterns.md` 中的清单从入口点或依赖项识别主要框架。 2. 该框架的已知约定指标的 Grep 源文件（请参阅框架模式参考）。 3. 扫描未绑定到特定框架的横切模式（请参阅框架模式参考，“横切”表）：错误处理、日志记录、配置加载、导入约定。 **在 monorepos 中：** 显式检测跨包导入约定（例如，像“@org/pkg”这样的作用域包名称与相对路径）。在模式中将所需的导入方法记录为指令：“始终通过`@scope/package-name`导入。切勿跨包边界使用相对路径。” 4. **检测代码约定** — 这些是可检测时的强制模式子项： * **模块系统：** Grep for `import`/`export` (ESM) 与 `require`/`module.exports` (CJS)。检查“package.json”、“tsconfig.json”模块设置中的“type”或等效语言指示符。如果混合，请说明新代码使用哪个。 * **异步模式：** Grep for `async`/`await`、`.then(`、回调签名。说明主要模式。如果混合，请说明用于新代码的模式。 * **命名约定：** 大小写模式的 10-20 个源文件名示例（kebab-case、camelCase、PascalCase、snake_case）。检查同一示例中的组件/类/函数命名。仅记录在 > 80% 的样本中保持一致的约定。 5. 阅读最多 3 个表现出检测到的模式的代表性文件，以确认并记录细节。 **仅记录有具体证据的模式。** 通常为 4-8 项（上限为 12 项）。如果一个类别显示两种共存模式（例如，较旧模块中的回调，较新模块中的异步/等待），**说明新代码使用哪一个**并将另一个标记为遗留模式。使用指令框架：“使用 X 作为新代码。Y 存在于旧模块中——除非请求，否则不要转换。”不要仅仅描述两者——代理需要知道该写什么。每个类别上限为 2 个；如果>2，请记下主要的并添加“<！--回顾：[类别]中的混合约定-->”。 **工具首选项**是特定于代理平台的。根据目标代理（Claude Code：更喜欢 Read/Edit/Glob/Grep 而不是 shell）和来自 CRITICAL 的项目命令进行填充。检查 README/CONTRIBUTING.md 以了解项目特定的首选项。 ## AGENTS.md 模板生成这个精确的结构。语言简洁，散文最少。 **省略没有具体数据的部分。** 去除模板/占位符 HTML 注释。 **在输出中保留**这些注释类型：``、``、``、``、``（如果用户添加）。 `agents-md-version` 跟踪输出模式 - 仅在添加、删除或重组部分时才进行碰撞（不适用于内容更改）。当前架构：**1**。有关变更日志，请参阅“references/schema-changelog.md”。 **处理较旧的架构版本：** 当现有 AGENTS.md 具有较旧的“agents-md-version”时，请照常应用自动检测/策划/混合更新策略。添加当前架构版本中引入的任何新部分。删除版本之间不推荐使用的部分。将版本标记更改为当前版本。 **版本标签：** 使用 `` 作为强制模式版本标签。可以选择存在单独的“”日期标签（用户添加，用于跟踪上次重新生成）——如果找到则保留它，但不生成它。 **行预算：** 单包存储库低于 150 行，单一存储库低于 200 行，复杂多堆栈单一存储库最多 250 行。当超出预算时，应用分析阶段的分类顺序。有关具体的 Next.js + Prisma 示例，请参阅“references/example-output.md”。 # 代理.md ## 关键 - 必须：[包管理器命令] - 必须：[lint 命令] 提交之前 - 必须：PR 之前的 [测试命令] - 必须：使用“[依赖命令]”更改依赖项（不要手动编辑配置） - 绝不：[禁止的工具/模式] - 从不：强制推送（`git push --force`、`git push -f`）到共享分支 - 从不：跳过预提交挂钩（--no-verify） - 从不：编辑“[path]”中生成的文件 - 首选：内置工具（文件读取器、编辑器、glob、grep）优于 shell 等效工具（`cat`、`sed`、`find`、`grep`） - ON FAIL：重试之前读取完整的错误输出。检查 Env 是否缺少 deps。 - 失败 (lint)：如果自动修复可用：运行“[lint:fix command]”，然后重新运行“[lint command]”。手动修复剩余错误。 - ON FAIL（测试）：首先运行单个测试文件：`[单个测试命令]` - 失败（monorepo）：使用“pwd”验证工作目录 ## 领域和上下文 - 目标：[1 句话项目目的] - 类型：[图书馆|应用 | CLI/工具 |两者] - 许可证：[SPDX 标识符] - 关键术语： - `[术语]`：[定义] - 决定：“[ADR/RFC 目录的路径]” ## 数据和状态 - 事实来源：“[模式文件的路径]” - 数据库：[引擎] - ORM/驱动程序：[名称] - 迁移：`[path]`（命令部分中的命令） - 播种：“[命令的路径或引用]” - API 架构：`[路径]`（[OpenAPI | GraphQL | Protobuf]） - Codegen: `[command]` -> `[output path]` （生成 - 请勿编辑） - 经纪人：[类型] ## 执行上下文 - 运行于：[主机|码头工人 |开发容器 |尼克斯 |混合动力|无服务器] - 前缀：[例如，“docker compose exec app”或“N/A”] - 部署到：[目标] - 子模块：[路径] ## 单一仓库 - 经理：[工具] - Root：[影响所有包的命令] - 范围：`[过滤器语法]` - 套餐：[图案] - 部门：[根级别 |包级 |两者] |类型 |路径|堆栈| |------|------|--------| | [类别] | `[路径]` | [运行时/工具] | **表压缩：** 当多个包共享相同的类型和堆栈时，使用大括号扩展将它们分组在一行中（例如，`packages/{auth,billing,users}`）。仅当堆栈有意义时才使用单独的行。目标是 12 行以下。每个包都必须出现在表中 - 根据工作区列表验证完全覆盖。 ## 命令 ````bash # 安装 [确切命令] # ON FAIL: [恢复步骤] # 测试：单元 [确切命令] # ON FAIL: [恢复步骤] # 棉绒 [确切命令] # ON FAIL: [恢复步骤] # [其他检测到的类别...] [确切命令] # ON FAIL: [恢复步骤] ```` **ON FAIL 注释：** 每个命令都必须包含内联“# ON FAIL: ...”注释以及具体的恢复步骤。使用命令的实际修复/重试机制（例如，“# ON FAIL: rm -rf node_modules && pnpm install”）。如果不存在编程恢复，请说明诊断步骤（例如“# ON FAIL：检查输出是否存在类型错误”）。仅对于失败不言自明的命令（例如“dev”服务器启动）省略 ON FAIL。 ## 结构 ```` [dir]/#[2-4字目的] [dir]/#[2-4字目的]（生成——不要编辑） ```` ## 模式 - **模块：** [ESM | CJS |双] - **异步：** [异步/等待|回调 |承诺|混合（使用 X 表示新代码）] - **命名：** [文件命名约定] 文件、[ComponentCase] 组件、[functionCase] 函数 - [框架/架构模式]：[适用的地方] ## 搜索 - 语义：`[工具] [索引]“[查询]”` - 概念查询。确切地说：`[grep tool] "[pattern]" [path]` -- regex 。文件：`[全局模式]` ## 测试策略 - 跑步者：[工具] - 装置：`[路径]`[和/或工厂库] - 分离：[方法] - 覆盖范围：[阈值或“无阈值”] - E2E：[工具] - 约定：[主要约定] ## 安全 - 切勿读/写：[路径] - 切勿记录/提交：[模式] - 秘密来自：[机制] - CI 秘密：[机制，例如“GitHub Actions 秘密”、“Vault”] - 部门扫描：`[命令]` ## 环境 - [运行时]: [版本或版本文件] ````bash # 必需的变量 [VAR]=[描述] # 特定于环境的配置 [开发/登台/产品差异化的路径或机制] # 本地设置 [命令] ```` ## 调试 - 日志：[如何在本地访问应用程序日志] - REPL：`[命令]` - 调试器：[启动配置或附加指令] ## git - 分支：`[模式]` - 提交：`[格式]` - 挂钩：[描述] - 公关：[要求] - 审查：[约定，例如“数据库迁移需要 DBA 审查”] - PR 模板：`[路径]` - 代码所有者：`[路径]` ## CI - 运行：[工作] - 所需检查：[列表] - 文物：[地点] ## 工具首选项 |任务|更喜欢 |避免 | |------|--------|--------| | [任务] | [首选工具] | [避免替代方案] | ## 何时重新运行在以下情况下重新生成：切换包管理器、更改 test/lint 框架、添加 monorepo 包、添加主要依赖项（ORM、框架、代理）、CI 重组或目录布局重组。不适用于常规代码更改或较小的依赖项更新。 ## 用户评论场景 |向用户显示|行动 ---|---|--- **新** |摘要：章节名称 + 各 1 行概要 |写作前询问确认。根据要求显示完整草稿。 **更新（完整）** |更改/添加/删除部分作为差异；列表仅按名称不变 |询问确认。 **更新（有针对性）** |仅将请求的部分作为 diff |询问确认。 **拒绝** |不适用 |询问哪些部分需要更改，仅重新分析那些部分，然后重新呈现。除非要求，否则跳过完整的重新分析。 **无人值守** |什么都没有|跳过审核；直接写。仅当用户明确请求时。批准后才可写入文件。 ## 执行批准后，编写“AGENTS.md”并在同一目录中创建或更新“CLAUDE.md”。 **CLAUDE.md 合并策略：** * **不存在** -> 使用 `@AGENTS.md` 导入创建。 * **已经导入`@AGENTS.md`** -> 保留所有内容，更新标题注释。 * **有内容但没有导入** -> 读取现有内容；扫描与 AGENTS.md 重叠的部分标题（`## CRITICAL`、`## Commands` 等）。如果发现重叠，则使用特定部分名称警告用户，并询问是否保留（作为覆盖）、合并或删除重复项。然后添加`@AGENTS.md`导入。始终保留额外的“@”导入。 **CLAUDE.md 内容** — 始终包含生成的标头 ``加上导入：场景 |克劳德.md 导入 ---|--- 独立仓库 | `@AGENTS.md` Monorepo 子项目（祖先有 CLAUDE.md/AGENTS.md） | `@AGENTS.md` \+ `@/CLAUDE.md` （走到 `.git` 根目录以查找祖先；计算相对路径）每个包拆分（根 >250 行，不同的堆栈）| `@AGENTS.md` \+ `@<相对路径>/AGENTS.md` （本地和根） **按包拆分规则：** 根 `AGENTS.md` 包含共享部分（CRITICAL、Monorepo、Git、CI、工具首选项）。包“AGENTS.md”包含特定于包的部分（命令、结构、模式、测试、环境、数据和状态）。包部分覆盖根； CRITICAL 是 **附加**（矛盾：包获胜，添加 ``）。仅当单个文件未达到行预算时才进行拆分。 **重新运行范围：** 从存储库根目录 -> 仅根目录（警告过时的每个包文件；列出可能需要重新运行的包）。仅从包目录 -> 该包。切勿在 CWD 之外默默更新文件。 **部分失败：**如果AGENTS.md已写入，但CLAUDE.md写入失败，则通知用户AGENTS.md已写入成功，CLAUDE.md需要手动创建。不要回滚 AGENTS.md。如果 AGENTS.md 写入本身失败，请不要继续执行 CLAUDE.md。 ### 其他代理上下文文件仅根据用户请求，生成等效文件：“.cursorrules”/“.windsurfrules”（内联内容）、“GEMINI.md”/“CODEX.md”/“.github/copilot-instructions.md”（复制内容）。所有都包含同步标头 `` （如果不是 git repo，请使用 ``）。 AGENTS.md 是事实来源——更新时重新生成派生文件。没有符号链接。 **特定于代理的调整：** 为非 Claude 代理生成时，请根据该代理的功能调整工具首选项（例如，光标使用终端命令；Copilot 使用内联建议）。将 Claude 特定的工具名称（Read/Edit/Glob/Grep）替换为通用等效项或该代理的工具名称。 ## 验证写入后验证： **结构检查（1-10）：** 1. **命令存在** — grep 构建配置中每个命令的二进制/脚本名称以确认可追溯性 2. **结构匹配** — glob 每个列出的目录以确认其存在于磁盘上 3. **无占位符** — 不保留 `[value]` 括号 4. **没有过时的注释** - 不保留任何 HTML 注释，除了： ``、``、``、`` 和 `` 5. **行数** — 在预算范围内 (150 / 200 / 250) 6. **CLAUDE.md 有效** — `@` 导入路径解析（glob 目标文件） 7. **生成的目录标记** - 所有代码生成/构建输出目录在结构中注释 8. **关键完整性** — 至少必须对以下各项进行规则：包管理器、linting、测试。警告用户如有遗漏 9. **命令最小集** — `install`、`lint` 和至少一个 `test` 命令存在。丢失时发出警告 10. **约束一致性** — 每一个 NEVER in CRITICAL 都跟踪到步骤 1 中的检测（例如，从不 `pip` 因为检测到 `uv.lock`）。用 `` 标记孤立的 NEVER **质量检查（11-15）：** 11\。 **特异性 lint** — 扫描 CRITICAL 和模式以查找没有相邻具体示例的模糊指令。标记诸如“遵循约定”、“使用标准”、“酌情”、“参见文档”、“必要时”等短语。每个指令必须包含命令、路径或文字示例。添加 `` 到模糊条目 12\。 **故障恢复覆盖率** — 命令代码块中的每个命令（除了 `dev`/server-start 命令）都有一个 `# ON FAIL:` 注释。缺少恢复注释：添加 `` 13\。 **领域术语覆盖率** — 如果领域和上下文有关键术语列表，请验证每个术语至少出现在其他部分（结构、模式、命令或数据和状态）中。文件中其他地方没有出现的孤立术语：删除或添加 `` 14\. **最低约定** — 如果模式部分存在并且项目有源代码，请验证它包括模块、异步和命名子项（或适合检测到的堆栈的子集）。检测到的堆栈缺少约定：添加 `` 15\ 的 [约定类型]。 **没有孤立的 REVIEW 注释** - 验证在验证过程中添加的每个“”都有清晰的、可操作的描述。删除验证期间解决的所有问题。 **失败时：**修复并重新验证。如果修复需要重新分析，请删除无效条目。切勿写入未通过验证的文件 - 向用户报告无法解决的失败。 ## 质量门验证后进行两阶段审查。目标：质量栏（分数 >= 4.5，无 P1 结果）。 ### 第一阶段：自我批评使用 [references/agents-md-rubric.md]() 对生成的 AGENTS.md 进行评分。阅读该文件就像第一次遇到该项目一样。 **检查：** 1. **不明确的关键规则** - 代理可能合理误解的任何“必须/绝不”的规则。测试：两个有能力的开发人员能否在这条规则的要求上存在分歧？如果是，请说得更具体一些。 2. **横截面矛盾** — CRITICAL 中引用的命令，但 Commands 中不存在；环境中未提及的命令中的工具；结构中的路径与其他部分中的路径不匹配。 3. **缺少危险防护** - 对于步骤 1 中检测到的每个有风险的工具（数据库、IaC、部署、包发布），验证 CRITICAL 或 Security 包含相应的防护措施。示例：检测到数据库但没有迁移安全规则；检测到部署工具，但没有“从不从本地部署”规则；检测到发布配置，但没有“在没有 CI 的情况下绝不发布”规则。 4. **无法解析的引用** — 使用的术语没有定义、引用外部文档的路径没有总结相关内容、没有版本或安装上下文的工具名称。 **行动：** * 无需重新分析即可修复（措辞澄清、添加缺失的交叉引用、收紧模糊规则）-> 修复内联。 * 需要重新分析或用户输入 -> 添加 `` 并继续。 * 如果分数 < 4.5 或 P1 结果仍然存在，请修复 P1/P2 差距并重新运行验证检查，然后再继续。 ### 第 2 阶段：新环境子代理审查使用 [references/review-prompt.md]() 运行 **新鲜上下文评论家** 传递： * 如果您的环境支持子代理，则**生成一个带有审阅提示的新上下文子代理**。否则，直接按照提示进行审核。 * 应用 **P1 + P2** 修复（P3 最后）。 * 重新运行验证检查。 * 最多重复 **3 个循环**，达到质量标准后尽早停止。 * 如果通过了 3 个循环但未达到标准：使用补丁文本向用户报告剩余的 P1/P2 结果，并询问是否应用修复或接受原样。 ## 输出规则 1. **最少的散文** — 优先使用项目符号/表格；没有占位符（解析或省略部分）；无示例（仅实际值） 2. **线路预算** — 首先省略优先级最低的部分（参见分类顺序）；仅 ASCII（无表情符号） 3. **安全** — 适用安全/约束规则（无秘密、无网络、无破坏性命令） 4. **幂等性** — 未更改项目的相同输出（无时间戳、随机值）；确定性字母顺序 5. **工具优先** — 使用内置文件读取器、glob 和 grep 工具作为 PRIMARY 方法； Bash 命令是 FALLBACKS — 仅当代理缺少内置等效命令时使用 6. **弹性** — 跳过不可读的配置（包括拒绝权限的错误）、空的 glob、二进制文件和没有具体数据的部分 — 切勿伪造值。如果分析不完整，请添加 `` 作为 AGENTS.md 的第一行

写作代理医学博士

包含技能