writing-agents-md

编写 AGENTS.md

目标

生成或更新 AI 编码 Agent 的唯一事实来源。同时生成 CLAUDE.md，并在其中导入 @AGENTS.md；其他 Agent 文件按需生成。范围： 当前工作目录（CWD）。所有输出路径均采用 POSIX 风格，并相对于 CWD。

适用情形 / 不适用情形

适用情形：

• 用户要求创建或更新 AGENTS.md、CLAUDE.md 或 Agent 上下文文件（.cursorrules、.windsurfrules、GEMINI.md、CODEX.md、.github/copilot-instructions.md）。
• 用户希望让 AI Agent 熟悉项目。
• 用户要求审查、评分或审计现有的 AGENTS.md —— 此技能是入口（没有单独的 reviewing-agents-md）：运行 references/review-prompt.md 中的只读评审器，以及 references/independent-critic.md 中不依赖评分标准的盲审，报告发现的问题，并且除非用户随后要求修复，否则不要生成、更新或写入任何文件。

不适用情形：

• 单文件脚本、没有构建配置的临时 PoC，或只有 README 的仓库。最低要求：包含至少一条可运行命令的构建配置文件。

路由自测（此请求是否适用？）：

请求	路由
“创建/更新 AGENTS.md、CLAUDE.md 或 Agent 上下文文件”	此处 — 写入模式
“审查 / 评分 / 审计我的 AGENTS.md”	此处 — 只读评审模式（不写入）
“编写或重构技能（SKILL.md）”	writing-skills
“审查 / 评分技能文件夹”	reviewing-skills
“撰写评分标准 / 规范 / 设计文档”	writing-rubrics / writing-specs / writing-designs

质量标准（默认）

目标结果：

• 没有规范违规（格式 / 架构 / 验证检查），且
• 评分 ≥ 4.5/5.0（A 级），且
• 评审中没有 P1 级问题

评分标准：references/agents-md-rubric.md（唯一事实来源）。

安全 / 约束（不可协商）

• 绝不读取、索取或粘贴机密（例如：.env、API 密钥、令牌、私钥、凭据）。
• 除非用户明确要求，否则不要浏览网页或调用外部系统。
• 不要在分析 / 验证过程中运行具有破坏性的命令（数据库重置、部署、发布）。
• 只有在用户明确批准后才能写入文件（参见“用户审阅”部分）。

分析阶段

执行以下步骤以收集事实。不要将分析输出包含在最终文件中。

优先级与分流： 上下文或时间有限时，按以下顺序投入精力。这些 T 级别用于排列章节优先级，与评分标准中对 审查发现 的 P1/P2/P3 排名不同——不要混淆两者。

• T0（必须，绝不省略）： CRITICAL 章节准确性、命令正确性、结构有效性、安全性
• T1（应该）： 领域与上下文、模式、测试策略、环境。如果检测到工作区配置（turbo.json、nx.json、pnpm-workspace.yaml、package.json 中的 workspaces、Cargo.toml 中的 [workspace]、go.work），则将 Monorepo 提升至 T1。
• T2（有则更好）： Monorepo（除非已提升）、CI、工具偏好、搜索、Git、调试

当输出超过行数预算时，按相反的优先级删除章节：先删 T2（调试 -> CI -> Git -> 搜索 -> 工具偏好 -> Monorepo），再删 T1（环境 -> 测试策略 -> 模式 -> 领域与上下文）。绝不删除 T0 章节——行数预算绝不能让安全性或任何安全相关内容被省略。 在同一优先级内，优先保留具体内容较多的章节。

定向更新： 如果用户要求更新特定章节，只运行与这些章节相关的分析步骤。跳过完整的重新分析。仅验证已更改的章节以及 CRITICAL（始终重新验证）。

文件与环境安全： 安全/约束规则仍然适用。此外，分析期间：

• 仅读取环境变量模板：.env.example、.env.template、.env.sample、.env.local.example
• 跳过二进制锁文件（例如 bun.lockb）——可通过 glob 检测其是否存在，但不要读取其内容
• 环境章节中的值：使用描述性占位符（例如 DB_PASSWORD=<from secrets manager>）；绝不要复制 .env.example 或源代码中的实际默认值
• 例外：可使用广为人知的本地开发默认值（localhost、5432、postgres）

