开篇暴击：为什么你的AI总在"造图谱交差"？

先看一个真实案例。开发者让AI构建项目知识图谱，AI交出的成果是：

• ✅ 36个节点、42条边、12个社区，数字很漂亮
• ❌ 但只认真读了3个文件
• ❌ 剩下的节点和边是编出来的
• ❌ 图谱没有回答任何实际问题

这就是典型的"AI幻觉式交付"——看起来像样，实际上没用。

问题的根源是什么？AI不会自己建立规范，它只会执行你给它的约束。 没有规范、没有约束、没有反馈循环，AI就是个"高级文本生成器"，不是工程师。

2026年，AI工程的核心已经从"让AI写得更好"转向"让AI跑得更稳、更可控"。这就是Harness Engineering（驾驭工程）的核心理念：人类掌舵，智能体执行。

第一部分：先分场景，再谈方案

🆕 场景A：全新项目 —— 向外对标，顶层设计

核心逻辑：白纸一张，先定标准，再填代码

关键动作：

1. 需求与技术栈锁定：明确业务边界、性能指标、技术选型
2. 行业规范对齐：引入权威规范（如Java《阿里巴巴开发手册》、Vue《官方风格指南》）
3. 开源项目对标：挑选GitHub Stars > 5k的同技术栈优秀项目，拆解其架构
4. 规范固化：将共识转化为可执行文件（ .editorconfig、 eslint.config.js、 CLAUDE.md）

交付物：

• 《技术栈选型清单》
• 《行业规范映射表》
• 《架构参考蓝图》
• 《项目规范基线包》

🔄 场景B：二次开发/遗留项目 —— 向内挖掘，渐进治理

核心逻辑：规范已死，代码还活着。强推新规范=重构灾难

关键动作：

1. 规范逆向提取：扫描现有代码库，提取"事实规范"（实际怎么写的）
2. 差异与风险评估：对比"事实规范"与"目标规范"，划分优先级
3. 兼容层设计：为新规范设计适配层，避免直接侵入老逻辑
4. 分阶段落地：按模块/服务逐步替换，每个迭代只推1-2条新规范

交付物：

• 《现有代码基线报告》
• 《规范演进优先级矩阵》
• 《渐进式重构架构草图》
• 《重构里程碑计划》

第二部分：5套工具组合方案（附实战步骤）

基于当前最热门的开源工具：

• snarktank/ralph：自主代理工作流，长任务稳定运行
• Spec-Kit：GitHub官方出品，规范可执行化
• OpenSpec：轻量级规范层，灵活迭代
• Superpowers：技能驱动工作流，强制TDD
• gstack：决策+测试，把控方向与质量
• **Compound Engineering (CE)**：经验沉淀，实现知识复利

方案1：【新手友好型】OpenSpec + ralph

适用场景：

• 个人项目/小团队
• 快速迭代，频繁调整
• 不想折腾复杂配置

核心优势：

• OpenSpec支持20+ AI工具，无需API Key和MCP
• ralph提供长任务自主运行能力
• 学习曲线平缓，上手快

实施步骤：

# 1. 安装OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. 克隆ralph
git clone https://github.com/snarktank/ralph.git
cd ralph

# 3. 配置项目
mkdir -p your-project/scripts/ralph
cp ralph.sh CLAUDE.md your-project/scripts/ralph/
chmod +x ralph.sh

# 4. 创建第一个规范提案
/opsx:propose "实现用户登录功能，支持邮箱+密码，JWT鉴权"

# 5. 启动ralph自主执行
./scripts/ralph/ralph.sh --tool claude 20

工作流：

/opsx:propose → ralph自动执行 → /opsx:apply → 测试验证 → /opsx:archive

避坑指南：

• ⚠️ OpenSpec不直接生成代码，只是规范管理
• ⚠️ ralph需要Git初始化，确保项目已 git init
• ⚠️ Windows用户推荐用Git Bash或WSL

方案2：【企业级质量型】Spec-Kit + gstack + CE

适用场景：

• 大型企业项目
• 严格流程要求
• 需要可追溯性

核心优势：

• Spec-Kit：规范可执行，直接生成代码
• gstack：双重审核（CEO视角+工程师视角）
• CE：经验沉淀，避免重复踩坑

实施步骤：

# 1. 安装Spec-Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 2. 初始化项目
specify init my-project

