跳转到主要内容
前几天 Anthropic 发了一篇文章,介绍他们在内部实践的 AI 辅助开发模式——让 AI 拥有”长时记忆”,能记住项目规范、过往决策和代码风格。这个思路很有启发性,但他们讲的比较理论化,没有给出太多实际落地的细节。 我们团队最近几天在 Mosi 项目里试着把这套思路落地了,并且为了适应真实的多人协作场景,做了不少扩展。这篇文章就来聊聊我们是怎么做的,遇到了哪些坑,以及最后搭出来的这套系统实际用起来是什么感觉。

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

Anthropic 提出的核心想法是:不要每次都从零开始跟 AI 对话,而是让 AI 一开始就能看到项目的”记忆”。 这个”记忆”包括:
  • 项目的技术栈和架构规范
  • 代码风格约定
  • 过去讨论过的设计决策
  • 常见问题的解决方案
他们的做法是把这些内容整理成文档,放在项目里,然后在跟 AI 对话时,把相关文档的内容喂给 AI。这样 AI 就能像一个”了解项目背景的老员工”一样工作,而不是每次都得从头解释一遍。 听起来很简单,但真要在一个多人协作的真实项目里落地,会遇到很多实际问题:
  • 多个开发者同时工作怎么办? 如果大家的进度都记在一个文件里,很容易冲突。
  • 规范文档太长怎么办? 我们的前端规范有 1600 多行,后端规范也有几百行,全塞给 AI 会爆 token,而且大部分内容对当前任务其实没用。
  • 怎么保证代码质量? AI 写的代码不能直接合到主分支,得有人审核、测试。
  • 怎么记录 AI 的工作? 如果出了问题,怎么回溯 AI 到底做了什么?
我们在 Mosi 项目里针对这些问题做了一些设计。

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

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

Anthropic 的文章里没怎么提多人协作的问题,但这在真实项目里是绕不开的。 我们的做法是:在 workflow/agent-progress/ 目录下,给每个开发者(包括 AI)创建一个独立的文件夹。 比如: 
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 的两层知识体系: 
workflow/
├── frontend-structure/
│   ├── index.md       # 索引层:快速导航(100 多行)
│   └── doc.md         # 详细层:完整规范(1600+ 行)
index.md 是什么? index.md 是一个轻量级导航表,它列出了规范的所有章节,并明确标注每个章节的行号范围。更重要的是,它按开发任务类型组织,而不是按文档结构组织。 比如: 
# 前端开发规范索引

> **完整文档**: 详细规范请查看 `./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 里可能写着： 
自己检查一下,刚刚写的代码是否符合前端开发规范 , 先使用 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 会话

我：/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 的回复： 
好的，我已经读取了你的进度记录和前端规范。
当前分支：feat/keyboard-navigation
任务：实现快捷键功能（Cmd+K 唤起搜索）

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

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

​
第 2 步:描述需求

我:帮我实现一个全局快捷键,按 Cmd+K(Mac)或 Ctrl+K(Windows)时,
   唤起搜索框。搜索框组件已经有了,路径是 components/SearchModal.tsx。
AI 做的事:
  1. 根据”快捷键”关键词,去读 workflow/frontend-structure/doc.md 的”快捷键系统”章节
  2. 了解到项目里已经有一个 useKeyboardShortcut hook,可以直接用
  3. 写代码:在合适的地方调用这个 hook,绑定 Cmd+K 快捷键
AI 的回复: 
好的,我会这样实现:

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

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

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

​
第 3 步:本地测试

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

​
第 4 步：代码自查

我：/check-frontend
当我输入这个短命令后，Cursor 自动将 check-frontend.md 的内容（一个详细的代码检查清单）注入到对话中。 AI 根据短命令模板执行检查： 按照模板中定义的检查项，review 刚才写的代码：
  • 检查组件命名是否符合规范
  • 检查 React hooks 的依赖数组是否完整
  • 检查类型定义是否严格
  • 检查是否有潜在的性能问题
    …
AI 的回复： 
检查了一下，发现两个小问题：

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

已经帮你修正了，重新跑一下应该没问题。
我重新测试，确认没问题。

​
第 5 步:提交代码

git add .
git commit -m "feat: add Cmd+K keyboard shortcut for search"
git push origin feat/keyboard-navigation

​
第 6 步：记录流程

我：/record-agent-flow
Cursor 将 record-agent-flow.md 的内容注入到对话中，这个模板指导 AI 如何记录工作流程。 AI 按照模板指引执行：
  1. 总结本次的工作内容（需求、实现方案、遇到的问题、解决方法等）
  2. 将这些信息格式化后追加到 workflow/agent-progress/taosu/index.md
AI 的回复： 
已记录本次工作流程到你的进度文件。

主要内容：
- 实现了全局快捷键 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 辅助开发,希望这篇文章能给你一些启发。欢迎交流。

​
附：相关资源