context-mode 上下文模式：给 AI 和同事一份会自动翻看的项目档案夹

1. 聊聊 context-mode：为什么我发现代码和文档开始“认人”了

我最初注意到 context-mode（上下文模式）这个概念，是因为一个特别头疼的问题：给同事交接一个写了半年的项目，人家打开代码第一句话永远是“这写的啥？”而我把代码给 AI 助手看，它给出的重构建议却意外地贴合项目思路。同一个项目，差距为什么这么大？答案就是上下文没有接上——人脑的上下文在脑子里，AI 和协作者的上下文却需要显式地“喂”进去。

后来我才意识到，context-mode 不是某个单一软件的功能开关，而是一整套关于“如何把项目背景、代码意图、团队约定和工具状态高效地组织起来，并在合适的时候释放给人和机器”的思路。它渗透在聊天对话框的提示词预设里、编辑器的规则文件里、命令行的自动化配置里，甚至在一个仓库的 README 注释风格里。

这篇文章就用一个老开发者的视角，结合我自己的实操，把 context-mode 这个概念掰开揉碎了讲清楚：它解决什么问题、包含哪些技术层面、怎么在工作流里落地，以及落地时一定会踩的坑。无论你是在调教 AI 编程助手、优化团队的工程规范文档，还是只是想让自己三个月后的某一天能看懂自己的脚本，这篇文章应该都能帮到你。

2. 为什么我们需要 context-mode：没有上下文，代码只是漂亮的无序字符串

2.1 代码本身的“信息断裂”与人类理解的“脑补成本”

我们先做一个极端的实验：打开你三个月前写的一个工具脚本，只看函数名和注释，不看 README、不看提交记录、不回忆当时的聊天记录。你会发现，能看懂注释不等于能看懂为什么这个函数要这么写、为什么那个参数要用魔法数字、为什么明明循环能解决的非要用递归。代码只记录了结果，很少记录决策过程。

传统工程实践里，这个“决策过程”其实是有地方承载的，比如架构设计文档、技术方案评审记录、代码评审意见。但现实是这些文档通常躺在公司协作平台里，跟代码库分离，很少有人持续维护，更不会定期同步给协作的新人。结果就是：人脑的上下文被迫在多个系统之间跳跃，信息消耗惊人。而 context-mode 的一个核心理念就是——把上下文从人的脑海和散落的文档里，收拢到代码库附近、工具链内部，让它们在运行的时刻就能被自动读取和利用。

2.2 与 AI 协作出现后，上下文问题的“量级爆炸”

这两年 AI 编程助手大量进入开发流，问题变得更有意思了。一个普通的中型项目可能有几千个文件、几十万行代码，但大多数 AI 助手的上下文窗口是有限的，你可以把整个仓库全塞进去让它“全局分析”，但成本高、响应慢，而且很很快就超过窗口上限。

所以你的选择变成了：要么给 AI 一段精简的背景说明，让它在这段背景里做局部修改；要么你自己手动挑文件往里贴，试图手动构造“局部上下文”。但前者往往背景写不清楚，后者挑选文件时又极容易漏掉关键依赖。于是你会发现，AI 给出天马行空的建议，不是因为它能力低，而是因为它看到的背景太少，它在“信息真空”里做判断。

context-mode 正是为了解决这种“信息真空”而设计的：它让你把项目的意图、技术栈约定、文件结构信息、甚至“当前我需要你扮演的角色”都编码成结构化上下文，然后让 AI 在每次交互时自动携带这些上下文。用大白话说，就像给 AI 配了一个能自动翻的项目档案夹，而不是每次都要现问“这项目是用什么框架写的”“代码风格是什么”“你这次要做什么”。

2.3 context-mode 本质上是一套“信息组织协议”

如果跳出单个工具看，context-mode 用一句话概括就是：在合适的粒度上，把合适的背景信息，用合适的格式，放在合适的位置，让需要的消费者（人类协作者或 AI 工具）可以随时、自动地消费。