# 3. 定义规范（.specify/specs/features/login.md）
# 编写User Story、验收标准、技术约束

# 4. 使用gstack审核
/plan-ceo-review   # 产品角度：这个功能值得做吗？
/plan-eng-review   # 架构角度：这个代码以后会不会出问题？

# 5. 执行规范生成代码
/speckit.implement

# 6. 使用gstack测试
/qa   # 真实浏览器端到端测试

# 7. 经验沉淀
/ce:compound   # 启动5个子Agent，提取经验到docs/solutions/

工作流：

constitution → specify → clarify → plan → tasks → analyze → implement
    ↓             ↓          ↓        ↓       ↓        ↓         ↓
 [门控]       [门控]     [门控]   [门控]  [门控]   [门控]    [门控]

避坑指南：

• ⚠️ Spec-Kit需要Python 3.11+和uv，环境配置有门槛
• ⚠️ 阶段门较严格，不适合频繁调整方向的项目
• ⚠️ 三个工具组合使用，需避免命令冲突

方案3：【质量优先型】Superpowers + ralph

适用场景：

• 对代码质量有严格要求
• 重视测试覆盖率
• 需要长任务自主运行

核心优势：

• Superpowers强制TDD（RED-GREEN-REFACTOR循环）
• 自动技能触发，减少人为疏漏
• ralph提供持久记忆和长任务稳定运行

实施步骤：

# 1. 安装Superpowers（以Claude Code为例）
/plugin install superpowers@claude-plugins-official

# 2. 配置ralph
cp ralph.sh CLAUDE.md your-project/scripts/ralph/
chmod +x ralph.sh

# 3. 启动开发（技能自动触发）
# 你只需要说：我想给登录功能加一个"记住我"选项

# Superpowers会自动：
# 1. 激活brainstorming技能，细化需求
# 2. 激活writing-plans技能，生成实现计划
# 3. 激活test-driven-development技能，先写测试
# 4. 实现功能
# 5. 激活verification-before-completion技能
# 6. 激活requesting-code-review技能

# 4. 长任务交给ralph
./scripts/ralph/ralph.sh --tool claude 50

核心技能示例：

# test-driven-development skill

## Trigger
When writing new code or modifying existing code

## Workflow
1. RED: Write a failing test
2. GREEN: Write minimal code to pass
3. REFACTOR: Improve code quality
4. Repeat until feature complete

## Constraints
- Never skip the RED phase
- Always run tests after GREEN phase
- Refactor only when tests pass

避坑指南：

• ⚠️ Superpowers非规范驱动，没有独立规范层
• ⚠️ 依赖代理平台，安装方式因平台而异
• ⚠️ 缺少正式文档站点，主要靠GitHub README

方案4：【遗留系统改造型】OpenSpec + CE + ralph

适用场景：

• 现有代码库的渐进式现代化
• 需要提取事实规范
• 避免一次性重构风险

核心优势：

• OpenSpec明确打出"built for brownfield"旗号
• CE自动扫描项目历史，避免重复踩坑
• ralph提供长任务稳定执行

实施步骤：

# 1. 逆向提取现有规范
# 让AI扫描代码库，提取命名习惯、错误码格式、DB访问模式
"分析src/目录下所有文件，提取：
1. 命名规范（类名、方法名、变量名）
2. 异常处理模式
3. 数据库访问模式
4. 公共工具类分布
输出《现有代码基线报告》"

# 2. 创建变更提案（渐进式）
/opsx:propose "重构用户模块，提取公共验证逻辑到Common/Validator"

# 3. CE研究Agent扫描历史
/ce:plan   # 自动扫描git提交记录、历史Bug

# 4. 执行重构
/opsx:apply refactor-user-module

# 5. 经验沉淀
/ce:compound   # 记录重构过程中的踩坑经验

# 6. 长任务交给ralph
./ralph.sh --tool claude 30

工作流：

提取事实规范 → 差异评估 → 兼容层设计 → 分模块重构 → 经验沉淀
     ↓              ↓            ↓             ↓           ↓
 [扫描代码]    [优先级矩阵]  [适配层设计]   [CI门禁]   [docs/solutions/]

避坑指南：

• ⚠️ 不要一次性推所有新规范，每个迭代只推1-2条
• ⚠️ 核心稳定模块限制AI权限，只能生成Patch，必须人工Review
• ⚠️ 建立反模式库（ANTI_PATTERNS.md），记录AI常犯错误

