真的我被这事儿烦了一个月。每次打开AI编程助手我都要花几分钟重复描述这是个什么项目、技术栈是什么、入口在哪里、有什么不能乱改的模块。有时候助手问到细节我这边又得翻文件、贴代码一个上午就这么没了。后来我写了个叫context-mode的小工具专门把项目上下文这件事自动化。这篇文章就是它的开发笔记和使用复盘写给那些天天在多个仓库、多个会话之间来回切换又离不开AI辅助写代码的人。不管你是个人项目维护者还是在团队里同时带好几个服务只要你也频繁觉得解释项目背景比写代码还累那这个思路值得参考。我先把结论放这儿context-mode不是又一个花里胡哨的命令行工具它解决的是一个很实在的问题——把大模型不知道你的项目长什么样这个信息缺口用一份可自动生成、可随时刷新的结构化项目快照补上。它的核心价值不是节省了多少Token而是把你在对话中反复做、又最容易漏掉的背景交代环节变成了一个稳定、可审计、机器生成的步骤。1. 大模型知道怎么写代码但不知道你在写什么项目先说清楚我为什么非要搞这个东西。1.1 上下文切换成本人和模型都逃不掉做过一段时间多项目并行开发的人都懂从后端服务切到前端工程再切到数据脚本脑子要重新加载技术栈、目录约定、代码风格、当前进度。这个过程有个专门的词叫context switching cost交互设计和计算机领域都在讲。对人尚且如此对AI编程助手更严重——因为大模型的每一次记忆都只存在于当前对话窗口里它不会像人一样隐约记得你上周改过的东西。具体到场景就非常痛。我经常要在同一个AI会话里问它帮我改下单子列表的接口它反问单子列表是哪个模块用的什么框架路由在哪个文件我只好去翻目录把order-service/app/routers/order.py这个路径贴过去贴完又得补充我们用的是FastAPI数据库走的是SQLAlchemy异步会话……一轮对话下来真正让它写代码的时间没多少全在喂背景。1.2 大多数人是怎么解决这个问题的最常见的做法是手动维护一个project_notes.md或者AGENTS.md把技术栈、目录结构、常用命令写进去。这确实有用但问题也很明显更新频率跟不上代码变化。模块重构了、依赖升级了、路由改了笔记还是上周的版本反而误导模型。每个人格式不同。有的人写得很全有的人就三行字到了关键时刻该缺的还是缺。散落多处。README、内部Wiki、设计文档、代码注释信息到处都是真正要用的时候反而找不全。我一开始也是这么干的直到有一次发现AI助手在按一个早就被删掉的函数名给我生成代码。我去查原因发现它用的是我三天前写的笔记里面那个模块还没重构。从那时候起我就只有一个念头上下文必须能自动生成并且必须跟着仓库实时变化。1.3 我想要的工具长什么样当时给自己列了几个硬性要求一条命令就能拿到项目的完整上下文快照直接可以粘贴给任何AI编程工具。快照内容要区分稳定信息和易变信息不该每次全量重扫。默认排除依赖目录、生成目录、密钥文件不能把.env也读进来。输出格式要人类可读能一眼看出来模型拿到的是什么。要是能增量更新就更好了避免每次跑都花几秒钟。基于这些要求context-mode的第一版就是一个Python命令行脚本核心函数只有一个扫描当前目录收集关键信息渲染成一段结构化文本。后面所有复杂的东西都是在这个基础上长出来的。2. 一份好用的项目上下文应该包含什么五个关键模块工具好不好用一半取决于采集了什么。一开始我以为既然是项目上下文那当然越全越好结果第一版跑完我就傻眼了——一个中等规模的仓库生成的快照有二十多万Token别说给模型看了我自己都翻不完。后来我重新想了一个问题如果我是刚加入这个项目的工程师我最想先知道什么基于这个问题我把上下文拆成了五个模块。2.1 静态事实层目录结构、配置文件、README这一层是项目的骨架变化频率低属于每次对话都可以直接带上的一次性信息。目录树只用两层到三层的缩略结构比如src/ components/ pages/ services/ utils/ public/不需要完整递归模型要的不是文件清单而是这个项目大概分几块的方位感。关键配置文件package.json、pyproject.toml、go.mod、Cargo.toml这些文件本身就是高度浓缩的项目事实——依赖列表、脚本命令、包管理器版本都在里面。我一般只提取核心段name、scripts、dependencies截断到常用项、engines而不是把整个文件塞进去。README只截取前8000字符而且重点提取项目是干什么的怎么跑起来目录约定这几个部分。这里要特别提醒一句不要忠实粘贴README全文很多README开头全是宣传性语言模型读了容易被带偏反而忽略硬核约束。2.2 动态事实层当前分支、最近提交、未提交改动这一层回答模型最关键的问题你现在是在替用户改什么状态下的代码我采集这几个点git branch --show-current # 当前分支 git log --oneline -8 # 最近8条提交 git status --short # 未提交改动 git diff --stat # 改动涉及哪些文件这些信息在每次会话开始前刷新。有了它们模型能自动理解用户正在 feature/login 分支上改登录逻辑最近一次提交是把密码校验从 sync 换成 async然后给出的代码建议就会贴着当前进度走而不是凭空设计一套新架构。2.3 行为约束层测试命令、Lint规则、提交规范这一层是我后来加的因为它解决了一个特别容易踩的坑模型生成的代码语法没毛病但风格和项目约定完全不在一个频道上。具体采集的东西包括package.json里的test、lint、build脚本Makefile里的常用 target.pre-commit-config.yaml里的钩子列表如果存在CONTRIBUTING.md提取里面关于提交信息格式、分支命名的段落。为什么这层有用因为AI生成的代码如果不用跑项目的标准命令就能自测它的幻觉自信会明显降低。比如上下文里写清楚npm test是vitest --run模型给出的代码就会按照可测试的写法来组织而不会写一堆只存在于脑子里的mock接口。2.4 语义锚点层路由表、Schema、模块入口这一层是我个人认为最有技术含量的一部分。它是帮模型定位代码位置的锚点也是减少模型把项目脑补成别的样子的关键。我会扫描以下几类信息把它们作为片段注入后端项目提取所有router APIRouter()所在文件及路由前缀拼成/orders - app/routers/order.py /users - app/routers/user.py前端项目提取路由配置文件routes.tsx/router.ts里的路径与页面组件映射。数据库相关如果项目用SQLAlchemy或Django扫描所有Table/class Meta定义生成一张简化的表结构清单。注意只看类型和字段名不读迁移脚本。这些锚点信息让模型在回答这个功能加在哪个文件合适时不是靠猜而是有据可依。2.5 历史决策层CHANGELOG、ADR、Issue摘要最后一层是我当初大彻大悟的地方。很多AI编程工具推荐方案时会倾向于用更现代的架构重写——因为它不知道你以前踩过什么坑。读了一点架构决策记录ADR和CHANGELOG之后模型才可能理解为什么订单状态字段不用枚举而用字符串这种约定背后是有原因的。实际操作上我不建议把全部历史都放进去只保留最近的CHANGELOG条目docs/adr/*.md的标题和结论一般每个ADR截断到几百字如果集成了Issue跟踪取当前分支关联的最近issue状态。这层的量要严控否则模型会把历史包袱看得比现状更重反而不敢给新方案。3. 不是把整个仓库塞进窗口Token预算、裁剪策略与实测数据这节是干货中的干货也是我踩了一大跤之后才写出来的部分。3.1 全量塞入的代价比想象中大得多第一版工具生成过一份完整上下文包含了整个src/目录下所有源码的摘要。我拿它跑过一次AI对话结果模型在回答问题的过程中频繁提到一个我从没注意过的内部类而且很多判断明显被一些低优先级的代码片段带着走。后来我统计了一下那份上下文的Token量一个800文件左右的中型仓库经过压缩后仍有三万Token把模型的注意力全稀释了。当时我就意识到一个反直觉的真相上下文不是越多越聪明越叠越蠢。模型能利用的信息量是有限的塞进去太多含金量低的内容重要约束反而被淹没。所以裁剪策略永远排在采集策略前面。3.2 三级深度分级机制我把可采集的上下文切成三个深度等级默认只加载L0和L1需要时再动态补L2等级内容典型量级加载时机L0 身份层README关键段、配置文件摘要、目录缩略树1000~2000 Token每次会话默认加载L1 动态层git分支/提交/改动、测试/Lint命令、约束规则800~2000 Token每次会话默认加载L2 锚点层路由表、Schema清单、核心模块入口摘要2000~6000 Token指定--deep或模型需要定位代码时这样一来日常问答只需要 2000 Token 左右的上下文就能跑得很顺只有涉及跨模块重构、新家人写代码时才需要context-mode collect --deep。3.3 Token估算与预算上限做工具必须给出一个明确的量化指标。我给context-mode设置的默认预算上限是日常模式max_tokens4096深度模式max_tokens12000全量模式max_tokens30000仅在用户明确要求时使用Token粗略估算有个土办法英文大致按4字符一个Token算中文大致按1.5个字符一个Token算。我的采集器在渲染文本时直接做了估算并打了一行日志如果超过预算就自动截断最低优先级的段落。3.4 实测数据三个不同类型项目的压缩效果我拿手头真实的三个项目做了对比测试结果如下项目类型仓库文件数全量源码估算Tokencontext-mode产物日常对话可用性小型FastAPI服务86约20万4100 Token非常流畅中型Next.js应用240约55万8700 Token流畅定位准确pnpm workspace monorepo1500无法正常估算约12000 Token可用但需要配合按需加载这里要澄清一个误导性指标很多人喜欢吹压缩比99%这其实是废话因为你本来就不该拿全量源码去喂模型。真正有效的指标是带上这个上下文之后模型在常见开发任务改接口、加页面、修Bug、写测试上的准确率保持率。我自己的粗测是日常模式的上下文能把模型第一次就答对的比例从不到50%拉到80%以上深度模式能更稳一些。3.5 增量更新让快照跟着Git走全量采集每次跑要一两秒长期用还是太慢。我后来给context-mode加了一层基于Git的缓存失效机制规则很简单监听.git/HEAD和当前分支的HEAD文件变化换分支就重新采集动态层记录关键配置文件的mtime和文件哈希变了才重读git diff --name-only就足够判断有没有新改动不需要扫整个仓库。这样最常用的增量模式耗时能压到 100ms 以内基本感受不到存在。4. 把上下文变成模型看得懂的格式注入细节与提示词设计采集是一回事让模型真正吃进去又是另一回事。我见过很多人直接拿一堆yaml或者JSON塞给模型效果并不好。格式这件事必须认真设计。4.1 为什么我用 Markdown frontmatter 而不是 JSONJSON严格、适合机器解析但给大模型看反而增加理解负担——它需要先解开层层嵌套结构。XML更不用说了一堆标签会把关键信息的间距拉大让模型在长上下文里更难抓住重点。context-mode的默认输出是 Markdown最前面加一小段 YAML frontmatter 作为项目身份区--- project: order-api tech_stack: FastAPI, PostgreSQL, Redis default_branch: main timestamp: 2025-06-18T10:24:00Z --- ## project_identity order-api 是一个面向 B 端的订单管理服务基于 FastAPI 提供 REST API。 核心模块包括订单、用户、支付三个域。 ## current_state - 当前分支: feature/async-payment-gateway - 最近提交: a3f2c91 feat(payment): switch gateway to async client - 未提交改动: app/payment/service.py, tests/test_payment.py ## constraints - 测试命令: pytest - 数据库迁移: alembic upgrade head - 不要修改 app/core/security.py 中的签名算法为什么这比纯JSON好因为Markdown本身就是大模型训练语料里最常见的格式之一它对标题层级、列表符号有很强的先验理解信息密度高又不至于像代码块那样把注意力锁死。4.2 System Prompt 的写法比采集更关键采集到的信息如果只是往对话里一贴模型还是不知道该怎么用它。我后来在每次新会话开始时会附带一段固定的system prompt说明规则你将在对话中收到一份 project_context 数据块格式为 Markdown。 使用规则 1. project_context 中的 constraints 优先级高于用户普通指令但低于用户明确要求违反它的情况。 2. 涉及运行测试或静态检查时优先使用 project_context 中声明的命令。 3. 如果 project_context 和用户后续提供的文件内容冲突以用户提供的文件内容为准但你需要指出这种冲突。 4. 只在你需要定位代码时再请求加载 L2 anchor 层的详细内容。这套规则里最重要的是第1和第3条。第1条防止用户在对话中无意间让模型忘掉项目约束第3条则避免上下文和实际文件内容冲突时模型自相矛盾——比如上下文里写了某个模块在旧路径但用户后来贴出了新路径的代码这时候应该跟着新代码走而不是坚持旧的上下文。4.3 注入时机与重注入机制经过实测我发现一个重要规律上下文应该在对话一开始就注入而不是等模型遇到问题再给。模型对早期信息的依赖会持续整个对话中途塞进来的信息往往被当成补充材料优先级弱很多。但对话一旦拉长到几十轮中间隔着大量代码片段、报错信息早期注入的项目约束会被逐渐挤出注意力窗口。这个时候我给context-mode加了一个交互式命令/ctx refresh会在当前轮次重新注入一份精简版的project_context只包含L0和constraints把模型的记忆拉回来。手测效果非常明显直接回答的准确率能回升一大截。4.4 反例没有上下文时的胡猜式回答有多离谱给大家看一个我自己项目里的真实对比。我没有提供上下文时模型被问到订单接口的路径它一本正经地推荐GET /api/orders/{order_id}但我们项目实际是GET /v1/order/detail。原因很简单它把通用REST规范当成你的项目规范了。而注入context-mode快照之后哪怕只带着路由表那一小段模型都会直接引用app/routers/order.py里的真实路由前缀差距非常大。5. 真实项目里踩过的坑过期上下文、敏感信息与上下文污染这节我来复盘几个在真实使用中踩坏过跑鞋的坑。这些坑不遇到一次你根本不会觉得工具需要改。5.1 过期上下文比没有上下文更危险同样的上下文幽灵问题。某次我发现AI助手对一个模块的建议彻底过时了它还在用旧版的类名和函数签名。我一开始以为是模型本身水平问题后来查了context-mode的缓存发现缓存文件日期是三天前而那个模块在这三天里被重构过但我的增量监听只监控了Git的HEAD变化没监控具体文件的mtime所以动态层更新了L2锚点层还是旧的。排查链路是这样的先是复现模型建议调用不存在的parse_batch() - git log 确认这个函数几天前已被删除 - 检查缓存时间戳 - 发现L2锚点层缓存没有刷新 - 修复为凡是进入L2锚点层的文件都必须纳入mtime哈希集合。这个坑的教训是静态采集和动态采集必须分开设计缓存策略动态层可以全部重刷锚点层得走文件级失效。5.2 敏感信息险些被塞进上下文这个坑想起来有点后怕。我在一个真实项目里跑context-mode collect --deep之后顺手打开产物文件检查结果发现.env.example里一个伪造的数据库连接字符串真的被采集进去了。问题出在我的忽略规则只写了.env没写.env.example、.env.test、config/secrets*.yml这类变体。修复方案有三层默认忽略任何文件名匹配*.env*、*secret*、*credential*的文件默认不读。内容过滤器对已采集的文本做正则扫描命中sk-、AKIA、password、mongodb://等敏感模式时直接删除该行。审计命令加一个context-mode audit输出本次采集的快照里命中了哪些风险项让用户人工确认。上线这个功能之后我自己才敢放心在真实密钥所在的机器上跑深度采集。5.3 信息过载历史决策区反而让模型变保守我在2.5节说过历史决策层要严控原因就在这里。有一段时间我把ADR全部塞了进去效果很诡异模型确实不再推荐激进重写了但连正常的简单优化都不敢提了动不动就说按背景文档此模块不应改动。这是因为历史决策文本被过度解释成禁止改变的指令。最后我改成了每个ADR只保留标题和单行结论并限制最多取最近10条。果然模型重新变得该激进时激进该保守时保守。5.4 跨平台环境差异Windows路径和换行符工具在macOS和Linux上跑没问题一放到Windows同事的机器上就出岔子。采集器渲染出来的目录树里全是反斜杠模型拿这些路径去执行命令时直接报错。修复方法很土但有效在渲染阶段把所有路径统一转成POSIX风格的正斜杠并在 frontmatter 里标注os: windows、shell: powershell让模型生成命令时自动改用正确的语法。5.5 上下文污染长对话中的早期记忆漂移最后这个坑是使用层面的。哪怕初始化时注入了完整上下文经过五六十轮对话来回贴代码、报错、修改意见之后模型对早期约束的记忆会明显变弱甚至开始给出与项目约定矛盾的建议。我统计过大概在三十轮左右衰减开始出现五十轮往后基本指望不上。/ctx refresh就是我针对这个现象加的补丁相当于人的会议纪要回顾花不了几秒效果立竿见影。我把这几个坑简单汇总一下现象根因对策模型引用已删除的函数锚点层缓存过期文件级mtime哈希失效快照里出现密钥忽略规则不完整缺乏过滤默认忽略正则清洗审计命令模型过于保守不敢改代码历史决策区塞太多ADR只保留标题和结论限10条Windows上生成无效路径路径格式未统一渲染时强制POSIX风格正斜杠长对话后期约束记忆衰退早期上下文被对话内容挤出窗口提供/ctx refresh重注入摘要6. context-mode 的下一步从个人脚本到日常工作流的一部分工具第一版能跑之后我开始琢磨怎么让它自然融入日常而不是多一个想起来才用的命令。6.1 给终端和编辑器做的几处集成最实用的几个接入点Shell别名alias cmcontext-mode进到任何项目目录直接cm get。目录切换自动检测我用的是zsh-navigation-tools的自定义钩子cd进项目目录时自动判断有没有.contextmode.yaml有就预生成一份L0快照放缓存里。编辑器插件思路保存文件时后台跑一次增量采集把结果写入.contextmode/cache/context.md打开AI助手窗口时会自动带上前缀。这个还没有做得很完整但已经足够让团队里不用命令行的人也能受益。6.2 团队使用场景让新人也能秒懂项目一个意外的收获是context-mode生成的快照对新人也非常友好。它不像Wiki那样冗长而是把最先要知道的事压在一屏之内。我们组有个惯例新人入职先跑一遍context-mode collect --deep再对着生成的快照读代码比从README硬啃效率高得多。团队协作还有一个价值做AI Code Review的时候把同一个上下文快照同时提供给评审AI能保证它和开发者在同一套项目约束下讨论问题避免评审AI建议用Flask重写FastAPI项目这类一看就没读过项目的离谱意见。6.3 我下一步想做的几个方向插件化数据源现在拓扑只吃Git、本地文件、常用配置文件后面想支持接入Jira/Issue状态、内网API文档、数据库Schema自动采集让上下文更加贴近真实运行环境。上下文版本化把每次生成的快照和Git提交哈希绑定对话时能指定以哪个版本的上下文为准彻底治好过期上下文的后遗症。离线安全模式项目里涉及客户敏感数据时可以开启只采集目录结构和配置项、不采集任何源码内容的最小模式保证上下文不触碰隐私红线。最后说点个人体会。写context-mode这件事技术难度并不高真正有价值的是逼自己重新想清楚了什么才算必要信息。我一度以为上下文管理是工程问题做下来才意识到更多是取舍问题——把什么排除在外、把什么放在最前面、给模型什么样的格式每一步都在和信息过载博弈。如果你也想做一个类似的东西我的建议是从小处开始先在你的项目里手写一份你希望AI看到的内容清单跑一星期看看哪些信息真正被用到了、哪些其实无关。等你对这份清单有把握了再考虑写工具自动化。这样产出的上下文才是真正懂你项目的上下文而不是又一个装满垃圾的大文件。