简单项目捷径： 仅当以下条件全部满足时适用：（1）只有一个主要构建配置（调用 uv run ... 的 Makefile 等辅助包装器不计入）；（2）只有一个主要源代码目录（测试/脚本/文档不计入）；（3）没有 monorepo 工作区配置。触发时：完整执行步骤 0-3；对于步骤 4，只读取主入口文件。

上下文预算： 如果分析消耗过多上下文（存在许多大型配置文件），停止扩展检测，并根据目前收集的数据继续生成。将 `` 添加到输出中。优先广度（浅层检测所有类别），而非深度（读取某个类别中的每个文件）。

0. 检查现有的 AGENTS.md 和 Agent 上下文文件

如果存在 AGENTS.md，请先阅读。将其视为起点，而非权威依据。核实经过整理的部分：

部分	核实依据
领域与上下文	README、package 描述、源代码
模式	实际目录布局、导入约定、代码风格
测试策略	测试配置文件、测试目录结构
安全	.gitignore、密钥管理器导入、环境变量模式
Git 约定	git log --oneline -20、分支名称（如果不是 git 仓库则跳过）

还要检查是否已存在 Agent 上下文文件（.cursorrules、.windsurfrules、GEMINI.md、CODEX.md、.github/copilot-instructions.md）——如果找到，请告知用户这些文件也可以与 AGENTS.md 一并更新。

部分更新策略：

更新模式	部分	重新运行时的行为
自动检测（始终重新生成）	CRITICAL、Commands、Structure、Env、Execution Context、Data & State、Search、Monorepo、CI、Tool Preferences、Debugging	根据项目文件覆盖
整理维护（有效时保留）	Domain & Context、Security	保留现有内容；仅在可验证地过时时更新（见下文）
混合（检测 + 合并）	Patterns、Testing Strategy、Git	根据检测结果重新生成基础内容，并合并手动补充内容

**过时标准：**当 README 的用途/名称变更、项目类型变更，或关键术语引用了不存在的标识符时，Domain & Context 即为过时。当密钥加载机制变更、.gitignore 模式不一致，或新增环境变量模板中包含未列出的敏感变量时，Security 即为过时。

强制重新核实（逃生机制）：上述狭窄的过时标准可能导致整理维护的内容虽然有误，却未达到这些测试的过时条件，因此每次重新运行都会保留下来（例如，代码中的某个概念改名为另一个仍然存在的标识符）。在用户明确要求重新核实整理维护的部分，或架构版本升级时，应从源文件重新推导 Domain & Context 和 Security，并与保留的副本进行差异比较；将差异呈现给用户确认，而不是默默保留。此路径下不要自动覆盖整理维护的内容——先呈现，再由用户决定。

**过时内容的移除：**对于自动检测的部分，移除对不存在的工具/路径/命令的引用。对于混合模式的部分，使用 `` 标记已移除的项目。

**冲突：**优先采用项目文件；若不确定，添加 ``。

**领域术语提取：**扫描 README（标题、粗体/斜体术语、术语表部分）、入口点中的文档注释，以及配置说明，提取领域专用术语（缩写、业务概念、项目专用行话）。纳入代码标识符中出现、且没有上下文时 Agent 可能会误解的术语（例如，Workspace 指“租户”而非“IDE 工作区”）。省略普遍理解的术语（API、URL、JSON）。如果未发现领域术语，则省略 Key Terms 字段。

**不存在 AGENTS.md：**从项目文件推断所有部分。仅填写有具体证据支持的部分。**最低可用输出：**必须为 T0 部分——CRITICAL、Commands 和 Structure——全部提供具体内容；如果项目涉及任何密钥、部署、发布或迁移操作，还必须包含 Security（这些部分共同构成 Priority & triage 中完整且绝不省略的 T0 集合）。只要能推断出用途/类型，就填写 Domain & Context。如果 Commands 会为空，则不要生成——告知用户项目结构不足。

1. 检测技术栈并识别约束

扫描项目根目录中的配置文件。如果构建配置仅存在于子目录中（例如，backend/pyproject.toml + frontend/package.json），还要向下扫描一层。使用 glob 检测；读取文件以提取详细信息。对于大型文件（>500 行），改为 grep 依赖项部分。

