> ## Documentation Index
> Fetch the complete documentation index at: https://gnero.genetind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 在真实项目中搭建 AI 协作开发系统

前几天 Anthropic 发了一篇文章,介绍他们在内部实践的 AI 辅助开发模式——让 AI 拥有"长时记忆",能记住项目规范、过往决策和代码风格。这个思路很有启发性,但他们讲的比较理论化,没有给出太多实际落地的细节。

我们团队最近几天在 Mosi 项目里试着把这套思路落地了,并且为了适应真实的多人协作场景,做了不少扩展。这篇文章就来聊聊我们是怎么做的,遇到了哪些坑,以及最后搭出来的这套系统实际用起来是什么感觉。

## 一、起点:Anthropic 的理念与现实的距离

Anthropic 提出的核心想法是:**不要每次都从零开始跟 AI 对话,而是让 AI 一开始就能看到项目的"记忆"**。

这个"记忆"包括:

* 项目的技术栈和架构规范

* 代码风格约定

* 过去讨论过的设计决策

* 常见问题的解决方案

他们的做法是把这些内容整理成文档,放在项目里,然后在跟 AI 对话时,把相关文档的内容喂给 AI。这样 AI 就能像一个"了解项目背景的老员工"一样工作,而不是每次都得从头解释一遍。

听起来很简单,但真要在一个多人协作的真实项目里落地,会遇到很多实际问题:

* **多个开发者同时工作怎么办?** 如果大家的进度都记在一个文件里,很容易冲突。

* **规范文档太长怎么办?** 我们的前端规范有 1600 多行,后端规范也有几百行,全塞给 AI 会爆 token,而且大部分内容对当前任务其实没用。

* **怎么保证代码质量?** AI 写的代码不能直接合到主分支,得有人审核、测试。

* **怎么记录 AI 的工作?** 如果出了问题,怎么回溯 AI 到底做了什么?

我们在 Mosi 项目里针对这些问题做了一些设计。

## 二、落地:四个核心设计决策

### 1. 多人协作:每个开发者有独立的进度文件夹

Anthropic 的文章里没怎么提多人协作的问题,但这在真实项目里是绕不开的。

我们的做法是:**在 **`workflow/agent-progress/`** 目录下,给每个开发者(包括 AI)创建一个独立的文件夹**。

比如:

```plaintext theme={null}
workflow/
├── agent-progress/
│   ├── taosu/          # 开发者 taosu 的进度
│   │   ├── index.md
│   │   └── progress-1.md
│   ├── developer2/     # 开发者 developer2 的进度
│   │   ├── index.md
│   │   └── progress-1.md
```

每个文件夹里有一个 `index.md`,记录这个开发者当前在做什么、做到哪一步了、遇到了什么问题等。AI 在开始工作前会先读这个文件,了解上下文;工作结束后会更新这个文件,记录新的进度。

这样多个开发者可以同时工作,不会互相干扰。

### 2. 解决信息过载:两层索引系统

前面提到,我们的规范文档很长(前端 1600+ 行,后端几百行)。在实践中,我们发现直接把完整文档喂给 AI 会带来几个问题:

**为什么需要结构化体系?**

1. **信息过载问题**:当 AI 需要实现一个"快捷键功能"时,如果把 1600 行的完整前端规范全部读取,AI 会被大量无关内容干扰——比如"API 调用规范"、"状态管理规范"等。这些内容虽然重要,但对当前任务没有帮助,反而会降低 AI 的注意力集中度。

2. **Token 经济性问题**:在长对话中,如果每次都读取完整文档,token 消耗会迅速累积。如果一个对话有 20 轮交互,重复读取文档会浪费大量成本。

3. **知识导航问题**:开发者(和 AI)需要能快速回答"我现在要实现 X 功能,应该看规范的哪个部分?"如果没有清晰的导航系统,只能靠全文搜索或逐章阅读,效率很低。

### 我们的解决方案：两层结构

我们设计了 `index.md + doc.md` 的两层知识体系:

```plaintext theme={null}
workflow/
├── frontend-structure/
│   ├── index.md       # 索引层:快速导航(100 多行)
│   └── doc.md         # 详细层:完整规范(1600+ 行)
```

**index.md 是什么?**

`index.md` 是一个**轻量级导航表**,它列出了规范的所有章节,并明确标注每个章节的行号范围。更重要的是,它按**开发任务类型**组织,而不是按文档结构组织。

比如:

