规范驱动开发_AI编码 Agent 规范比较研究

规范驱动开发中的 AI 编码代理知识组织与工作流研究：基于 CLAUDE.md、Cursor Rules、AGENTS.md、Kiro Specs 与 GitHub Spec Kit 的比较分析

摘要

随着 AI 编码代理逐渐进入软件工程实践，开发者与团队开始从“临时提示词驱动”转向“规范驱动开发”（Specification-Driven Development, SDD）。在这一转向中，CLAUDE.md、Cursor Rules、AGENTS.md / AGENT.md、Kiro Specs 与 GitHub Spec Kit 等机制分别承担了项目知识持久化、局部规则注入、跨代理协作、需求设计任务分解和规范生命周期管理等职责。本文围绕这些工具与规范文件展开比较研究，提出一个两层分析框架：第一层是“代理长期指令层”，用于帮助 AI 编码代理持续理解项目；第二层是“规范工作流层”，用于将业务需求转化为可审查、可执行、可追踪的开发工件。本文认为，成熟的 AI-native 软件项目不应把所有规则堆叠进单个提示文件，而应采用“AGENTS.md 作为跨工具项目总纲，CLAUDE.md 与 Cursor Rules 作为工具适配与局部规则层，Kiro Specs 或 GitHub Spec Kit 作为功能级规范工作流”的组合架构。

关键词： 规范驱动开发；AI 编码代理；CLAUDE.md；Cursor Rules；AGENTS.md；Kiro Specs；GitHub Spec Kit；软件工程

1. 引言

AI 编码工具的使用方式正在经历明显转变。早期开发者通常依赖一次性提示词，让模型根据当前上下文生成代码。这种方式可以提高短期编码速度，但也带来上下文丢失、需求漂移、架构不一致、测试缺失和团队协作困难等问题。

为缓解这些问题，开发社区逐渐形成两类互补机制：

第一类是代理长期指令文件，例如 CLAUDE.md、Cursor Rules、AGENTS.md 或 AGENT.md。它们的共同目标是为 AI 编码代理提供稳定、可重复读取的项目上下文，包括构建命令、测试命令、代码风格、目录结构、架构原则和安全边界。

第二类是规范工作流系统，例如 Kiro Specs 和 GitHub Spec Kit。它们的目标不是简单告诉代理“怎么写代码”，而是把一个功能请求拆解为需求、设计、任务、验收标准和实现计划，从而将 AI 编码过程纳入更接近传统软件工程的可审查流程。

本文的核心问题是：这些机制在规范驱动开发中分别承担什么角色？如何组合才能形成稳定、可维护、适合团队协作的 AI-native 开发体系？

2. 规范驱动开发的两层结构

本文将相关工具划分为两个层次。

2.1 代理长期指令层

代理长期指令层解决的问题是：AI 编码代理如何持续理解项目？

这类文件通常包含以下内容：

项目简介；
技术栈；
安装、构建、测试、类型检查和 lint 命令；
目录结构说明；
编码风格；
安全规则；
禁止事项；
代码审查与 Definition of Done。

这一层的代表包括：

CLAUDE.md；
Cursor Rules；
AGENTS.md；
AGENT.md。

它们的共同特征是：面向项目长期存在的信息，而不是单个功能需求。

2.2 规范工作流层

规范工作流层解决的问题是：如何把业务意图变成可执行、可验证、可追踪的开发任务？

这类系统通常生成或维护以下工件：

requirements.md；
design.md；
tasks.md；
plan.md；
spec.md；
constitution.md；
checklists；
research.md。

这一层的代表包括：

Kiro Specs；
GitHub Spec Kit。

它们的共同特征是：围绕一个功能、一个变更或一个产品目标展开，强调需求澄清、架构设计、任务拆解、验收标准和实现回写。

规范驱动开发的两层结构：代理长期指令层支撑功能级规范工作流

3. `CLAUDE.md`：Claude Code 的项目记忆机制

CLAUDE.md 是 Claude Code 场景下常用的项目记忆文件。它的主要作用是为 Claude 提供持续可读取的项目上下文，使新的会话不必从零开始理解项目。

一个典型的 CLAUDE.md 可以包含如下内容：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# Project Context## Commands- Install: pnpm install- Dev: pnpm dev- Test: pnpm test- Typecheck: pnpm typecheck## Architecture- Frontend: Next.js App Router- API: Hono- DB: PostgreSQL via Drizzle## Rules- Do not introduce new dependencies without asking.- Always update tests for behavior changes.- Prefer small, composable functions.

CLAUDE.md 的价值在于将重复性项目知识固化下来。例如，每次都要运行哪些命令、哪些目录不能随意改动、数据库迁移必须怎么处理、测试策略是什么等，都适合写入该文件。

