README 是别人认识你项目的第一眼。

好 README 的标准其实只有一条：

别人不用打开任何一个代码文件，就能看懂这是什么、怎么玩 / 怎么用、你为什么做它。

做到这条，你的项目才算「别人能看懂、能复现」。做不到，无论核验的人还是三年后的你自己，都得花很久去猜——很多项目被退回，就卡在这里。

一个好 README 会回答这些

• 这是什么？ 一句话说清。别用「一个基于 XX 的智能系统」这种正确的废话。
• 它长什么样？ 放一张主图（头图），最好再放几张能说明问题的截图或实拍。
• 你为什么做它？ 一两句来由。这是让它从「作业」变成「作品」的地方。
• 怎么玩 / 怎么用？ 游戏说清操作和目标；硬件说清怎么接、怎么跑起来。
• 它是怎么拼起来的？ 用了什么、大致的结构。够别人看懂就行，不用写成论文。
• 哪里能真的打开它？ 有 demo 或在线版就放链接。
• 参考了谁？ 用了别人的东西，就在这里注明出处、感谢作者。

对比一下

一个能直接抄的骨架

野生CLI 的 README.md 支持 YAML Frontmatter，头图在图片 alt 里加 [head] 标记（详见野生CLI 指南）：

---
tagline: 一句话介绍，比如「躲着 boss 弹幕收集猫粮的横版跑酷」
tags: [Game, Pixel]
demo_urls: [https://你的在线演示链接]
---

# 项目名字

![[head] 项目主图](./images/cover.png)

## 这是什么

一句话说清。再用两三句讲你为什么做它。

## 怎么玩 / 怎么用

- 操作 / 接线说明
- 目标 / 效果

## 怎么做出来的

用了什么、大致怎么拼的。放几张关键截图。

![调试中的样子](./images/debug.png)

## 参考与致谢

参考了 XXX（附链接），感谢作者。

两类项目各自要注意的

• 口袋街机（游戏） —— 主图用游戏画面而不是代码截图；讲清怎么操作、赢的条件是什么；有在线版一定放 demo 链接，让人点开就能玩。
• 桌面造物（硬件） —— 放实物照，别只放渲染图；讲清怎么接线、怎么烧录跑起来；中间的调试和翻车照片也放上，它们让项目显得真实。

别往 README 里放的东西

• API Token、密码、密钥 —— 绝不写进 README、日志、配置或截图。
• 手机号、家庭住址、真实全名 等隐私信息。

写好 README 之后，配上讲清过程的开发日志，你的项目就站得住了。