这里面有几层意思：

• 合适的位置：比如 AI 工具通常在项目根目录读取规则文件，你就把规则放在那里，而不是放在 wiki 里。
• 合适的格式：纯文本、Markdown、YAML、JSON、语义化的标签，哪种格式既便于人工阅读又便于机器解析？答案是分场景选择。
• 合适的粒度：全局上下文管全局约定（比如代码风格、安全规范），模块上下文管模块说明（比如这个服务做什么、依赖谁），局部上下文管当前任务的细节。
• 合适的消费者：人是慢速高理解力的消费者，AI 是快速低记忆力的消费者，两者需要的内容形态天然不同。

理解了这层本质，后面我们选工具、写配置文件、设计协作流程时，所有“为什么要这么干”的逻辑就都串起来了。

2.4 一个生活化的类比：团队新人的“入职培训包”

想象一下你公司来了个新人，你家 HR 如果只甩给他一本几千页的员工手册，那他大概率只能记住考勤时间，其他全部懵。而好的 onboarding 流程是怎样的？一份三页纸的团队简介、一位指定导师、一套可以直接跑的本地环境脚本、一次最近上线功能的口头梳理。新人需要的不是全量信息，而是按需供给的高质量上下文。

context-mode 本质上就是在构建这样一个“入职培训包”，只不过这个包是给 AI 助手用的，也是给六个月后的自己用的。当这个包被放在了固定的地方、按固定格式组织起来，所有需要它的人（或程序）都能直接拿起来用，不需要反复考古——这就是这个模式的妙处。

3. 落地 context-mode：三个层级的工程化实操

3.1 层级一：面向人——让仓库自解释的文档上下文

最朴素、最好上手的一种 context-mode 实践，就是改造你的仓库文档，让它们从“装饰品”变成“上下文源”。

具体来说，我推荐的打法：

1. 强化根 README 的“第一屏”信息。不要写“这是某某项目”这种废话，直接写“这个项目是什么、它解决什么问题、怎么跑起来、怎么测试、架构总览图指向哪个文件”。
2. 建立 docs/ 目录并规定“谁负责维护什么”。每个模块、每个服务都单独建文档，文档的第一节必须是“背景与目标”，第二节是“核心术语表”，第三节是“常见修改点与影响面”。这样，无论谁来改代码，第一件事就是先读这个文档的这几节，上下文几秒钟就能建立起来。
3. 在关键代码的注释里写“决策注释”，而非“重复注释”。变量命名不清楚可以重命名，但为什么不用某个现成的库、为什么这个边界条件这么处理，这类信息加一行# Why注释，价值远超十行“这是对 xx 进行 xx 处理”的废话。
4. 给每个重要目录放一个 README。不用长，三五句话讲清这个目录是干什么的、里面哪些文件可以动、哪些文件最好别碰。新人进来就能快速画出地图。

这层实践的好处是零成本、不依赖任何工具、对人也对 AI 友好。缺点是相对静态——文档和代码有同步问题，一旦维护不积极，上下文还是会老化。

3.2 层级二：面向 AI——活用代码库助手与规则文件

现在主流的 AI 编程工具（比如 GitHub Copilot、Cursor、Windsurf、Claude Code 等）都支持在项目根目录放一个规则文件来注入上下文。它们有的叫.cursorrules，有的叫CLAUDE.md，有的叫.window/rules，有的在设置界面里配置“项目级提示词”，机制大同小异：它们在每次会话开始时，会把这份文件读入上下文窗口，作为模型理解的“初始状态”。

这一层，我给三个具体可抄的配置思路。

思路一：写清楚项目质量底线

不要只写“请帮我写高质量代码”这种空话，要写：

本项目为支付网关服务，任何代码变更必须考虑：

• 幂等性（重复提交不会产生重复扣款）
• 超时与重试机制（外部渠道最大超时 3 秒，失败重试最多 2 次）
• 安全审计（日志中不得出现完整卡号等敏感信息）
• 测试要求（新增核心逻辑必须提交单元测试）

