Coding Agent ：对比理解 AGENT.md、SPEC.md、SKILL.md

以 Claude Code 为典型 coding agent，统一讲解三类文档的定位、痛点、业界实践与整合之道。

一、三类文件分别在做什么？

快速对比

维度	AGENT.md / CLAUDE.md	SPEC.md / spec.md	SKILL.md
角色	项目级「写给 AI 的 README」	功能/迭代级「可执行规范」	可插拔的「技能包」
生命周期	长期稳定，随项目演进	每个功能/迭代一份	按需激活，持久存在
作用域	整个仓库 / 子目录	单个功能或任务	单个工作流或能力
核心问题	我们怎么干活？	这次要干什么？什么算完成？	具体怎么做这一步？
加载时机	每次对话自动加载	任务启动时读取	匹配到场景时按需加载

1. AGENT.md / CLAUDE.md —— 给「代理人格」和「项目」定规矩

「把它当成给 AI coding agents 的 README」—— 是专门写给智能体看的项目说明书，而不是写给人的 README。

以 Claude Code 为例，其官方使用 CLAUDE.md。AGENTS.md 是一个更通用的开放规范，两者本质作用类似。

典型内容

AGENT.md 内容结构
** 项目/仓库级信息**
依赖安装: pnpm install
构建命令: npm run build
测试命令: pytest, pnpm typecheck
** 代码风格/规范**
单引号 vs 双引号
类型注解要求
Linter / Formatter 选型
** 工作流与约定**
分支命名、Commit / PR 格式
是否先写测试再写实现
** 特殊注意事项**
常见坑、脚本套路
安全/隐私约束

核心意义

对 AI：稳定、可缓存的「行为准则 + 项目简介」，可被多种工具一致读取（Claude Code、Copilot、Cursor、Gemini CLI 等都支持 AGENTS.md）
对团队：把「平时口头说的套路」固化为 repo 内的真实文档，开发者和 agent 共用同一套规则

类比理解

README.md：写给人看的「项目介绍」
AGENT.md / CLAUDE.md：写给所有 AI 代理看的「工作手册」

2. SPEC.md / spec.md —— 用「规范」驱动 AI 写代码

以 GitHub Spec Kit、OpenSpec 等为代表的 SDD (Spec-Driven Development, 规范驱动开发)，把项目上下文和规格视为一等公民。Spec 相当于 AI 理解仓库的长期记忆，是代码之外的业务规则、约束与边界，不让 AI 乱跑偏。

核心思路：「先明确提案、拆解规范（Spec）→ 然后再让 Agent 按规格实现」，而不是一上来就盲目 vibe coding。

典型 Spec 模板

# Feature: 聊天功能

## 用户故事（User Stories）
- 作为一个用户，我希望能实时发送消息...

## 验收场景（Given / When / Then）
- Given: 用户已登录
- When: 用户发送一条消息
- Then: 消息出现在聊天窗口中

## 功能需求（Functional Requirements）
- FR-001: 消息发送延迟 < 200ms
- FR-002: 支持文字、图片、视频三种消息类型

## 关键领域实体（Key Entities）
- Message, ChatRoom, User

## 成功标准（Success Criteria）
- 消息到达率 > 99.9%

## [NEEDS CLARIFICATION: 离线消息的同步策略？]

Spec Kit 工作流

graph LR
    A["/speckit.specify"] -->|产出| B("specs/xxx/spec.md")
    B -->|/speckit.plan| C("plan.md")
    C -->|/speckit.tasks| D("tasks.md")
    D -->|逐项执行| E("代码实现")

核心意义

把 AI 从「一次性生成代码」提升为「围绕规范持续迭代的执行器」
规范是「单一事实来源」，代码是规范的投影；修改需求时改 spec 再重生成，而不是到处补丁
产品、架构、开发谈的是同一份 spec.md

一句话区分：AGENT.md 规定「怎么干活」；SPEC.md 规定「要干什么」和「什么算干成」。

3. SKILL.md —— 给 Agent「外挂新技能」

Claude 的 Agent Skills 是一个较新且重要的概念：

「Skill 是一个文件夹，里面有一个 SKILL.md，再加一些脚本/参考文档，用来教 agent 做一件非常具体的事情。」

示例结构

.claude/skills/
├── commit-helper/
│   ├── SKILL.md          # 如何生成符合团队规范的 commit message
│   └── scripts/
│       └── validate.sh
├── pdf-processing/
│   ├── SKILL.md          # 何时、如何解析 PDF
│   ├── scripts/
│   │   └── parse_pdf.py
│   └── forms.md          # 固定表单模板
└── pr-review/
    ├── SKILL.md          # 按团队 checklist 做 PR 审查
    └── reference.md

SKILL.md 结构

