用 AI Coding 做项目时，我踩过的坑
最近我在做一个叫 wherewasai 的小项目。
它的起点很简单：我用 Codex、Claude Code、Cursor 这类工具写代码时，经常隔几天才回到某个项目。再打开的时候，我已经忘了上次做到哪一步。之前为什么选 CLI？哪个功能已经写完？哪个坑还没填？下一步本来想做什么？
这些东西不在代码里，也不在 README 里。它们散在一段段对话里。
时间一长，AI Coding 的对话记录就像一堆临时便签。每张便签都有用，但你真要找某个项目的上下文时，只能一条条翻。
所以 wherewasai 想解决的不是“帮我记笔记”，而是：
我重新打开一个项目时，能不能快速知道上次和 AI 一起开发到哪里了？
更具体一点，它应该是一个面向 AI Coding 的本地项目记忆工具。它识别当前项目，保存和这个项目有关的开发记忆，记录关键决策、当前进度、待办事项，并在需要时导出一段可以直接贴给 AI Coding 工具的上下文。
做这个项目的过程中，我对 AI Coding 的感受也变得更具体了。AI 能写代码，但它不太会自然地替你守住项目边界。你不给边界，它就会补全。补着补着，一个小工具就变成了平台。
这篇不是 wherewasai 的完整设计文档，只是我在做它时踩过的一些坑。
不要一开始就让 AI 做完整项目
最开始构思 wherewasai 时，我很自然地想对 AI 说：
帮我实现一个 AI 项目记忆管理器。
这句话看起来没毛病，但对 AI 来说太大了。
wherewasai 牵涉的东西不少：项目识别、对话记录整理、本地存储、CLI 命令、上下文恢复、摘要生成、历史决策、待办管理。再往后想，还能加 Web UI、编辑器插件、云同步、团队协作、各种 AI Coding 工具集成。
如果一上来就让 AI “实现完整项目”，它通常会给你一套看起来挺完整的系统：前端页面、后端接口、数据库表、用户系统、标签系统，甚至云同步和权限管理。
问题是，第一版根本不需要这些。
wherewasai 的第一版应该很克制：在本地项目目录下保存项目记忆，通过 CLI 查看和更新记忆，再导出一段恢复上下文。只要这条主流程跑通，项目的价值就能验证。
我后来才意识到，复杂项目的第一步不是写代码，而是缩范围。你要先让 AI 帮你把问题说清楚：
先不要写代码。请帮我分析 wherewasai 的 MVP 范围：
- 它解决什么问题；
- 第一版必须做什么；
- 哪些功能暂时不做；
- 为什么第一版优先选择 CLI；
- 本地 JSON 存储是否够用；
- 后续可以怎么扩展。
这一步看着像空谈，其实很值。很多个人项目不是死在代码上，而是死在第一版做得太满。
wherewasai 很容易被 AI 写偏
wherewasai 很容易被理解错。
它像笔记工具，因为它要记录项目记忆。它像项目管理工具，因为它要记录进度和待办。它像知识库，因为它要整理历史上下文。它也有点像 AI Coding 工具的辅助插件。
这些相似点会让 AI 自动脑补。
提示不清楚时，AI 可能会把它写成普通笔记软件，让用户手动创建笔记、手动打标签、手动维护分类。这个方向其实偏了。wherewasai 不是为了记录更多笔记，而是为了恢复 AI Coding 项目的开发上下文。
AI 也可能把它写成 Web 平台：登录注册、多用户空间、团队协作、云端同步、权限系统，一套配齐。这些功能不是没价值，只是对第一版太重。个人开发者做 MVP，最怕的就是核心需求还没验证，先背上平台级复杂度。
还有一种偏法更隐蔽：把 wherewasai 写成聊天记录搜索工具。它解决了“怎么找到历史对话”，却没解决更关键的问题：找到之后怎么恢复上下文？恢复给谁？恢复成什么格式？哪些信息对下一次开发有用？
所以我现在会先把边界写清楚：
wherewasai 是一个面向 AI Coding 的本地项目记忆管理工具。它不是普通笔记软件，也不是团队项目管理平台。
它的目标是帮助用户在重新打开旧项目时，快速找回之前和 AI Coding 工具一起开发形成的上下文。第一版优先做 CLI，不做复杂 Web UI，不做云同步，不做多用户系统。
这类“它不是什么”的描述很重要。AI 经常不是不会写，而是会沿着它觉得合理的方向把项目补大。边界不写清楚，它就容易把轻量工具写成复杂平台。
小闭环比大功能可靠
做 wherewasai 时，我越来越相信“小闭环”。
一个小闭环至少要满足四件事：能写完，能运行，能验证，出问题能回滚。
比如：
实现 init 命令。
运行 wherewasai init 后，在当前项目下创建 .wherewasai 目录和 memory.json。
这就是一个小闭环。目标清楚，影响范围小。写完以后跑一次命令，看目录和文件有没有生成，就知道结果对不对。
但“实现完整项目记忆管理系统”就不是小闭环。它里面有太多设计选择。AI 可能写出一堆代码，但你很难判断它到底完成了什么，也很难在出问题时快速回到上一步。
wherewasai 可以拆得很小：
- 第一步只做
init - 第二步只做本地记忆文件读写
- 第三步只做添加一条项目记忆
- 第四步只做列出项目记忆
- 第五步只做导出恢复上下文
每一步都能单独运行、单独验证。
我现在更常这样给 AI 分配任务：
本次只实现 init 命令。要求：
- 执行 wherewasai init 后，在当前项目根目录创建 .wherewasai 目录；
- 在目录下创建 memory.json；
- 如果目录已经存在，不要覆盖已有内容；
- 完成后给出运行命令、预期输出和失败排查点。不要实现 add、list、restore 等其他命令。
任务越小，AI 越不容易发散。它很擅长在明确边界里完成工作，但不适合在没有边界的情况下自由发挥整个系统。
先让 AI 解释项目，再让它改代码
wherewasai 第一版不算特别大，但模块边界仍然要守住。
CLI 负责命令入口，storage 负责本地文件读写，project detector 负责识别当前项目，memory 模块负责管理记忆内容，exporter 负责导出上下文。AI 如果没理解这些边界，很容易把代码写乱。
比如项目里已经有 storage 层了，它可能还在 command 文件里直接读写文件。已经有统一类型了，它可能又在新文件里定义一套。已经有 CLI 注册机制了，它可能再写一个入口。
代码可能能跑，但结构会越来越乱。
所以我不太会直接让 AI 上手改代码，而是先让它解释当前项目：
你先不要修改代码。请先阅读这些文件：
- src/cli.ts
- src/commands/init.ts
- src/storage/jsonStore.ts
- src/types/memory.ts请说明这些文件的职责、当前调用关系，以及如果要新增 list 命令，最合适的接入点在哪里。
如果 AI 连现有逻辑都解释不清楚，我就不会让它继续写。因为它大概率会接错位置。
复杂项目里，AI 最常犯的不是语法错，而是结构错。语法错很好修，结构错会让项目越写越拧巴。
文件级任务能明显减少失控
我现在用 AI Coding 时，最常做的一件事就是限制文件范围。
不要让 AI 在整个项目里自由改。直接告诉它：本次允许读哪些文件，允许改哪些文件，哪些文件不能碰。
比如：
本次任务只实现 list 命令。允许修改：
- src/commands/list.ts
- src/cli.ts
- src/types/memory.ts禁止修改：
- src/commands/init.ts
- src/storage/jsonStore.ts
- package.json
- 项目目录结构如果你认为必须修改其他文件，请先说明原因，不要直接改。
这样做之后，AI 的影响范围会小很多。就算写错，也错在几个文件里，检查和回滚都方便。
wherewasai 这种项目看起来不大，但一旦涉及 CLI、存储、项目识别、上下文导出、摘要结构，就很容易牵一发动全身。不限制文件范围，AI 可能为了一个小功能顺手改好几个模块。
修 bug 时更要限制：
只修复当前 bug。
不要重构。
不要修改公共接口。
不要改变现有目录结构。
不要实现本任务之外的功能。
这些话看起来重复，但对 AI 有用。AI 经常喜欢“顺手优化”。复杂项目最怕的就是顺手优化。
禁止事项要写得比需求还清楚
我以前给 AI 提需求时，更多写“要做什么”。后来发现，在复杂项目里，“不能做什么”同样重要，有时更重要。
wherewasai 开发中，我会经常写这些限制：
不要重构无关代码。
不要修改已有命令的行为。
不要改变 memory.json 的字段结构。
不要引入新的大型依赖。
不要改变现有目录结构。
不要删除已有注释。
不要实现本任务之外的功能。
不要把本地 CLI 工具改成 Web 项目。
其中“不要改变 memory.json 的字段结构”尤其重要。项目记忆文件一旦写入，就会成为后续功能依赖的数据基础。AI 随手改字段，之前保存的数据可能就不兼容了。
“不要把本地 CLI 工具改成 Web 项目”也很有必要。AI 很容易把产品做完整，但 wherewasai 第一版追求的是轻量、直接、能验证，而不是一开始就做成平台。
说到底，AI Coding 不是让 AI 尽情发挥，而是让它在清楚的边界里执行任务。
让 AI 先复述规则
真正写代码前，我会让 AI 先复述一遍任务。
在开始之前，请先复述本次任务目标、允许修改的文件、禁止事项和验收标准。
复述完后，先不要写代码。
这一步能提前发现偏差。
比如我明明说了“不修改 storage 层”，AI 复述时却说“需要调整 storage 的读写逻辑”，那就说明它已经准备走偏了。这个时候纠正，比等它写完一堆代码再改省事得多。
这其实就是开发前的需求对齐。复杂项目里，越早发现理解偏差，代价越小。
不只要运行命令，还要预期输出
AI 写完代码后，不能只让它告诉你怎么运行。因为“能运行”和“运行正确”不是一回事。
wherewasai 是 CLI 工具，很多结果发生在本地文件系统和命令行里。如果没有明确的预期输出，很容易出现“没报错就算成功”的错觉。
比如 init 命令写完后，我会要求 AI 给出这样的验收说明：
运行命令：
wherewasai init预期结果：
- 当前项目根目录下生成 .wherewasai 目录；
- 目录中生成 memory.json；
- memory.json 包含初始结构；
- 重复执行 init 不会覆盖已有内容。如果失败，优先排查：
- CLI 入口是否注册；
- 当前工作目录是否正确；
- 文件写入权限是否正常；
- storage 模块是否处理了目录不存在的情况。
这类信息对调试很有用。尤其是普通开发者，很多时候不是不会运行项目，而是不知道运行后的结果算不算对。
我现在会要求 AI 在完成后说明：改了哪些文件，怎么运行，怎么测试，成功时看到什么，失败时先查哪里。
项目记忆不能只是堆文本
wherewasai 的核心是项目记忆，但项目记忆不能只是把一堆对话塞进文件。
如果只是把历史对话或摘要原样堆起来，时间一长，它会变成另一个信息垃圾堆。你本来想解决上下文混乱，结果只是把混乱从聊天记录搬到了本地文件。
有用的项目记忆应该是结构化的。至少要区分：
- 项目目标
- 技术栈
- 当前进度
- 已完成功能
- 关键决策
- 已知问题
- 下一步任务
- 常用命令
导出的恢复上下文可以长这样：
# 项目目标# 当前技术栈# 已完成功能# 关键设计决策# 当前待办# 已知问题# 常用命令# 本次建议恢复上下文
wherewasai 真正要保存的不是“更多内容”，而是“下一次开发真的用得上的内容”。
上下文不是越多越好。给 AI Coding 工具恢复上下文时，如果贴进去一大堆不分层的信息，AI 反而容易抓不住当前任务。
restore 不能太长
刚开始设计 restore 功能时，我本能地想把历史信息尽可能都导出来。毕竟 wherewasai 是做项目记忆的，似乎导出越多越完整。
后来发现，这个想法不对。
AI Coding 工具不是读得越多效果越好。上下文太长时，它会看到很多过去的细节，却抓不住现在最要紧的任务。尤其是复杂项目里，过多历史会干扰当前开发。
所以 restore 应该有取舍。它不该只是把所有历史记录拼起来，而应该导出一段面向下一步开发的上下文。
比较合理的恢复内容包括：项目目标、当前架构、最近完成的功能、关键技术决策、当前待办、禁止事项和下一步建议。
wherewasai 的价值不是“存得多”，而是“恢复得准”。
AGENTS.md 比 AI_RULES.md 更适合长期项目
做 wherewasai 时，我一开始想在项目里放一个 AI_RULES.md，专门写给 AI Coding 工具看。这个文件的作用很直接：告诉 AI 在这个项目里怎么工作，比如不要随便重构、不要改已有命令行为、不要引入新依赖、修改前先说明计划、写完后给出测试方式。
后来我觉得，AGENTS.md 可能更合适。
两者定位很接近，都是项目级规则文件。区别在于，AI_RULES.md 更像自定义文件名，通常需要你在提示词里明确要求 AI 去读它。AGENTS.md 更像写给 coding agent 的项目 README，适合放项目背景、构建命令、测试命令、代码风格、目录约束和禁止事项。
如果工具支持自动读取这类文件，AGENTS.md 更自然。即使不自动读取，也可以在提示词里说：
请先阅读 AGENTS.md，然后按其中规则完成任务。
wherewasai 里我更倾向于直接使用 AGENTS.md，而不是再单独维护一个 AI_RULES.md。两个文件同时存在，容易重复，甚至冲突。
一个适合 wherewasai 的 AGENTS.md 可以这样写：
# AGENTS.md## Project Goalwherewasai is a local-first AI coding memory manager.Its goal is to help users recover project context from previous AI Coding sessions.This project is not a general note-taking app, not a cloud platform, and not a team collaboration system.## Current Product DirectionThe MVP should focus on CLI-first and local-first workflows.Do not introduce Web UI, cloud sync, login system, team features, or permission systems unless explicitly requested.## Coding Rules- Explain the plan before modifying code.
- Do not perform unrelated refactoring.
- Do not change existing command behavior unless the task explicitly requires it.
- Do not change the existing directory structure without approval.
- Do not introduce new dependencies unless necessary and explained.
- Keep each task small and verifiable.
- Prefer modifying 1 to 5 files per task.
- Reuse existing utilities, types, storage logic, and command registration patterns.
- If similar code already exists, reuse it instead of duplicating logic.
- If a required change breaks these rules, stop and explain why before editing.## Verification RulesAfter changes, always provide:- changed files;
- run command;
- expected output;
- test method;
- failure troubleshooting points.## Data Rules- Do not casually change the memory file schema.
- Keep project memory structured.
- Recovery context should be concise and useful for the next AI Coding session.
- Do not turn project memory into a plain text dump.
这个文件不要写太长。它应该只保留长期稳定、真正重要的规则。临时需求写进去太多，AI 每次都要读一大堆无关信息，反而会分散注意力。
不要让 AI 重复造轮子
项目迭代几轮后，代码里一定会有已有工具函数、已有类型、已有命令注册方式。AI 如果不先搜索，很容易重复写一套类似逻辑。
比如项目里已经有 jsonStore.ts 负责读写文件，它可能又在 list.ts 里直接用 fs.readFileSync。项目里已经有 MemoryItem 类型，它可能又定义一个 MemoryRecord。短期看没什么，长期会让项目越来越难维护。
所以我会在提示词里加一句：
实现前，请先搜索项目中是否已有类似实现。
如果已有类似函数、类型、命令注册方式或工具方法，请优先复用。
不要重复造轮子。
AI 写新代码很快，但如果每次都写一套新风格，项目会散掉。一致性比单段代码写得漂亮更重要。
让 AI 换角度审查代码
AI 不只适合写代码，也适合审查代码。
在 wherewasai 里，写完一个功能后，我会让 AI 换几个角度看刚才的改动：
请分别从 reviewer、测试工程师、架构师三个角度审查刚才的改动。reviewer 关注代码可读性、维护性和是否有无关改动；
测试工程师关注测试是否充分、边界情况是否覆盖；
架构师关注是否破坏项目结构、接口设计和长期扩展。
对 wherewasai，我还会加一个产品角度：
请站在产品设计角度检查：
- 这个功能是否服务于“恢复项目上下文”；
- 是否把项目做复杂了；
- 是否偏离 CLI 优先、本地优先的 MVP 方向；
- 是否增加了用户的使用负担。
这个角度很有用。wherewasai 最大的风险之一，就是做着做着变成复杂知识库、复杂笔记系统或复杂项目管理平台。产品视角能把问题拉回最初那句：用户上次在这个项目里和 AI 做到哪里了？
我踩过的几个坑
第一个坑，是把 wherewasai 做成普通笔记工具。普通笔记工具关注“记录”，但 wherewasai 更关注“恢复开发上下文”。如果只是让用户手动写笔记，它没有解决 AI Coding 对话历史混乱的问题。
第二个坑，是过度设计。AI 很容易上来推荐 Web UI、数据库、登录系统、云同步和插件生态。第一版真正需要的是跑通本地 CLI 工作流。个人项目先验证价值，再考虑平台化。
第三个坑，是项目和记忆的绑定关系没想清楚。wherewasai 的核心问题是“这段记忆属于哪个项目”。如果项目识别不稳定，比如只靠目录名，就容易出错。后续可能需要结合 Git remote、项目路径、package.json、README 等信息来判断。
第四个坑，是上下文摘要没有结构。只保存一段自然语言摘要，短期够用，时间一长就会乱。项目目标、关键决策、当前任务、已知问题最好分开记录。
第五个坑，是恢复上下文太长。AI Coding 工具不是读得越多越好。恢复内容应该突出当前开发最需要的信息，而不是把所有历史都导出。
第六个坑，是没有及时沉淀技术决策。比如为什么第一版选 CLI，为什么暂时不用数据库，为什么先用 JSON，为什么不做 Web UI。这些不写下来，后面 AI 很容易推翻原来的方向。
第七个坑，是让 AI 自由修改范围。早期我只说“帮我实现 list 命令”，AI 可能顺手改 storage、改类型、改 CLI 入口，甚至重构目录。后来我开始用文件级任务，项目稳定很多。
第八个坑，是忽视验收标准。CLI 工具很多结果都不直观，所以必须写清楚运行命令、预期输出、生成文件和失败排查点。否则很容易出现“看起来完成了，其实不可用”的情况。
最后
做 wherewasai 让我更确定一件事：AI Coding 的关键不是让 AI 一次性写完整项目，而是把 AI 放进一个可控的工程流程里。
先说清楚项目解决什么问题，再把任务拆成小闭环。限制文件范围，写清楚禁止事项，让 AI 先复述规则，再让它动手。写完以后，不只看能不能运行，还要看输出是不是符合预期。
wherewasai 本身在解决“上下文丢失”的问题，而 AI Coding 做复杂项目最怕的也正是上下文失控。这两个问题其实是同一个方向。
有效的 AI Coding，不是让 AI 自由发挥，而是用文档管理上下文，用任务拆分降低复杂度，用文件边界控制改动范围，用验收标准保证结果可靠。
做到这些之后，AI 才不只是一个黑盒代码生成器，而更像一个能长期协作的开发助手。