这就是在告诉 AI：在这里干活，有些红线是不能碰的，有些糖是要冲的。它会直接影响模型输出时对方案的选择。

思路二：给出模块地图和关键路径

在规则文件里写上一段“模块速览”，比如：

模块速览

• internal/domain/：领域模型，纯业务逻辑，禁止依赖任何外部服务
• internal/repository/：数据访问层，只负责 SQL/Redis，不写业务逻辑
• api/handler/：HTTP 入口，负责参数绑定、鉴权、调用用例层，禁止直接访问 repository
• pkg/：可对外暴露的公共库，不允许引入本项目内部包

这样一来，AI 在帮你新增一个接口时，它会自动按这个分层去找代码应该插在哪个目录，而不会把repository里的 DB 查询逻辑写到handler里。你也可以在规则文件中写明“推荐依赖：使用 xx 库作为日志库、xx 框架作为命令行解析库”，避免 AI 每次都用流行的新库替换你已经稳定的技术选型。

思路三：定义“角色”背景

有些工具支持在会话里切换角色，也就是你把“作为 xxx 专家”写进上下文。一个比较稳的模板是：

你是一位资深的 Go 后端工程师，具备五年微服务架构经验。现在请基于当前仓库的代码逻辑，帮我 Review 这个 PR。重点关注：并发安全、错误处理、可扩展性。请以“发现的问题 + 修改建议”的结构输出，拒绝空泛的建议。

这种角色定义不是玄学，它降低了模型在众多可能回答风格中随机游走的概率，输出的语言风格、思考侧重都会更贴近你的需求。

3.3 层级三：面向流程——把上下文做进自动化里

文档和规则文件都到位了，但还有一层互动式上下文，是人和工具在动态协作时产生的：执行环境的信息。比如你在跑测试时当前的分支、环境变量、上次构建的产物、线上日志里的最新报错。这类上下文很难靠静态文件承载，所以我们要让工具替我们把上下文“抓”进上下文模式里。

一个简单的例子：我写了一个脚本，每次运行时就自动收集当前仓库的 Git 分支、最近 5 条提交信息、当前变更文件列表，然后把这些信息自动粘贴到我的 AI 聊天输入框上方，作为小上下文卡。这样一来，我只要一句话“帮我 review 我改了什么”，AI 就知道改了什么、在哪条分支上、跟哪些提交相关，完全不需要我手动贴。

实操中，这个思路可以通过一套 MCP（Model Context Protocol）服务来实现：

1. 在本地起一个轻量服务，暴露几个工具接口：
   • get_git_diff：返回当前工作区变更
   • get_recent_commits：返回最近 n 条提交
   • get_logs_by_scope：返回最近某个服务的关键日志
2. 在 AI 编辑器中配置好这些 MCP，让模型在需要时可以主动调用。
3. 于是你的 AI 不再是从纯文本里猜“发生了什么”，而是可以直接查“当前实际发生了什么”。

这个层级的落地比较偏工程，需要一定的编码和调试能力，但对团队的协作效率提升是碾压级的——上下文不再依赖人肉搬运和记忆，而是由运行时环境自动提供。

3.4 context-mode 与“热词”的关系：从概念到形态

现在网上关于 context-mode 的讨论越来越热，不少 AI 工具官网也开始专门宣传“上下文模式”，这个“热”，本质上是因为大家发现了一个痛感极强的事实：单纯靠聊天式对话来做 AI 协作，上下文的组织成本高到让人想放弃。

市面上很多工具各自给出了答案，有的用“项目知识库”，有的用“索引文件”，有的用“代码图谱”，有的用“会话记忆”。我的观点是：不要迷信某个厂商的定义，你得把 context-mode 理解成一套方法论。你自己是可以组装出最适合自己的上下文方案的。形式不同，原理趋同——都在解决“把信息高效编码并在合适的时刻释放给合适的消费者”的问题。

4. 千字长文：从零搭建一个“ context 优先”的工作流

