【AI启示录】2025 w14：文档集 + 规则库 + 循环迭代 = 好的氛围编程

推荐语

探索AI编程新境界，发现文档集、规则库与循环迭代的协同魅力。

核心内容：
1. AI编程新模式：文档集、规则库、循环迭代的融合
2. stdlib规则库：AI的“外部大脑”与智能提升机制
3. IF-THIS-THEN-THAT：规则设计的简洁原则与实践案例

杨芳贤

53A创始人/腾讯云(TVP)最具价值专家

题记

上周在"懒人编程新境界：让AI写代码，你只需写文档"一文中，我探讨了"文档驱动的氛围编程"这种新型开发模式。发布之后，读者和我自己都有一系列的疑问：如何建立Cursor的规则系统？文档集应该如何与规则库配合？它们在编程的过程中如何演进？

带着这些问题，我继续调研，在读了大量文章之后，发现了Geoffrey Huntley的From Design doc to code，对AI编程做了更加深入的实践，他提出了一个公式：

文档集(specs) + 规则库(rules) + 循环迭代(loopback) = 好的氛围编程?

原文中，作者把规则库称为stdlib，我觉得rules更贴切，更普适。

今天，我将分享这三要素如何协同工作，以及如何通过开源项目"Groundhog"将其付诸实践。

1. stdlib：建立AI的"外部大脑"

1.1 什么是stdlib？

你有没有遇到过这种情况：AI助手今天学会了某个特定的编码风格，明天又完全"忘记"了？这就是AI的"健忘症"问题。

Geoffrey Huntley在他的实践中提出了一个解决方案：stdlib（规则库）。这不是传统编程语言中的标准库，而是一套规则文件集合，它们共同构成了AI的"外部大脑"或"长期记忆"。

在Cursor中，规则库以.mdc规则文件的形式存在，整齐地存放在项目的.cursor/rules/目录下：

PROJECT_ROOT/
├── .cursor/
│   └── rules/
│       ├── python-style.mdc       // Python编码规范
│       ├── git-commit.mdc         // 自动提交规则
│       ├── security-checks.mdc    // 安全检查规则
│       └── ...
└── ...

每个规则文件就像一个"记忆胶囊"，定义了特定编程场景中AI应该如何思考和行动。

1.2 规则驱动的智能提升机制

规则库的魔力在于解决了AI的"健忘"问题。Huntley一针见血地指出："当前的基础LLM模型准确率大约在45%左右，需要频繁引导。"

但通过不断丰富规则库，这个数字能大幅提升！其工作原理是：

• 当AI犯错时，你纠正它
• 将这次纠正转化为规则，永久记录到规则库中
• 在后续开发中，AI会参考这些规则，避免重蹈覆辙

这形成了一个正向循环：AI错误→人工干预→规则记录→AI改进→更少错误→更高效率

效果有多惊人？Huntley只用了8小时构建规则库，就将AI输出的准确率大幅提升，从简单的代码提交到复杂的Linux内核补丁，都能稳定输出。在我自己的SQL-Agent项目中，也获得了类似的飞跃：从反复纠错到一次成功的愉悦体验！

1.3 规则设计的核心原则：IF-THIS-THEN-THAT

有效的规则遵循一个简单但强大的原则：IF-THIS-THEN-THAT条件触发机制。就像写代码一样："如果遇到这种情况，就执行那个操作"。

看一个真实的例子，这是一个自动提交代码的规则：

# Git Conventional Commits

Rule for automatically committing changes made by CursorAI using conventional commits format.

<rule>
name: conventional_commits
description: Automatically commit changes made by CursorAI using conventional commits format
filters:
  - type: event
    pattern: "build_success"  # 当构建成功时触发
  - type: file_change
    pattern: "*"              # 适用于所有文件变更

