AI Coding 落地指南：模型 × 项目宪法 × Spec × Skills 的工程化打法

AI Coding 真正难的从来不是“让模型写几段代码”，而是把它变成可复制、可审计、可持续演进的工程能力：不同人用同一个助手，产出质量要稳定；不同项目复用同一套规则，协作成本要下降；出了问题能定位、能回滚、能改进。

这篇文章给出一套我在团队里实践过、可直接照抄的落地方案，把 AI Coding 拆成三层治理（其中“规范层”又分为项目宪法与 Spec 两个工件）：

• 模型层（Model）：把“会写”变成“稳定写、能对齐、可路由”。
• 规范层（Constitution + Spec）：把“口口相传”变成“机器可执行的团队约定”。
• 能力层（Skills）：把“临时对话”变成“可复用的工具与流程资产”。

---

一、模型层：从“选大模型”到“模型路由 + 质量闭环”

落地时请把“选模型”当成一个工程决策而不是个人偏好。关键不是谁更强，而是你能不能把它放进流程里稳定产出。

1.1 你需要的不是一个模型，而是三类能力

把需求拆开后，模型选型会非常清晰：

任务类型	典型动作	需要的模型能力	常见坑
规划与拆解（Plan）	读需求、定方案、列清单	长上下文、结构化输出、推理稳定	规划漂亮但不落地
代码与修复（Code）	写代码、补测试、改接口	代码生成质量、依赖理解、局部修改	一次改动扩散，破坏约定
审阅与防线（Review）	对照规范检查、找风险	细节敏感、审计式思维	“看起来没问题”但漏关键

工程上最推荐的做法是模型路由（Model Routing）：同一件事在不同阶段，调用不同“角色模型”，减少随机性。

1.2 最小可用的路由策略（直接照抄）

先用最小策略跑起来，不要一上来就做复杂编排：

1. Plan 模式：先产出“可执行计划”，包含验收条件、影响面、测试策略。
2. Code 模式：严格限制改动范围：只改指定文件/目录；必须补测试；必须通过已有命令验证。
3. Review 模式：对照项目宪法与 Spec 清单逐条验收，输出“通过/不通过 + 证据”。

把路由写成团队统一的交互格式（无论你用 Cursor、Windsurf 还是自研 Agent 都适用）：

Mode: PLAN | CODE | REVIEW
Inputs: 需求/上下文/约束
Outputs: 计划/补丁/审计结果
Gates: 不满足则必须停止并返回缺口

1.3 质量闭环：基准任务 + 回放机制（比争论模型更有效）

把争论“哪个模型更强”改成“哪个模型更稳定”：

• 基准任务库（Bench）：选 10 个你们真实会遇到的任务：新增接口、改字段、修 bug、重构、补测试、性能排查等。
• 固定评测口径：每个任务都有验收条件（编译/单测/接口契约/性能指标/安全规则）。
• 回放（Replay）：每次宪法/Spec/Skill 更新后，跑一遍 Bench 看回归情况。

如果你们用 Confluence 做知识中枢，建议为 Bench 建一页“基准任务清单”作为跨团队共识，并把每次回放结果写成子页，方便审计与复盘。

---

二、规范层（1）：项目宪法——让 AI 和团队“守同一套规矩”

项目宪法（Project Constitution）是 AI Coding 落地的第一性原则：任何人、任何模型、任何技能都必须遵守的底线与共识。它不是“风格指南”，而是“工程宪法”。

2.1 宪法放哪里最有效

推荐“双主存储”，兼顾“机器可用”与“组织可治理”：

• 仓库内（机器优先）：放到项目根目录的规则文件（例如 AGENTS.md、IDE 规则文件等），让助手每次都能加载。
• Confluence（治理优先）：放到团队空间，作为带版本、带审批、可讨论的“制度页”，并在页面顶部明确 Owner 与变更流程。

仓库内的版本是“执行版本”，Confluence 是“治理版本”。两者通过链接互相引用：Confluence 页面链接到仓库文件，仓库文件头部链接回 Confluence 页面。

2.2 宪法模板（可直接复制到仓库/Confluence）

宪法不要长；要“能执行、能验收”。下面是一份足够强、又不臃肿的 v1 模板：

## 项目宪法 v1

### 1. 目标与范围
- 本项目的核心目标/非目标是什么
- AI 助手允许做什么，不允许做什么

### 2. 不可违背的规则（Must）
- 变更必须最小化：只改必要文件，不做无关重构
- 必须补测试：新增行为必须有测试或验证步骤
- 必须可回滚：对外接口/数据结构变更要给迁移与回滚方案
- 必须保护信息：禁止输出或记录密钥、用户隐私、内部链接

