上下文工程

AI 编程质量的另一半在代码之外：管理代理能看到什么。用项目说明、任务边界和文档同步把上下文变成资产。

一、同一个模型，为什么表现差这么多

给代理一个没有说明文档的仓库，它要花大量轮次摸索：这是什么框架、命令怎么跑、代码放哪里。这些摸索不仅慢，还会产生错误假设，后面的实现全部建立在错误之上。上下文工程的全部内容，就是把这些摸索提前变成明确的信息。

二、三份高回报的文档

项目说明（AGENTS.md / CLAUDE.md）

放在仓库根目录：技术栈、目录结构、常用命令、代码约定。代理每次启动自动读取，是投入一次、长期生效的资产。

任务规格

上一节的方法：目标、行为要求、明确不做、完成标准。为单个任务划定边界，控制改动半径。

决策记录

用过的方案、踩过的坑、为什么不用某个库。防止代理（以及未来的你）重新提出已被否决的路线。

文档同步约定

约定「接口或目录变动时，必须同步更新说明文档」，写进项目说明让代理遵守。文档不更新，资产很快变负债。

三、一份能直接用的项目说明骨架

# 项目说明

## 技术栈
Next.js 15 (App Router) + TypeScript，样式为原生 CSS，无 UI 框架。

## 目录
- app/        页面路由
- components/  React 组件
- lib/        内容加载与解析
- content/    课件 HTML（只在此目录增删文件）

## 常用命令
- npm run dev     本地开发
- npm run build   构建（内容变更后必须重新执行）
- npm test        全量测试，提交前必须通过

## 约定
- 新增页面必须在 app/ 下建目录，禁止修改 content/ 之外的生成物
- 改动接口时同步更新本文件

维护成本的控制

文档保持「一页能读完」。写不下的细节放子文档，在主文件里链接即可——代理缺的是入口，不是全集。

本节小结

代理表现的差距，大头来自上下文质量而不是模型差距。
三份高回报文档：项目说明、任务规格、决策记录，外加文档同步约定。
项目说明控制在「一页读完」，细节外链。