写 README
08-02 写 README
Section titled “08-02 写 README”这一课讲项目 README。项目完成第一版后，需要一份入口说明，让未来的自己、同学、老师或同事知道这个项目做什么、怎么运行、有哪些功能、还有哪些待改进。
README 是项目门口的说明牌，也是后续继续开发的入口。
这一课的成果是一份「项目 README」。
- 能写清项目用途。
- 能写清本地运行方式。
- 能说明文件结构。
- 能列出当前功能和待改进事项。
- 能让 AI 根据项目材料整理 README，再由学员校对。
- 建议时长：25 到 35 分钟。
- 用已完成版本的项目继续演示。
- 先让 AI 整理草稿，再人工补真实经验。
- README 要能照着运行，不追求华丽。
- 收尾按 README 重新跑一遍项目。
- 项目说明。
- 运行记录。
- 验收记录。
- 版本保存记录。
- AI 工作台工具。
可以这样开场：
“项目做出来以后，如果没有 README，过几天你自己回来都可能忘了怎么运行。README 是写给未来自己的说明牌。”
先讲一个真实画面：
“你三周后打开项目，只看到一堆文件：index.html、style.css、script.js、inputs、outputs。如果 README 写得清楚，你一分钟就能重新进入项目；如果没有 README，你要重新问 AI、重新试命令、重新猜文件作用。”
一份第一版 README 可以包含七块。
第一，项目名称。
比如：CSV 转 Markdown 小工具。
第二，项目用途。
用一两句话说明它解决什么问题。不要只写“这是一个小工具”，要写“把 CSV 文本转换成 Markdown 表格，方便写文档时复制使用”。
第三，使用场景。
说明谁会在什么情况下使用它。比如写教程、整理课程资料、快速生成表格。
第四，本地运行方式。
写清打开哪个文件，或运行什么命令。命令要可复制，目录要写清。
第五，文件结构。
说明主要文件和文件夹用途。未来的自己要知道哪里放输入，哪里看输出，哪里记录日志。
第六，当前功能。
列出第一版已经完成的功能。当前功能要真实，不要把后续计划写成已完成。
第七，待改进事项。
把暂缓需求和下一版计划放进去。这样新想法不会丢，也不会干扰当前版本。
让 AI 写 README 时，要提供项目说明、运行记录、验收记录、版本保存记录。AI 可以帮你整理，真实使用经验和坑点要由学员补上。
可以这样说：
请根据项目说明、运行记录、验收记录和新需求收纳表，帮我整理 README。重点写清怎么运行、当前功能、注意事项和后续计划。最后必须按 README 重新跑一遍项目：
“README 写得好不好，就看未来的自己能不能照着它把项目打开。我们现在就扮演未来的自己，照着 README 操作一次。”
最后收束：
“README 写得清楚，项目就有了回家的路。未来的你打开它，会很快想起这个小工具为什么存在、怎么启动、下一步去哪。”
屏幕演示流程
Section titled “屏幕演示流程”- 打开项目说明、运行记录、验收记录。
- 让 AI 根据这些材料整理 README。
- 人工检查项目用途是否准确。
- 人工检查运行方式是否可执行。
- 补充真实注意事项。
- 写入当前功能和待改进事项。
- 保存 README。
- 按 README 重新运行项目。
- 修正不准确的说明。
给 AI 的协作卡
Section titled “给 AI 的协作卡”请根据当前项目材料帮我整理 README。
请包含：1. 项目名称2. 项目用途3. 使用场景4. 本地运行方式5. 文件结构6. 当前功能7. 待改进事项8. 注意事项
请写得清楚、可执行。运行步骤要让未来的我照着做。README 检查卡
Section titled “README 检查卡”- 项目名称清楚：
- 项目用途清楚：
- 使用场景清楚：
- 运行方式可执行：
- 文件结构准确：
- 当前功能完整：
- 待改进事项已写：
- 按 README 重新运行是否成功：
让学员整理自己的主项目 README。
要求：
- 必须包含运行方式。
- 必须包含当前功能和待改进事项。
- 必须包含注意事项。
- 按 README 重新运行一次。
- 修正不准确的说明。
- README 写得像宣传语：补具体运行步骤。
- 运行命令漏目录：写清在哪个文件夹执行。
- 文件结构不准确：让 AI 重新读取文件列表。
- 待改进事项太多：按下一版优先级排序。
- 当前功能写虚：只写已经验收通过的功能。
完成主项目 README。
提交内容：
- README 文件截图。
- README 检查卡。
- 按 README 运行的结果截图。
- 一条真实注意事项。
- 第 1 页：README 是项目门口的说明牌
- 第 2 页：三周后的自己如何重新进入项目
- 第 3 页：README 七块内容
- 第 4 页：让 AI 整理，人补真实经验
- 第 5 页：按 README 重新运行
- 第 6 页：README 检查卡