方案5：【全栈豪华型】Spec-Kit + Superpowers + gstack + CE + ralph

适用场景：

• 超大型项目
• 多团队协作
• 追求极致质量和效率

核心优势：

• 全链路覆盖：规范生成→技能触发→双重审核→经验沉淀→长任务执行
• 质量门最严格
• 知识复利最大化

实施步骤：

# 1. 定义规范（Spec-Kit）
specify init mega-project
# 编写.specify/specs/下的规范文件

# 2. 双重审核（gstack）
/office-hours   # AI采访，挖透真实需求
/plan-ceo-review   # 产品审核
/plan-eng-review   # 架构审核

# 3. 技能触发开发（Superpowers）
# 自动激活TDD、系统化调试、代码审查等技能

# 4. 执行规范生成代码（Spec-Kit）
/speckit.implement

# 5. 端到端测试（gstack）
/qa   # 真实浏览器测试

# 6. 经验沉淀（CE）
/ce:compound   # 启动5个子Agent，提取经验

# 7. 长任务自主运行（ralph）
./ralph.sh --tool claude 100

工作流全景：

需求挖掘 → 规范定义 → 双重审核 → 技能触发 → 规范执行 → 测试验证 → 经验沉淀
   ↓          ↓          ↓          ↓          ↓          ↓          ↓
[AI采访]  [Spec-Kit] [gstack] [Superpowers] [Spec-Kit]  [gstack]   [CE]
                                                              ↓
                                                        长任务执行
                                                            ↓
                                                         [ralph]

避坑指南：

• ⚠️ 五个工具组合，命令冲突风险高，需仔细配置
• ⚠️ 学习曲线陡峭，团队培训成本高
• ⚠️ 不是所有项目都需要这么豪华的配置，小项目用方案1或2即可

第三部分：Harness Engineering（驾驭工程）四大护栏

无论选择哪套方案，都必须建立以下四大护栏：

护栏1：上下文工程 —— AI的"活态员工手册"

错误做法：

# CLAUDE.md（静态厚文档）
- 必须使用驼峰命名
- 必须写注释
- 必须写单元测试
...（1000行）

正确做法：

# CLAUDE.md（动态反馈循环）
## 历史失败案例
- 2026-01-15：直接new Thread导致线程泄漏 → 必须使用@ThreadPoolConfig
- 2026-01-20：硬编码URL导致配置漂移 → 所有外部地址必须走ConfigCenter
- 2026-02-01：未加事务导致数据不一致 → 写操作必须加@Transactional

## 按需检索指令
遇到不确定时，先搜索：
- /search docs/solutions/ 类似问题的解决方案
- /search src/common/ 是否有现成工具类

护栏2：架构约束 —— AI的"刚性缰绳"

实施方法：

# .github/workflows/arch-lint.yml
name: Architecture Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check Layer Dependencies
        run: |
          # 检查分层依赖：Types → Config → Repo → Service → Runtime → UI
          # 下层不得反向依赖上层
          ./scripts/check-architecture.sh
      - name: Check Code Reuse
        run: |
          # 检查是否有重复代码（相同逻辑≥3次必须提取）
          ./scripts/check-duplication.sh

Linter错误信息示例：

❌ 违反架构规则：Service层直接依赖UI层
📖 规则说明：分层依赖必须是单向的，下层不得反向依赖上层
✅ 正确做法：通过事件总线或依赖注入解耦
🔧 自动修复：运行 ./scripts/refactor-decouple.sh

护栏3：反馈循环 —— AI的"自我审查机制"

实施方法：

# pre-commit hook
#!/bin/bash
# 1. 运行测试
npm test

# 2. 运行Linter
npm run lint

# 3. 如果有错误，让AI自动修复
if [ $? -ne 0 ]; then
  echo "❌ 检查失败，启动AI自动修复..."
  claude --prompt "修复以下错误：$(npm run lint 2>&1)"
  
  # 重新检查
  npm run lint
  if [ $? -ne 0 ]; then
    echo "❌ AI修复失败，请人工介入"
    exit 1
  fi
fi

CI/CD门禁：

# GitHub Actions
- name: AI Code Review
  uses: actions/github-script@v7
  with:
    script: |
      // 让AI审查PR
      const review = await claude.reviewPR(context.payload.pull_request);
      if (review.hasIssues) {
        core.setFailed(review.comments);
      }

