用AI生成README，先让它从项目文件中找出启动命令、依赖、数据来源和预期结果，再写成新人能照做的说明。最后把项目复制到一个干净目录，只按README操作一遍：命令能运行、结果能对上，文档才完成了交接任务。
最容易出错的地方往往很小：项目只有dev脚本，README却写着npm start；程序只输出终端报告，文档却让人打开一个不存在的网页地址。下面用一个工单汇总脚本，把这些问题逐项解决。
先让README回答：运行后会看到什么
这个练习读取本地JSON，只列出状态为open的工单，保持数据中的顺序。它没有网页、数据库和登录流程。给同事的第一段说明应该把这些事实讲清楚，而不是先列一串技术名词。
项目文件准备好后，可以在墨刀AI客户端读取项目文件，提取启动依据，再生成Markdown草稿。把授权范围限在本次项目目录，先要求它说明准备读取哪些文件；真实项目中的密钥、个人数据和不相关资料无需作为写README的材料。
如果还不知道项目从哪里启动，先沿入口读懂一条业务调用链。确认它实际做什么，比先选择一个漂亮的README模板更有用。
用四份小文件提供完整依据
新建一个练习目录，按下面的路径保存文件。示例没有第三方依赖，因此不需要安装依赖。本例在Node.js v24.19.0、npm 11.9.0下运行；这是实际验证版本，不代表项目的最低版本要求。
package.json给出可执行脚本。这里没有start，只有dev和test：
{
"name": "ticket-summary-example",
"private": true,
"type": "module",
"scripts": {
"dev": "node src/report.mjs",
"test": "node --test"
}
}data/tickets.json包含三条虚构工单：
[
{"id":"T-101","title":"补齐导出提示","status":"open"},
{"id":"T-102","title":"修复空列表间距","status":"done"},
{"id":"T-103","title":"确认筛选规则","status":"open"}
]src/report.mjs是实际入口。它读取文件、筛选工单并打印文本，没有监听端口的代码：
import { readFileSync } from 'node:fs';
const tickets = JSON.parse(readFileSync(new URL('../data/tickets.json', import.meta.url), 'utf8'));
const open = tickets.filter(ticket => ticket.status === 'open');
console.log(`待办工单：${open.length}`);
for (const ticket of open) console.log(`${ticket.id} ${ticket.title}`);report.test.mjs放在根目录，固定报告内容和条目顺序：
import test from 'node:test';
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
test('报告仅列出 open 工单，并保持文件中的顺序', () => {
const output = execFileSync(process.execPath, ['src/report.mjs'], { encoding: 'utf8' }).trim().split(/\r?\n/);
assert.deepEqual(output, ['待办工单：2', 'T-101 补齐导出提示', 'T-103 确认筛选规则']);
});在真实项目中，材料通常还包括锁文件、已有环境示例和部署说明。由项目采用的包管理器及锁文件决定安装方式，不要把本练习“无需安装依赖”的结论套到其他仓库。
补充运行说明前，先检查环境变量的实际读取和默认行为，避免把隐含的本机配置遗漏在README之外。
先要事实清单，再要README草稿
一次让AI“写一份专业README”，它容易补上项目根本没有的功能。可以先给出下面这段任务，要求每条启动事实都找到对应文件：
阅读 package.json、src/report.mjs、data/tickets.json 和 report.test.mjs。
先列出项目用途、可用脚本、输入文件、输出位置、依赖与测试方式，并标明依据。
然后生成给首次接手同事阅读的 README.md。
快速开始必须包含工作目录、实际命令和报告的预期输出。
只修改 README.md，不修改代码或增加脚本来迁就文档。
没有依据的端口、环境变量、许可证、维护人和部署能力不要补写。
无法确认的必要信息先向我指出，不把猜测写成已支持的功能。本例应得到的事实很明确：入口是src/report.mjs；启动命令是npm run dev；输入是data/tickets.json；输出在终端；done工单不进入报告。如果AI把“没有第三方依赖”推成“任何电脑都能直接运行”，仍需收回这个结论，因为Node.js和npm是运行前提。
GitHub的README说明也将项目用途、开始方式和求助渠道视为常见内容。不过，具体写哪些章节，应由仓库的实际使用方式决定。
把可执行命令和预期输出写在一起
这个小项目的README可以压缩成下面几部分。仓库内文件使用相对链接，移动仓库后更容易保持有效。
# 工单汇总示例
读取本地 JSON，向终端输出状态为 open 的工单。
它是命令行脚本，不启动网页服务器，也不修改输入文件。
## 快速开始
需要支持 ES Modules 和 node --test 的 Node.js 与 npm。
项目没有第三方依赖，无需运行 npm install。
在项目根目录执行：
npm run dev
报告部分的预期输出：
待办工单：2
T-101 补齐导出提示
T-103 确认筛选规则
npm 可能另外打印脚本名称，这不属于工单报告。
## 数据与测试
数据放在 [data/tickets.json](data/tickets.json)。
status 为 open 的记录进入报告，顺序与文件相同。
运行 npm test，检查输出条目与顺序。
本例不需要环境变量，不连接数据库或外部接口。
## 范围
这是本地练习，不包含网页、身份权限、部署流程或许可证声明。
运行脚本或数据规则变化后，同步更新快速开始与预期输出。
启动命令与预期输出写在同一份README中，便于运行时核对。
示例中的“范围”避免读者把命令行工具误认为完整工单系统。实际仓库有许可证时应链接真实文件，有维护流程时写真实渠道；未知内容不用先填一个看起来合理的答案。
在干净目录中照着文档走一遍
将这四份文件和README复制到新目录，保持目录结构，在新目录中先执行npm run dev，再执行npm test。这样可以发现文档漏写的文件、工作目录和隐含步骤。这里的“干净目录”仍使用同一台电脑的运行环境，不能证明跨系统或所有Node版本都兼容。
| 照文档执行的动作 | 本地练习结果 | 文档如何处理 |
|---|---|---|
| 使用旧说明里的npm start | 退出码1，提示缺少start脚本 | 修正文档为npm run dev |
| 运行npm run dev | 输出待办工单2条，顺序为T-101、T-103 | 附上可比对的报告文本 |
| 运行npm test | 报告条目和顺序断言通过 | 写清测试命令与检查内容 |
| 在干净副本重复运行 | 启动与测试均通过 | 确认无需额外的未记录文件 |
上表记录了这组文件的本地练习结果。将同样的方法用于团队项目时，应保留实际命令、环境和失败信息，再决定改文档还是处理代码问题。
遇到失败，不要让AI顺手增加一个新脚本，使错误说明“终于能跑”。例如，这里的旧文档写错了npm start，修改README即可；新增start会改变项目接口，属于另一项决定。
项目变化时，README只更新受影响的入口
启动脚本、数据格式或配置方式发生变化时，让AI先比较相关差异，再更新对应段落。接口参数、鉴权和错误码很多时，另写可联调的API文档，README保留入口与链接，避免同一规则在两处长期不一致。
下一次交接前，可以请未参与开发的同事从README开始操作。如果他需要额外询问“在哪个目录执行”“结果应该是什么”“为什么不用开浏览器”，把答案写回相关步骤。README是否有用，最终体现在这些问题能否就地解决。