```markdown theme={null}
# 前端开发规范索引

> **完整文档**: 详细规范请查看 `./doc.md`

本索引帮助你快速定位需要阅读的规范章节。根据你要开发的功能类型,参考下表找到对应的章节和行号。

## 相关工作流文档

| 文档                                | 适用场景              |
| ----------------------------------- | --------------------- |
| `../frontend-figma-workflow/doc.md` | 根据 Figma 设计稿开发 |

## 快速导航

| 开发任务                 | 需要阅读的章节                     | 行号范围   |
| ------------------------ | ---------------------------------- | ---------- |
| **新建功能模块**         | 目录结构规范                       | L5-36      |
| **编写 Command Palette** | 组件开发规范 > Command Palette     | L876-1425  |
| **编写 Query Hook**      | Hook 开发规范 > Query Hook         | L179-265   |
| **编写 Mutation Hook**   | Hook 开发规范 > Mutation Hook      | L266-351   |
| **调用后端 API**         | API 调用规范                       | L382-735   |
| **实时通信 (WebSocket)** | API 调用规范 > 实时通信            | L419-465   |
| **AI 流式响应 (SSE)**    | API 调用规范 > SSE                 | L466-497   |
| **AI Tool Calls 处理**   | API 调用规范 > Tool Calls          | L498-735   |
| **状态管理**             | 状态管理规范                       | L736-873   |
| **URL 状态同步**         | 状态管理规范 > URL/Context         | L738-873   |
| **编写组件**             | 组件开发规范                       | L874-1645  |
| **可访问性和图片优化**   | 组件开发规范 > 语义化 HTML & Image | L1426-1544 |
| **性能优化**             | 性能优化规范                       | L1676-1762 |
| **代码质量检查**         | 代码质量和格式化规范               | L2140-2317 |
| **代码审查**             | 通用硬性规则 + 检查清单            | L1763-2344 |

......
```

**核心优势:**

1. **即时知识访问(Instant Knowledge Access)**:AI 只需要读取 100 多行的 index.md,就能在几秒内定位到"实现快捷键功能需要看第 876-1425 行"。这比全文搜索或逐章浏览快得多。

2. **按需加载(On-Demand Loading)**:AI 根据当前任务,只读取 `doc.md` 的相关章节(比如 500 行而不是 1600 行)。这样既节省了 token,又避免了信息过载。

3. **标准化工作流(Standardized Workflow)**:这个两层结构成为团队标准——所有人(包括 AI 和新加入的人类开发者)都知道"先看 index,再读 doc"。这降低了认知负担,提高了协作效率。

**工作流程:**

1. AI 读 `index.md`,了解规范的整体结构

2. 根据当前任务(比如"实现快捷键功能"),AI 在导航表中找到"编写 Command Palette → L876-1425"

3. AI 精确读取 `doc.md` 的第 876-1425 行,获取详细的实现指导

4. AI 按照规范编写代码,避免了"不知道从哪里开始"或"遗漏关键细节"的问题

### 与 Claude Skills 的本质区别

你可能会问:Anthropic 不是推出了 Claude Skills 吗?为什么不直接用 Skills,而要自己搞这套 structure?

这是因为两者解决的问题不同:

* **Claude Skills** 是一种**生态驱动的通用能力包**,它的设计目标是跨项目复用。比如"git 操作"、"Python 测试"、"文件系统操作"等,这些能力在任何项目里都适用。Skills 追求的是**广度和复用性**。

* **我们的 structure** 是一种**项目专用的深度定制体系**,它索引,存放了 Mosi 项目的特定架构、技术栈、状态管理模式、API 调用约定等。这些知识是项目独有的,无法跨项目复用。我们的体系追求的是**深度和精确性**。

举个具体例子:

* **Skills 可以教 AI**:"如何写一个 React 组件"(通用知识)

* **我们的 doc.md 教 AI**:"在 Mosi 项目里,如何按照我们的特定架构(Monorepo + Turborepo)、状态管理模式(Zustand + URL 状态同步)、API 调用规范(tRPC + SSE + Tool Calls)来写组件"(项目专属知识)

Skills 像是"通用工具箱",我们的 structure 像是"项目施工图纸"。两者不是替代关系,而是互补关系——Skills 提供基础能力,structure 提供项目特定的实施细节。

我们对后端规范也用了相同的组织方式。

### 3. 封装最佳实践:短命令系统

为了让开发流程更规范,我们定义了一系列"短命令",每个短命令对应一个特定的操作。

短命令存放在 `.cursor/commands/` 目录下,每个命令是一个 `.md` 文件。

目前常用的短命令有：

* `/init-agent`：初始化 AI 会话，让 AI 读取当前开发者的进度和相关规范