### 3. 工程约定（Conventions）
- 目录结构与模块边界
- 命名/错误处理/日志/配置约定
- 依赖管理与版本策略

### 4. 质量门槛（Gates）
- 必须通过的命令（lint/typecheck/test/build）
- 代码审查清单（安全/性能/可维护性）

### 5. 交付物格式（Deliverables）
- 需求变更：必须附 Spec
- 代码变更：必须附测试与验证记录
- 风险变更：必须附 Review 结论

2.3 宪法如何落地到日常开发（关键在“可执行”）

落地不是“写完一页文档”，而是把它变成日常工作的默认轨道：

• 在 PR 模板里引用宪法 Gate：让“必须跑哪些命令、必须补哪些测试”变成固定项。
• 把宪法映射成助手规则：例如 IDE 的规则文件、或你们自研 Agent 的系统提示，让模型每次自动对照。
• 宪法变更要走流程：在 Confluence 上用“变更提案 → 讨论 → 审批 → 发布”，并保留版本记录。

---

三、规范层（2）：Spec——把一次性对话变成可复用的“任务说明书”

如果宪法回答的是“永远要怎么做”，Spec 回答的就是“这一次要做什么，做到什么程度算完成”。

3.1 Spec 分层：从需求到实现的最小集合

从落地效果看，不要一开始就建一套宏大体系；先抓住能显著提升成功率的 4 类 Spec：

1. 需求 Spec：目标、范围、验收标准、约束、非目标。
2. 接口/契约 Spec：API、事件、数据库 schema、错误码、兼容策略。
3. 实现 Spec：模块边界、关键流程、风险点、迁移步骤。
4. 测试 Spec：用例清单、回归范围、验证命令、观测指标。

3.2 Spec 最小模板（适合放 Confluence，也适合落盘到仓库）

## 背景
- 为什么要做：业务与技术动因

## 目标与非目标
- Goals:
- Non-goals:

## 方案概述
- 关键设计决策
- 影响面（模块/接口/数据/性能）

## 验收标准（Acceptance Criteria）
- [ ] ...
- [ ] ...

## 风险与回滚
- 风险：
- 监控：
- 回滚：

## 测试与验证
- 必跑命令：
- 回归范围：

3.3 用 OpenSpec 思路写“机器可执行的规则片段”

当你们开始稳定产出后，可以把常见约束进一步结构化，变成“可复用的规则片段”，让 AI 在生成时自动对齐（这里给一个轻量示例）：

name: WebServiceSpec
description: 约束后端接口新增与修改的交付标准

rules:
  - name: BackwardCompatibility
    pattern: "对外接口变更必须兼容旧调用方"
    details: "字段新增可选；字段删除/语义变更必须提供迁移期与灰度方案"

  - name: Observability
    pattern: "关键路径必须可观测"
    details: "至少包含结构化日志、关键指标埋点与错误告警策略"

  - name: TestsRequired
    pattern: "新增行为必须有自动化测试或可重复验证步骤"
    details: "单测优先；若无法单测，必须给出可脚本化的集成验证"

examples:
  - input: "新增创建订单接口"
    output: "给出接口契约、错误码、幂等策略、测试清单与回滚步骤"

3.4 Confluence 在 Spec 落地中的最佳用法（组织协作利器）

Confluence 最适合承载 Spec 的三个特性：

• 页面模板：强制所有 Spec 结构一致（验收标准、回滚、测试是必填）。
• 评审与审批：关键 Spec 必须 @Owner 审批后才能进入实现阶段。
• 版本与追溯：谁改了什么、为什么改、什么时候改，一目了然。

推荐你在团队空间里建立三个固定目录（或用标签体系也行）：

• Constitution：项目宪法与治理规则
• Specs：所有需求/接口/迁移 Spec（按系统/模块分组）
• Skills：技能目录、变更记录与使用手册

然后把仓库里的执行文件（宪法/Spec 片段/脚本入口）在 Confluence 中做成“索引页”，让新人从一个入口就能跑通整套体系。

---

四、能力层：Skills——把“会对话”升级为“会干活、能复用”

Skills 的本质是：把高频任务沉淀成标准输入输出 + 可调用工具 + 可验证结果。它是 AI Coding 从“偶尔好用”走向“生产力资产”的关键一跃。

4.1 什么是一个合格的 Skill

只要满足下面四点，就可以称为工程化 Skill：

要素	说明	验收方式
触发条件	什么时候该用它	有明确的使用场景描述
输入输出	输入字段、输出格式	输出可被下一步流程消费
边界与权限	允许/禁止的动作范围	违反边界必须中止
验证步骤	产出如何被验证	有可重复的命令/用例

