第一次意识到 context-mode 这个问题的价值是在某个周三下午改一个用了三年的老项目。AI 辅助工具已经装好了提示词写得很清楚“帮我看看这个函数为什么偶发异常”结果模型答非所问给了我一篇关于异常处理的最佳实践论文一字没提我这个函数。问题不是它不懂异常而是它根本不知道我在改哪个文件、这个函数被谁调用过、项目里有没有约定俗成的写法。那一刻我意识到AI 的能力上限在模型但实际效果的下限往往在“上下文”。context-mode 就是用来治这个病的——它不是什么魔法而是一套让 AI 助手明确感知“你现在在哪个项目、在处理哪个问题、能看哪些信息”的工作模式。这篇文章适合所有把 AI 当成生产力工具但又被“懂很多却接不住话”折磨的开发者、技术文档写作者和数据工程师。1. 先想清楚context-mode 到底治什么病1.1 我遇到的“懂很多但接不住话”的AI绝大多数人用 AI 辅助编程时工作流是这样的把当前文件里的几十行代码复制出来粘贴进对话框然后问问题。运气好的时候AI 能给出像模像样的答案运气不好的时候它会盯着这段孤零零的代码开始自由发挥甚至会“纠正”一个根本不是 bug 的地方。问题出在哪出在上下文缺失。你脑子里有一整座冰山——项目背景、模块关联、历史决策、编码偏好、最近改动——但粘贴给 AI 的只有露出水面的一角。context-mode 的思路就是把这些本该被 AI 感知的信息用一种结构化、可控的方式主动喂给它。我自己的经历是最典型的教材。有一次我让 AI 给一个 Python 服务加限流逻辑我贴了 middleware 的代码AI 给了我一个挺标准的滑动窗口实现。结果一跑压力测试直接把这台机器的 Redis 连接打满了。原因很简单项目里已经有另一个中间件在统一管理 Redis 连接池我贴的几十行代码里根本没有暗示这件事AI 自然不知道。如果当时把项目上下文带进去它大概率会优先复用现有连接池而不是从零起一个新的。这个教训让我开始认真对待“上下文”这件事而不是动不动就骂模型蠢。1.2 一张表看懂三种“上下文模式”我把开发者跟 AI 协作的常见姿势分成三类你可以对照一下自己属于哪种。模式典型动作AI 能看到什么常见结果纯对话模式直接敲问题不带任何资料只有你打的字答案泛泛而谈正确但没用剪贴板模式复制粘贴当前文件代码孤立的一段代码能改局部经常改崩全局context-mode主动注入项目骨架、文件清单、改动记录、目标说明项目结构 相关文件 任务意图回答贴合实际可落地可执行纯对话模式适合问“Python 怎么删列表元素”这种通用问题剪贴板模式适合小范围调优。但一旦任务涉及跨文件改动、老项目改造、性能排查、架构决策只有 context-mode 能让你获得稳定的高质量结果。1.3 context-mode 的边界与适用场景需要先说清楚context-mode 不是银弹。它解决的是“现场感”问题也就是让 AI 知道“这里是哪、这里有什么、这里正在发生什么”。但它不能解决模型本身能力不足的问题也不能替代你的工程判断力。我现在的判断标准很简单任务越依赖“项目特有信息”越值得用 context-mode任务越通用反而没必要折腾。比如“这个函数为什么报错”是项目特有问题必须带上下文“Python 的 asyncio 和 threading 有什么区别”是通用知识直接聊就行。适用场景主要集中在四类老项目维护依赖关系复杂全局信息比局部代码更重要。跨文件重构牵一发动全身需要 AI 理解调用链。代码审查需要结合 diff 和项目约定来判断改动质量。技术文档撰写AI 需要知道项目实际结构而不是凭空生成“通用文档”。2. 核心设计context 的三层结构与注入时机2.1 第一层项目级静态上下文context-mode 最基础的一层是项目级的静态上下文。它不随会话变化描述的是这个项目本身长什么样。我在实际项目中通常会维护一个CONTEXT.md文件放在仓库根目录内容围绕五个问题展开这个项目是做什么的主要模块有哪些各在哪个目录技术栈和关键依赖是什么有什么特殊的编码约定和架构决策入口文件、配置文件、测试文件分别在哪文件不需要长三百到五百字足够。关键在于把“你花了三个月才摸清的脉络”浓缩成 AI 一眼能看懂的说明。很多团队用README.md来代替但 README 面向人讲的是“怎么用”CONTEXT.md 面向 AI讲的是“怎么理解”。两者有交集但不完全重合。我在一个微服务项目里甚至建了CONTEXT_SERVICES.md来描述每个服务的职责、依赖的上游接口、关键数据结构这样在涉及跨服务改造时AI 不会再“为了重构一个订单服务而去假设支付服务怎么实现”。2.2 第二层会话级动态上下文静态上下文描述“项目是什么”动态上下文描述“现在在发生什么”。这层上下文需要实时收集典型内容包括当前打开的文件路径和行数范围当前分支和git diff/git log --oneline -5最近一次编译运行报错的关键日志当前工作目录的目录树限制深度用户正在提问的具体目标这层是 context-mode 区别于普通文档模式的关键。我在脚本设计里会把动态上下文做成一个函数每次调用 AI 前自动生成一段格式化的文本再跟静态上下文拼在一起注入。有一次排查线上偶发超时我就把最近两小时的日志过滤片段、相关服务的调用链信息、当前的 git 分支一起带了进去。AI 很快定位到是一个第三方 SDK 在某些异常网络环境下没有设置超时导致的而这个 SDK 的使用方式项目里有自己包了一层封装全靠上下文才避免了“建议换个 SDK”这种正确但没法落地的回答。2.3 第三层工具级运行时上下文第三层是我后面加上的也是 context-mode 比较进阶的部分——让工具自己把“模型需要知道的信息”暴露出来。最常见的是语言服务器和编译诊断。比如你在 Neovim 里用 LSP 查到一个类型错误与其手动复制错误消息和代码不如让 context-mode 自动收集光标所在符号的引用列表、文件内的 lint 错误、最近的编译失败信息。这些信息是工具内部就有的只是平时没人把它们结构化地喂给 AI。再比如调试场景很多调试器支持导出变量快照和调用栈。把这些运行时信息并入上下文AI 给出的排查方向会精确得多。我自己在做一个 Python 数据处理管道时就让脚本把异常堆栈、关键变量的 shape 和 dtype、最近几条日志一并收集AI 几乎每次都能直接指出数据对齐问题出在哪一行。2.4 注入时机与窗口预算有了三层上下文下一个问题是什么时候注入全部注入显然不现实。模型上下文窗口再大塞满了无关信息也会影响效果这就像让一个专家读一份一百页的无关材料之后回答你的问题他依然会很累、很容易抓错重点。我的经验是遵循“够用就停”的原则。一个普通任务上下文控制在 2000 到 4000 token 是最舒服的区间。系统提示词占一部分项目卡片占一部分动态信息占一部分。超过 8000 token 时效果会明显下降因为关键信息会被大量边角料淹没。实际操作时我会对要注入的内容做一次“信息密度”检查删掉修饰性描述保留路径、文件名、函数名、报错信息、调用关系这五类硬信息。上下文是给模型吃的压缩饼干不是给你看的散文。3. 实操落地三步骤把 context-mode 跑起来3.1 第一步搭项目上下文卡片落地 context-mode 的第一步不是装插件而是先把项目自己搞清楚。我建议从今天开始给每个重要项目建一个CONTEXT.md参考下面的模板。# 项目上下文卡片 ## 项目定位 一句话说清楚这个项目解决什么问题服务对象是谁。 ## 技术栈 - 后端Python 3.11 FastAPI PostgreSQL - 前端React 18 TypeScript Vite - 消息队列RabbitMQ - 部署Docker Compose Nginx ## 目录结构 src/api/ # HTTP 接口层 src/services/ # 业务逻辑层 src/models/ # 数据模型与 ORM src/workers/ # 异步任务消费者 tests/ # 单元测试与集成测试 ## 关键约定 - 数据库迁移使用 Alembic字段命名 snake_case - 所有外部接口调用必须走 httpx.Client 封装禁止裸调 requests - 新的业务逻辑必须配套单元测试覆盖率目标 80% ## 入口文件 src/main.py # FastAPI 实例 src/worker.py # Celery worker 启动写卡片有两条经验值得分享。一条是“只写稳定信息”不要写频繁变化的内容比如“当前有 37 个待办 bug”这种信息今天写完明天就过期写了反而误导。另一条是“为 AI 优化表达”AI 对列表结构的理解好过大段散文能分条就分条能加路径就直接给相对路径。3.2 第二步写一个上下文收集脚本有了静态卡片接下来我们把动态信息自动化。我写了一个名为ctx.sh的 Bash 脚本放在项目根目录的scripts/下每次用到 AI 前跑一下自动生成context_snapshot.txt。#!/usr/bin/env bash set -euo pipefail SNAPSHOTcontext_snapshot.txt PROJECT_CARDCONTEXT.md OUT_DIR.ctx mkdir -p $OUT_DIR { echo # 项目静态上下文 if [[ -f $PROJECT_CARD ]]; then cat $PROJECT_CARD else echo (未找到 CONTEXT.md) fi echo echo # 当前分支与最近提交 git branch --show-current 2/dev/null || echo (非 git 仓库) git log --oneline -5 2/dev/null || true echo echo # 最近改动文件 (git diff --stat) git diff --stat HEAD 2/dev/null || true git diff --cached --stat HEAD 2/dev/null || true echo echo # 目录树 (深度2忽略常见无关目录) if command -v tree /dev/null 21; then tree -L 2 -I node_modules|venv|dist|build|.git|__pycache__ . else find . -maxdepth 2 -type d \ -not -path ./node_modules* \ -not -path ./venv* \ -not -path ./.git* \ -not -path ./dist* \ -not -path ./build* fi echo echo # 当前会话目标 echo ${SESSION_GOAL:-未设置请在调用时手动补充} } $OUT_DIR/$SNAPSHOT echo Context snapshot written to $OUT_DIR/$SNAPSHOT脚本本身不复杂但有两个细节很关键。第一个是set -euo pipefail避免某个git命令报错导致整个脚本退出也避免静默错误。第二个是输出到一个固定路径而不是直接打印到终端——AI 工具导入长文本时从文件读比从终端复制稳定得多。SESSION_GOAL这个环境变量是我特意留出来的口子让每次会话可以追加“我这次具体想做什么”避免快照变成一份没有目标感的纯资料堆。3.3 第三步绑进编辑器与终端脚本写好后手动跑还是有点懒。我把它做成了编辑器快捷键和终端命令让调用成本降到几乎为零。Neovim 里加一段映射 一键生成 context 快照并复制到剪贴板 nnoremap leadercx :silent !$HOME/.local/bin/ctx.shCR:redraw!CR:let system(cat .ctx/context_snapshot.txt)CRVS Code 用户可以在.vscode/tasks.json里加一个自定义任务绑定到快捷键。终端用户则在~/.bashrc加个别名alias ctxbash scripts/ctx.sh echo --- snapshot ready ---值得一提的是有些 AI 辅助工具本身支持引用文件或目录比如一些新出的 CLI 工具允许你在启动时指定“读哪些文件”。context-mode 的做法其实跟这些工具的底层机制同源只是我们手动控制了内容的选择和裁剪不让工具一股脑全读。3.4 一次真实调用演示我拿一个实际例子完整过一遍。假设我在处理一个 Django 项目问题是“用户注册接口偶尔返回 500”。第一步跑ctx.sh生成快照。第二步打开快照文件手动补充本次目标SESSION_GOAL用户注册接口 POST /api/v1/auth/register 偶发 500需要定位可疑代码路径并给出修复建议 bash scripts/ctx.sh第三步把context_snapshot.txt的内容粘贴到 AI 助手的第一个消息里然后追问一句“请结合以上项目上下文分析”。实际效果是AI 会看到注册接口的路径在src/api/auth.py看到最近的 diff 动过auth_service.py看到项目里统一用db.session操作数据库而不是裸连接然后它的分析大概率会沿着这些线索走而不是给一篇“注册接口设计最佳实践”。这不是玄学是 AI 的注意力被信息密度引导了。4. 踩坑实录context 本身也会骗人4.1 上下文膨胀塞得越多模型越糊涂我刚开始做 context-mode 时踩过最大的坑就是“为了全面而全面”。我把能找到的信息全塞进上下文——完整的数据库 schema、几十个迁移文件、所有服务的 README、助手的说明书。结果模型给出的答案比不塞还差它会在无关信息里“找到”太多似是而非的线索。后来我才想明白上下文不是资料库而是注意力分配器。模型看太多无关内容真实的关键信息会被稀释。现在我的指标很简单——如果一个文件里的信息不能直接影响当前任务的处理方式就不该进上下文。判断标准是删掉它回答会不会变差不会变差就删。压缩也有技巧。我常用“三行摘要”代替整段代码文件路径 核心职责 与当前任务的关系。比如src/services/user_service.py 职责用户注册、登录、资料更新。 与当前任务的关系注册接口 500 的错误被业务日志指向该文件第 142 行附近。这比把整个user_service.py塞进去高效得多。4.2 上下文污染旧的会话把方向带偏另一个常见坑是上下文污染。我一开始图省事在一个长会话里连续聊好几个不同任务结果 AI 把上一个任务里的假设带到了下一个任务里。比如先聊“Redis 缓存失效问题”紧接着让它看“Nginx 配置有没有坑”。模型很可能在分析 Nginx 时还带着 Redis 的思维框架给出一些莫名其妙的关联性建议。会话之间要隔离这是一个很便宜但很重要的习惯。我现在会刻意遵循“一个会话一个目标”的原则。如果发现对话跑偏就直接新开会话重新注入这次任务的上下文而不是在旧对话里试图“纠正方向”。还有一个细节如果你用了 AI 助手的“记忆”或“长期上下文”功能注意旧的记忆也可能污染新任务。定期清理无关的历史摘要比一味堆记忆更有效。4.3 上下文泄露隐私与权限边界context-mode 做的是“把更多信息喂给 AI”这也意味着你必须对喂出去的信息负责。内部服务名、数据库连接串、客户数据字段、未公开的架构决策一旦进入上下文就会被发送到模型服务端。我的底线是三条生产环境的敏感配置密钥、口令永远不写入 CONTEXT.md 和任何快照。涉及真实用户数据的字段名、表名在快照中做脱敏处理用user_profile代替users表里那个包含身份证号的id_card_no列。私有项目的完整目录树可能透露过多信息必要时把目录树替换成只列出“与当前任务相关”的几个关键目录。安全不是加分项是底线。就算你的 AI 工具宣称“数据不用于训练”也不代表数据不经过它的服务端。能少给就少给能脱敏就脱敏。4.4 常见问题速查表现象可能原因解决方式AI 回答泛泛而谈上下文里没有项目结构信息确认注入 CONTEXT.md 和目录树AI 答非所问会话目标不明确在快照里写清“当前会话目标”回答越来越偏旧任务信息污染新任务新开会话重新生成快照输出质量反而不如不带上下文上下文膨胀关键信息被稀释按“三行摘要”压缩删无关内容上下文太长被模型截断注入内容超过窗口限制控制 token 预算优先保留硬信息AI 引用了不存在的文件快照过期与当前仓库状态不一致动手前重新跑ctx.sh刷新快照5. 进阶玩法与我的经验补充5.1 让 context-mode 跟自动化任务联动当你习惯了手动触发 context-mode下一步可以试试让它融入自动化流程。比如 CI 流水线里每次构建失败后跑一个脚本自动生成包含“失败日志、相关改动文件、最近提交信息”的上下文包然后把分析请求发给 AI让它在代码合并前给出问题定位。这相当于给团队加了一个值日生每个失败的构建都会自带“案发现场资料”。我在一个数据同步任务里做过类似的事情。定时任务失败时脚本会把错误堆栈、最近一次成功运行的快照差异、相关配置文件 diff 打包成一个 markdown 文件然后调用 AI 服务分析原因。以前这种问题要人肉翻日志现在几分钟内就能拿到初判。持续跑了三个月定位效率提升很明显。自动化联动还有一个好处它逼着你把上下文模板改得更精简。因为没有人会在流水线里等一段冗长的分析输出必须短、准、直接给结论。5.2 我的几条实操建议做到现在我自己总结了几条简单但管用的规则。第一CONTEXT.md 不是写一次就完了。项目结构大变时要同步更新至少每两周过一遍确认里面说的目录、约定还成立。过期的上下文比没有上下文更恐怖因为它会一本正经地把 AI 带偏。第二善用“角色 目标 约束”三段式提示词来配合上下文。注入项目信息之后用一句“你是一位熟悉该项目的资深后端工程师请先看上下文再回答我的问题”来设置角色用“不需要给通用方案只针对项目现状给出可落地修复”来设置约束。上下文负责提供“现场感”提示词负责提供“行动方向”。第三不要迷信任何“全自动上下文注入”的工具。自动收集容易自动判断“什么信息对这个任务是关键”极难。我会用工具做收集用自己做判断在注入之前扫一眼快照里有没有明显多余、过时、敏感的东西。第四尽量让上下文“可追溯”。我在快照文件头部加了一行生成时间和 git 版本号这样如果发现 AI 基于过期信息回答我能立刻知道是哪次快照导致的而不是对着空气猜。这些规则看上去都不起眼但叠加在一起就是 context-mode 真正提升 AI 协作质量的底层逻辑不是给 AI 更多信息而是给它更准确、更干净、更可控的信息。我个人现在的工作习惯是凡是改动跨了三个文件以上的任务一律先生成快照再开对话。这个动作多花三十秒但省掉的返工时间远远不止三十秒。
第一次意识到 context-mode 这个问题的价值是在某个周三下午改一个用了三年的老项目。AI 辅助工具已经装好了提示词写得很清楚“帮我看看这个函数为什么偶发异常”结果模型答非所问给了我一篇关于异常处理的最佳实践论文一字没提我这个函数。问题不是它不懂异常而是它根本不知道我在改哪个文件、这个函数被谁调用过、项目里有没有约定俗成的写法。那一刻我意识到AI 的能力上限在模型但实际效果的下限往往在“上下文”。context-mode 就是用来治这个病的——它不是什么魔法而是一套让 AI 助手明确感知“你现在在哪个项目、在处理哪个问题、能看哪些信息”的工作模式。这篇文章适合所有把 AI 当成生产力工具但又被“懂很多却接不住话”折磨的开发者、技术文档写作者和数据工程师。1. 先想清楚context-mode 到底治什么病1.1 我遇到的“懂很多但接不住话”的AI绝大多数人用 AI 辅助编程时工作流是这样的把当前文件里的几十行代码复制出来粘贴进对话框然后问问题。运气好的时候AI 能给出像模像样的答案运气不好的时候它会盯着这段孤零零的代码开始自由发挥甚至会“纠正”一个根本不是 bug 的地方。问题出在哪出在上下文缺失。你脑子里有一整座冰山——项目背景、模块关联、历史决策、编码偏好、最近改动——但粘贴给 AI 的只有露出水面的一角。context-mode 的思路就是把这些本该被 AI 感知的信息用一种结构化、可控的方式主动喂给它。我自己的经历是最典型的教材。有一次我让 AI 给一个 Python 服务加限流逻辑我贴了 middleware 的代码AI 给了我一个挺标准的滑动窗口实现。结果一跑压力测试直接把这台机器的 Redis 连接打满了。原因很简单项目里已经有另一个中间件在统一管理 Redis 连接池我贴的几十行代码里根本没有暗示这件事AI 自然不知道。如果当时把项目上下文带进去它大概率会优先复用现有连接池而不是从零起一个新的。这个教训让我开始认真对待“上下文”这件事而不是动不动就骂模型蠢。1.2 一张表看懂三种“上下文模式”我把开发者跟 AI 协作的常见姿势分成三类你可以对照一下自己属于哪种。模式典型动作AI 能看到什么常见结果纯对话模式直接敲问题不带任何资料只有你打的字答案泛泛而谈正确但没用剪贴板模式复制粘贴当前文件代码孤立的一段代码能改局部经常改崩全局context-mode主动注入项目骨架、文件清单、改动记录、目标说明项目结构 相关文件 任务意图回答贴合实际可落地可执行纯对话模式适合问“Python 怎么删列表元素”这种通用问题剪贴板模式适合小范围调优。但一旦任务涉及跨文件改动、老项目改造、性能排查、架构决策只有 context-mode 能让你获得稳定的高质量结果。1.3 context-mode 的边界与适用场景需要先说清楚context-mode 不是银弹。它解决的是“现场感”问题也就是让 AI 知道“这里是哪、这里有什么、这里正在发生什么”。但它不能解决模型本身能力不足的问题也不能替代你的工程判断力。我现在的判断标准很简单任务越依赖“项目特有信息”越值得用 context-mode任务越通用反而没必要折腾。比如“这个函数为什么报错”是项目特有问题必须带上下文“Python 的 asyncio 和 threading 有什么区别”是通用知识直接聊就行。适用场景主要集中在四类老项目维护依赖关系复杂全局信息比局部代码更重要。跨文件重构牵一发动全身需要 AI 理解调用链。代码审查需要结合 diff 和项目约定来判断改动质量。技术文档撰写AI 需要知道项目实际结构而不是凭空生成“通用文档”。2. 核心设计context 的三层结构与注入时机2.1 第一层项目级静态上下文context-mode 最基础的一层是项目级的静态上下文。它不随会话变化描述的是这个项目本身长什么样。我在实际项目中通常会维护一个CONTEXT.md文件放在仓库根目录内容围绕五个问题展开这个项目是做什么的主要模块有哪些各在哪个目录技术栈和关键依赖是什么有什么特殊的编码约定和架构决策入口文件、配置文件、测试文件分别在哪文件不需要长三百到五百字足够。关键在于把“你花了三个月才摸清的脉络”浓缩成 AI 一眼能看懂的说明。很多团队用README.md来代替但 README 面向人讲的是“怎么用”CONTEXT.md 面向 AI讲的是“怎么理解”。两者有交集但不完全重合。我在一个微服务项目里甚至建了CONTEXT_SERVICES.md来描述每个服务的职责、依赖的上游接口、关键数据结构这样在涉及跨服务改造时AI 不会再“为了重构一个订单服务而去假设支付服务怎么实现”。2.2 第二层会话级动态上下文静态上下文描述“项目是什么”动态上下文描述“现在在发生什么”。这层上下文需要实时收集典型内容包括当前打开的文件路径和行数范围当前分支和git diff/git log --oneline -5最近一次编译运行报错的关键日志当前工作目录的目录树限制深度用户正在提问的具体目标这层是 context-mode 区别于普通文档模式的关键。我在脚本设计里会把动态上下文做成一个函数每次调用 AI 前自动生成一段格式化的文本再跟静态上下文拼在一起注入。有一次排查线上偶发超时我就把最近两小时的日志过滤片段、相关服务的调用链信息、当前的 git 分支一起带了进去。AI 很快定位到是一个第三方 SDK 在某些异常网络环境下没有设置超时导致的而这个 SDK 的使用方式项目里有自己包了一层封装全靠上下文才避免了“建议换个 SDK”这种正确但没法落地的回答。2.3 第三层工具级运行时上下文第三层是我后面加上的也是 context-mode 比较进阶的部分——让工具自己把“模型需要知道的信息”暴露出来。最常见的是语言服务器和编译诊断。比如你在 Neovim 里用 LSP 查到一个类型错误与其手动复制错误消息和代码不如让 context-mode 自动收集光标所在符号的引用列表、文件内的 lint 错误、最近的编译失败信息。这些信息是工具内部就有的只是平时没人把它们结构化地喂给 AI。再比如调试场景很多调试器支持导出变量快照和调用栈。把这些运行时信息并入上下文AI 给出的排查方向会精确得多。我自己在做一个 Python 数据处理管道时就让脚本把异常堆栈、关键变量的 shape 和 dtype、最近几条日志一并收集AI 几乎每次都能直接指出数据对齐问题出在哪一行。2.4 注入时机与窗口预算有了三层上下文下一个问题是什么时候注入全部注入显然不现实。模型上下文窗口再大塞满了无关信息也会影响效果这就像让一个专家读一份一百页的无关材料之后回答你的问题他依然会很累、很容易抓错重点。我的经验是遵循“够用就停”的原则。一个普通任务上下文控制在 2000 到 4000 token 是最舒服的区间。系统提示词占一部分项目卡片占一部分动态信息占一部分。超过 8000 token 时效果会明显下降因为关键信息会被大量边角料淹没。实际操作时我会对要注入的内容做一次“信息密度”检查删掉修饰性描述保留路径、文件名、函数名、报错信息、调用关系这五类硬信息。上下文是给模型吃的压缩饼干不是给你看的散文。3. 实操落地三步骤把 context-mode 跑起来3.1 第一步搭项目上下文卡片落地 context-mode 的第一步不是装插件而是先把项目自己搞清楚。我建议从今天开始给每个重要项目建一个CONTEXT.md参考下面的模板。# 项目上下文卡片 ## 项目定位 一句话说清楚这个项目解决什么问题服务对象是谁。 ## 技术栈 - 后端Python 3.11 FastAPI PostgreSQL - 前端React 18 TypeScript Vite - 消息队列RabbitMQ - 部署Docker Compose Nginx ## 目录结构 src/api/ # HTTP 接口层 src/services/ # 业务逻辑层 src/models/ # 数据模型与 ORM src/workers/ # 异步任务消费者 tests/ # 单元测试与集成测试 ## 关键约定 - 数据库迁移使用 Alembic字段命名 snake_case - 所有外部接口调用必须走 httpx.Client 封装禁止裸调 requests - 新的业务逻辑必须配套单元测试覆盖率目标 80% ## 入口文件 src/main.py # FastAPI 实例 src/worker.py # Celery worker 启动写卡片有两条经验值得分享。一条是“只写稳定信息”不要写频繁变化的内容比如“当前有 37 个待办 bug”这种信息今天写完明天就过期写了反而误导。另一条是“为 AI 优化表达”AI 对列表结构的理解好过大段散文能分条就分条能加路径就直接给相对路径。3.2 第二步写一个上下文收集脚本有了静态卡片接下来我们把动态信息自动化。我写了一个名为ctx.sh的 Bash 脚本放在项目根目录的scripts/下每次用到 AI 前跑一下自动生成context_snapshot.txt。#!/usr/bin/env bash set -euo pipefail SNAPSHOTcontext_snapshot.txt PROJECT_CARDCONTEXT.md OUT_DIR.ctx mkdir -p $OUT_DIR { echo # 项目静态上下文 if [[ -f $PROJECT_CARD ]]; then cat $PROJECT_CARD else echo (未找到 CONTEXT.md) fi echo echo # 当前分支与最近提交 git branch --show-current 2/dev/null || echo (非 git 仓库) git log --oneline -5 2/dev/null || true echo echo # 最近改动文件 (git diff --stat) git diff --stat HEAD 2/dev/null || true git diff --cached --stat HEAD 2/dev/null || true echo echo # 目录树 (深度2忽略常见无关目录) if command -v tree /dev/null 21; then tree -L 2 -I node_modules|venv|dist|build|.git|__pycache__ . else find . -maxdepth 2 -type d \ -not -path ./node_modules* \ -not -path ./venv* \ -not -path ./.git* \ -not -path ./dist* \ -not -path ./build* fi echo echo # 当前会话目标 echo ${SESSION_GOAL:-未设置请在调用时手动补充} } $OUT_DIR/$SNAPSHOT echo Context snapshot written to $OUT_DIR/$SNAPSHOT脚本本身不复杂但有两个细节很关键。第一个是set -euo pipefail避免某个git命令报错导致整个脚本退出也避免静默错误。第二个是输出到一个固定路径而不是直接打印到终端——AI 工具导入长文本时从文件读比从终端复制稳定得多。SESSION_GOAL这个环境变量是我特意留出来的口子让每次会话可以追加“我这次具体想做什么”避免快照变成一份没有目标感的纯资料堆。3.3 第三步绑进编辑器与终端脚本写好后手动跑还是有点懒。我把它做成了编辑器快捷键和终端命令让调用成本降到几乎为零。Neovim 里加一段映射 一键生成 context 快照并复制到剪贴板 nnoremap leadercx :silent !$HOME/.local/bin/ctx.shCR:redraw!CR:let system(cat .ctx/context_snapshot.txt)CRVS Code 用户可以在.vscode/tasks.json里加一个自定义任务绑定到快捷键。终端用户则在~/.bashrc加个别名alias ctxbash scripts/ctx.sh echo --- snapshot ready ---值得一提的是有些 AI 辅助工具本身支持引用文件或目录比如一些新出的 CLI 工具允许你在启动时指定“读哪些文件”。context-mode 的做法其实跟这些工具的底层机制同源只是我们手动控制了内容的选择和裁剪不让工具一股脑全读。3.4 一次真实调用演示我拿一个实际例子完整过一遍。假设我在处理一个 Django 项目问题是“用户注册接口偶尔返回 500”。第一步跑ctx.sh生成快照。第二步打开快照文件手动补充本次目标SESSION_GOAL用户注册接口 POST /api/v1/auth/register 偶发 500需要定位可疑代码路径并给出修复建议 bash scripts/ctx.sh第三步把context_snapshot.txt的内容粘贴到 AI 助手的第一个消息里然后追问一句“请结合以上项目上下文分析”。实际效果是AI 会看到注册接口的路径在src/api/auth.py看到最近的 diff 动过auth_service.py看到项目里统一用db.session操作数据库而不是裸连接然后它的分析大概率会沿着这些线索走而不是给一篇“注册接口设计最佳实践”。这不是玄学是 AI 的注意力被信息密度引导了。4. 踩坑实录context 本身也会骗人4.1 上下文膨胀塞得越多模型越糊涂我刚开始做 context-mode 时踩过最大的坑就是“为了全面而全面”。我把能找到的信息全塞进上下文——完整的数据库 schema、几十个迁移文件、所有服务的 README、助手的说明书。结果模型给出的答案比不塞还差它会在无关信息里“找到”太多似是而非的线索。后来我才想明白上下文不是资料库而是注意力分配器。模型看太多无关内容真实的关键信息会被稀释。现在我的指标很简单——如果一个文件里的信息不能直接影响当前任务的处理方式就不该进上下文。判断标准是删掉它回答会不会变差不会变差就删。压缩也有技巧。我常用“三行摘要”代替整段代码文件路径 核心职责 与当前任务的关系。比如src/services/user_service.py 职责用户注册、登录、资料更新。 与当前任务的关系注册接口 500 的错误被业务日志指向该文件第 142 行附近。这比把整个user_service.py塞进去高效得多。4.2 上下文污染旧的会话把方向带偏另一个常见坑是上下文污染。我一开始图省事在一个长会话里连续聊好几个不同任务结果 AI 把上一个任务里的假设带到了下一个任务里。比如先聊“Redis 缓存失效问题”紧接着让它看“Nginx 配置有没有坑”。模型很可能在分析 Nginx 时还带着 Redis 的思维框架给出一些莫名其妙的关联性建议。会话之间要隔离这是一个很便宜但很重要的习惯。我现在会刻意遵循“一个会话一个目标”的原则。如果发现对话跑偏就直接新开会话重新注入这次任务的上下文而不是在旧对话里试图“纠正方向”。还有一个细节如果你用了 AI 助手的“记忆”或“长期上下文”功能注意旧的记忆也可能污染新任务。定期清理无关的历史摘要比一味堆记忆更有效。4.3 上下文泄露隐私与权限边界context-mode 做的是“把更多信息喂给 AI”这也意味着你必须对喂出去的信息负责。内部服务名、数据库连接串、客户数据字段、未公开的架构决策一旦进入上下文就会被发送到模型服务端。我的底线是三条生产环境的敏感配置密钥、口令永远不写入 CONTEXT.md 和任何快照。涉及真实用户数据的字段名、表名在快照中做脱敏处理用user_profile代替users表里那个包含身份证号的id_card_no列。私有项目的完整目录树可能透露过多信息必要时把目录树替换成只列出“与当前任务相关”的几个关键目录。安全不是加分项是底线。就算你的 AI 工具宣称“数据不用于训练”也不代表数据不经过它的服务端。能少给就少给能脱敏就脱敏。4.4 常见问题速查表现象可能原因解决方式AI 回答泛泛而谈上下文里没有项目结构信息确认注入 CONTEXT.md 和目录树AI 答非所问会话目标不明确在快照里写清“当前会话目标”回答越来越偏旧任务信息污染新任务新开会话重新生成快照输出质量反而不如不带上下文上下文膨胀关键信息被稀释按“三行摘要”压缩删无关内容上下文太长被模型截断注入内容超过窗口限制控制 token 预算优先保留硬信息AI 引用了不存在的文件快照过期与当前仓库状态不一致动手前重新跑ctx.sh刷新快照5. 进阶玩法与我的经验补充5.1 让 context-mode 跟自动化任务联动当你习惯了手动触发 context-mode下一步可以试试让它融入自动化流程。比如 CI 流水线里每次构建失败后跑一个脚本自动生成包含“失败日志、相关改动文件、最近提交信息”的上下文包然后把分析请求发给 AI让它在代码合并前给出问题定位。这相当于给团队加了一个值日生每个失败的构建都会自带“案发现场资料”。我在一个数据同步任务里做过类似的事情。定时任务失败时脚本会把错误堆栈、最近一次成功运行的快照差异、相关配置文件 diff 打包成一个 markdown 文件然后调用 AI 服务分析原因。以前这种问题要人肉翻日志现在几分钟内就能拿到初判。持续跑了三个月定位效率提升很明显。自动化联动还有一个好处它逼着你把上下文模板改得更精简。因为没有人会在流水线里等一段冗长的分析输出必须短、准、直接给结论。5.2 我的几条实操建议做到现在我自己总结了几条简单但管用的规则。第一CONTEXT.md 不是写一次就完了。项目结构大变时要同步更新至少每两周过一遍确认里面说的目录、约定还成立。过期的上下文比没有上下文更恐怖因为它会一本正经地把 AI 带偏。第二善用“角色 目标 约束”三段式提示词来配合上下文。注入项目信息之后用一句“你是一位熟悉该项目的资深后端工程师请先看上下文再回答我的问题”来设置角色用“不需要给通用方案只针对项目现状给出可落地修复”来设置约束。上下文负责提供“现场感”提示词负责提供“行动方向”。第三不要迷信任何“全自动上下文注入”的工具。自动收集容易自动判断“什么信息对这个任务是关键”极难。我会用工具做收集用自己做判断在注入之前扫一眼快照里有没有明显多余、过时、敏感的东西。第四尽量让上下文“可追溯”。我在快照文件头部加了一行生成时间和 git 版本号这样如果发现 AI 基于过期信息回答我能立刻知道是哪次快照导致的而不是对着空气猜。这些规则看上去都不起眼但叠加在一起就是 context-mode 真正提升 AI 协作质量的底层逻辑不是给 AI 更多信息而是给它更准确、更干净、更可控的信息。我个人现在的工作习惯是凡是改动跨了三个文件以上的任务一律先生成快照再开对话。这个动作多花三十秒但省掉的返工时间远远不止三十秒。