检测目标： 扫描 references/detection-reference.md 中列出的文件，涵盖以下类别：构建与运行时、质量与钩子、基础设施与部署、数据与 API、安全与可观测性、文档与元信息。

消歧规则：

• template.yaml -> 仅当前 20 行包含 AWSTemplateFormatVersion/Transform: AWS::Serverless 时，才视为 SAM
• app.json -> 仅当包含 expo 字段或依赖项中有 react-native 时，才视为移动应用
• package.json 中的 volta -> 固定 Node/npm/yarn 版本
• config.yaml/config.yml -> 如果包含 apiVersion + kind，则视为 Kubernetes 配置；否则视为应用配置
• package.yaml -> 仅当同时存在 *.cabal 或 stack.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	biome	eslint、prettier
依赖项中的 ruff	ruff	flake8、black、isort
Cargo.toml	cargo fmt、cargo clippy	--
go.mod + .golangci.yml	golangci-lint	--
deno.json	deno fmt、deno lint	--
.editorconfig	遵循缩进样式/大小	--
Pre-commit 钩子	--	--no-verify
依赖项中的互斥库	选定的库	被替代的库
pom.xml（无 build.gradle*）	mvn	gradle
build.gradle 或 build.gradle.kts（无 pom.xml）	如果存在 gradlew，则使用 ./gradlew；否则使用 gradle	mvn
project.clj	lein	clj
deps.edn（无 project.clj）	clj	lein
build.sbt	sbt	mill
build.mill	mill	sbt
stack.yaml	stack	cabal
*.cabal + cabal.project（无 stack.yaml）	cabal	stack
.scalafmt.conf	scalafmt	--
.clj-kondo/	clj-kondo	--
checkstyle.xml	checkstyle	--

附加规则：

• 锁文件冲突 -> 检查 CI 以确定使用哪个包管理器；必须使用该包管理器。如果无法确定，则使用 ``。
• 私有注册表 -> 在 Env 中注明 URL（不含凭据）。
• 容器 -> 仅当应用在 Docker 中运行时使用 docker compose run/exec（不适用于仅包含数据库等基础设施的场景）。
• Monorepo -> turbo.json -> turbo run；nx.json -> nx run/nx affected；注明根目录或包的作用范围。
• 多语言项目（无工作区配置） -> 按技术栈标注命令（例如 # install (backend)）。没有编排工具时，不要使用 Monorepo 部分。
• Git 子模块 -> 在 Structure 中注明路径。
• 无法识别的技术栈 -> 阅读 README 和构建配置以查找命令。不要猜测；没有证据的部分应省略。
• 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 管理工具链；使用 stack。

2. 映射入口点与数据

定位主入口点、测试运行器入口和 fixture 位置，以及 CI 配置。

执行上下文： Host（默认 / 仅 Docker 基础设施） | Docker（应用运行于 compose 中） | Devcontainer | Nix | Hybrid | Serverless（Lambda/Cloud Functions 等）

项目类型——分类为：Library（发布脚本，无部署） | Application（部署配置、Dockerfile、入口点） | CLI/Tool（bin/[project.scripts] 条目，无部署） | Both（发布 + 部署）。区分方式：若发布和部署配置都存在，优先归为 Both；不确定时默认归为 Application。

数据、基础设施与生成代码——检测并归类：

• DB/ORM/迁移/消息代理/API 架构 -> Data & State（仅记录路径和元数据；可运行命令放入 Commands，避免重复）
• IaC/K8s/Helm -> Execution Context + Structure；密钥 -> Security；Env 加载与模板 -> Env
• 构建输出目录（dist/、target/、.next/） -> Structure（生成内容）；代码生成目录 -> Structure (generated -- do not edit) + CRITICAL NEVER
• 代码生成工作流（OpenAPI 代码生成、protobuf、GraphQL 代码生成） -> 在 Commands 中注明生成命令，在 Data & State 中记录源架构，在 Structure 中记录输出
• 可观测性 -> Patterns；ADR/RFC -> Domain & Context；依赖扫描 -> Security；调试工具 -> Debugging
• 虚拟环境 -> 从 Structure 中排除，并在 Env 中注明

