面试前十分钟，面试官打开简历上的仓库链接。他不会 clone，不会读源码，看的是 README 和 commit 列表。README 决定接下来三十秒是继续往下翻，还是关掉回去看简历。
所以 README 不是给用户看的文档，在求职这个场景里，它是你项目经历的展开页。
面试官读 README 的顺序
第一屏：这是什么，能不能看到它跑起来的样子。
往下：怎么跑起来。
再往下：有没有设计说明，作者做过什么决策。
最后：commit 列表，看时间分布和 message 质量。
这个顺序决定了 README 的段落顺序。
该有的几段
一句话定位加状态。「一个给 XX 场景用的 XX」，后面跟着「在维护」或「功能完整，2025.06 起只修 bug」。不要写「一个基于 Spring Boot 的项目」，那是技术栈不是定位。
截图、GIF 或线上地址。有界面的必须有图，没界面的给一段示例输出或一条 curl 及其返回。看不到运行效果的项目，读者默认它跑不起来。
快速开始。三条命令以内跑起来，docker compose up 最好。跑不起来的 README 是负资产，比没有 README 更伤。
设计说明。一张图或一段话，说清模块划分和数据流，以及一到两个关键决策为什么这么选、没选什么。这一段是面试官真正在找的，多数仓库没有。
已知问题和不做的事。这段写的人最少，但最能建立可信度：编出来的项目没有已知问题。
可选段：性能数据（附测法和脚本位置）、目录结构。个人项目不需要贡献指南和行为准则，那是模板复制的痕迹。
改一个 README 开头看
改前：
# my-blog A blog system built with Spring Boot and Vue. ## Features - User login - Post articles - Comments ## How to run See the source code.改后：
# tinyblog 单人博客后端，重点解决文章列表在十万级数据下的分页性能。 状态：功能完整，2025.06 起只修 bug。在线示例：demo.xxx.dev（只读账号 guest / guest） ## 快速开始 docker compose up -d # MySQL + Redis + 应用，首次约 1 分钟 curl "localhost:8080/api/posts?cursor=0&size=20" ## 设计说明 - 列表分页用游标不用 offset：10 万行下 offset 分页 P99 约 800ms，游标 + 覆盖索引 50ms，压测脚本在 bench/ - 评论缓存用延迟双删，没接 binlog 订阅，原因是单机部署不值得多一个组件 ## 已知问题 - 游标分页不支持跳页，按产品定位可接受 - 全文搜索是 LIKE，数据量上去要换检索引擎，暂不做改后每一段都在回答面试官的一个问题，而且「没选什么」和「不做什么」写出来了。面试官看到「没接 binlog 订阅」，追问的方向就是「什么情况下你会接」，这是你准备过的题。
commit 列表是 README 的旁证
README 说做了分页优化，commit 里应该找得到对应记录。message 全是 update、fix、修改 的仓库，README 写得再好也打折。至少保证最近二十条 commit 的 message 能读懂在做什么，时间分布不要集中在一个晚上。
不该出现的
徽章排一整行，个人项目一个 CI 状态徽章足够。技术栈列表当设计说明，「用了 Redis」不是设计，「为什么在这里用 Redis」才是。「持续更新中」但最后一次提交在一年前。README 里的功能列表和实际代码对不上。
README 和简历条目的对应
简历上一条三行，README 是它的展开。简历上写的每个技术点，README 里都应该有对应段落，措辞可以一致。面试官在两处看到同样的说法，会更信；在两处看到不同的说法，会先问哪个是真的。
写完之后建议反过来核一次：拿 README 对照简历上那条，看简历有没有漏写 README 里最有价值的决策。
最后
面试官点开仓库，想确认的只有一件事：这个项目是不是真的，作者是不是真的想过。README 的几段，就是按这个顺序给证据。