---
name: commit-helper           # 技能标识（小写 + 连字符）
description: >-               # 精确描述何时应该用这个技能
  Generate commit messages following team conventions
  when the user commits code changes.
allowed-tools: [bash, write]   # 可选
model: claude-sonnet           # 可选
context: fork                  # 可选：子 agent
---

## 何时使用
当用户完成代码修改并需要提交时触发。

## 工作流
1. 读取 git diff
2. 按团队模板生成 commit message
3. 引用 reference.md 中的示例...

生命周期

graph LR
    A["启动<br/>(读取 name & description)"] --> B["发生请求"]
    B --> C{"匹配 (是/否)"}
    C -- 是 --> D["拉取完整 SKILL.md"]
    D --> E["执行脚本 & 工作流"]
    E --> F["完成"]
    C -- 否 --> G["跳过"]

核心意义

按需挂载专业能力：复杂 PDF/Excel 处理、特定 API 调用、安全审计流程等
渐进披露：不是一上来把所有文档塞进上下文，而是先告诉 Agent「有这个技能」，需要时再读
跨环境复用：在 Claude Code、Claude Web、Agent SDK 等多形态统一支持

对比 AGENT.md

AGENT.md：一份项目范围的「常驻规则」
SKILL.md：一个「可插拔 workflow / 能力模块」，只在匹配场景下启用

二、相比旧方案，解决了哪些痛点？

「旧方案」= 只用自然语言 prompt + 临时复制粘贴代码/文档

1. AGENT.md 解决的痛点

旧痛点	AGENT.md 带来的改进
每进新对话，重新告诉 AI「我们用 pnpm 不是 npm」	持久规则写在仓库，自动读取，不占用对话 prompt
多工具（Claude/Copilot/Cursor）各有配置方式，规则散落	统一的 `AGENTS.md` 格式被多种 Agent 识别
Monorepo 中不同子项目的规则难以管理	支持分层：根目录全局规则 + 子目录特有规则
新人 / 新 AI 上手需要反复交代	一次编写，长期生效

2. SPEC.md 解决的痛点

旧痛点	SPEC 驱动的改进
「Vibe coding」：一句话生成代码，来回试错	强制把需求/行为/边界写清楚，有模板和 Checklist
需求、设计和代码之间没有稳定映射	Agent 先补全 spec → 生成 plan → 拆分 tasks → 实现
需求变更时只改代码不改文档	规范是「单一事实来源」，改需求先改 spec
PRD、设计文档逐渐失效	spec.md 是可执行的、活的文档

关键范式转变：把「写代码」降级成「按规范执行的最后一步」，核心资产变成一系列 markdown 规范。

3. SKILL.md 解决的痛点

旧痛点	SKILL.md 带来的改进
复杂流程只能写到 system prompt 或长 prompt，每次都要塞	打包为 Skill 文件夹，按需加载
工具 vs Prompt 完全割裂	一个 Skill 内统一：程序性知识 + 可执行脚本 + 参考文档
所有文档常驻上下文，token 浪费	平时只记 name + description，激活时才拉入完整内容
不同环境下的能力难以复用	跨 Claude Code / Web / SDK 统一支持

三、业界主流实践

1. AGENT 层实践

文件位置

~/.claude/CLAUDE.md                   # 全局（用户级）
repo/AGENTS.md                        # 仓库根（项目级）
repo/CLAUDE.md                        # Claude 专用
repo/packages/frontend/AGENTS.md      # 子目录（模块级）

内容风格要点

跨 AI 工具统一：构建/测试命令、代码规范、流程约定
避免过度膨胀：不写太多业务细节，避免「1000 行说明书」
Claude 特有功能：
- 可通过 /init 自动生成
- 多级 CLAUDE.md 自动发现（root + 子目录 + ~/.claude 组合）
- 可在对话中动态更新（「记忆」功能）

2. SPEC 层实践：SDD 与 OpenSpec 工作流

业界目前推崇 SDD (Spec-Driven Development, 规范驱动开发)。不仅是单文件 spec.md，目前更主流的实践（如 OpenSpec）是将复杂需求拆解为结构化的多文档协同模型：

proposal.md 提案：阐述业务需要解决的问题（Why）与核心改动点（What Changes）。
design.md 思路：技术设计思路、上下文（Context）、权衡决策（Decisions）与潜在风险（Risks）。
task.md 任务：针对前两项的具体实现蓝图（Infrastructure、Core Services、API 等维度的 Todo List）。
spec.md 规范：定义具体的业务逻辑判断条件、场景与边界，供 AI 按规矩实现。

案例演练：某核心业务“赚钱页补签机制”的 SDD 拆解

以开发一个复杂的“补签功能”为例，规范文档在 Agent 工程中可以这样组织：

