AI Coding 工程规范化方法论：从 Vibe Coding 到 Rules·Spec·Eval 三位一体

2026 年，AI 编码工具（Claude Code、Cursor、Codex、Copilot、各类本地 Agent）已经从”补全玩具”演进为能独立读代码、跑测试、提 PR 的”准同事”。但行业共识正在快速收敛：模型本身不再是瓶颈，工程纪律才是。Django 创始人 Simon Willison 把专业开发者使用编码 Agent 的过程定义为 Agentic Engineering——区别于非程序员”完全不看代码”的 Vibe Coding，前者是用 Agent 放大既有工程经验。本篇把一年来各路实践（Agentic SDLC 研究、规范文件约定、执行式评测、代码库接地）归纳为一个可落地的工程规范化方法论：规范即代码（Rules）+ 规格驱动（Spec）+ 评测护栏（Eval） 三柱一体。

一、为什么需要方法论：Vibe Coding 的天花板

依赖一次性 prompt 生成功能的 Vibe Coding 是常见陷阱：它产出在 demo 里”看起来能用”、却在边界条件与跨文件依赖上崩塌的代码。没有正式规格，Agent 被迫猜测开发者意图，制造的技术债往往比手写代码更难调试。Appamass 对 2026 年头部开发者的调研结论很直白：一天交付功能与陷在无限 AI 循环里的团队之间，差距不在模型，而在工作流。达成 3 倍提效的团队，早已不再把 Agent 当自动补全，而是当作需要明确规格、计划评审与严格上下文卫生的”团队成员”。

由此引出三条核心经验：(1) 采用 spec-first 防止 Agent 猜测架构需求；(2) 执行前强制计划评审，尽早捕获错误架构决策；(3) 频繁重置上下文，防止长会话中 Agent 自相矛盾。代码评审已成为 Agentic SDLC 的关键瓶颈——Agent 生成代码的速度远快于人类核验速度，瓶颈已从”写代码”转移到”审代码”。

二、柱一：规范即代码（Rules）——把团队契约写进仓库

Agent 无法可靠遵守它”发现不了”的规则。最务实的做法是把架构约束、模块边界、批准依赖、API 约定、测试期望、安全约束、ADR 放到仓库里、贴近代码。这就催生了 2026 年最热闹的”规范文件”生态：AGENTS.md、CLAUDE.md、.cursorrules/.cursor/rules、.github/copilot-instructions.md、JULES.md 等。

关键洞察是“单一真相源 + 分层适配器”：AGENTS.md（由 Linux Foundation 的 Agentic AI Foundation 托管，已被超 60,000 个仓库采用）是跨工具通用标准，应作为 canonical 项目策略；CLAUDE.md 是 Claude Code 的轻量”记忆层”适配器；.cursor/rules 是 Cursor 的编辑器行为适配器。最佳实践不是在三处重复写同一份规则（必然漂移），而是让项目策略从 AGENTS.md 单向流出，其余文件只补充工具特有机制，甚至用 symlink 指向它。一份好的根 AGENTS.md 应短而可操作：构建/测试/lint 命令、架构边界、代码风格、安全警告、PR 期望，目标 500–2,000 token——每个 token 都在每次 Agent 调用时加载，过长是直接的上下文税。