* `/check-frontend`：让 AI 检查前端代码是否符合规范

* `/check-backend`：让 AI 检查后端代码是否符合规范

* `/record-agent-flow`：记录本次 AI 工作的内容到进度文件

**短命令是什么？**

短命令其实就是**预定义的提示词模板**。每个 `.md` 文件里写的是一段完整的 AI 指令。

比如 `check-frontend.md` 里可能写着：

```markdown theme={null}
自己检查一下,刚刚写的代码是否符合前端开发规范 , 先使用 git status 查看修改过的代码, 然后根据改动类型去 `.cursor/rules/frontend-structure/index.md` 文件寻找对应的doc 详情并查阅 `.cursor/rules/frontend-structure/doc.md` 进行检查
...
```

**工作原理：**

当开发者在对话框中输入 `/check-frontend` 并回车后：

1. Cursor 会自动读取 `.cursor/commands/check-frontend.md` 的内容

2. 将这个内容作为提示词注入到当前对话中

3. AI 根据这个提示词执行相应的检查操作

**为什么要用短命令？**

因为每次让 AI 做代码检查、记录进度这些事情，都得输入一大段详细的检查清单或操作步骤。如果这些指令写得不够详细，AI 的输出质量就会不稳定。

短命令把这些**最佳实践的提示词**封装起来，开发者只需要输入 `/check-frontend`，就相当于发送了一个精心设计的完整提示词，保证了指令的一致性和完整性。

而且短命令可以在团队间共享，新人也能直接用上团队积累的经验。

> 可以把短命令当成一种prompt 的sdk,使用短命令就是在调用我们团队为了某种场景制造的专门的sdk

### 4. 质量把关:人类开发者的审核机制

虽然 AI 能写代码,但我们不会让 AI 直接提交代码。**所有代码都需要人类开发者审核、测试通过后,才能 commit**。

典型的流程是:

1. AI 写代码

2. 开发者本地运行,看看功能是否正常

3. 开发者 review 代码,看看有没有明显问题

4. 如果有问题,让 AI 修改;如果没问题,开发者手动 commit

这样既能享受 AI 的高效,又能保证代码质量。

## 三、实战:一个完整的开发流程

前面讲了一堆设计理念,可能还是有点抽象。下面用一个真实的例子,展示完整的开发流程。

**背景:**

我要在前端实现一个快捷键功能,按 `Cmd+K` 唤起搜索框。我已经在本地创建了一个 Git 分支 `feat/keyboard-navigation`。

### 第 1 步：初始化 AI 会话

```plaintext theme={null}
我：/init-agent
```

当我输入这个短命令后，Cursor 会将 `init-agent.md` 的内容注入到对话中。这个模板里定义了 AI 需要做的初始化步骤：

**AI 按照短命令的指引执行：**

1. 读取 `workflow/agent-progress/taosu/index.md`，了解我当前的进度和上下文

2. 读取 `workflow/frontend-structure/index.md`，了解前端规范的整体结构

3. 如果有需要，进一步读取 `doc.md` 的相关章节

**AI 的回复：**

```plaintext theme={null}
好的，我已经读取了你的进度记录和前端规范。
当前分支：feat/keyboard-navigation
任务：实现快捷键功能（Cmd+K 唤起搜索）

我注意到前端规范里有"快捷键系统"这一章，我会按照那里的规范来实现。

准备好了，请告诉我具体要做什么。
```

### 第 2 步:描述需求

```plaintext theme={null}
我:帮我实现一个全局快捷键,按 Cmd+K(Mac)或 Ctrl+K(Windows)时,
   唤起搜索框。搜索框组件已经有了,路径是 components/SearchModal.tsx。
```

**AI 做的事:**

1. 根据"快捷键"关键词,去读 `workflow/frontend-structure/doc.md` 的"快捷键系统"章节

2. 了解到项目里已经有一个 `useKeyboardShortcut` hook,可以直接用

3. 写代码:在合适的地方调用这个 hook,绑定 Cmd+K 快捷键

**AI 的回复:**

```plaintext theme={null}
好的,我会这样实现:

1. 在 SearchModal 组件里使用 useKeyboardShortcut hook
2. 监听 Cmd+K / Ctrl+K,触发时打开搜索框
3. 按 ESC 时关闭搜索框

代码已经写好了,文件路径:
- components/SearchModal.tsx(已修改)

你可以本地运行看看效果。
```

### 第 3 步:本地测试

我在本地运行项目,按 `Cmd+K`,搜索框成功唤起。功能正常。