1. proposal.md 提案

Why: 14天连续签到玩法由于某种原因中断，导致完签率下降，补签机制可转化为看广告、消耗金币等其他营收场景。
What Changes: 新增补签入口、三种补签方式（广告、补签卡、邀请）、限制条件（每周期最多2次，仅限补签昨日）。
New Capabilities: checkin-makeup, makeup-ad-task, makeup-card, makeup-invite.

2. design.md 思路

Context: 现有 14 天签到流程由老业务服务驱动保障。
Decisions: 补签状态独立存储、新增独立服务编排补签事件触发、奖励通过 Kconf 下发配置。
Risks: 超大并发下的数据一致性（需加用户级分布式锁）、跨服务状态延迟（需幂等校验）。

3. task.md 具体的改动点

基础设施：新增补签记录数据表、Kconf 配置下发通道。
核心服务：实现资格判断逻辑、补签次数原子累加校验、主活动连续天数恢复。
API 层：广告回调接口及对冲异常重试防刷机制。

4. specs/checkin-makeup/spec.md 规范 定义了补签资格和状态检查的具体业务 Requirement（前提、容错边界）与场景测试用例（Given/When/Then）。

3. SKILL 层实践

典型使用场景

🔧 生成团队风格的 PR / Commit
🔐 公司规范的安全审计流程
📡 API 文档阅读 + Client 生成
📄 大型 PDF / 文档解析
⚙️ 需要运行脚本的复合任务

组织方式

~/.claude/skills/                    # 全局技能
<repo>/.claude/skills/               # 项目技能
packages/frontend/.claude/skills/    # 子目录技能

写法要点

description 一定要精确清晰，便于自动触发匹配
SKILL.md 尽量控制在 500 行以内，额外材料放在 reference.md 等文件
多用脚本执行，少把代码直接塞进正文（节省上下文）

四、三者能否整合？如何整合？

1. 概念上的分层关系

graph TD
    A["长期约束: AGENT.md<br/>(我们要怎么干活)"] -- 遵守 --> B["本次目标: SPEC.md<br/>(这次要干什么)"]
    B -- 调用 --> C["战术模块: SKILL.md<br/>(用什么快捷套路做)"]

一句话：AGENT = 长期约束，SPEC = 本次任务的目标，SKILL = 实现目标的战术模块。

2. 整合原则

❌ 不推荐

做法	问题
三者全塞进一个超大 AGENT.md	上下文臃肿、可维护性差、Skill 无法按需加载
把 SPEC 内容写在 AGENT 里	规范是迭代级，Agent 规则是项目级，混在一起易混乱
物理文件合并	破坏各自的生命周期和加载机制

✅ 推荐：逻辑协同，物理分离

① 在 AGENT.md 中引用 SPEC 流程：

## 开发规范
我们采用 Spec-Driven Development —— 所有新功能必须先有 `specs/xxx/spec.md`。
Agent 在实现任务前，要先查找/生成对应 spec，并遵循其中的约束。

② 在 SPEC 里引用 Skills：

## 实现指引
- 生成架构可使用 `arch-design` skill
- 生成 API 文档使用 `openapi-doc` skill

③ 在 SKILL.md 里遵守 AGENT 规则：

## 前置条件
执行脚本前，一定先跑 `pnpm test`，详见 AGENT.md 的 Testing 部分。

3. 三层协同实例

以 Claude Code + Spec Kit 为例：

用户: 用 Spec Kit 帮我为新聊天功能建立 spec，并按照项目规则开发

Agent 的理想行为：

读取 AGENTS.md (得知项目使用 Spec-Driven 与 pnpm 规范)
调用 /speckit.specify 产出 specs/chat/spec.md
依据 spec 准备进入开发步骤
自动发现相关 Skill（例如 skills/api-client/ 和 skills/test-generator/）
在开发各环节中，始终遵循 AGENTS.md 定义的代码格式和测试流程。

五、2025–2026 推荐实践

1. 搭好「三层文档骨架」

repo/
├── AGENTS.md                    # 项目级 agent 说明书
│
├── specs/                       # 功能级规范
│   └── 000-chat-feature/
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
│
└── .claude/
    └── skills/                  # 可插拔技能
        ├── pdf-processing/
        │   ├── SKILL.md
        │   └── scripts/...
        └── pr-review/
            ├── SKILL.md
            └── reference.md

2. 配好 CLAUDE.md

记录以下关键信息，保持精炼：

✅ 依赖安装命令
✅ 测试命令
✅ 代码风格
✅ 目录结构说明
✅ 禁止修改的文件夹
✅ 可被其他 agent（Copilot、Cursor）通过 AGENTS.md 复用

3. 准备常用 Skills

