智能体文档

agents-md
分类数据
作者Agentic Awesome Skills 社区
许可MIT
评分4.80/5
使用7.6K

维护 AGENTS.md

AGENTS.md 是面向 agent 的权威文档。请保持极简——agent 具备足够能力，不需要冗长的引导。目标长度在 60 行以内，绝不超过 100 行。文档越长，指令遵循质量越低。

使用场景

  • 用户要求创建、更新或审计 AGENTS.md 或 CLAUDE.md。
  • 项目需要基于实际工具链和仓库布局的精简、高信号 agent 指令。
  • 现有的 agent 文档过长、重复或与实际项目规范脱节。

文件设置

1. 在项目根目录创建 AGENTS.md
2. 创建符号链接：ln -s AGENTS.md CLAUDE.md

编写前准备

分析项目以确定应包含的内容：

1. 包管理器 — 检查锁文件（pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock）
2. Linter/格式化配置 — 查找 .eslintrc, biome.json, ruff.toml, .prettierrc 等（不要在 AGENTS.md 中重复这些内容）
3. CI/构建命令 — 检查 Makefile, package.json 脚本, CI 配置以获取权威命令
4. Monorepo 标识 — 检查 pnpm-workspace.yaml, nx.json, Cargo workspace 或子目录中的 package.json 文件
5. 现有规范 — 检查现有的 CONTRIBUTING.md, docs/ 或 README 模式

编写规则

  • 标题 + 列表 — 不要写段落
  • 代码块 — 用于命令和模板
  • 引用而非嵌入 — 指向现有文档：例如 “关于设置请参阅 CONTRIBUTING.md” 或 “遵循 src/api/routes/ 中的模式”
  • 拒绝废话 — 不要写前言、结语或客套话
  • 信任能力 — 省略显而易见的上下文
  • 优先使用文件级命令 — 优先使用针对单个文件的测试/lint/类型检查命令，而非项目级构建
  • 不要重复 Linter 规则 — 代码风格应在 Linter 配置中定义，而非 AGENTS.md

必填章节

Package Manager (包管理器)

仅列出工具及关键命令：
markdown
## Package Manager
使用 pnpm: pnpm install, pnpm dev, pnpm test

File-Scoped Commands (文件级命令)

单文件命令比全项目构建更快且成本更低。只要可用就必须包含：
markdown
## File-Scoped Commands
| 任务 | 命令 |
|------|---------|
| 类型检查 | pnpm tsc --noEmit path/to/file.ts |
| Lint | pnpm eslint path/to/file.ts |
| 测试 | pnpm jest path/to/file.test.ts |

Commit Attribution (提交归属)

必须包含此章节。Agent 应使用自己的身份：
markdown
## Commit Attribution
AI 提交必须包含：
Co-Authored-By: (agent 模型名称及归属署名)
code
示例：Co-Authored-By: Claude Sonnet 4 <[email protected]>

Key Conventions (关键规范)

Agent 必须遵循的项目特定模式。保持简练。

可选章节

仅在确实需要时添加：

  • API 路由模式（展示模板，而非解释）

  • CLI 命令（表格形式）

  • 文件命名规范

  • 项目结构提示（指向关键文件，标记需避开的遗留代码）

  • Monorepo 覆盖（子目录中的 AGENTS.md 覆盖根目录配置）

反面模式

避免出现以下内容：

  • “欢迎来到...” 或 “本文档解释了...”

  • “你应该...” 或 “记得...”

  • Linter/格式化详细规则

配置文件中已有的规则（如 .eslintrc, biome.json, ruff.toml）
  • 已安装技能或插件的列表（Agent 会自动发现）

  • 在有文件级替代方案时，避免使用全项目构建命令

  • 显而易见的指令（如“运行测试”、“编写整洁代码”）

  • 冗长的原因解释（直接说明做什么即可）

  • 篇幅过长的段落

结构示例

markdown
# Agent 指令

包管理器

使用 pnpm: pnpm install, pnpm dev

Commit 署名

AI 提交必须包含：
Co-Authored-By: (Agent 模型名称及署名行)
code
## 文件级命令
| 任务 | 命令 |
|------|---------|
| 类型检查 | pnpm tsc --noEmit path/to/file.ts |
| Lint | pnpm eslint path/to/file.ts |
| 测试 | pnpm jest path/to/file.test.ts |

API 路由

[模板代码块]

CLI

| 命令 | 描述 |
|---------|-------------|
| pnpm cli sync | 同步数据 |

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为环境特定验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或验收标准，请停止操作并请求澄清。