把经验写进项目：AI Coding 如何用文档、技能和工具摆脱上下文依赖
很多人用 AI coding 一段时间之后，都会遇到同一个问题：刚开始很好用，但项目一复杂、上下文一长、对话一断开，体验就迅速下滑。模型并不是突然变笨了，而是项目本身没有把“该知道的事情”沉淀下来，导致每次协作都像重新开工。所以，AI coding 真正要解决的，不只是提示词怎么写，而是怎样把项目知识、约束、流程和工具组织进仓库里，让 AI 不再严重依赖即时上下文。换句话说，重点不是“如何喂更多上下文”，而是“如何让项目自己带着上下文”。这篇文章想整理一套更可持续的做法：善用 Markdown 文档、技能包、工具包、环境文件和项目约定，把一次次对话中的经验沉淀成结构化资产。这样做的结果，不是让 AI 永远记住一切，而是让它在任何一个新上下文里，都更容易重新接住项目。一、AI coding 最大的问题，往往不是模型能力，而是知识挥发很多团队在用 AI 编码时，会自然陷入一种“会话式工作流”：需求来了，开个对话，解释背景，写代码，改一轮，结束。这个流程在短任务里没有问题，但一旦项目进入持续开发，就会暴露出非常明显的损耗： 规则只存在于聊天记录里，没有沉淀到仓库。 模型知道怎么做，却不知道为什么这样做。 换个上下文、换个成员、换个入口，很多约定就丢了。 每次都要重新解释目录结构、发布流程、命名习惯和边界条件。 这类问题本质上不是“上下文不够长”，而是项目知识没有外化。只要知识还停留在对话里，AI 就很难真正形成持续协作能力。二、先接受一个现实：AI 不会天然记住项目很多人对 AI coding 的期待，隐含着一种假设：只要模型足够强，它就会慢慢“理解这个项目”。但现实里，大多数协作型 AI 更像是按上下文工作的系统，而不是长期驻留在项目中的开发成员。所以更可持续的思路不是要求模型“像人一样记住”，而是让项目本身具备可被重新理解的结构。你可以把它理解成： 对人类开发者，项目需要 README、注释、设计文档。 对 AI 开发者，项目同样需要规则、技能、工具入口和边界说明。 一旦你接受这一点，很多实践就会变得非常明确：不要把关键信息藏在聊天里，而要写进仓库。三、Markdown 不是补充材料，而是 AI coding 的“长期记忆层”在这件事上，Markdown 的价值非常高，因为它同时具备几个特点： 结构简单，AI 很容易读取和理解。 能跟代码一起版本化管理。 对人也友好，不会变成只给机器看的黑箱配置。 适合从粗到细逐步拆分，不需要一开始就设计复杂系统。 真正用得好的项目，Markdown 往往不只是 README 一篇，而是形成一个轻量但清晰的知识层。例如： AGENTS.md：告诉 AI 这个项目怎么协作。 SKILL.md：告诉 AI 某类任务怎么做。 docs/architecture.md：解释系统边界和核心决策。 docs/runbooks/：记录运维、发布、排障和回滚流程。 .env.local.example：定义本地运行需要哪些环境变量。 这些文档一旦形成，AI 的工作方式就会从“每次吃一大段背景说明”，逐步转成“按项目结构自己找答案”。四、AGENTS.md：把项目协作规则固定下来AGENTS.md 最适合写的是“项目级规则”，而不是实现细节。它更像一张给 AI 的协作说明书，用来告诉它： 这个仓库主要做什么。 有哪些现成技能可以用。 哪些目录最关键。 默认的工作方式是什么。 哪些事情绝对不能乱做。 比较好的写法不是堆很多长篇解释，而是尽量高密度、低歧义。例如： “技术文默认发到筑码。” “首页摘要通常两段后加 。” “发文和更新统一走某个技能。” “敏感信息从环境变量读取，不写入仓库。” 这类规则的好处在于，哪怕换一个全新上下文，只要 AI 能读到仓库，它就能迅速恢复正确的工作方式。五、Skill：把重复任务做成可复用能力如果说 AGENTS.md 解决的是“在这个项目里怎么合作”，那么 Skill 更适合解决“某一类事应该怎么做”。它本质上是一个可复用的任务能力包，通常至少包含： SKILL.md：任务流程、默认参数、适用场景。 scripts/：可执行脚本。 必要时再加模板、参考文档或资源文件。 Skill 最适合承载那些“会重复出现、又容易做歪”的任务，例如： 博客发布。 日志分析。 部署脚本生成。 固定格式的周报或复盘。 某类代码迁移或重构。 一旦这类任务沉淀成 Skill，AI 下次就不必重新猜你的习惯，而是按已经写好的方法执行。六、工具包：把“方法”变成“可执行动作”只写文档还不够，因为很多任务不是“知道怎么做”就能稳定做好，而是需要真正可执行的动作。这时候就要把方法继续往下沉到工具包里。工具包通常包括： 脚本，例如 scripts/publish.py、scripts/deploy.sh。 模板，例如文章模板、配置模板、命令模板。 固定输入输出约定，例如 JSON 格式、目录结构、命名规则。 它和 Skill 的区别在于： Skill 偏方法论和流程。 工具包偏实际执行器。 真正稳定的 AI coding 项目，往往不是靠 AI 每次现场拼命写 shell 命令，而是让它优先调用已经存在的脚本和模板。这样做的好处非常直接：更可复用、更少随机性、更容易回归测试。七、env：不要只把它理解成环境变量很多人提到 env，第一反应就是 API Key、数据库密码、端口这些配置项。但对 AI coding 来说，env 的意义其实更大，它代表的是“AI 当前工作在哪个上下文里”。一个更完整的 env 通常包括： 环境变量。 工作目录。 目标环境，例如 dev / test / prod。 可访问的网络和资源边界。 允许执行什么，不允许执行什么。 也就是说，env 决定的不只是“密钥在哪”，还决定“这个 Agent 当前到底能碰什么、该碰什么”。这对持续协作特别关键，因为很多错误不是模型不会写代码，而是它不知道自己当前正面对哪个环境。所以比较好的实践是： 把私有变量收进 .env.local 一类本地文件。 把模板放到 .env.local.example。 把高风险环境显式写出来，而不是默认猜。 让脚本优先从环境读取，而不是把敏感值写死在仓库里。 八、让 AI 依赖项目结构，而不是依赖你反复解释真正好的 AI coding 体验，通常不是“你提示词写得多厉害”，而是 AI 进入项目以后，自己就能顺着结构找到答案。也就是说，项目里最好存在一条清晰的查找路径： 先看 AGENTS.md，知道全局规则。 再看对应 Skill，知道这类任务怎么做。 再看脚本和模板，知道具体怎么执行。 最后看 env 和配置，知道边界和运行上下文。 一旦这条路径存在，AI 的工作就更像一个新加入项目的工程师：先读规范，再看工具，再动手。而不是每次都要你从头带一遍。九、什么样的项目最容易从 AI coding 中持续受益并不是所有项目都适合一上来就把文档体系做很重。真正最适合这套做法的，通常有几个特征： 任务经常重复，例如部署、发版、写文档、生成配置。 协作会跨多个上下文，比如不同会话、不同成员、不同入口。 项目里有明显的规则和约束，不能每次临场发挥。 对稳定性要求高，不能依赖“这次模型正好答对”。 对这类项目来说，Markdown、Skill、工具包和 env 不是额外负担，而是降低长期协作成本的基础设施。十、落地顺序建议：从轻开始，但要能持续积累如果你想把 AI coding 做得更可持续，我更建议按下面这个顺序推进： 先补一份简洁的 AGENTS.md，把最关键的项目规则写进去。 再把最容易重复的一个任务做成 Skill。 把这个任务对应的脚本收进 scripts/，别让 AI 每次现写。 把敏感配置和运行变量收进 .env.local 和示例文件。 再逐步补架构说明、runbook 和模板。 这样做的好处是你不会一开始就掉进“文档工程”的陷阱，但每做一步，项目的可复用性都会上一个台阶。结语AI coding 要想长期好用，关键不在于上下文越来越长，而在于项目越来越清楚。Markdown 负责把知识沉淀下来，AGENTS.md 负责定义协作规则，Skill 负责收敛重复任务，工具包负责保证执行稳定，env 负责划清环境和权限边界。当这些东西逐渐成形以后，AI 就不再只是一个“临时帮忙的对话对象”，而更像一个能反复进场、持续接住项目的协作者。真正让项目摆脱上下文依赖的，不是某个更大的模型，而是你有没有把经验写进项目本身。