你可以把 Skill 当作“一个可复用的 SOP + 工具箱”。Confluence 的 Skills 区域建议维护一份技能目录表，包含：Owner、版本、最近变更、风险等级、依赖系统。

4.2 技能分层：从“纯提示词”到“工具化技能”

落地上建议分三档推进，循序渐进：

1. 提示词技能：只固化流程与输出格式（最快见效）。
2. 仓库内脚本技能：把重复动作脚本化（例如生成模板、跑回归、抽取变更日志）。
3. 工具调用技能（MCP）：让 AI 能安全访问 Confluence/Jira/仓库/数据库等系统，做到“读写闭环”。

4.3 5 个最值得优先沉淀的技能（团队收益最高）

下面这五个 Skill 几乎适用于所有工程团队，建议优先落地：

1. Spec 生成器：根据需求对话生成符合模板的 Spec（并自动补齐验收/回滚/测试）。
2. 变更影响分析：给定一个改动点，输出调用链、影响面、回归建议。
3. 按宪法生成补丁：只改指定范围，严格遵守约定，并输出验证记录。
4. 审计式 Code Review：对照宪法与 Spec 的 Gate 输出逐条审计结论。
5. 发布前检查：聚合测试/构建/变更日志/风险提示，生成发布摘要。

如果你已经使用 Confluence，可以让 Skill 的默认输出直接变成“可发布的页面内容”：比如生成 Spec 后自动创建页面、生成 Review 后自动写评论、生成发布摘要后自动挂到版本发布页下。

---

五、一套可执行的落地路线图（从 0 到 1，再到可规模化）

5.1 第 0 阶段：先跑通“最小闭环”

• 选定一个试点项目：不要从全公司开始，先从一个中等复杂度服务开始。
• 宪法 v1：1 页纸，强制 Gate（必须跑哪些命令、必须补哪些测试）。
• Spec v1：先只要求“需求 Spec + 测试与回滚”两块齐全。
• Skill v0：先沉淀一个“按模板生成 Spec”的技能，让所有人用同一格式。

5.2 第 1 阶段：把“稳定性”做起来

• 建 Bench：用真实任务做回放。
• 做路由：Plan/Code/Review 三段式固定下来。
• 上治理：宪法与 Spec 的变更进入 Confluence 流程（Owner + 审批 + 版本）。

5.3 第 2 阶段：规模化（多人多项目复用）

• 技能目录化：每个 Skill 都有 Owner、版本、风险等级。
• 工具化：引入 MCP/脚本，让 Skill 具备自动化能力与审计能力。
• 指标化：统计一次任务的“返工次数、回归缺陷、交付耗时分布、违规率”等，用数据驱动迭代。

---

六、实战复盘与展望：来自 SEDP 项目的一线数据

理论是灰色的，而生命之树常青。我们在产品项目的 5 个版本及补丁中全面践行了这套打法，覆盖新功能开发、Bug 排查与代码重构。实战数据表明，综合研发效率提升超过 40%，但过程并非一帆风顺，以下是我们的真实复盘：

6.1 收益与短板：OpenSpec 驱动下的两重天

• 新功能开发：效果最显著。尤其在前端领域，基于 OpenSpec 规范生成的代码可用性极高，效率提升达 60%-70%；后端业务逻辑开发提升约 30%-40%。
• 存量维护（Bug 排查/修改）：效果不及预期。主要痛点在于 AI 缺乏完整的历史需求与业务背景（Context），导致在复杂逻辑排查时容易“一本正经胡说八道”。

6.2 效能边界的思考：50% 的天花板在哪里？

经过大量实践，我们发现 AI 辅助编程的提效上限目前约为 50%。

• 对于复杂业务：让 AI 全权负责代码编写，开发者需要花费大量时间编写高质量 Spec，甚至出现“写 Spec 的时间 > 自己写代码的时间”。
• 对于简单任务：直接手写往往比“写 Prompt -> 调整 -> 再调整”更快。

结论：不应追求“全自动”，而应根据具体项目的任务情况动态调整策略。开发人员的核心价值从“写代码”转向了“定义规范”与“判断 ROI”。

6.3 下一步演进：补齐业务背景

针对“缺背景”的痛点，我们计划将现有产品文档与知识库同步至 RAGFlow，为 AI 补齐业务上下文（Business Context）。同时，继续深化 OpenSpec 的落地颗粒度，用更标准化的输入换取更稳定的输出。

AI Coding 不是银弹，但它是催化剂。它倒逼我们把隐性的知识显性化，把随意的开发规范化。这不仅是工具的升级，更是研发文化的重塑。

---

从今天开始，不妨先做一件事：写出你们项目的宪法 v1，然后把下一个需求用 Spec 驱动一次交付。你会立刻感受到稳定性带来的复利。