任务、上下文与验收
一句话需求为什么经常失败
标题为“一句话需求为什么经常失败”的章节“优化这个页面”“修一下登录”“把项目迁到新框架”只表达了方向，没有给 Agent 决策边界。Agent 只能自己猜入口、完成定义、允许改动和验证方法；猜得越多，结果越不可审查。
一个可执行任务至少要冻结四格：
| 格子 | 要回答的问题 | 最小证据 |
|---|---|---|
| 上下文 Context | 现在是什么状态，入口和已有证据在哪里？ | 仓库、分支、关键文件、复现或基线 |
| 目标 Task | 完成后谁能观察到什么变化？ | 一个用户可见或系统可测的结果 |
| 边界 Boundaries | 可以改什么，不能做什么，何时必须停下来问？ | allowed paths、禁区、高风险动作 |
| 验证 Verification | 用什么证明完成，而不只是“看起来可以”？ | 命令、退出码、diff、页面或人工检查 |
第一步：只给必要上下文
标题为“第一步：只给必要上下文”的章节上下文不是把所有聊天和文档倒进去。优先提供：
- 真实仓库、当前分支和工作树状态。
- 与任务直接相关的入口文件、运行命令和现有测试。
- 已知失败的原始输出，而不是转述后的“它报错了”。
- 已经做过的尝试，以及为什么没有采纳。
如果 Agent 可以用只读搜索确认，就让它先调查并列出证据；不要靠猜测把可能过时的目录和 API 写进任务。
第二步：把目标写成可观察变化
标题为“第二步：把目标写成可观察变化”的章节弱目标：“改善新手体验。”
可执行目标：“第一次访问 /start-here/ 的读者能按三类任务进入对应教程；所有入口链接在静态构建后存在，页面不新增外部脚本。”
后者仍没有规定具体排版或组件，因此保留实现空间；同时它让 reviewer 知道应该检查什么。
第三步：把权限边界写在执行前
标题为“第三步：把权限边界写在执行前”的章节边界至少分三类：
- 文件边界：允许修改哪些路径，哪些用户改动必须保留。
- 动作边界：是否允许安装依赖、联网、删除、提交、push 或部署。
- 升级边界：遇到秘密、付费调用、生产数据、含糊产品选择时必须停下来问。
“谨慎操作”不是边界；“允许修改两篇 MDX 和自己的 research 目录，不修改配置，不 push”才是。
第四步：让验证覆盖目标和边界
标题为“第四步：让验证覆盖目标和边界”的章节一条 build 通过，只能证明项目能构建，不能自动证明链接都正确、页面符合读者任务、没有越界修改。把验证拆成三层：
| 层 | 例子 | 能证明什么 |
|---|---|---|
| 确定性检查 | test、lint、typecheck、validator、链接扫描 | 明确合同没有被机械反例击穿 |
| 变更检查 | git diff --check、文件清单、敏感扫描 | 修改范围和基本卫生符合要求 |
| 人工检查 | 浏览器走读、视觉、文案、风险判断 | 机器难以判断的体验和语义 |
验收命令要能复制，人工检查要写观察点。不要只写“请自行确认”。
从模糊需求到任务合同
标题为“从模糊需求到任务合同”的章节模糊版本：
把 LearnPrompt 收口一下，质量高一点。冻结版本：
# 目标升级 start-here 的两个入口页，让新手、现有 Claude Code/Codex 用户、长期 Agent 工作流建设者都能在两次点击内进入第一篇深度教程。
# 上下文- 仓库与分支：先用 git status 核对，不从聊天猜。- 深度教程：41 篇已 verified；导航页不冒充深度教程。- 现有栏目：AI 编程、Claude Code、Codex、Agent 工程、Skills、 Loop、Obsidian AI、Hermes/OpenClaw。
# 边界- 只改指定的两篇 start-here MDX。- 不改深度教程、组件、依赖和站点配置。- 不 push、不部署、不发布。
# 验收- 内部链接都对应现有路由。- git diff --check 通过。- 49 页 Starlight build 通过。- reviewer 分别走三条读者路径，没有死路或错误状态承诺。
# 交付- 两个本地 commit、检查结果和未关闭风险。这份合同没有替 writer 决定每句话，却把完成与越界都变成可判断的问题。
Agent 开始前的五个问题
标题为“Agent 开始前的五个问题”的章节让执行者先回答：
- 你认为目标产物和非目标分别是什么？
- 你将读取哪些入口，为什么这些信息足够？
- 计划修改哪些文件？是否有未提交用户改动？
- 最快的相关检查和完整检查分别是什么？
- 哪些情况会让你停止并请求授权？
回答仍很抽象时，任务还没冻结，不要进入自动执行。
常见失败与修正
标题为“常见失败与修正”的章节| 失败 | 为什么危险 | 修正 |
|---|---|---|
| 只给技术方案，没有读者或产品结果 | Agent 可能完美实现错误目标 | 先写可观察变化，再讨论方案 |
| 把全部仓库当默认范围 | 顺手重构和覆盖用户改动难以发现 | 写 allowed paths 与非目标 |
| 验收只有“build 通过” | 语义、链接和视觉缺口不会被发现 | 增加变更检查和人工路径 |
| 要求信息不足时“自行判断” | 高风险选择被悄悄假设 | 写升级条件和默认安全动作 |
| 给出不存在的路径或过时命令 | 合同从起点就是假的 | 先只读核对当前状态 |
可复制模板
标题为“可复制模板”的章节# 目标完成后，谁能观察到什么变化？
# 上下文- 当前状态：- 关键入口：- 已知证据或错误：
# 范围与禁区- 允许读取：- 允许修改：- 禁止动作：- 必须请求授权：
# 验收- 最快相关检查：- 完整机械检查：- 人工检查点：- 失败时保留：
# 交付变更、证据、未关闭风险和下一步分别是什么？来源与延伸阅读
标题为“来源与延伸阅读”的章节- Anthropic：Claude Code best practices：探索、计划、实现、验证与上下文管理的一手实践。
- OpenAI：Codex prompting：给 coding agent 提供任务、上下文与验证要求的官方说明。
- OpenAI：AGENTS.md guide：项目级持久指令的官方边界。
- 项目清单 与 指令层：把本页四格合同继续落到机械 gate 和项目地图。