至少准备 2–3 个提升效率明显的技能：

技能	用途
`commit-helper`	生成团队标准 commit message
`pr-review`	按团队 checklist 做 PR 审查
`pdf-processing`	业务中大量使用 PDF/Excel 时
`api-client`	按内部 HTTP 规范生成 client

4. 从「直接写代码」转向「Spec-First」

graph LR
    A["需求描述"] --> B["生成 spec.md"]
    B --> C["人工确认无误<br/>(解决 NEEDS CLARIFICATION)"]
    C --> D["生成方案 plan / tasks"]
    D --> E["AI 逐项实现"]
    E --> F["测试校验"]

重点：如果在实现过程中发现某些具体实现步骤是重复套路，及时把它抽出来写成一个 SKILL.md。

5. 跨工具统一

如果团队中使用多种 AI 工具：

工具	配置方式
Claude Code	`CLAUDE.md` + `.claude/skills/`
VS Code + Copilot	读取 `AGENTS.md`
Cursor	读取 `AGENTS.md`
Gemini CLI	读取 `AGENTS.md`

建议在仓库根放通用的 AGENTS.md，只写对所有 agent 都适用的项目规则。Claude Code 用 .claude/skills 做增强，Spec Kit 管功能级规范。

六、简明总结（决策者速览）

三层定位一览

层级	文件	角色	作用
Agent 层	`AGENT.md` / `CLAUDE.md`	项目级「写给 AI 的工作守则」	对齐所有 coding agent 的行为规范，减少重复说明
Spec 层	`SPEC.md` / `spec.md`	功能级「可执行规范/PRD」	用规范而非 prompt 驱动开发，需求即文档
Skill 层	`SKILL.md`	工作流「可插拔技能包」	给 agent 安装能力模块，按需激活不常驻上下文

一、三类文件分别在做什么？#

快速对比#

1. AGENT.md / CLAUDE.md —— 给「代理人格」和「项目」定规矩#

典型内容#

核心意义#

2. SPEC.md / spec.md —— 用「规范」驱动 AI 写代码#

典型 Spec 模板#

Spec Kit 工作流#

核心意义#

3. SKILL.md —— 给 Agent「外挂新技能」#

示例结构#

SKILL.md 结构#

生命周期#

核心意义#

二、相比旧方案，解决了哪些痛点？#

1. AGENT.md 解决的痛点#

2. SPEC.md 解决的痛点#

3. SKILL.md 解决的痛点#

三、业界主流实践#

1. AGENT 层实践#

文件位置#

内容风格要点#

2. SPEC 层实践：SDD 与 OpenSpec 工作流#

案例演练：某核心业务“赚钱页补签机制”的 SDD 拆解#

推荐工作流与工具集成#

3. SKILL 层实践#

典型使用场景#

组织方式#

写法要点#

四、三者能否整合？如何整合？#

1. 概念上的分层关系#

2. 整合原则#

❌ 不推荐#

✅ 推荐：逻辑协同，物理分离#

3. 三层协同实例#

五、2025–2026 推荐实践#

1. 搭好「三层文档骨架」#

2. 配好 CLAUDE.md#

3. 准备常用 Skills#

4. 从「直接写代码」转向「Spec-First」#

5. 跨工具统一#

六、简明总结（决策者速览）#

三层定位一览#

推荐实践总结#

一、三类文件分别在做什么？

快速对比

1. AGENT.md / CLAUDE.md —— 给「代理人格」和「项目」定规矩

典型内容

核心意义

2. SPEC.md / spec.md —— 用「规范」驱动 AI 写代码

典型 Spec 模板

Spec Kit 工作流

核心意义

3. SKILL.md —— 给 Agent「外挂新技能」

示例结构

SKILL.md 结构

生命周期

核心意义

二、相比旧方案，解决了哪些痛点？

1. AGENT.md 解决的痛点

2. SPEC.md 解决的痛点

3. SKILL.md 解决的痛点

三、业界主流实践

1. AGENT 层实践

文件位置

内容风格要点

2. SPEC 层实践：SDD 与 OpenSpec 工作流

案例演练：某核心业务“赚钱页补签机制”的 SDD 拆解

推荐工作流与工具集成

3. SKILL 层实践

典型使用场景

组织方式

写法要点

四、三者能否整合？如何整合？

1. 概念上的分层关系

2. 整合原则

❌ 不推荐

✅ 推荐：逻辑协同，物理分离

3. 三层协同实例

五、2025–2026 推荐实践

1. 搭好「三层文档骨架」

2. 配好 CLAUDE.md

3. 准备常用 Skills

4. 从「直接写代码」转向「Spec-First」

5. 跨工具统一

六、简明总结（决策者速览）

三层定位一览

推荐实践总结