3. 提取命令

从构建配置脚本、任务运行器（Makefile、Justfile、Taskfile.yml）或工具惯例中查找准确命令。若存在相应脚本，也要包含发布/版本发布、文档、部署/IaC、调试/REPL、代码生成命令。反映 CI 或构建配置中固定的工具版本。确认命令确实存在于配置文件中——分析期间不要执行任何命令（包括只读命令）。工作目录： 对于必须从子目录运行的命令（例如在特定包中运行迁移），在 Commands 代码块中添加 cd <path> && 前缀，使命令可以从仓库根目录复制并运行。

恢复步骤： 对每条命令，确定其失败时的恢复操作。来源包括配套的 :fix 脚本（例如 lint -> lint:fix）、清理缓存命令（例如 rm -rf node_modules）、单文件重跑变体（例如 vitest run <file>）或诊断步骤（例如“检查输出中的类型错误”）。如果工具有常见的修复命令，请使用该命令；否则，注明诊断操作。

4. 检测架构模式

**范围：**仅检查在步骤 1 中检测到的生态系统。

方法：

1. 使用 references/framework-patterns.md 中的检查清单，从入口点或依赖项识别主要框架。
2. 在源文件中搜索该框架已知的惯例指示（参见 framework-patterns 参考文档）。
3. 扫描与特定框架无关的跨领域模式（参见 framework-patterns 参考文档中的 “Cross-cutting” 表）：错误处理、日志记录、配置加载、导入惯例。**在单体仓库中：**明确检测跨包导入惯例（例如，使用 @org/pkg 这样的作用域包名，还是相对路径）。在 Patterns 中将所需的导入方式记录为指令：“始终通过 @scope/package-name 导入。绝不要跨包边界使用相对路径。”
4. 检测代码惯例——可检测时，这些是 Patterns 中必需的子项：
   • **模块系统：**搜索 import/export（ESM）与 require/module.exports（CJS）。检查 package.json 中的 "type"、tsconfig.json 的 module 设置，或语言中等效的指示。如果两者混用，说明新代码应使用哪种。
   • **异步模式：**搜索 async/await、.then(、回调签名。说明主要模式。如果两者混用，说明新代码应使用哪种。
   • **命名惯例：**抽取 10-20 个源文件名，查看大小写模式（kebab-case、camelCase、PascalCase、snake_case）。同时检查同一批样本中的组件/类/函数命名。仅记录在 >80% 的样本中保持一致的惯例。
5. 阅读最多 3 个体现已检测模式的代表性文件，以确认并记录具体细节。

**只记录有具体证据支持的模式。**通常记录 4-8 项（最多 12 项）。如果某个类别中存在两种并行模式（例如，旧模块使用回调，新模块使用 async/await），说明新代码应使用哪一种，并将另一种标为旧式模式。使用指令式表述：“新代码使用 X。旧模块中存在 Y——除非收到要求，否则不要转换。”不要只描述两种模式——Agent 需要知道应写哪种代码。每个类别最多记录 2 项；如果超过 2 项，指出主要模式并添加 ``。

工具偏好因 Agent 平台而异。根据目标 Agent（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。

# AGENTS.md


## CRITICAL

- MUST: [package manager command]
- MUST: [lint command] before commit
- MUST: [test command] before PR
- MUST: Use `[dependency command]` to change deps (DO NOT edit config manually)
- NEVER: [forbidden tool/pattern]
- NEVER: Force push (`git push --force`, `git push -f`) to shared branches
- NEVER: Skip pre-commit hooks (--no-verify)
- NEVER: Commit or read secrets (`.env`, API keys, tokens, private keys)
- NEVER: Edit generated files in `[path]`
- PREFER: Built-in tools (file reader, editor, glob, grep) over shell equivalents (`cat`, `sed`, `find`, `grep`)
- ON FAIL: Read full error output before retry. Check Env for missing deps.
- ON FAIL (lint): If autofix available: run `[lint:fix command]`, then re-run `[lint command]`. Fix remaining errors manually.
- ON FAIL (test): Run single test file first: `[single test command]`
- ON FAIL (monorepo): Verify working directory with `pwd`

## Domain & Context

- Goal: [1 sentence project purpose]
- Type: [Library | Application | CLI/Tool | Both]
- License: [SPDX identifier]
- Key Terms:
  - `[Term]`: [Definition]
- Decisions: `[path to ADR/RFC dir]`

## Data & State

- Source of Truth: `[path to schema file]`
- Database: [engine]
- ORM/Driver: [name]
- Migrations: `[path]` (commands in Commands section)
- Seeding: `[path or reference to Commands]`
- API Schema: `[path]` ([OpenAPI | GraphQL | Protobuf])
- Codegen: `[command]` -> `[output path]` (generated -- do not edit)
- Broker: [type]

## Execution Context

- Run on: [Host | Docker | Devcontainer | Nix | Hybrid | Serverless]
- Prefix: [e.g., "docker compose exec app" or "N/A"]
- Deploys to: [target]
- Submodules: [paths]

## Monorepo

- Manager: [tool]
- Root: [commands that affect all packages]
- Scope: `[filter syntax]`
- Packages: [pattern]
- Deps: [root-level | package-level | both]

| Type | Path | Stack |
|------|------|-------|
| [category] | `[path]` | [runtime/tools] |

**Table compaction:** When multiple packages share the same type and stack, group them in a single row using brace expansion (e.g., `packages/{auth,billing,users}`). Use individual rows only where the stack differs meaningfully. Aim for under 12 rows. Every package must appear in the table — verify full coverage against the workspace listing.

## Commands

```bash
# install
[exact command]                # ON FAIL: [recovery step]
# test:unit
[exact command]                # ON FAIL: [recovery step]
# lint
[exact command]                # ON FAIL: [recovery step]
# [additional detected categories...]
[exact command]                # ON FAIL: [recovery step]
```

**ON FAIL comments:** Every command must include an inline `# ON FAIL: ...` comment with a concrete recovery step. Use the command's actual fix/retry mechanism (e.g., `# ON FAIL: rm -rf node_modules && pnpm install`). If no programmatic recovery exists, state the diagnostic step (e.g., `# ON FAIL: check output for type errors`). Omit ON FAIL only for commands where failure is self-explanatory (e.g., `dev` server start). **Never** use a destructive command (data-dropping reset, force-push, publish) as an `# ON FAIL:` recovery step — if the only recovery is destructive, omit ON FAIL and rely on the named danger guard in CRITICAL/Security instead.

## Structure

```
[dir]/          # [2-4 word purpose]
[dir]/          # [2-4 word purpose] (generated -- do not edit)
```

## Patterns

- **Module:** [ESM | CJS | dual]
- **Async:** [async/await | callbacks | Promises | mixed (use X for new code)]
- **Naming:** [file-naming-convention] files, [ComponentCase] components, [functionCase] functions
- [Framework/architectural pattern]: [where it applies]

## Search

- Semantic: `[tool] [index] "[query]"` -- conceptual queries . Exact: `[grep tool] "[pattern]" [path]` -- regex . Files: `[glob pattern]`

## Testing Strategy

- Runner: [tool]
- Fixtures: `[path]` [and/or factory library]
- Separation: [method]
- Coverage: [threshold or "No threshold"]
- E2E: [tool]
- Conventions: [key conventions]

## Security

- NEVER read/write: [paths]
- NEVER log/commit: [patterns]
- Secrets via: [mechanism]
- CI secrets: [mechanism, e.g., "GitHub Actions secrets", "Vault"]
- Dep scanning: `[command]`

## Env

- [Runtime]: [version or version file]

```bash
# Required vars
[VAR]=[description]
# Env-specific config
[path or mechanism for dev/staging/prod differentiation]
# Local setup
[commands]
```

## Debugging

- Logs: [how to access application logs locally]
- REPL: `[command]`
- Debugger: [launch config or attach instructions]

## Git

- Branch: `[pattern]`
- Commit: `[format]`
- Hooks: [description]
- PR: [requirements]
- Reviews: [conventions, e.g., "DB migrations require DBA review"]
- PR template: `[path]`
- Code owners: `[path]`

## CI

- Runs: [jobs]
- Required checks: [list]
- Artifacts: [location]

## Tool Preferences

| Task | Prefer | Avoid |
|------|--------|-------|
| [task] | [preferred tool] | [avoided alternative] |

何时重新运行

以下情况应重新生成：切换包管理器、更换测试/代码检查框架、添加单体仓库包、添加主要依赖项（ORM、框架、消息代理）、重组 CI，或重新整理目录结构。常规代码更改或次要依赖项更新无需重新生成。

用户审核

场景	向用户展示	操作
新建	摘要：章节名称 + 每节 1 行概要	写入前询问确认。用户要求时展示完整草稿。
更新（完整）	以差异形式展示已更改／新增／删除的章节；仅按名称列出未更改的章节	询问确认。
更新（指定部分）	仅以差异形式展示指定的章节	询问确认。
拒绝	不适用	询问哪些章节需要修改，仅重新分析这些章节，然后重新展示。除非用户要求，否则跳过完整重新分析。
无人值守	不展示任何内容	跳过审核；直接写入。仅在用户明确要求时执行。

仅在获得批准后写入文件。

执行

获得批准后，写入 AGENTS.md，并在同一目录中创建或更新 CLAUDE.md。

CLAUDE.md 合并策略：

• 不存在 -> 创建文件并导入 @AGENTS.md。
• 已导入 @AGENTS.md -> 保留所有内容，更新标题注释。
• 已有内容但未导入 -> 读取现有内容；扫描与 AGENTS.md 重叠的章节标题（例如 ## CRITICAL、## Commands 等）。若发现重叠，向用户说明具体章节名称，并询问是保留（作为覆盖内容）、合并还是删除重复内容。然后在文件开头添加 @AGENTS.md 导入。始终保留其他 @ 导入。

CLAUDE.md 内容 — 始终包含生成的标题 `` 和导入内容：

场景	CLAUDE.md 导入内容
独立仓库	@AGENTS.md
单体仓库子项目（祖先目录中存在 CLAUDE.md/AGENTS.md）	@AGENTS.md + @<relative-path>/CLAUDE.md（向上遍历至 .git 根目录以查找祖先文件；计算相对路径）
按软件包拆分（根文件超过 250 行，且技术栈不同）	@AGENTS.md + @<relative-path>/AGENTS.md（本地和根目录的文件）

按软件包拆分规则： 根目录的 AGENTS.md 存放共享章节（CRITICAL、Monorepo、Git、CI、Tool Preferences）。软件包的 AGENTS.md 存放软件包专属章节（Commands、Structure、Patterns、Testing、Env、Data & State）。软件包章节优先于根目录章节；CRITICAL 为增补式（若有矛盾，以软件包为准，并添加 ``）。仅当单文件无法满足行数限制时才拆分。

重新运行范围： 从仓库根目录运行 -> 仅处理根目录（提醒用户可能存在过时的软件包文件；列出可能需要重新运行的相关软件包）。从软件包目录运行 -> 仅处理该软件包。绝不在未告知的情况下更新 CWD 以外的文件。

部分失败： 如果已写入 AGENTS.md，但写入 CLAUDE.md 失败，告知用户 AGENTS.md 已成功写入，且需要手动创建 CLAUDE.md。不要回滚 AGENTS.md。如果 AGENTS.md 写入失败，则不要继续处理 CLAUDE.md。

其他 Agent 上下文文件

仅在用户要求时，才生成等效文件：.cursorrules/.windsurfrules（内联内容）、GEMINI.md/CODEX.md/.github/copilot-instructions.md（复制内容）。所有文件都包含稳定的同步标头 `` — 不使用 git sha 或时间戳，因此当 AGENTS.md 内容未改变时，派生文件的字节内容保持不变（git-sha 标头会在每次提交时产生差异，破坏幂等性）。AGENTS.md 是事实来源 — 更新时重新生成派生文件。不使用符号链接。

针对特定 Agent 的调整： 为非 Claude Agent 生成文件时，根据该 Agent 的能力调整 Tool Preferences（例如，Cursor 使用终端命令；Copilot 使用内联建议）。将 Claude 专属工具名称（Read/Edit/Glob/Grep）替换为通用名称或该 Agent 的工具名称。

验证

编写后，验证以下内容：

结构检查（1-10）：

1. 命令存在且已定义 — 在构建配置中 grep 每个命令的二进制文件／脚本名称，以确认可追溯性；并确认所指对象确实已定义，而不只是被命名：npm/pnpm 脚本正文非空，Makefile/Justfile/Taskfile 中存在对应目标，或者二进制文件可解析到某个依赖、bin/ 条目或已记录的外部工具。命令若引用的脚本正文为空或缺失，则此项检查失败 — 用 `` 标记。（追踪名称是必要条件，但并非充分条件：请勿执行命令来测试。）
2. 结构匹配 — 对列出的每个目录执行 glob，确认其在磁盘上存在
3. 无占位符 — 不得残留 [value] 方括号
4. 无过时注释 — 不得残留 HTML 注释，以下内容除外：, , , 和 ``
5. 行数 — 不超过预算（150 / 200 / 250）
6. CLAUDE.md 有效 — @ 导入路径可解析（对目标文件执行 glob）
7. 生成目录已标注 — 在 Structure 中标注所有代码生成／构建输出目录
8. 关键完整性 — 至少为以下各项分别设置一条 MUST 规则：包管理器、lint、测试。若有缺项，提醒用户
9. 命令最低要求 — 必须存在 install、lint 和至少一条 test 命令。若有缺项，提醒用户
10. 约束一致性 — CRITICAL 中的每条 NEVER 都必须能追溯到 Step 1 中检测到的内容（例如，检测到 uv.lock 后禁止使用 pip）。使用 `` 标记无对应依据的 NEVER

质量检查（11-16）： 11. 具体性 lint — 检查 CRITICAL 和 Patterns 中是否有缺少相邻具体示例的模糊指令。标记诸如 follow conventions、use standard、as appropriate、see docs、when necessary 等表述。每条指令都必须包含命令、路径或字面示例之一。为模糊条目添加 12. **失败恢复覆盖** — Commands 代码块中的每条命令（`dev`／服务器启动命令除外）都必须有一条 `# ON FAIL:` 注释。缺少恢复注释时，添加 13. 领域术语覆盖 — 如果 Domain & Context 中包含 Key Terms 列表，则验证每个术语至少在其他一个部分（Structure、Patterns、Commands 或 Data & State）中出现。若术语孤立存在、未在文件其他位置出现，则删除该术语或添加 14. **约定最低要求** — 如果存在 Patterns 部分且项目包含源代码，则验证其中包含 Module、Async 和 Naming 子项（或适用于检测到的技术栈的部分子项）。若检测到的技术栈缺少对应约定，则添加 15. 无孤立的 REVIEW 注释 — 验证验证过程中添加的每个 `` 都有明确且可执行的说明。删除验证过程中已解决的问题所对应的注释。 16. 执行安全底线 — 如果 Step 1 检测到任何涉及机密信息、部署、发布或破坏性迁移的内容，则文件必须包含 Security 部分，和／或包含对此进行防护的 CRITICAL 规则。这是硬性结构底线（Priority & triage 中的 T0）：检测到安全相关内容却没有防护措施，绝不可接受，即使超出行数预算也不例外。若缺失：请勿编写文件 — 添加防护措施，或告知用户项目存在未设防的安全相关内容。

**未通过时：**修复并重新验证。如果修复需要重新分析，请删除无效条目。切勿编写未通过验证的文件 — 向用户报告无法解决的问题。

质量门槛

验证后进行两阶段审查。目标：达到 Quality Bar（得分 >= 4.5，且无 P1 级问题）。

阶段 1：自我批评审查

使用 references/agents-md-rubric.md 为生成的 AGENTS.md 评分。假设你是第一次接触该项目，阅读此文件。

检查以下方面：

1. 含糊不清的 CRITICAL 规则 — 任何可能被 Agent 合理误解的 MUST/NEVER 规则。判断标准：两位能力相当的开发者是否可能对规则要求产生分歧？如果可能，请进一步明确。
2. 跨章节矛盾 — CRITICAL 中引用的命令未出现在 Commands 中；Commands 中提到的工具未出现在 Env 中；Structure 中的路径与其他章节中的路径不匹配。
3. 缺少危险操作防护 — 对于步骤 1 中识别出的每种高风险工具（数据库、IaC、部署、包发布），确认 CRITICAL 或 Security 中有对应的防护措施，明确写出具体的破坏性命令并说明禁止执行（像“谨慎处理迁移”这样含糊的句子不符合要求）。例如：检测到 DB 迁移 -> NEVER: 在本地开发环境之外运行 \prisma migrate reset` / `drizzle-kit drop`（会删除数据）；检测到部署工具 -> NEVER: 从本地部署（`vercel --prod`）——只能通过 CI 部署；检测到发布配置 -> NEVER: 在本地运行 `npm publish`——只能通过 CI 标签发布。此外，破坏性命令**绝不能**作为 # ON FAIL:恢复步骤出现（例如，将migrate reset` 作为恢复步骤）；应将其改为有明确警告的受保护命令。
4. 无法解析的引用 — 未定义便使用的术语；引用外部文档中的路径，却未概述相关内容；缺少版本或安装说明的工具名称。

操作：

• 无需重新分析即可修复（澄清措辞、添加缺失的交叉引用、收紧含糊规则）-> 直接修改。
• 需要重新分析或用户输入才能修复 -> 添加 `` 并继续。
• 如果得分 < 4.5 或仍有 P1 级问题，请修复 P1/P2 级缺陷，并在继续前重新运行验证检查。

阶段 2：新上下文批评审查

分两轮进行新上下文批评审查，确保评估结果不仅依赖此技能自身的评分标准（生成器已经针对该标准进行了优化，而使用相同标准的批评者也可能存在相同盲点）：

1. 盲审（不使用评分标准） — 使用 references/independent-critic.md，从第一性原理出发，站在即将实际执行工作的 Agent 角度评估文件。此轮不得看到评分标准或其维度名称；只需思考“遵循此文件的 Agent 可能会遇到哪些问题、受到哪些误导或面临哪些风险？”其目的是发现评分标准未涵盖的风险。
2. 评分标准审查 — 使用 references/review-prompt.md，依据共享的评分标准评分并评级。
3. 协调结果 — 对于盲审发现、但评分标准审查未涵盖的每项风险，都应将其按盲审评定的严重程度加入修复清单（未覆盖的风险表明评分标准存在缺口，并不意味着该风险较轻）。

执行方式：

• 如果环境支持子 Agent，为每轮审查启动一个新上下文子 Agent（盲审子 Agent 的上下文中不得包含评分标准）。否则，直接自行完成两轮审查——但在当前上下文中进行的审查并不独立：请在生成的 AGENTS.md 前添加 ``，并在用户摘要中说明。
• 应用 P1 + P2 级修复，以及所有经协调后升级的盲审风险（P3 最后处理）。
• 重新运行验证检查。
• 最多重复 3 轮，若达到质量门槛则提前停止。
• 如果 3 轮后仍未达到门槛：向用户报告实际评级以及剩余的 P1/P2 级问题，并提供补丁文本，询问用户是应用修复还是按现状接受。绝不能将已按现状接受或低于门槛的文件说成 A 级或“达到门槛”——应如实说明实际评级和未满足的要求。

输出规则

1. 精简文字 — 优先使用项目符号列表和表格；不留占位符（解析或省略整个部分）；不提供示例（仅使用实际值）
2. 行数限制 — 优先省略最低优先级的部分（参见分流顺序）；仅使用 ASCII 字符（不使用表情符号）
3. 安全 — 遵守安全 / 约束规则（不包含密钥、不访问网络、不执行破坏性命令）
4. 幂等性 — 项目未更改时，输出必须一致：不包含时间戳、git SHA 或随机值；各部分按固定模板顺序输出；表格行和 CRITICAL 项目符号列表按确定性顺序排列。`` 按磁盘上缺少证据的类别生成，而非根据某次运行读取了多少内容生成——切勿仅因某次运行的读取预算更紧而添加 GAPS。在内容未更改时重新运行，生成的文件必须逐字节一致。
5. 工具优先级 — 使用内置文件读取、glob 和 grep 工具作为主要方法；Bash 命令作为后备方案——仅当 Agent 不具备相应的内置工具时使用
6. 容错性 — 跳过无法读取的配置（包括因权限不足而无法读取的配置）、空 glob、二进制文件和没有具体数据的部分——绝不编造值。如果分析不完整，将 `` 作为 AGENTS.md 的第一行