规范文件	适用工具	层级/覆盖	2026 定位
AGENTS.md	Codex/Cursor/Aider/通用	仓库根，可子目录 override	跨工具开放标准，首选 baseline
CLAUDE.md	Claude Code	~/.claude 全局 → 项目 → 子目录三层	Anthropic 维护，活跃
.cursor/rules/*.mdc	Cursor	按 glob 路径/文件类型作用域	取代 legacy 单文件 .cursorrules
.github/copilot-instructions.md	GitHub Copilot	.github 目录	GitHub 约定

三、柱二：规格驱动（Spec）——把”写得快但写不对”关进笼子

规范解决”怎么写”，规格（Spec）解决”写什么、写到哪”。Agentic Coding 的黄金工作流是五阶段：规格 → 计划生成 → 计划评审 → 执行 → 验证，强制 Agent 在写第一行代码前就与现有架构对齐。CoderBlog 的实践更具体：让模型先把计划写成结构化文档（编号步骤、预期改动文件、预期验证命令），并把计划注入后续每一步的 prompt——计划就是 Agent 的工作记忆；同时为每一步设验证（通过的测试/类型检查/截图比对）和步数预算，没有步数预算的 Agent 会螺旋而非收尾。

中文社区把这一层提炼为 DDD（道）· SDD（法）· TDD（术）的”黄金三角”：用 DDD 做战略设计与领域建模，用 SDD 定义战术执行契约（OpenAPI、Protobuf、Cucumber 特性文件作为唯一真相源，CI 中自动校验代码符合契约），用 TDD 保证质量。三者的有机融合，构成从战略设计到战术执行的完整闭环，直击”AI 写得快但写不对”的核心痛点。

四、柱三：评测护栏（Eval）——用执行而非文本判断代码

这是最容易被忽视、却最致命的一柱。用 BLEU、文本 diff 等静态相似度评测智能体是灾难性的：一次干净的重构会被判 90% 失败，而一个复刻变量名却悄悄引入内存泄漏的 Agent 反而得高分。唯一有效的正确性检验是执行（Execution-Based Evaluation）——在临时沙箱里真正编译、跑回归测试、跑 issue 测试，以退出码判定 resolved。

公开基准也已进入”后饱和”时代：HumanEval/MBPP 已接近饱和（~95%）毫无区分度；SWE-bench Verified（500 个经人工验证的真实 PR 修复）是当下最可信的公开下限；但其也暴露出污染与缺陷——OpenAI 2026-02 审计发现至少 59.4% 的硬任务存在测试/设计缺陷，且存在训练污染；更严峻的是 METR 的研究：2024 年中至 2025 年的 Agent 产出的”测试通过”SWE-bench PR 中，约一半不会被真实维护者合并。因此 2026 的工程答案不是换一个基准，而是分层评测栈：CI 内快速回归门禁 + 抗污染公开基准（SWE-bench-Live、SWE-bench Pro，后者多语言、跨 4.1 文件、比 Verified 低 40+ 个百分点）+ 周期性”人类可合并性”复核。

基准	形态	语言	用途
HumanEval/MBPP	函数补全 ~150/1000	Python	已饱和，不再区分前沿模型
SWE-bench Verified	500 真实 PR 修复	Python	公开可信下限，外部宣发须报此
SWE-bench Pro	1,865 任务	Python/Go/TS/JS	抗污染、多语言，2026 前沿信号
SWE-bench Multilingual	9 语言 300 任务	C/C++/Go/Java/Rust…	多语言代码库必测

五、知识注入（Grounding）：让 Agent 从”互联网平均”回到”你的代码”

通用模型知道公共模式，但你的项目有私有真相：目录约定、实际在用（与被禁用的）库、领域语言（你的 “Account” ≠ “User”）、多租户与数据驻留约束、历史雷区（”动 legacy/billing 必须带 feature flag”）。没有这些，AI 会针对”平均 GitHub 仓库”而非”你的仓库”优化。接地（Grounding）是通用模型与具体代码库之间的概念桥梁。

落地手段分四层：手动上下文（粘贴文件/日志）、常驻指令（AGENTS.md 类）、repo-aware 工具（Agent 自己检索、读树、跑命令）、以及检索增强（RAG）。对代码库做 RAG 的关键不在生成而在检索：代码不是散文，朴素按字符切分会切断类与方法边界，生产级索引器（Tree-sitter/AST）按方法/类边界切分；优先用混合检索（向量 + BM25/精确标识符匹配）——纯向量会漏掉确切的技术标识符；再用 cross-encoder 重排提升 top-5 相关性；并按服务名/语言/文件类型做元数据过滤。经验法则：对代码库知识永远默认用 RAG 而非微调——代码随每个 PR 演进，微调快照在下一秒就过时。这一步也直接呼应本公众号另一个长期主题：把私有知识库（如 kshare）作为 Agent 的”项目大脑”，让编码 Agent 在生成前先检索内部架构文档、ADR、runbook、API 契约与历史 issue，是 2026 年最划算的工程投入之一。

六、协作节奏与角色重构：Human-on-the-Loop 与有界自治

当 Agent 能快速产出大 diff，审查必须更严而非更松。trust! NICKOL 提出的“有界自治（Bounded Autonomy）”按风险分级委派：低风险（文档、测试脚手架、lint 修复、明确重构）给 Agent 充分自由；中风险（功能、集成、依赖变更，带明确验收标准）需更强测试与资深评审；高风险（认证、架构边界、生产基础设施、不可逆迁移）必须由人类主导决策。判断依据不是 Agent 看起来多强，而是“错误决策的成本、影响与可逆性”。

对应的治理框架是四层：策略层（Agent 能做什么）→ 上下文层（必须守什么规则）→ 执行层（能访问什么，沙箱化 + 最小权限 + 临时凭据）→ 验证层（合并前必须发生什么）。OWASP 当前指南明确要求对 Agent 运行时沙箱化、限制文件系统与工具访问、把仓库内容与外部信息视为潜在不可信输入——因为 issue、文档、PR 评论、网页都可能携带间接提示注入。七个护栏可记为：让架构对 Agent 可读、保持变更小而可回滚、强化质量门禁、最小权限沙箱、审慎治理依赖、评审架构意图而非仅语法、人类对架构保持问责。

七、决策权衡汇总

决策点	选项 A	选项 B	推荐
规范文件	分散在各工具文件	AGENTS.md 单一真相源 + 适配器	B（防漂移）
规格粒度	一次性 prompt	五阶段 spec→plan→review	B（防猜测）
评测方式	文本 diff/BLEU	执行式沙箱 + SWE-bench	B（真正确定性）
知识注入	微调代码库	RAG + 常驻指令	RAG（保鲜）
自治程度	全开放	按风险分级有界自治	分级

八、演进路线与 30/60/90 落地

演进主线：从 ad-hoc 提示 → 规范即代码标准化（AGENTS.md 成为事实标准）→ 规格驱动与 Agentic SDLC → 评测内建进 CI 实时化 → 知识接地成为 Agent 的一等公民 → 多智能体编排与协议层（MCP）成熟。CoderBlog 的预判很清醒：模型易得、循环周围的工程最难——把工具打磨干净、把作用域收得最紧、像资深工程师带新人一样对待 Agent（高期望、清晰边界、失败时读 transcript）的团队，才会拿到最大收益。

30/60/90 落地：前 30 天，落地 AGENTS.md（构建/测试/架构边界/PR 规则），接入 CI 既有 lint/test 作为质量门禁，选 1–2 个低风险场景试点有界自治；30–60 天，建立内部 SWE-bench 风格基准（从本仓库真实 PR 中挖 50–500 条），把执行式评测接入 CI 回归门禁，引入代码库 RAG/私有知识库接地；60–90 天，推行五阶段 spec→plan→review 工作流，按风险分级授权，配置 Agent 运行时沙箱与最小权限，把评测与架构评审纳入合并闸门，并形成每月基准回归的常态化节奏。

九、量化基线参考

指标	数值/现象	来源语境
SWE-bench Verified 前沿	~80.9%（半年 74.9%→80.9% 放缓）	OpenAI 2026-02 分析
硬任务测试缺陷率	≥59.4% 审计子集存在测试/设计缺陷	OpenAI 审计
“测试通过”PR 可合并性	约半数不会被真实维护者合并	METR 2026-03 研究
AGENTS.md 采用	超 60,000 仓库，Linux Foundation 托管	Agentic AI Foundation
规范文件 token 预算	500–2,000 token 为甜区	多份规范指南共识
评测实例预算	封顶 20 步 / 200K token 防失控	SWE-bench 实操经验