护栏4：熵管理 —— AI系统的"垃圾回收与债务清零"

实施方法：

# 定期运行后台任务（每周）
#!/bin/bash
# 1. 扫描技术债务
./scripts/scan-tech-debt.sh > tech-debt-report.md

# 2. 扫描文档与代码不一致
./scripts/scan-doc-drift.sh > doc-drift-report.md

# 3. 自动提交修复PR
git add .
git commit -m "chore: 自动修复技术债务和文档漂移"
git push origin tech-debt-fix

CE的文档园丁Agent：

# docs/gardening-agent.md
## 职责
- 自动扫描docs/目录，发现过时内容
- 对比代码变更，更新相关文档
- 提交PR修复不一致

## 触发条件
- 每次main分支合并后
- 每周日凌晨2点定时任务

第四部分：避坑指南（血泪教训）

坑1：造图谱交差

症状：

• AI生成的知识图谱看起来很漂亮（节点多、边多、社区多）
• 但只读了3个文件，剩下的都是编的
• 图谱没有回答任何实际问题

解决方案：

# 正确的知识图谱构建指令
"请按以下步骤构建知识图谱：

1. **逐文件扫描**：
   - 遍历src/目录下所有文件
   - 提取每个文件的：类名、方法名、依赖关系
   
2. **事实验证**：
   - 每个节点必须有文件路径和行号
   - 每条边必须有调用关系证据
   
3. **问题回答能力**：
   - 图谱必须能回答：'我上次修复的Bug对应的代码模式是什么？'
   - 图谱必须能回答：'哪些模块使用了UserService？'
   
4. **增量更新**：
   - 每次代码变更后，自动更新图谱
   - 记录变更历史

输出格式：
- 节点：{name, type, filePath, lineRange}
- 边：{from, to, type, evidence}
"

坑2：规范文档化，不代码化

症状：

• 写了100页规范文档
• AI完全不看，继续乱写
• 团队也不遵守

解决方案：

# 规范必须转化为可执行代码
# ❌ 错误：规范只在文档里
"必须使用驼峰命名"

# ✅ 正确：规范在Linter里
# .eslintrc.js
module.exports = {
  rules: {
    'camelcase': 'error',
    'no-console': 'error'
  }
};

# ✅ 正确：规范在CI门禁里
# .github/workflows/lint.yml
- name: Lint
  run: npm run lint
  # 失败则阻断合并

坑3：一次性推所有规范

症状：

• 老项目一次性引入20条新规范
• CI全红，无法合并
• 团队抵触，放弃执行

解决方案：

# 渐进式规范落地计划

## 第1周：基础规范（必须改）
- [ ] 代码格式化（Prettier）
- [ ] 基础Linter规则（ESLint）

## 第2周：架构规范（建议改）
- [ ] 分层依赖检查
- [ ] 禁止循环依赖

## 第3周：质量规范（逐步改）
- [ ] 单元测试覆盖率≥80%
- [ ] 代码复用检查

## 第4周：安全规范（必须改）
- [ ] 敏感信息脱敏
- [ ] SQL注入检查

每个阶段：
1. 先在新代码中执行
2. 老代码逐步重构
3. CI门禁逐步收紧

坑4：AI权限过大

症状：

• AI直接修改核心支付模块
• 引入严重Bug
• 线上事故

解决方案：

# AI权限分级

## Level 1：只读权限
- 核心支付/财务模块
- AI只能查看，不能修改

## Level 2：生成Patch权限
- 业务逻辑模块
- AI生成Patch，必须人工Review后合并

## Level 3：自动合并权限
- 测试代码
- 文档更新
- AI可直接合并

# 实施方法
# CODEOWNERS
/docs/ @ai-bot
/tests/ @ai-bot
/src/payment/ @human-reviewers

第五部分：实战案例

案例1：某电商公司新项目（方案2：Spec-Kit + gstack + CE）

背景：

• 技术栈：Java 17 + Spring Boot 3 + Vue3 + TypeScript
• 团队：8人（3前端、4后端、1架构师）
• 目标：6个月上线MVP

实施过程：

第1周：规范对齐

# 1. 引入阿里巴巴Java开发手册
# 2. 引入Vue官方风格指南
# 3. 对标GitHub优秀项目（mall、ruoyi-vue-pro）