4.1 工作流全景：从任务输入到上下文助手的五步走

在第 3 节里我们理清了原理和层级，现在我要给出一份可以直接照抄的、完整的“context 优先”工作流搭建步骤。建议你按顺序做一遍，然后根据自己项目的复杂度增减。

第一步：盘点你的“上下文资产”。把项目相关的信息源全列出来：代码库、README、架构文档、API 文档、数据库 Schema、历史决策记录（ADRs）、环境配置、运行日志。不用全量组织，先挑影响最大的 20%。

第二步：确定资产归属层级。哪些适合放仓库里（代码注释、目录 README、规则文件），哪些适合放工具配置里（会话预设、MCP 配置），哪些适合放人脑之外的记忆系统里（团队 wiki、操作手册、操作视频）。

第三步：选一个 AI 编码工具，配置项目级规则文件。可以从 Cursor 开始，也可以从 Claude Code 开始，关键是把它当成活文档来维护——每次发现 AI 反复犯同一个错，就在规则文件里加一条对应的约定。比如你发现 AI 老给日志加 ANSI 颜色转义码，你就加一行“禁止在日志中使用 ANSI 转义码，统一使用 JSON 格式输出日志”。这样下次它就记住了，再也不用每次在 prompt 里追着说。

第四步：把常用任务的“标准操作上下文”写成可复用的 prompt 模板。比如“新增需求”模板密码三段式：

• 需求原文（尽量粘原文，不要自己转述）
• 影响范围（我判断会影响哪些模块）
• 约束条件（性能指标、兼容性要求、不做哪些东西）

每次直接套用，这个模板本身就是上下文模式的人工版。用多了你会发现，你给 AI 的信息质量，直接决定它的输出质量。你这个 prompt 模板，就是 AI 的“上下文模式”。

第五步：跑一个“上下文审计”。定期抽测：随机选一个功能模块，让一个不熟悉该项目的新同事或一个 AI 助手，仅凭仓库内的上下文来回答问题——能答上多少？遗漏了什么？答错在哪里？把问题记录下来，补齐对应的文档或规则。三个月后再审计一次，你会看到上下文资产的质量在持续提升。

4.2 实用编写技巧：给 AI 写规则文件的五个高频套路

• 开头用“身份”定调：直接声明“你是一个 XX 项目的资深开发/运维/测试，目标是帮用户高效地完成任务。项目背景：……”。身份定调不是套话，它帮助模型调整回答的用户视角。
• 列出“必须遵守”的红线：不夸大、不用模棱两可的词，直接列负面清单，比如“禁止猜测依赖文件的路径”“禁止给出未在代码库中引用的第三方库”。
• 给出 Positive 的“推荐路径”：AI 容易在开放问题中迷路，你直接给出推荐方案、推荐库、推荐代码结构，让它做选择题而不是做问答题。
• 示例优先：“推荐写法”下面配 2~3 个代码示例，比 50 行描述有用得多。模型对示例的模仿能力远强于对指令的遵从能力。
• 要求 AI 主动提问：让 AI 遇到不确定时，不要强行给出答案，而是返回“当前上下文不足，需要补充以下信息：……”。这能避免大量幻觉，让你的上下文模式变成一个闭环——它会主动告诉你哪里有缺口。

4.3 小项目快速实践：context-mode 的“最低可行配置”

如果你只是一个正在学习新技术的小白，或者手里只是一些脚本级项目，根本不需要整套工程化方案。只需要做两件事，效果就立竿见影：

1. 在项目根目录建一个AGENTS.md（或CLAUDE.md，取决于你用哪个工具），写上三句话：项目是干嘛的、主要目录结构、编码风格要求。
2. 每次让 AI 帮忙写代码之前，先花 30 秒把“本次任务背景 + 目标 + 约束”粘贴进对话框。

就这两步，你的 AI 输出质量大概率能从一个什么都不懂的“外行程序员”提升到一个“刚入职但读过 README 的新人”的水平。后面再慢慢加固，每一步都能看得见效果。

