声明：本文为学习笔记与工程化延伸，核心脉络来自阿里云开发者技术号发布的《AI coding 智能体设计》，在此基础上按“可落地教程”的方式重组，并补充了上下文选取、压缩与排错清单；如有出入，以原文与官方文档为准。原文链接见文末参考。
很多人用 AI coding 的痛点并不是“它不会写”，而是“它总在猜”。
你让它修 bug，它先问你贴代码；你贴一段，它又问配置；你贴多了，它开始忘前面说过的约束。
《AI coding 智能体设计》里提到一个很关键的工程点：在提示词预处理阶段，如果输入包含@路径，系统会先读取该路径对应的文件（或目录下文件）作为上下文，再发给模型。
这一点能显著减少对话轮次，但也会带来新的问题：上下文膨胀。
本文目标：给你一套“工程化”的 @路径使用方法——给材料，但不喂爆上下文。
01｜先把 @路径当成“取证动作”，而不是“喂资料动作”
两种完全不同的心态：
- 喂资料：把一堆文件塞进去，希望模型“自己理解”
- 取证：明确你要它找什么证据（函数/配置/错误码/接口），只取与证据相关的最小集合
建议你每次写 @路径时，都同时写出“关注点”：
请阅读 @src/auth/ @src/api/client.ts 关注点：token 校验、过期时间、错误码映射、重试策略。 输出：按 1) 现状 2) 问题 3) 修复方案 4) 风险 5) 验证步骤。这句“关注点”，往往比多塞 10 个文件更有用。
02｜三件套模板：范围 + 关注点 + 输出协议
这是我最推荐的“工单式提示词”，适配绝大多数 AI coding 工具：
【范围】请阅读 @pathA @pathB（最多 1 个目录 + 1～3 个文件） 【关注点】你要找的具体对象/证据是什么？（函数名/错误码/配置项/边界条件） 【输出协议】必须包含：现状、问题、最小修改、风险、验证步骤为什么要限制范围？因为上下文资源是有限的：
你塞得越多，模型越可能“只记得后半段”，并且会把 token 花在“理解世界”，而不是“解决问题”。
03｜目录怎么读才不炸？两段式：先清单后取证
当你想引用一个目录（例如@src/）时，直接整目录读入通常会爆。
更稳的做法是“两段式”：
- 先要清单（Manifest）：列出目录中“可能相关”的文件名与理由
- 再取证（Evidence）：只读清单里排名前 N 的文件（N 通常 3～6）
可复制提示词：
先不要直接读全目录。请基于 @src/ 的文件清单（仅列文件名，不展开内容）， 挑出与“登录/鉴权/会话”最相关的 3～6 个文件，并说明理由。 然后我会让你逐个读取。这样做的收益是：你让模型“做选择题”，而不是“做阅读理解”。
04｜上下文压缩：别等爆了再压，先建立“摘要层”
一旦你开始让模型读多个文件，就要有“摘要层”意识：
先把每个文件压成结构化摘要，再在摘要上推理。
建议你为每个文件摘要固定字段：
- 文件职责（1 句话）
- 关键入口函数/类（列名）
- 关键配置项（列名）
- 关键边界条件（列 3 条以内）
- 与本问题的关联（Yes/No + 理由）
这样做有两个好处：
- 后续讨论只需要引用摘要，不需要反复把原文件塞回上下文
- 当你需要扩展范围时，摘要能像“索引”一样帮助你快速定位
05｜四种常见“上下文失真”与修复方式
失真 1：它说的像对，但没有证据
处理：要求“引用证据”，例如：
你的结论必须引用你读取到的代码证据：文件路径 + 函数名 + 关键逻辑描述。 不允许只给结论。失真 2：它忘了你前面说过的约束
处理：把约束写成“硬规则”，并让它复述确认：
硬规则： 1) 不改 public API 2) 改动最小 3) 必须给验证步骤 请先复述硬规则，再给方案。失真 3：它读了目录，但其实读到的不是你以为的那些文件
处理：先让它输出“本次读入上下文的文件清单”，再继续。
失真 4：上下文太大导致“只读到后半段”
处理：减少一次性读入；用摘要层；分批读取；必要时压缩历史（保留硬规则与摘要）。
06｜一套“上下文预算”经验值（不求精确，但很好用）
你可以用三个档位做决策：
- 小任务（单点修复）：1～3 个文件，直接读原文
- 中任务（跨模块）：目录清单 → 读 3～6 个文件 → 做摘要层
- 大任务（架构/重构）：先写 spec（proposal/tasks），再按任务分批取证
当你发现自己要读第 10 个文件时，往往说明：你需要的不是更多上下文，而是更清晰的任务拆解。
07｜排错清单：@路径为什么没生效？
- 路径写错/相对路径不一致：先让工具列目录确认真实路径
- 目录过大被截断：改为“先清单后取证”，不要一把梭
- 文件编码/格式导致解析异常：优先读纯文本/关键片段；必要时转成更易读格式
- 上下文被压缩丢关键信息：把“硬规则 + 摘要层”放在压缩后仍保留的位置
08｜系列导航（收藏用）
- 系列 01：从 Chat 到 Agent：4 个关键零件
- 系列 02：命令系统：从提示词模板到可扩展子命令
- 系列 03（本文）：@路径上下文：如何给材料而不喂爆上下文
- 系列 04：MCP 与工具闭环：注册、调用、回填与失败恢复
- 系列 05：上下文治理：清空/压缩/摘要与预算控制
- 系列 06：SubAgent：上下文隔离与模块化协作
- 系列 07：规约驱动：让交付可复现的 Spec 工作流
- 系列 08：迷你 CLI：从伪代码到最小可运行骨架
参考与致谢
- 阿里云开发者技术号原文：《AI coding 智能体设计》
