上下文与规则文件
上下文工程不是把更多文字塞进提示词，而是让 Agent 在正确的时间看到正确的事实。对代码任务来说，仓库规则、当前 diff、相关源码、测试结果和用户约束通常比一份巨大的项目介绍更重要。
上下文的四层
- 平台层：权限、网络和安全策略。
- 仓库层：构建、测试、目录、提交和代码风格。
- 模块层：某个 Go package 或 Java module 的局部约束。
- 任务层：当前需求、相关文件、已有改动、验证命令和用户偏好。
越靠近任务，信息越具体；越靠近平台，约束越应该稳定。
CLAUDE.md 与 AGENTS.md
不同工具约定的文件名、搜索路径和优先级可能不同。不要假设一个工具读取的规则文件会被另一个工具自动读取。建议把真正重要的约束维护在仓库文档中，再生成或同步工具专用入口。
text
repository/
├── AGENTS.md # Codex/兼容工具的仓库级入口
├── CLAUDE.md # Claude Code 的仓库级入口
├── backend/
│ ├── AGENTS.md # 后端模块局部规则
│ ├── go.mod
│ └── ...
└── services/order/
└── README.md # 领域事实和运行说明规则文件应该写“可执行的约束”，例如：
markdown
## Verification
- Run `go test ./...` for Go changes.
- Run the narrowest Java test before the full Maven test.
- Include the exact command and result in the final report.
## Change scope
- Preserve unrelated working-tree changes.
- Do not change public API names without updating callers and tests.
- Prefer existing error types and logging conventions.避免写成：
markdown
写出高质量代码，认真检查所有问题。这类要求无法验证，也不能帮助 Agent 选择下一步。
渐进式加载
推荐的上下文预算顺序：
- 用户目标和验收标准；
- 当前分支、diff 和工作区状态；
- 最近邻模块的 README、接口和测试；
- 只读搜索得到的相关符号；
- 失败日志和审查意见；
- 必要时再加载全局设计文档。
可以把每次加载记录为一个短摘要：
json
{
"task": "add idempotency key",
"facts": [
"HTTP handler is in internal/order/http.go",
"repository uses PostgreSQL transactions",
"integration tests require docker compose"
],
"unknowns": [
"whether old clients may omit the key"
]
}事实和未知项分开，能减少模型把猜测当成结论。
长任务与上下文压缩
将长任务切成可恢复阶段：
text
discover -> plan -> implement -> verify -> review -> handoff每个阶段保存：
- 已完成的目标；
- 修改过的文件；
- 验证命令及结果；
- 未决问题；
- 下一阶段的入口。
压缩上下文时保留状态，不保留所有对话原文。一个好的摘要应该能让新的 Agent 继续执行，而不是只能复述过去发生了什么。
记忆的边界
适合保存：
- 稳定的仓库工作方式；
- 用户明确要求长期遵循的协作偏好；
- 外部资料入口。
不适合保存：
- Token、密码、个人隐私；
- 某次任务的临时状态；
- 可以直接从代码推导出的函数和目录；
- 未经验证的模型猜测。
Go/Java 实践建议
Go 项目优先把 package 边界、go test、lint 和生成代码规则写清楚；Java 项目优先写 Maven/Gradle 命令、模块边界、Spring 配置和集成测试依赖。不要把两套语言的命令混在一张没有条件说明的清单里。
练习
- 为一个 Go 微服务写一份 20 行以内的仓库规则。
- 把一条“提交前要检查”的要求分别改写成模型建议和机器门禁。
- 设计一个包含 5 个字段的长任务检查点。