ops x - Prompt
type: channel
link: https://opsx.me/tag/Prompt/
items: 把经验写进项目：AI Coding 如何用文档、技能和工具摆脱上下文依赖

把经验写进项目：AI Coding 如何用文档、技能和工具摆脱上下文依赖
type: item
date: 2026-03-15T17:03:00+00:00
description: 很多人用 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。 模板，例…