### 第 4 步：代码自查

```plaintext theme={null}
我：/check-frontend
```

当我输入这个短命令后，Cursor 自动将 `check-frontend.md` 的内容（一个详细的代码检查清单）注入到对话中。

**AI 根据短命令模板执行检查：**

按照模板中定义的检查项，review 刚才写的代码：

* 检查组件命名是否符合规范

* 检查 React hooks 的依赖数组是否完整

* 检查类型定义是否严格

* 检查是否有潜在的性能问题\
  ...

**AI 的回复：**

```plaintext theme={null}
检查了一下，发现两个小问题：

1. useKeyboardShortcut 的依赖数组里少写了一个 state
2. 类型定义可以更严格一点

已经帮你修正了，重新跑一下应该没问题。
```

我重新测试，确认没问题。

### 第 5 步:提交代码

```bash theme={null}
git add .
git commit -m "feat: add Cmd+K keyboard shortcut for search"
git push origin feat/keyboard-navigation
```

### 第 6 步：记录流程

```plaintext theme={null}
我：/record-agent-flow
```

Cursor 将 `record-agent-flow.md` 的内容注入到对话中，这个模板指导 AI 如何记录工作流程。

**AI 按照模板指引执行：**

1. 总结本次的工作内容（需求、实现方案、遇到的问题、解决方法等）

2. 将这些信息格式化后追加到 `workflow/agent-progress/taosu/index.md`

**AI 的回复：**

```plaintext theme={null}
已记录本次工作流程到你的进度文件。

主要内容：
- 实现了全局快捷键 Cmd+K 唤起搜索
- 使用了 useKeyboardShortcut hook
- 修正了依赖数组和类型定义的问题
- 已提交到分支 feat/keyboard-navigation
```

这样，下次我再跟 AI 继续工作时，AI 就能通过读取这个进度文件,快速了解我最近做了什么。

## 四、踩过的坑与解决方案

### 问题 1：短命令的学习成本

新人刚开始用这套系统时,需要学习有哪些短命令、每个命令是干什么的。

我们提供了 `/onboard-developer` 短命令来引导新人。新人只需要运行这个命令,AI 就会按照预设的引导流程,介绍整个工作流系统、常用的短命令、以及如何开始第一个任务。

### 问题 2：AI 在长对话中会"遗忘"规范

即使在会话开始时通过 `/init-agent` 让 AI 读取了所有规范,但随着对话轮次增加、上下文变长,AI 可能会逐渐"淡忘"最初读取的开发规范细节。这会导致 AI 在写代码时偏离规范要求。

我们的解决方案是:**在关键节点用短命令强制 AI 重新查阅规范**。

比如 `/check-frontend` 这个短命令,它的模板内容明确要求 AI:

1. 先用 `git status` 查看刚才修改了哪些代码

2. 根据改动类型(比如"新增了一个 Hook"),去 `index.md` 找到对应的章节

3. 重新读取 `doc.md` 的相关部分(比如"Hook 开发规范 L179-265")

4. 对照规范逐项检查代码

这样即使上下文已经很长,AI 也会在检查代码时**强制性地**重新学习一遍规范,确保代码质量不会因为"遗忘"而下降。

这也是为什么我们要把这些操作封装成短命令——不仅是为了方便,更是为了**在工作流的关键环节强制执行质量保证流程**。

## 五、总结和展望

Anthropic 的"AI 长时记忆"理念很有价值,但要真正落地到多人协作的实际项目中,需要解决很多工程问题。

我们在 Mosi 项目里的实践,核心做了这几件事:

* **多人协作支持**:每个开发者有独立的进度文件夹

* **规范索引系统**:index.md + doc.md 的结构,让 AI 能高效查找规范

* **短命令系统**:封装常用操作,提高开发效率

* **人在回路**:AI 写代码,人审核提交,保证质量

这套系统目前还在不断完善中,但已经能明显感受到开发效率的提升。

接下来可能会做的改进:

* **自动化更多流程**:比如让 AI 自动创建分支、自动写 commit message 等

* **更智能的规范索引**:现在 AI 需要手动判断要读哪些章节,未来可以让 AI 根据任务描述自动匹配相关章节

* **团队知识库**:把团队讨论过的设计决策、踩过的坑等,也整理成文档,让 AI 能学习到这些经验

如果你也在尝试用 AI 辅助开发,希望这篇文章能给你一些启发。欢迎交流。

***

## 附：相关资源

* Anthropic 的原文: [Building effective agents](https://www.anthropic.com/research/building-effective-agents)