# 4. 生成规范基线
specify init ecommerce-platform
# 生成.specify/目录下的规范文件

第2周：工具配置

# 1. 配置gstack
/plan-ceo-review   # 审核每个功能的产品价值
/plan-eng-review   # 审核架构合理性

# 2. 配置CE
/ce:brainstorm   # 头脑风暴
/ce:plan        # 研究Agent扫描历史

# 3. 配置CI门禁
# GitHub Actions自动运行Checkstyle、SonarQube

第3-20周：开发迭代

# 每个迭代流程：
1. /office-hours   # AI采访，明确需求
2. /plan-ceo-review   # 产品审核
3. /plan-eng-review   # 架构审核
4. /speckit.implement   # 生成代码
5. /qa   # 端到端测试
6. /ce:compound   # 经验沉淀

成果：

• 6个月按时上线MVP
• 代码质量：SonarQube A级，测试覆盖率85%
• 经验沉淀：docs/solutions/目录下127条解决方案
• 重复踩坑率：从第1个月的30%降至第6个月的3%

案例2：某金融公司老系统改造（方案4：OpenSpec + CE + ralph）

背景：

• 系统：10年历史的Java单体应用
• 代码量：50万行
• 问题：技术债务严重，无规范，无测试
• 目标：渐进式改造为微服务

实施过程：

第1个月：规范逆向提取

# 1. 让AI扫描代码库
"分析所有Java文件，提取：
1. 命名习惯（类名、方法名、变量名）
2. 异常处理模式（try-catch分布）
3. 数据库访问模式（JDBC/MyBatis）
4. 公共工具类分布
输出《现有代码基线报告》"

# 2. 差异评估
# 对比事实规范与目标规范（Spring Boot最佳实践）
# 输出《规范演进优先级矩阵》

# 3. 创建OpenSpec变更提案
/opsx:propose "提取用户模块为独立服务"

第2-6个月：分模块重构

# 每个模块重构流程：
1. /opsx:propose "重构X模块"
2. /ce:plan   # CE扫描历史Bug和踩坑经验
3. /opsx:apply   # 执行重构
4. ralph自主运行长任务
5. /ce:compound   # 沉淀经验

# 优先级：
- 第1个月：用户模块（低风险）
- 第2个月：订单模块（中风险）
- 第3个月：支付模块（高风险，人工Review）
- 第4-6个月：其他模块

成果：

• 6个月完成5个核心模块微服务化
• 线上事故：0次（渐进式改造，兼容层保护）
• 技术债务：从D级降至B级
• 团队满意度：从3/10提升至8/10

总结：AI编程规范落地的核心公式

规范落地 = 场景区分 × 工具组合 × 四大护栏 × 渐进执行

1. 场景区分（必须做）

• 新项目：向外对标，顶层设计
• 老项目：向内挖掘，渐进治理

2. 工具组合（按需选）

3. 四大护栏（必须有）

• 上下文工程：CLAUDE.md动态反馈循环
• 架构约束：Linter + CI门禁
• 反馈循环：pre-commit + AI自动修复
• 熵管理：定期技术债务扫描

4. 渐进执行（必须做）

• 不要一次性推所有规范
• 每个迭代只推1-2条
• 先新代码，后老代码
• 先建议，后强制

最后的话

AI不会自己建立规范，它只会执行你给它的约束。

2026年，AI工程的核心已经从"让AI写得更好"转向"让AI跑得更稳、更可控"。工程师的角色正在发生根本性转变——从"代码的编写者"转变为"AI运行环境的建筑师"。

正如Birgitta Böckeler所说：

"为了获得更高的AI自主性，运行时必须受到更严格的约束。增加信任需要的不是更多自由，而是更多限制。"

规范的质量，决定了AI编码的上限。

选择适合你的方案，开始构建你的AI驾驭系统吧！

参考资源：

• 📦 snarktank/ralph：https://github.com/snarktank/ralph
• 📦 Spec-Kit：https://github.com/github/spec-kit
• 📦 OpenSpec：https://github.com/fission-ai/openspec
• 📦 Superpowers：https://github.com/obra/superpowers
• 📦 Compound Engineering：https://github.com/everydotdev/compound-engineering
• 📦 gstack：https://github.com/garrytan/gstack

你在用哪套方案？评论区聊聊你的实战经验！