核心论点：提示词不足以定义代码行为

Agentic coding（智能体编程）正在打破软件开发的门槛，让不同背景的人都能参与构建。然而，开发者必须掌握主动权，确保给予AI Agent高质量的上下文（Context）。以添加登录端点为例，如果仅通过单句提示词要求实现功能，Agent无法自动遵循既有的错误格式、文件夹布局或特定的认证库。代码决策必须依赖于仓库中已有的数千个文件及多年积累的技术债务与架构选择。

"All of that is going to come down to the context that this agent here has."

相同的请求在不同仓库中应产生不同的代码结果。例如，在Repo A中使用FastAPI路由配合Pydantic模型，而在Repo B中可能使用Go语言Handler且结构完全不同。因此，理想的状态是让Agent能够理解特定仓库的框架、数据库层及验证模式。提示词本身无法解释所有细节，代码决策必须基于现有代码库的状态。

关键输入一：文件搜索与仓库结构映射

Agent的最佳实践是具备自主搜索、读取和打开文件的能力，从而理解无法直接写入提示词的信息。开发者的角色转变为指引方向，例如在Prompt中加入"遵循README中的模式"以引导Agent定位起点。此外，仓库结构（Repository Structure）至关重要，包括测试文件位置及模块布局。

建议为Agent构建紧凑的仓库地图（Repo Map），列出文件和符号，使模型能在不逐行阅读的情况下看清项目整体形状。这种结构化的概览能帮助Agent快速建立对项目架构的认知，避免陷入无关细节。通过提供文件列表和符号索引，模型可以高效理解项目形态。

关键输入二：依赖版本与测试反馈闭环

第三个容易被忽视的输入是依赖项（Dependencies）。仅仅知道使用了某个库是不够的，Agent必须知晓具体版本。锁文件（Lock File）作为机器生成的记录所有依赖及其传递性依赖确切解析版本的文档，直接决定了哪些API实际存在。许多由Agent生成的幻觉函数（Hallucinated functions）往往源于版本不匹配导致的API误用。

第四个关键输入是测试用例。当Agent知道如何通过这些测试时，它便能建立"编写-运行-修复失败测试"的反馈闭环。在这种机制下，Agentic coding的优势得以充分发挥，因为Agent明确知道什么是"正确"的结果。测试为Agent提供了明确的验证标准，使其能够通过迭代修正错误。

关键输入三：文档规范与开发者意图

第五个重要维度是文档（Documentation）。对Agent有价值的信息包括编码约定、构建命令以及禁忌指令（如"不要触碰此目录"）。这些内容可存入名为agents.md的已检查入指令文件中，这是一种新兴的开约定俗成规范。许多工具已有各自版本的实现。

第六个输入是开发者意图（Developer Intent）。这包括对"完成状态"的定义、约束条件以及Agent不应执行的操作。这是唯一无法通过阅读代码库发现的上下文，仅由开发者掌握。明确意图能防止Agent在边界条件上产生偏差。结合文档与意图，Agent能在遵循技术规范的同时满足业务逻辑需求。

主动探索：让Agent反向提问与规划

对于不熟悉如何提供上下文的初学者，可以让Agent主动暴露其所需信息。第一步是指示Agent在写代码前"采访我（Interview me）"，通过提问直到完全理解需求。第二步是要求Agent探索仓库并用通俗语言解释其结构。双方共同建立对仓库地图的理解，能显著降低沟通成本。

第三步是制定计划并列出假设。在开始编码前了解Agent的假设，有助于发现开发者未曾想到的问题。最后，让Agent将其学习到的知识写回agents.md文件。这种机制将隐性知识显性化，为后续任务积累可复用的上下文资产。

上下文过滤：避免信息过载与注意力分散

自然本能倾向于"越多越好"，将整仓代码倒入上下文。但研究表明，模型对长输入中的信息关注度不均：开头和结尾的信息处理效果最好，而中间部分容易被忽略。每个无关文件都会与关键文件竞争注意力资源。

"Every irrelevant file is going to compete with a file that does matter."

因此，上下文必须经过任务相关性过滤。例如在修改登录流程时，Agent需要认证模块、测试及约定文档，但不需要计费服务或三周前的构建日志。保持上下文的相关性是提升模型表现的关键策略。实践中，应为每个新任务启动新的会话（Session），以便指向特定文件并在会话过长时清除噪音。

结论

Agentic coding的核心不在于提示词的长短，而在于上下文的精准度。好的代码依赖于围绕它的代码库状态、结构映射、依赖版本、测试反馈及开发者意图。当缺乏明确指引时，应让Agent主动探索并记录假设。最终目标不是提供更多上下文，而是提供正确的上下文，并确保开发者始终掌控决策权。