ARTICLE / 2026·07·09
AI代码开发规范方法论
面向网络博客发布的 AI coding agent 开发规范综述，合并说明 Spec-driven development、仓库级指令文件、IDE Rules、Skills 与可复用工作流的主流做法、选型边界和落地模板。
AI代码开发规范方法论
一、概述
AI coding agent 的开发规范，本质上是在回答两个问题：
- Agent 应该依据什么上下文做决定。
- Agent 应该按照什么流程把需求变成可验证代码。
从 GitHub、OpenAI、Anthropic、Cursor、Cline、Windsurf 以及开源社区实践看，主流方法可以归为四类：
| 大类 | 代表方式 | 解决的问题 |
|---|---|---|
| Spec-driven development | GitHub Spec Kit、OpenSpec、traceSDD | 让需求、设计、任务和实现可追踪 |
| 仓库级指令文件 | AGENTS.md、CLAUDE.md、copilot-instructions.md | 让 Agent 每次进入仓库都遵守统一工程约定 |
| IDE Rules 与项目上下文 | Cursor Rules、Cline Rules、Windsurf Memories、VS Code instructions | 让规则按工具、文件类型、目录或工作区自动生效 |
| Skills 与可复用工作流 | Codex Skills、Claude Skills、Superpowers | 把可重复的工程流程封装成可调用能力 |
这些方法不是互斥关系。更成熟的团队通常会组合使用：用 AGENTS.md 承载稳定仓库约定，用 Spec 工件管理复杂需求，用 IDE Rules 做文件级触发，用 Skills 固化 TDD、debug、review 等重复流程。
二、整体关系
graph TD
A["Project Constitution<br/>长期原则"] --> B["Spec<br/>需求和验收"]
B --> C["Plan<br/>技术方案"]
C --> D["Tasks<br/>执行任务"]
E["AGENTS.md / CLAUDE.md<br/>仓库约定"] --> D
F["IDE Rules<br/>文件/目录规则"] --> D
G["Skills<br/>可复用流程"] --> D
D --> H["Implementation<br/>代码和测试"]
H --> I["Review<br/>对照规范验收"]
一个实用判断是：
- “项目长期都要遵守”的内容，放仓库级指令文件。
- “某类文件或目录才触发”的内容，放 IDE Rules。
- “某个复杂需求的一次性上下文”，放 Spec/Plan/Tasks。
- “反复执行的工作流”，封装成 Skill。
三、Spec-driven development
Spec-driven development（SDD）的核心是先写可验证 specification，再让 Agent 基于规范生成 plan、tasks 和代码。它不是简单的 Prompt 模板，而是把需求工程、设计约束、任务拆分和验收标准版本化。
3.1 工件链路
| 工件 | 作用 | 应包含 | 常见风险 |
|---|---|---|---|
constitution | 固化项目不可违背的原则 | 技术栈、分层、测试、安全、可访问性、禁用库 | 写得太抽象，Agent 无法执行 |
spec | 描述业务目标和验收标准 | user story、acceptance criteria、边界条件、非功能需求 | 混入实现方案，导致需求与设计耦合 |
plan | 描述如何实现 | 架构选择、数据模型、接口、迁移、测试策略 | 未引用现有代码证据，容易产生虚构 API |
tasks | 拆成可执行工作项 | 顺序、依赖、并行标记、测试步骤 | 粒度过大，Agent 一次改太多 |
implement | 执行任务 | 代码、测试、验证输出 | 跳过测试或偏离 spec |
GitHub Spec Kit 的典型流程是 Specify -> Plan -> Tasks -> Implement。它的价值在于把 AI coding agent 的输入从“临时口头需求”变成结构化上下文。
3.2 OpenSpec/traceSDD 类增强
OpenSpec、traceSDD、Constitutional SDD 等实践进一步强调 traceability 和约束可审计。一个可落地的写法是给需求条目编号：
REQ-001: 用户可上传头像
REQ-001.1: WHEN 文件超过 2MB THE SYSTEM SHALL 拒绝上传并提示原因
REQ-001.2: WHEN 文件类型不是 PNG/JPEG THE SYSTEM SHALL 拒绝上传
后续 plan.md、tasks.md、测试用例和 PR 描述都引用 REQ-001.x，这样 review 时可以检查 Agent 是否遗漏需求。
3.3 与 TDD 的结合
sequenceDiagram
participant H as Human
participant A as Agent
participant T as Tests
H->>A: Provide spec and acceptance criteria
A->>A: Create plan and tasks
A->>T: Write failing tests
T-->>A: Red
A->>A: Implement minimal code
A->>T: Run tests
T-->>A: Green
A->>A: Refactor and check spec coverage
| 规范条目 | 测试落点 |
|---|---|
| user story | 端到端或集成测试 |
| acceptance criteria | 单元测试/行为测试 |
| 非功能需求 | 性能、安全、可访问性检查 |
| 边界条件 | 参数化测试 |
3.4 推荐目录
docs/specs/
constitution.md
features/
user-avatar/
spec.md
plan.md
tasks.md
review.md
SDD 适合复杂功能、跨模块改动、长期维护项目和多人协作项目；不适合单文件 typo、一次性脚本或无需维护的小改动。
四、仓库级 Agent 指令文件
仓库级 Agent 指令文件是给 AI coding agent 的“项目操作手册”。它和 README.md 不同：README.md 面向人类理解项目，AGENTS.md、CLAUDE.md、.github/copilot-instructions.md 等文件面向 Agent 约束行为。
4.1 主流文件
| 生态 | 常见文件 | 作用范围 | 典型用途 |
|---|---|---|---|
| OpenAI Codex | AGENTS.md、AGENTS.override.md | 全局、仓库、子目录层级 | Codex 每次工作前读取的持久项目指导 |
| GitHub Copilot | .github/copilot-instructions.md、AGENTS.md、.github/instructions/*.instructions.md | 仓库、组织、文件 glob | 代码生成、review、commit message、PR 描述 |
| Claude Code | CLAUDE.md | 用户、项目、子目录层级 | 项目记忆、命令、约定、偏好 |
| VS Code Agent | .instructions.md、.agent.md | workspace/user/org | 自定义指令、自定义 Agent、handoff |
| 通用社区实践 | AGENTS.md | 仓库根目录或子目录 | 跨工具共享的 Agent 指令入口 |
4.2 推荐结构
# AGENTS.md
## Project
- 一句话说明项目目标
- 主要技术栈和运行时版本
## Commands
- Build: `...`
- Test: `...`
- Lint: `...`
## Architecture
- 关键目录职责
- 禁止跨越的边界
## Coding Rules
- 命名、错误处理、日志、安全、兼容性
## Workflow
- 修改前先读哪些文件
- 何时写测试
- 何时更新文档
## Review Checklist
- 交付前必须验证的命令和风险点
4.3 适合放入指令文件的内容
| 内容 | 示例 | 原因 |
|---|---|---|
| 构建与测试命令 | npm test -- --runInBand | 降低 Agent 猜命令概率 |
| 目录职责 | src/domain 不依赖 src/ui | 防止破坏架构 |
| 安全规则 | 不记录 token，不关闭 CSRF | 高频且高风险 |
| 代码风格 | 使用 existing helper，不新增同类工具 | 保持一致性 |
| 文档同步 | 新增 API 后更新 OpenAPI 和 README | 避免半成品 |
| 禁止事项 | 不运行 destructive command | 保护工作区 |
指令文件不要变成业务知识大全。它应该短、稳定、可执行、可验证。
五、IDE Rules 与项目上下文
IDE 规则运行在开发工具内，典型代表包括 Cursor Rules、Cline Rules、Windsurf/Cascade Rules 与 Memories、VS Code custom instructions。它们通常比仓库级指令更贴近编辑器交互，可按文件类型、目录、用户、工作区或组织级别自动生效。
5.1 主流系统
| 工具 | 规则形态 | 自动生效粒度 | 适合内容 |
|---|---|---|---|
| Cursor | Project Rules、Team Rules、User Rules、AGENTS.md | 文件 glob、项目、团队、用户 | 框架约定、目录说明、编码风格 |
| Cline | .clinerules 或 .clinerules/ Markdown | 项目级，可组织成多个规则文件 | 工作流、工具使用、架构约束 |
| Windsurf/Cascade | Rules + Memories | global、workspace、自动记忆 | 用户显式规则 + 对话中沉淀的项目知识 |
| VS Code/Copilot | .instructions.md、custom instructions | user、workspace、organization、glob | Copilot Chat、review、commit、PR 文案 |
5.2 Rules 与 Memories 的边界
| 类型 | 来源 | 适合记录 | 不适合记录 |
|---|---|---|---|
| Rules | 人工编写 | 强约束、稳定约定、团队标准 | 临时任务状态 |
| Memories | 工具自动或半自动生成 | 反复出现的偏好、项目事实、已验证经验 | secret、短期 debug 结论、未确认猜测 |
规则要像法律，少而稳定；memory 要像工作笔记，允许演进但必须可删除。
5.3 示例
---
description: "React 组件开发规则"
globs: ["src/**/*.tsx"]
---
- 优先复用 `src/components` 中的现有组件。
- 新增状态逻辑时优先放在 hook 中，避免组件过长。
- 样式使用现有 design token，不新增硬编码颜色。
- 新增交互必须覆盖 loading、empty、error 状态。
- 修改后运行 `npm test` 和 `npm run lint`。
跨工具迁移时，建议把工具无关内容放入 AGENTS.md 或 docs/agent/*.md，把工具私有触发条件放入 .cursor/rules、.clinerules、.github/instructions。
六、Skills 与可复用工作流
Skills 是把重复的 Agent 工作方法封装成可发现、可复用、可分发的能力包。与仓库级指令文件相比，Skills 更适合“如何做某类任务”，例如 TDD、code review、系统化调试、生成文档、处理 PDF 或创建 release note。
6.1 Skill 与规则文件的区别
| 维度 | 规则文件 | Skill |
|---|---|---|
| 目标 | 每次都应遵守的约束 | 特定任务触发的专业流程 |
| 粒度 | 项目级、目录级、工具级 | 能力级、工作流级 |
| 内容 | 命令、约定、禁止事项 | 步骤、脚本、模板、参考资料 |
| 加载方式 | 通常会随会话或文件上下文加载 | 相关时按需加载 |
| 风险 | 上下文膨胀 | 恶意脚本、过度自动化 |
6.2 典型结构
my-skill/
SKILL.md
scripts/
validate.py
references/
checklist.md
assets/
template.md
| 组成 | 作用 |
|---|---|
SKILL.md | 元数据、适用场景、执行步骤 |
scripts/ | 可执行脚本，减少 Agent 手写重复逻辑 |
references/ | 长文档、规范、示例，按需读取 |
assets/ | 模板、静态资源、示例文件 |
agents/ | 可选的专用 subagent 配置 |
6.3 Superpowers 方法论
Superpowers 把工程习惯拆成多个流程 skill，例如 writing-plans、subagent-driven-development、test-driven-development、requesting-code-review、systematic-debugging。这种方法的重点不是“多写 Prompt”，而是把可重复的工程纪律变成 Agent 必须遵守的流程。
graph LR
A["User Request"] --> B["Select Skill"]
B --> C["Read SKILL.md"]
C --> D["Load references/scripts as needed"]
D --> E["Execute workflow"]
E --> F["Verify output"]
6.4 编写原则
| 原则 | 说明 |
|---|---|
| 单一职责 | 一个 skill 只解决一类任务 |
| 渐进披露 | 主文件短，长资料放 references |
| 可验证 | 每个流程应包含验证命令或检查清单 |
| 可复用 | 避免绑定单个仓库路径 |
| 安全边界 | 脚本权限、外部网络、secret 操作要明确 |
| 人机协同 | 说明何时需要用户确认 |
七、选型速查
| 场景 | 优先采用 |
|---|---|
| 新功能需求复杂、容易跑偏 | Spec-driven development |
| 希望所有 Agent 每次进入仓库都遵守统一命令和约定 | AGENTS.md / CLAUDE.md |
| 使用 Cursor/Cline/Windsurf 等 IDE，想让规则随项目自动生效 | IDE Rules |
| 团队有重复工作流，如 TDD、code review、release note | Skills |
| 大任务需要调研、实现、测试、评审分离 | 多 Agent 协作 |
| 规则越来越多、效果不稳定 | 规则治理 |
参考资料：
- GitHub Spec Kit
- Spec Kit Documentation
- GitHub Blog: Spec-driven development with AI
- OpenAI Codex: Custom instructions with AGENTS.md
- GitHub Docs: Adding repository custom instructions for GitHub Copilot
- Claude Code Docs: How Claude remembers your project
- Cursor Docs: Rules
- Cline Docs: Rules
- Devin Docs: Cascade Memories
- OpenAI Codex: Agent Skills
- Anthropic Claude Code: Extend Claude with skills
- Superpowers GitHub Repository
相关文档：