从宪法到代码：用Spec-Kit重塑Codex驱动的AI工程化实践

1. 为什么AI编码需要工程化约束？

最近两年，AI辅助编程工具如Codex、Copilot的爆发式增长，让很多开发者养成了"随口提问、直接生成"的习惯。这种模式在小规模临时脚本编写时确实高效，但当我在团队项目中观察到一个现象：三个月前用AI生成的模块，现在没人敢动——因为没人记得当初的生成逻辑，也没有任何文档说明边界条件。这让我意识到，缺乏工程化约束的AI编码就像在沙滩上盖房子。

工程化的核心矛盾在于：AI生成具有随机性，而软件工程要求确定性。去年我们团队做过一次统计，未经规范的AI生成代码在三个月后的维护成本是手工代码的2.3倍。主要表现在：

• 上下文断裂：Prompt与生成代码的关联性随时间消失
• 边界模糊：非功能性需求（如性能、安全）缺乏显式约束
• 架构漂移：多次生成导致系统结构逐渐失控

Spec-Kit提供的"宪法优先"（Constitution-First）方法，本质上是在AI的创造力与工程纪律之间建立缓冲层。就像建筑行业要先打地基再盖楼，我们通过.specify/memory/constitution.md预先定义：

markdown复制# 隐私宪法
• 所有用户数据必须经过脱敏才能进入日志系统
• 前端禁止存储超过1MB的本地缓存

# 性能宪法
• API响应时间超过500ms必须启用缓存
• 列表渲染超过100条必须实现虚拟滚动

这种约束不是限制创新，而是为AI划定安全创新区。实际项目中，我们用它成功避免了多次潜在事故——比如有次Codex试图生成全量数据导出的SQL时，宪法中的"数据权限"条款自动触发了分页机制。

2. Spec-Kit工作流解剖

2.1 宪法设计实战技巧

写宪法不是立规矩，而是建立团队共识。我们摸索出的最佳实践是采用"负面清单"形式：

markdown复制# 禁止条款
🚫 不得在未经验证的情况下执行动态SQL
🚫 不得在前端硬编码API密钥

# 必须条款
✅ 所有错误处理必须包含用户可读信息
✅ 异步操作必须提供取消机制

这种写法比抽象原则更易执行。有个实际案例：当新成员尝试用AI生成动态表单时，宪法里的"禁止eval"条款自动将方案引导到安全的JSON Schema实现。

2.2 规格说明书（Spec）的黄金结构

好的Spec应该像产品经理的需求文档，但更侧重技术边界。这是我们验证过的模板：

markdown复制## [功能名称]规格
### 不做什么
• 不支持IE11以下浏览器
• 不处理并发写冲突

### 死亡案例
• 用户上传2GB文件时？
• 第三方API返回HTML而非JSON时？

在电商项目实践中，明确"不做什么"帮我们节省了38%的无效开发。比如有个商品推荐模块，通过事先声明"不做实时个性化"，避免了复杂的用户画像系统开发。

3. 从Plan到Implement的防坑指南

3.1 计划阶段的模块切割术

Plan阶段最容易犯的错误是模块划分过粗。我们发明了"5分钟测试法"：如果一个模块的描述超过5分钟讲不清楚，就需要继续拆分。例如：

markdown复制## 支付模块计划
### 拆分前
- 处理所有支付相关逻辑

### 拆分后
1. 支付方式路由
2. 支付宝适配器
3. 微信支付适配器
4. 结果回调处理器

这种颗粒度让后续的AI生成更精准。实测显示，合理拆分的模块首次生成通过率能提升60%。

3.2 任务拆分的艺术

Tasks不是待办列表，而是可验证的交付单元。关键要包含验收条件和依赖声明：

markdown复制- [ ] 用户登录API
  ✅ 测试：连续错误5次触发锁定
  ⚠️ 依赖：先完成限流中间件

在最近的后台项目里，我们通过这种明确的任务卡点，将Codex的返工率从45%降到了12%。

4. 一致性维护的自动化策略

4.1 Analyze命令的进阶用法

除了基础的/prompts:speckit.analyze，我们还开发了自动化检查脚本：

bash复制#!/bin/bash
# 预提交检查
spec-kit analyze --diff HEAD~1
if [ $? -ne 0 ]; then
  echo "违反宪法变更！"
  exit 1
fi

这个脚本集成到Git hooks后，成功拦截了多次危险的AI生成代码提交，比如有次尝试引入未经验证的第三方SDK。

4.2 版本化宪法管理

随着项目演进，宪法也需要迭代。我们采用分支策略：

code复制constitution/
  ├── v1-basic.md
  ├── v2-security.md
  └── v3-gdpr.md

每次大版本升级时，用spec-kit migrate命令自动更新所有关联的Spec文件，确保约束条件同步更新。这套机制在金融项目的数据合规改造中发挥了关键作用。

在持续交付流水线中，我们增加了Spec检查环节：任何AI生成的代码必须通过宪法测试、Spec一致性检查、任务覆盖率验证三道关卡。这使AI生成代码的生产环境缺陷率降到了人工代码同等水平。