但是，CLAUDE.md 并不是强制执行的配置系统。它更接近“上下文提示”而不是“编译器规则”或“CI 约束”。因此，安全要求、测试要求、类型检查要求和格式化要求仍然需要通过 CI、lint、测试框架和代码审查机制来保证。

本文认为，CLAUDE.md 最适合作为 Claude Code 的“项目宪法 + 操作手册”。它适合记录长期有效的项目规则，但不适合承载复杂功能 spec，也不适合堆叠所有团队流程。

4. Cursor Rules：IDE 内的分层规则系统

Cursor Rules 是 Cursor IDE 中的持久规则机制。与 CLAUDE.md 相比，Cursor Rules 更强调作用域控制和局部规则注入。它可以按照目录、文件类型、技术栈或任务场景拆分规则。

典型目录结构如下：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(line.cursor/rules/  frontend.mdc  backend.mdc  database.mdc  testing.mdc  security.mdc

一个面向 React 组件的规则文件可以写成：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line---description: React component conventionsglobs: ["src/components/**/*.tsx"]alwaysApply: false---# React Component Rules- Use function components.- Keep components under 150 lines when reasonable.- Use server components by default.- Client components must start with `"use client"`.

Cursor Rules 的优势在于细粒度。例如，前端组件、API 路由、数据库迁移、测试文件和安全敏感逻辑可以分别拥有不同规则。这样可以避免把所有项目知识塞入一个庞大文件，降低模型上下文噪声。

本文认为，Cursor Rules 不应被当作单一总纲，而应作为局部规则层使用。全局原则应保持简短，具体规则则按照目录和技术栈拆分。

5. `AGENTS.md` 与 `AGENT.md`：跨工具代理说明书

AGENTS.md 可以理解为“给 AI 编码代理看的 README”。它的目标是为不同编码代理提供统一的项目上下文和操作规范。与 CLAUDE.md 偏向 Claude Code、Cursor Rules 偏向 Cursor IDE 不同，AGENTS.md 更强调跨工具兼容。

一个推荐的 AGENTS.md 示例：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# AGENTS.md## ProjectThis is a B2B SaaS dashboard for analytics and billing.## Commands- Install: pnpm install- Dev: pnpm dev- Test: pnpm test- Typecheck: pnpm typecheck- Lint: pnpm lint## Architecture- Frontend: Next.js App Router- API: Hono- Database: PostgreSQL + Drizzle- Auth: Clerk## Non-negotiables- Do not add dependencies without approval.- Do not change database schema without a migration.- All behavior changes require tests.- Never commit secrets or generated credentials.## Definition of Done- Tests pass.- Typecheck passes.- Relevant docs/specs updated.- Edge cases considered.

AGENT.md 则是另一个单数形式的通用代理配置提案。二者内容定位接近，但从生态兼容性看，AGENTS.md 更适合作为当前主文件名。为了兼容可能读取 AGENT.md 的工具，可以建立软链接：

ounter(lineln -s AGENTS.md AGENT.md

本文建议在多代理、多 IDE 或团队协作场景中，将 AGENTS.md 作为项目总纲。其他工具特定文件不应与其冲突，而应引用或补充它。

6. Kiro Specs：IDE 内置的功能级规范工作流

Kiro Specs 是一种面向功能开发的规范工作流。它将一个功能从自然语言请求推进到需求、设计和任务清单。

Kiro Feature Specs 通常包含三类核心工件：

ounter(lineounter(lineounter(linerequirements.mddesign.mdtasks.md

其典型流程有两种：

ounter(lineounter(lineRequirements-First: Requirements → Design → TasksDesign-First:       Design → Requirements → Tasks

Requirements-First 适合需求已经比较明确的场景；Design-First 适合技术可行性、架构约束或接口设计优先的场景。

Kiro Specs 的重要特征之一是鼓励使用 EARS 风格需求写法。例如：

ounter(lineounter(lineWHEN a user enters invalid credentialsTHE SYSTEM SHALL show a generic authentication error without revealing whether the email exists.

这种写法把需求转化为可测试陈述，减少“看起来差不多”的模糊实现。

本文认为，Kiro Specs 的价值不在于生成几个 Markdown 文件，而在于将产品经理、架构师和开发者之间的隐性协作流程显性化。它适合复杂功能、多任务变更、团队协作和需要保留设计依据的项目。

7. GitHub Spec Kit：跨代理的 SDD 脚手架

GitHub Spec Kit 是面向规范驱动开发的工具包。它强调将 specification 放在 AI 辅助开发的中心位置，通过一系列结构化阶段将意图转化为实现。

其核心流程可以概括为：

ounter(lineSpec → Plan → Tasks → Implement

更完整的命令式流程包括：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line/speckit.constitution  定义项目原则/speckit.specify       写 what / why/speckit.clarify       澄清歧义/speckit.plan          写技术计划/speckit.tasks         拆任务/speckit.analyze       审核计划/speckit.implement     执行实现

Spec Kit 与 Kiro Specs 的区别在于：Kiro 更像 IDE 内置的规范流程，而 Spec Kit 更像 repo 内的跨代理开发脚手架。它不绑定单一编码代理，而是通过生成项目结构、命令文件和上下文规则，使不同 AI 编码工具围绕同一套规范协作。

本文认为，GitHub Spec Kit 特别适合多工具团队、长期维护项目和需要将规范工件纳入版本控制的场景。它可以把 spec 从临时聊天记录转化为仓库中的正式开发资产。

8. 横向比较

工具 / 文件	主要作用	适合放什么	不适合放什么	推荐定位
`AGENTS.md`	跨工具代理总纲	项目概览、命令、测试、风格、安全边界	具体功能需求长文档	单一事实源
`CLAUDE.md`	Claude Code 项目记忆	Claude 特定工作方式、常用命令、项目约束	大量 feature spec	Claude 适配层
Cursor Rules	IDE / 目录 / 文件级规则	React、API、DB、测试等局部规则	所有项目知识的大杂烩	细粒度规则层
Kiro Specs	IDE 内 spec 工作流	`requirements.md` 、`design.md`、`tasks.md`	全局团队编码规范	功能级 SDD
GitHub Spec Kit	跨代理 SDD 框架	constitution、spec、plan、tasks、checklists	工具私有偏好	repo 级规范工作流
`AGENT.md`	单数版通用代理配置提案	与 `AGENTS.md` 类似	作为唯一标准押注	兼容软链接

从表中可以看到，这些工具并非竞争关系，而是处于不同层级。将它们混为一谈，容易导致规则冗余、冲突和上下文污染。更合理的做法是明确每一层的职责边界。

AI 编码代理相关工具的职责边界比较

9. 推荐的仓库组织模型

一个现代 AI-native 项目可以采用如下目录结构：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line.├── AGENTS.md                    # 跨工具总纲：项目、命令、约束、边界├── CLAUDE.md                    # Claude Code 适配，可引用 AGENTS.md├── AGENT.md -> AGENTS.md        # 可选：兼容单数提案├── .cursor/│   └── rules/│       ├── frontend.mdc│       ├── backend.mdc│       ├── database.mdc│       ├── testing.mdc│       └── security.mdc├── .kiro/│   └── specs/│       └── user-authentication/│           ├── requirements.md│           ├── design.md│           └── tasks.md├── .specify/│   ├── memory/│   │   └── constitution.md│   └── templates/└── specs/    └── 001-user-authentication/        ├── spec.md        ├── plan.md        ├── tasks.md        └── research.md

该结构体现了三条原则。

第一，AGENTS.md 作为跨工具项目总纲，承担长期稳定的项目上下文。

第二，CLAUDE.md 和 Cursor Rules 不重复定义项目原则，而是作为工具适配层和局部规则层。

第三，Kiro Specs 或 Spec Kit 负责功能级开发工件，使每个重要功能都有可追踪的需求、设计和任务。

AI-native 项目的推荐仓库组织结构

10. 推荐工作流

10.1 建立项目总纲

项目初期应首先创建 AGENTS.md，明确技术栈、命令、代码风格和不可违反的规则。该文件应简洁、稳定，并作为其他工具规则的源头。

10.2 编写工具适配文件

CLAUDE.md 可以写成：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line# Claude Code InstructionsFollow the project-wide rules in AGENTS.md.Additional Claude-specific rules:- Before editing, briefly inspect related files.- Prefer small, reviewable patches.- After implementation, summarize changed files and tests run.

Cursor Rules 则按照目录和文件类型拆分。例如，前端组件规则、API 路由规则、数据库迁移规则和测试规则应分别维护。

10.3 为每个重要功能创建 spec

每个重要功能都应至少包含：

ounter(lineounter(lineounter(linerequirements.mddesign.mdtasks.md

或在 Spec Kit 中包含：

ounter(lineounter(lineounter(lineounter(linespec.mdplan.mdtasks.mdresearch.md

需求部分应重点回答“做什么”和“为什么做”，避免过早陷入技术实现。技术选型、接口设计、数据模型和错误处理应进入 design 或 plan 阶段。

10.4 实现后回写规范

功能完成后，应要求 AI 编码代理执行以下检查：

ounter(lineounter(lineounter(line1. Check implementation against requirements.md.2. Mark completed tasks in tasks.md.3. List any spec drift or missing acceptance criteria.

这一步是规范驱动开发能否长期有效的关键。如果实现完成后不更新 spec，规范很快会退化为过期文档。

规范驱动开发从项目总纲到实现回写的闭环工作流

11. 风险与反模式

11.1 把规则文件误认为强制约束

CLAUDE.md、Cursor Rules 和 AGENTS.md 都主要通过上下文影响模型行为，而不是强制执行规则。因此，真正关键的约束仍应进入 CI、测试、lint、类型检查、安全扫描和代码审查流程。

11.2 把所有内容写进单个大文件

过长的规则文件会稀释模型注意力，也会让团队难以维护。更好的策略是：总纲短、局部规则细、功能规范独立。

11.3 多源规则冲突

如果 AGENTS.md、CLAUDE.md 和 Cursor Rules 中存在三套互相矛盾的编码风格或测试命令，AI 代理会更容易犯错。团队应指定一个主源，其他文件只做引用、补充或局部覆盖。

11.4 只做 spec-first，不做 spec-maintained

规范驱动开发不应只是在开发前写一份 spec。真正成熟的做法是让 spec 在需求变更、实现完成、测试失败和后续维护中持续更新。否则，spec 会变成一次性文档，无法支撑长期演进。

12. 场景化建议

12.1 个人项目

个人项目可以采用轻量组合：

ounter(lineounter(lineounter(lineounter(lineAGENTS.mdCLAUDE.md.cursor/rules/*specs/<feature>/{requirements,design,tasks}.md

该组合既能提供稳定项目上下文，也不会引入过重流程。

12.2 小型团队

小型团队应将 AGENTS.md 作为单一事实源，并把 Cursor Rules 拆分到关键目录。重要功能通过 Kiro Specs 或 Spec Kit 管理。

ounter(lineounter(lineounter(lineounter(lineounter(lineAGENTS.md as source of truthCLAUDE.md references AGENTS.mdCursor Rules for file-scoped behaviorSpec Kit or Kiro Specs for feature lifecycleCI enforces tests, lint, typecheck, security

12.3 大型组织

大型组织需要更强的治理能力：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineOrganization policy rulesAGENTS.md repo-level rulesNested AGENTS.md per packageSpec Kit constitutionFeature specs with approval gatesArchitecture/security review gatesAutomated drift checks

在这一场景中，规范文件不仅服务于 AI 编码代理，也服务于审计、合规、知识传承和跨团队协作。

13. 结论

CLAUDE.md、Cursor Rules、AGENTS.md、Kiro Specs 和 GitHub Spec Kit 并不是同一层次的替代品。它们共同构成了 AI-native 软件工程中的规范体系。

其中，AGENTS.md 适合作为跨工具项目总纲；CLAUDE.md 适合作为 Claude Code 的适配层；Cursor Rules 适合作为局部、文件级、目录级规则系统；Kiro Specs 适合在 IDE 内完成需求、设计和任务拆解；GitHub Spec Kit 适合为多代理团队提供 repo 级规范驱动开发脚手架。

本文的核心建议是：

把 AGENTS.md 当作“项目宪法”，把 CLAUDE.md 和 Cursor Rules 当作“代理适配器”，把 Kiro Specs 与 GitHub Spec Kit 当作“功能开发流水线”。

规范驱动开发的关键不在于写更多 Markdown，而在于让规则、需求、设计、任务和实现之间形成持续一致的闭环。只有当规范能够被代理读取、被团队审查、被 CI 验证、被实现回写时，它才真正成为软件工程的一部分。

参考文献

Anthropic. Claude Code Memory Documentation. https://docs.anthropic.com/en/docs/claude-code/memory
Cursor. Rules Documentation. https://cursor.com/docs/rules
NVIDIA. NeMo Agent Toolkit: Cursor Rules Developer Guide. https://docs.nvidia.com/nemo/agent-toolkit/1.2/extend/cursor-rules-developer-guide.html
Agents.md. AGENTS.md Official Website. https://agents.md/
OpenAI. Codex: AGENTS.md Guide. https://developers.openai.com/codex/guides/agents-md
AgentMD. Universal Agent Configuration File. https://github.com/agentmd/agent.md
Kiro. Feature Specs Documentation. https://kiro.dev/docs/specs/feature-specs/
Kiro. Specs Best Practices. https://kiro.dev/docs/specs/best-practices/
GitHub. Spec Kit Documentation. https://github.github.com/spec-kit/
GitHub. Spec Kit Quickstart. https://github.github.com/spec-kit/quickstart.html
Martin Fowler. Exploring Gen AI: SDD Tools. https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html