actions:
  - type: execute
    command: |
      # 根据变更描述智能提取提交类型
      CHANGE_TYPE=""
      case "$CHANGE_DESCRIPTION" in
        *"add"*|*"create"*|*"implement"*) CHANGE_TYPE="feat";;
        *"fix"*|*"correct"*|*"resolve"*) CHANGE_TYPE="fix";;
        *"refactor"*|*"restructure"*) CHANGE_TYPE="refactor";;
        *"test"*) CHANGE_TYPE="test";;
        *"doc"*|*"comment"*) CHANGE_TYPE="docs";;
        *"style"*|*"format"*) CHANGE_TYPE="style";;
        *"perf"*|*"optimize"*) CHANGE_TYPE="perf";;
        *) CHANGE_TYPE="chore";;
      esac

      # 从文件路径提取作用域
      SCOPE=$(dirname "$FILE" | tr '/' '-')

      # 提交变更
      git add "$FILE"
      git commit -m "$CHANGE_TYPE($SCOPE): $CHANGE_DESCRIPTION"

  - type: suggest
    message: |
      Changes should be committed using conventional commits format...

examples:
  - input: |
      # 在添加新函数后
      CHANGE_DESCRIPTION="add user authentication function"
      FILE="src/auth/login.ts"
    output: "feat(src-auth): add user authentication function"

metadata:
  priority: high
  version: 1.0
</rule>

太棒了！这个规则实现了一个魔法：当构建成功时，自动提交代码变更，并根据变更描述智能选择合适的提交类型（feat、fix等）。这意味着你再也不用手动敲git commit命令了！?

规则可以执行多种强大操作：

• reject：对不符要求的代码说"不"（比如拒绝不安全的代码）
• suggest：提供改进建议（比如更好的编码实践）
• execute：执行命令（如上例中的git提交）
• notify：发送通知（提醒你重要事项）

通过组合这些操作，我们可以像训练宠物一样"训练"AI，确保它始终遵循最佳实践工作。懒人编程的最高境界！

1.4 构建你自己的AI规则库

想开始打造自己的AI规则库吗？这比你想象的简单多了！最佳方法是从几个基础规则开始，然后逐步扩展。就像搭积木一样，一块一块地构建你的AI"外部大脑"。

以下是几个必备的规则类别：

1. 编码规范规则：让AI统一代码风格，就像团队里的老程序员一样严格
2. 安全最佳实践：防止AI生成含有SQL注入、XSS等常见安全漏洞的代码
3. 架构约束：确保AI生成的代码符合你的系统架构，不会乱搞
4. 工作流自动化：让AI帮你处理提交、测试等繁琐流程
5. 错误记忆：记录AI常犯的错误及解决方案，防止重蹈覆辙

最神奇的是，你可以让AI帮你创建这些规则！正如Huntley所说："当Cursor在你干预后做对了事情，让它编写或更新规则，记录学到的经验。"

这就像教一个学生编程，当他终于理解了某个概念，立刻让他把这个理解写下来，形成自己的"学习笔记"。只不过这个"笔记"会永久地增强AI的能力！

2. specs：AI编程的地图与指南针

2.1 specs是什么？

如果说规则库是AI的"外部大脑"，那么specs（文档集）就是项目的"灵魂"。没有灵魂的开发，就像没有目的地的旅行——可能很有趣，但很难到达想去的地方。

文档集是一系列结构化文档，清晰定义了项目的需求、架构、API设计和实现计划。在我上周文章中提到的"implementation-plan.mdc就是项目的灵魂"，正是这个概念。

在Groundhog项目中，文档集以markdown文件形式整齐地存储在specs/目录下：

PROJECT_ROOT/
├── specs/
│   ├── SPECS.md            # 总览文档（项目的"地图"）
│   ├── core/
│   │   ├── architecture.md # 系统架构
│   │   └── data-model.md   # 数据模型
│   ├── ui/
│   │   └── components.md   # UI组件规格
│   └── ...
└── ...

这些文档的存在，对AI来说就像GPS导航对司机一样重要！

2.2 文档集与规则库的协同效应

文档集和规则库的结合使用产生了1+1>2的神奇效果：

• 文档集告诉AI"做什么"——功能、目标和预期结果
• 规则库告诉AI"怎么做"——编码风格、架构约束和最佳实践

这种组合极大地提高了AI输出的准确性和一致性。效果有多惊人？Vivek Haldar分享了他的经历："使用规范驱动的氛围编程，我只用周六下午的时间就完成了一个完整的时间追踪应用，从几点想法到可运行代码，一气呵成！"