5. 常见问题与排查经验：我把能踩的坑都踩了一遍

5.1 规则文件失效或不生效怎么办

很多用户配置完规则文件后发现 AI 根本不听，最常见的原因有三个：

• 规则文件放错了位置，工具根本不会读它。不同工具的读取优先级不同，有的读项目根目录，有的还要看主分支的远端文件，有的工具只能在特定级别生效。注意查看你所用工具的官方文档，把文件放到正确的关键位置。
• 规则写得像“愿望清单”，没有约束力。给 AI 下的规则要具体到可以被代码检查的程度，比如“禁止使用全局变量”就比“代码要整洁”有用得多。
• 上下文窗口太满，规则被截断。尤其项目规则文件极长时，早期内容可能被截掉，模型实际“看不到”。对策是把最重要的红线放在文件最前面，并控制总长度。

5.2 AI 上下文幻觉：它“假装知道”怎么办

在我实际使用中，另一种很烦的情况是：AI 明明没有看到某个文件的关键定义，但它依然会假装根据“你的描述”做出非常具体的修改，结果改出来根本无法编译。

我的应对策略：

1. 任何涉及具体符号名、具体文件路径、具体配置项的任务，都强依赖代码图谱或工具检索，不要只靠聊天。
2. 在规则文件中写死一条：“如果你没有在代码库中找到目标函数定义，请直接说明，不要猜测。”
3. 如果 AI 开始瞎编 API，我会立刻减少它的“自由度”，把 prompt 改为“请先搜索项目代码中关于 xx 的用法，列出三种现有相似实现，再基于这些实现写修改方案”。

上下文模式不是为了让 AI 变成一个依赖你喂信息的“哑终端”，而是要让它建立一种检索-确认-判断-行动的思维链，减少幻觉出现的空间。

5.3 上下文维护成本过高，要不要全部外包

还有人说“context-mode 好是好，但是要维护这些规则文档和配置文件，比写代码还累啊”。

我的体会：这是真的，所以你要学会做减法。宁可维护一份“只写最重要的 20% 约定”的精简规则，也不要写一份没人读的 80 页大全。规则文件的精神是“高频使用的关键约束”，不是“全量百科全书”。凡是 AI 不做也不会出大错的细节，都不写进上下文，让它随查随用；凡是 AI 一旦做错就毁灭性影响的，才值得写。

比如你的项目里有一条硬性要求“生产环境禁止输出日志中的用户手机号”，这必须写在规则文件第一屏；但“变量命名推荐驼峰式”这种约定，AI 统计代码风格后大概率自己就会模仿，就没必要写。

5.4 传统工程流程与 context-mode 如何共存

有团队会担心“我们有一套严格的代码审查和需求管理流程，是不是和 context-mode 矛盾”？其实完全不冲突。你可以把 context-mode 的上下文文件当成流程文档的“动态摘要版”：需求管理系统的需求详情是权威，但 AI 规则文件里记录的是“从需求到代码的关键映射”，每次开发时 AI 自动读的是后者。到了评审阶段，人工再去看权威需求文档，双方互补，效率只会更高。

6. 最后说点我的真实体会

我把 context-mode 从概念变成自己的默认工作方式，已经小半年了。最大的变化其实是心态上的：以前我总指望 AI 工具能像人一样“有感觉地理解”项目，现在我不这么想了。AI 需要上下文，人也需要上下文，而上下文不是玄学，它是可以被设计、被组织、被自动化的工程元素。你愿意投入多少心思去设计上下文，你的协作效率和输出质量的上限就有多高。

如果在看完这篇文章后，你只愿意做一件事，那我建议你把项目里最重要的那个规则文件建起来，先写三行你最重要的项目约束，然后持续迭代一个月。一个月后你回头看，大概率会觉得——以前那些 AI 给的蠢建议，不是 AI 蠢，是我没有给它好好讲明白项目的故事。而 context-mode 就是给这把“理解之锁”配的钥匙。