从作业到作品集：用 README 讲清项目

你将学会什么

说清课程作业与作品集之间的差距在表达而非功能
用「问题定义—解决方案—可验证结果」组织项目表达
减少一次性脚本和临时堆叠，提升结构清晰度

正文

作业和作品集的差距，多数时候不在功能多少，而在交付形态：作业通常只是一份能跑的代码，作品则需要别人能看懂、能复用、能展示。工程化视角帮你把「能运行」升级成「能交付」——用 README 把问题、方案与结果讲清楚，让评审官不用读完代码也能判断项目价值：

保留最小运行说明，降低观看门槛
突出问题定义、解决方案和可验证结果
减少一次性脚本和临时堆叠，提高结构清晰度

如果你未来要投实习或研究生项目，评审官未必仔细看所有实现细节，但一定会快速判断你能不能交付一个结构清晰的工程对象。所以在 README 里按这个顺序写三件事：

1. 问题：这个项目解决什么具体问题
2. 方案：核心做法是什么，为什么这样选
3. 结果：可验证的产出，如功能完成度、性能数据、使用反馈

「问题—方案—结果」每部分怎么写？

三部分各自回答一个问题，合起来构成项目的完整叙述：「问题」写清场景、对象与具体的不便之处，问题具体了，方案和结果才有判断基准；「方案」说明核心做法与选择理由，不用罗列全部实现细节，可以给出取舍说明——为什么选择这种做法、放弃过哪些替代做法；「结果」写出可验证的产出与判断依据，避免「完成了所有功能」这类无法核实的表述，数据与截图要和提交时的运行状态一致。三部分的顺序不调换：问题引出方案，方案带出结果。每部分控制在几行以内，信息密度比篇幅更重要。

写作前先收集素材：功能清单、运行截图、测试记录。问题部分用直陈句开头，读者第一眼就知道项目在解决什么；问题描述里提到的对象，后续方案需要与之对应。方案列举技术选型时说明各选项的适用边界。结果部分区分完成与验证：完成表示实现，验证表示确认效果。「问题—方案—结果」的表达方式同样适用于口头介绍，面试或评审时按同一顺序展开，信息不会丢。README 写完后站在评审官的角度通读一遍，确认三个问题都能快速回答。

README 怎么组织才容易看？

README 是评审官最先看到的文件，也是作品集展示的入口。把「问题—方案—结果」写进 README，等于替评审官标好阅读路线：顶部用几句话说明项目解决什么，再按顺序展开细节。最小运行说明的目标是让读者在最短时间内跑起来看到结果：运行步骤按执行顺序排列，每步只做一件事；环境依赖在步骤中注明安装方式，启动命令的输出也写下，读者能对照判断是否成功。运行说明放在靠前位置，演示入口（可访问的链接或截图）比大段文字描述更直观；项目截图放在摘要之后，配上说明讲清当前展示的功能。

评审官先看 README，再看仓库结构，最后才决定要不要读代码，所以仓库结构本身也参与表达。README 的标题直接点明项目功能，比代号更容易被记住；套用模板可以，把与项目无关的占位表述删掉。代码里保留必要的注释，与 README 的说明互相印证：README 说明项目意图，注释说明具体做法的理由。

为什么要发布成可访问的站点？

作品集项目可以考虑发布成可访问的站点，让评审官直接体验运行效果。GitHub Pages 提供把仓库发布为站点的现成方式，完整步骤在官方文档中有说明：站点内容直接来自仓库，推送新提交后确认页面已更新；README 里的演示链接保持可访问，失效的链接会削弱可信度，并把站点链接同时放进 README，形成相互引用的入口。

仓库本身也是展示对象，目录结构与提交记录都会被看到：提交前删除临时文件和调试输出，大改动完成时在 README 里补一段变更说明，删除的功能同步从 README 移除。把 README 当作项目的一部分持续维护，写一次就不再更新会让文档与代码脱节；日常开发中把 README 的更新当成提交的一部分。投递作品集前把仓库与站点都检查一遍再发链接，发布与演示用的分支保持稳定，不把半成品推到展示分支。作品集仓库长期不用时，回归运行一次确认项目仍然可用；定期走一遍从克隆到运行的完整流程，确认说明没有过时。

把「做了什么」翻译成「解决了什么、结果如何」，是作业与作品集最关键的一步。

动手练

知识检查

先自己回答，再看答案：

课程作业和作品集的差距通常体现在哪里？
「可验证结果」为什么要写进项目表达？
为什么一次性脚本和临时堆叠会拖累展示？

参考答案

差距主要在表达方式，而不是功能数量。
可验证结果让评审官快速判断项目的真实完成度。
它们让项目结构变乱，也让别人难以判断核心逻辑在哪。

本章小结

作品集表达三要素：问题定义、解决方案、可验证结果
最小运行说明降低观看门槛，让人快速跑起来
清理一次性脚本，结构清晰本身就是竞争力