在实践中，这意味着你可以：

1. 先让AI根据你的简单想法，拓展出完整产品规格
2. 用另一个模型生成工程设计文档
3. 带着这两个文档享受"零样本氛围编程"的畅快体验

2.3 规格域的概念与并行开发

随着项目规模扩大，单个AI会话很难处理整个复杂系统。这时，Geoffrey Huntley提出的"规格域"（specification domain）概念就显得非常关键了！

规格域是指将项目按功能区域分解为相对独立的部分，例如：

• src/core - 核心应用逻辑（大脑）
• src/ai/mcp_tools - MCP工具（工具箱）
• src/ui - 用户界面（脸面）

每个域有自己独立的文档集，这种分解让我们可以：

1. 先实现核心基础功能，打好基础
2. 然后启动多个Cursor实例，分别处理不同域的开发（多AI协作）
3. 最后像乐高积木一样，整合所有组件

这种方法让AI编程可以扩展到更大规模的项目，实现真正的并行开发。从单兵作战到指挥团队的飞跃！

2.4 多会话并行开发技术

想象一下，如果你能同时指挥多个AI助手，每个负责一个模块，效率会提高多少？这就是"多会话并行开发"的魅力！

实现这种并行开发的关键是使用git-worktree创建独立的工作目录：

git worktree add ../project-core core
git worktree add ../project-ui ui

然后，你可以为每个工作目录启动一个Cursor实例，实现真正的并行开发。Huntley将这种方法形象地称为"multi-boxing"（多开），它让开发者能够同时管理多个AI助手，就像游戏中同时操控多个角色一样。

效率提升有多大？Huntley提到他能在几小时内完成原本需要数周的工作量！这就像是从带领一个程序员，变成指挥一个小型开发团队。?

3. loopback：氛围编程的秘密武器

3.1 什么是循环迭代机制？

规则库和文档集很重要，但还缺少一个关键环节：如何让AI持续保持在正轨上？这就是循环迭代（loopback）的魔力所在！

循环迭代是更好氛围编程的秘密武器，就像DJ不断调整音乐节拍一样，它持续将文档集、规则库和环境信息反馈给AI，确保AI始终按照正确的"节拍"工作。

Geoffrey Huntley分享了一个简洁而强大的循环迭代提示词模板（可以直接复制使用）：

Study @SPECS.md for functional specifications.
Study @.cursor for technical requirements
Implement what is not implemented
Create tests
Run a "cargo build" and verify the application works

这个看似简单的提示词模板实际上是一个强大的指令集，让AI能够：

1. 理解项目的功能需求（文档集）：先知道要做什么
2. 遵循技术约束和最佳实践（规则库）：再知道怎么做
3. 实现缺失的功能：动手做出来
4. 创建测试确保质量：验证做得对不对
5. 验证代码是否正常工作：确保能跑起来

3.2 为什么循环迭代如此重要？

想象一下AI就像一个聪明但记忆力有限的新员工。当项目变得复杂时，单次对话无法让它记住所有要点和上下文。循环迭代解决了这个问题 —— 它定期"提醒"AI应该关注什么，就像对新员工进行周期性复训一样。

循环迭代的神奇之处在于：

• 解决上下文窗口限制：即使最强大的AI模型也有上下文长度限制，循环迭代确保重要信息不会被"挤出"记忆
• 维持开发连贯性：即使重启会话，也能保持项目开发的连贯性
• 利用编译器反馈：将编译错误作为新的输入，指导AI改进代码
• 防止"目标漂移"：确保AI不会逐渐偏离原始需求

Huntley给出了一个关键建议："当AI偏离正轨时，不要沮丧，直接重启一个新的会话，使用同样的循环迭代提示，直到所有功能都实现。"

这种方法特别适合与强类型编程语言（如Rust和Haskell）结合使用。想象一下：AI写代码→编译器报错→错误反馈给AI→AI修复问题→代码改进。这形成了一个自然的、不断进步的循环！

4. Groundhog：三要素的完美实践案例

