ARTICLE · 1063277
给 Agent 看的 Install 文档应该怎么写
README 写给人，Install.md 写给 Agent；安装文档要像执行契约，明确目标、边界和停点。
从 Goal、Success Criteria 到 Operating Rules，写出能被 Agent 安全执行的安装说明
用户安装一个项目的入口正在变化。
过去是人打开 README，复制命令，遇到报错再查文档。现在越来越多用户只会对 Coding Agent 说一句：帮我把这个项目跑起来。
这时，README 仍然有价值，但它不再够用。README 是写给人读的，Install.md 应该写给 Agent 执行。两者服务的是不同读者。
给 Agent 看的安装文档，不能像一篇说明文章。它更像一份执行契约：目标是什么，默认走哪条路径，哪些动作不能做，做到哪一步算成功，失败时应该停在哪里。
图：安装文档要把目标、分支和停止条件写成可执行契约
README 写动机，Install.md 写执行边界
README 通常回答项目定位、使用价值、功能架构和贡献方式。
这些信息对人有用。人会跳读，会判断哪些段落先看，遇到命令也会根据经验调整。
Agent 的阅读方式不同。它打开文件后，更关心接下来要执行什么。背景介绍太多，会浪费上下文，也可能让它把叙述当成任务线索。
所以 Install.md 要收窄目标。它只回答安装现场的问题。
这些问题包括当前角色是谁、项目要装到什么状态、默认路径怎么选，以及哪些文件和命令不能碰。失败时怎么交付，成功后停在哪一步，也要写清楚。
可以把两份文档的职责拆开：
图：README 面向理解，Install.md 面向执行
README 让人理解项目，Install.md 让 Agent 安全执行安装。
第一行就声明读者身份
Install.md 的开头不要写项目故事。
第一句话应该告诉 Agent：这份文件是给你读的，你当前的角色是什么，起手从哪里开始。
推荐结构：
# Project InstallThis file is for coding agents.If the repository is not already cloned and open, clone it first.Then continue from the repository root.这句话同时完成两件事。
Agent 知道自己可以按文件执行。人类读者也会发现它面向执行场景，自然切回人类文档。
文件定位不要靠正文慢慢解释。Agent 第一次扫描根目录时，越早识别用途，越少跑偏。
Goal 要写成任务，不写成背景
Agent 不需要被说服，它需要知道目标。
Goal 段要短，最好同时给出默认优先级。
## GoalBootstrap a local development workspace with the least risky path available.Default preference:1. Container-based setup2. Local setup这里的重点是“安装应该达到什么状态”，项目动机留给 README。
如果存在多条安装路径，必须写默认顺序。否则 Agent 会根据自己读到的碎片自行选择，可能走到风险更高的路径。
Success Criteria 决定 Agent 什么时候停
Agent 不会天然知道“装好了”是什么。
依赖装完算成功吗？配置文件生成算成功吗？
服务启动算成功吗？测试通过算成功吗？
这些边界如果不写清楚，Agent 可能越做越多。
一份可执行的 Success Criteria 应该包含：
• 必须存在的文件 • 必须通过的检查 • 哪些服务只准备，不启动 • 哪些密钥只提示用户配置，不读取 • 最后交给用户的下一条命令
示例：
## Success Criteria- `config.yaml` exists.- Dependencies are installed.- Setup check passes or reports only user-provided credentials missing.- Services are not started automatically.- The user receives the exact next command to launch the app.这段本质上是 stop condition。它告诉 Agent，做到哪里可以收手，哪里不能顺手继续。
Operating Rules 要把安全边界写死
安装任务最容易出事故的地方，通常是 Agent 自己补了一步。命令写错反而更容易暴露。
它可能覆盖已有配置，读取密钥文件，使用 sudo，启动后台服务，或者为了修复报错去改系统环境。
Operating Rules 就是给这些行为划线。
## Operating Rules- Be idempotent. Re-running this file must not damage an existing setup.- Prefer repository commands over ad hoc shell commands.- Do not use `sudo` without explicit user approval.- Do not overwrite existing user config values.- Do not read secret-bearing files.- If a step fails, stop and report the smallest next action.这些规则不是礼貌提醒。它们是安装契约的一部分。
尤其要写清幂等性。安装文档经常被重复执行，如果第二次执行会覆盖用户配置，这份文档就不适合给 Agent 用。
Steps 要写成决策树
人读安装教程，可以自己判断分支。
Agent 需要分支被写出来。
好的 Steps 要写成可执行分支，而不是线性教程：
## Steps1. Confirm repo root by checking `Makefile` and source directories.2. If `config.yaml` is missing, generate the default config.3. If Docker is available, prepare the container environment.4. If Docker is not available, run local prerequisite checks.5. If credentials are missing, stop and report required variable names.6. Report the next launch command.如果维护者希望优先走容器路径，就直接写。如果本地安装会改系统包，也要写出审批要求。
不要让 Agent 猜维护者偏好。
TODO 让长安装变成可恢复状态机
安装经常被中断。
依赖下载慢、测试失败、用户补密钥、进程重启，都会让 Agent 在中途停下来。显式 TODO 可以让它恢复时知道做到了哪里。
推荐写法：
## TODO- [ ] Confirm repository root- [ ] Generate config if missing- [ ] Choose container or local setup path- [ ] Run setup command- [ ] Report missing credentials- [ ] Hand the next command to the user这份清单面向 Agent 的执行状态，不是给人看的进度装饰。
Agent 通常会把这类列表纳入自己的计划，逐条更新，出错后也更容易恢复。
结尾要写清执行边界
安装文档最后应该明确一句：执行到哪里停。
## Execute NowComplete the steps above.When finished, stop at the setup boundary and report status.Do not continue into unrelated project work.这句话很重要。
Agent 的默认倾向是继续推进任务。它看到项目有启动命令，可能顺手拉起服务。
看到测试命令，它可能跑完整套；看到部署脚本，它甚至可能继续研究发布方式。
安装阶段只应该完成安装边界内的事。后续启动、调试、部署，交给用户确认。
一份可复用的 Install.md 骨架
可以从这个模板开始：
# Project InstallThis file is for coding agents.Start from the repository root.## GoalBootstrap a local development workspace with the least risky path available.Default preference:1. Container setup2. Local setup## Success Criteria- Required config file exists.- Dependencies are prepared.- Setup checks pass or only user-owned credentials are missing.- No long-running service is started automatically.- The user receives the exact next launch command.## Operating Rules- Be idempotent.- Prefer repository commands.- Do not use `sudo` without approval.- Do not overwrite existing user config.- Do not read secret-bearing files.- Stop on blockers and report the smallest next action.## Steps1. Confirm repository root.2. Generate missing config.3. Choose setup path.4. Run setup.5. Report blockers.6. Hand off the next command.## TODO- [ ] Confirm repository root- [ ] Prepare config- [ ] Run setup path- [ ] Report missing credentials- [ ] Stop at setup boundary## Execute NowComplete the steps above and stop.这份骨架不追求漂亮，追求可执行、可恢复、可审计。
最好的 Install.md 要让 Agent 跑过一遍
人很难凭空写出完整边界。
维护者容易漏掉自己默认知道的前置条件，也容易把“装好了”写得模糊。更稳的做法，是让 Agent 在干净环境里真实安装一次，再把它踩到的坑写回文档。
可以按这个循环维护：
1. 先写最小版本 2. 让 Agent 按文档安装 3. 记录失败点、误判和越界动作 4. 把失败原因写入 Operating Rules 或 Steps 5. 再跑一次，直到能稳定收口
人在这个循环里做审稿人。Agent 提供真实安装现场的摩擦，维护者决定哪些摩擦应该固化成规则。
给 Agent 的文档是执行契约
项目根目录以后可能不只需要 README。
测试、部署、基准复现、数据准备，都可能需要写给 Agent 的专门文档。它们的共同点是：读者不只是读，读者会执行。
执行文档的标准也不同。
它不需要文采。它要把目标、边界、分支、停止条件和恢复方式写清楚。
README 让人愿意理解项目，Install.md 让 Agent 能把项目安全装起来。
当读者变了，文档就该变。