来看一个真实案例！Geoffrey Huntley的开源项目"Groundhog"完美展示了文档集、规则库和循环迭代三要素如何协同工作。Groundhog是一个AI无头代理编码助手，完全由AI辅助编程实现，代码质量令人惊艳。

4.1 从零开始一个Groundhog式项目

想尝试这种方法？以下是启动一个类似项目的步骤（我亲测有效）：

第一步：创建基础规则 这是你的第一个提示词，直接复制到Cursor中：

Create a Cursor IDE AI MDC rule in ".cursor/rules" which instructs Cursor to always create new MDC rules in that folder. Each rule should be a separate file.

第二步：定义编码规范 接着，让AI帮你创建语言特定的编码规范：

Create a new Cursor MDC rule for all *.rs files (in all subdirectories).
You are an expert software engineer who knows rust. In fact, you are the software engineer who created rust.
Your task is to come up with technical recommendations in this rule which document best practices when authoring rust.

第三步：创建文档集 现在，告诉AI你想要构建什么：

We are going to create an AI coding assistant command line application in rust. The AI coding assistant is called "groundhog".

It uses the "tracing" crate for logging, metrics and telemetry.
All operations have appropriate tracing on them that can be used to troubleshoot the application.

Use the clap cargo crate for command line parsing.

The first operation is
"$ groundhog explain"

When groundhog explain is invoked it prints hello world.

IMPORTANT: Write up the specifications into the "specs/" folder with each domain topic (including technical topic) as a separate markdown file. Create a "SPECS.md" in the root of the directory which is an overview document that contains a table that links to all the specs.

第四步：启动循环迭代 最后，使用这个循环迭代提示词开始编码：

Study @SPECS.md for functional specifications.
Study @.cursor for technical requirements
Implement what is not implemented
Create tests
Run "cargo build" and verify the application works

神奇的是，AI会根据文档集和规则库，一步步实现功能，并且质量越来越高！如果AI在某处卡住，只需重启一个新会话，使用相同的循环迭代提示，直到功能完成。

4.2 扩展项目规模：从单兵作战到团队协作

当基础功能实现后，就可以通过添加新规格域来扩展项目规模了。这就像从一个人创业，逐步扩张成一个小团队。例如，添加新的MCP工具模块：

Look at specifications in @specs.
New requirement.

What should be implemented for MCP (model context protocol) registry? Include security best practices.
What should be implemented for a new MCP (model context protocol) tool that can be invoked to list directory contents ("ls"). Include security best practices.
Provide a LLM system prompt for this MCP protocol tool.

Update with this guidance. Store them under "specs/mcp" with each technical topic as a separate markdown file.

然后，你可以：

1. 创建一个新的git工作树：git worktree add ../groundhog-mcp mcp
2. 在新工作目录中启动一个新的Cursor会话
3. 使用相同的循环迭代提示词实现新功能

这样，你就能同时在不同的模块上并行开发，大大加快进度！就像有了多个AI助手组成的小型开发团队！??‍??

结语：氛围编程的艺术与未来

更好的氛围编程绝不是把自己完全交给AI，放飞自我。恰恰相反，它是一种建立结构化框架的艺术，让AI在这个框架内发挥最大潜力。

文档集、规则库和循环迭代三要素共同构成了这个框架：

• 文档集定义了目标和期望（做什么）
• 规则库确保AI遵循最佳实践（怎么做）
• 循环迭代保持AI在正确轨道上（持续改进）

随着这三要素的不断完善，AI编程的准确率和效率会持续提升，从最初的45-50%飙升到90%以上。更重要的是，这种方法让每次与AI的交互都成为一次积累，每个项目都比上一个项目更顺利，更高效。

就像我在上篇文章中提到的那样：写文档成为了编程过程中最有价值的环节。当我们利用文档集、规则库和循环迭代三要素，文档不再只是记录，而是成为指导AI的关键工具，成为项目的灵魂和大脑。

借用Huntley的比喻："规则驱动的氛围编程就像是教会AI骑自行车。首先你教它什么是踏板，然后纠正它的错误，最终它不仅能自己组装自行车，还能制造法拉利。"