你有没有过过这样的经历：
项目开发时觉得一切都记得很清楚：接口怎么设计、问题怎么排查、为什么选择这个方案，似乎都能随时讲出来。
但几周或几个月后，真正面对导师验收或面试官提问时，却只剩下几句模糊的描述：
“我做了一个管理系统。”
“项目用了 Go、MySQL 和 Redis。”
“我主要负责后端。”
“具体细节……有点记不清了。”
代码明明写过，功能明明完成过，为什么最后却讲不清？
因为你留下了代码，却没有留下能够证明代码价值的材料。
一个完整的项目交付，不应该只包含“能运行的代码”，还应该包含：
- 这个项目解决了什么问题；
- 你具体负责了什么；
- 核心链路是怎么工作的；
- 技术方案为什么这样选；
- 遇到问题时如何定位和解决；
- 你用什么测试、日志或提交记录证明它完成了；
- 面试时如何在 30 秒、1 分钟和 3 分钟内讲清楚。
开发完成后不要只留下代码，要留下可验证的证据链。
本文介绍的 learner-project-storyteller，就是围绕这个目标设计的一套项目沉淀方法。
它不是把项目包装得更“高级”，也不是替你虚构一段漂亮经历，而是尝试从代码、Git、测试和文档中，整理出一条更可靠的技术叙事：
任务目标
↓
实际代码改动
↓
技术决策与取舍
↓
问题排查与解决
↓
测试、运行与验收证据
↓
项目沉淀、面试表达与追问准备
一、为什么“功能做完”不等于“项目交付完成”
对于刚完成项目的开发者或学员来说，最容易忽略的不是写代码，而是整理开发过程。
项目开发过程中，你可能经历了：
- 需求从模糊到明确；
- 数据结构多次调整；
- 接口字段反复修改；
- 前后端联调失败；
- 测试发现边界问题；
- Git 提交逐步记录改动；
- 最终通过运行、测试或导师验收。
这些内容，才是项目中最有价值的部分。
但如果没有及时沉淀，开发结束后通常会出现三种断裂。
1. 代码和业务目标断裂
你知道某个函数做了什么，却说不清：
- 为什么需要这个功能；
- 它服务于哪个用户问题；
- 这个模块在整个系统中承担什么职责。
面试官问“这个项目解决了什么问题”，你只能开始罗列技术栈。
2. 实现和技术决策断裂
你记得项目用了某个框架、数据库或中间件，却说不清：
- 为什么选它；
- 有没有考虑过其他方案；
- 这个方案解决了什么问题；
- 它带来了什么限制。
技术名词很多，但缺少因果关系，回答就容易变成“背组件清单”。
3. 结论和证据断裂
你说“功能已经完成”“性能有提升”“系统已经上线”，但面试官继续追问：
- 你怎么验证的？
- 测试命令是什么？
- 哪个提交实现了这个功能？
- 指标来自哪里？
- 是你个人完成的，还是团队共同完成的？
如果手里没有代码位置、提交记录、测试结果、日志或验收记录，这些结论就很难站住。
所以，项目沉淀的重点不是把内容写得更好听，而是把开发过程中的事实、判断和证据重新连接起来。
二、什么是“可验证的项目证据链”
一份可信的项目总结，至少应该把下面六个问题串起来。
1. 任务目标：为什么做
先说明项目背景和任务目标：
- 项目面向什么用户；
- 用户遇到了什么问题；
- 本次开发解决了哪一部分；
- 任务范围是什么，哪些内容不在本次范围内。
2. 实际改动：做了什么
不能只写“完成了后端开发”，而要进一步定位：
- 修改了哪些目录和文件；
- 新增了哪些接口、模块或数据结构；
- 哪些功能已经实现；
- 哪些内容仍然是计划。
3. 技术决策：为什么这样做
技术方案需要和问题对应起来：
- 为什么使用当前的接口设计；
- 为什么采用某种数据模型；
- 为什么选择某种鉴权、缓存或异常处理方式；
- 是否考虑过替代方案；
- 当前方案有哪些代价和限制。
4. 问题排查：遇到什么困难
真实的技术经验往往来自问题，而不是来自顺利完成的部分。
可以按照这条路径记录：
现象
→ 影响
→ 定位思路
→ 根因
→ 解决方案
→ 验证结果
→ 可迁移经验
如果仓库里没有真实踩坑记录，也不要为了让复盘“看起来完整”而虚构问题。更稳妥的方式是记录：
- 当前已经发现的风险；
- 尚未验证的边界情况；
- 建议补充的测试项；
- 仍需要开发者确认的事实。
5. 验证证据：怎么证明完成了
可以作为证据的材料包括：
- 文件路径和关键代码位置；
- Git diff；
- 相关提交记录；
- 测试文件和测试命令；
- 构建结果；
- API 调用结果；
- 数据库结构；
- 配置文件；
- 运行日志；
- 截图、指标或验收记录。
需要特别注意：
“代码里存在”不等于“测试通过”，“测试通过”也不等于“已经上线”。
这三个结论需要分别说明，不能混写。
6. 面试表达：如何讲清楚
最后才是把技术事实转化为可表达的内容：
- 30 秒版本，用于快速介绍；
- 1 分钟版本，用于完整概括；
- 3 分钟版本，用于展开架构、链路和问题；
- 面试追问清单，用于模拟深挖；
- 简历项目描述，用于压缩成几条可靠的 bullet。
这条链路的价值在于：每个表达都尽量能回到事实和证据，而不是凭印象发挥。
三、这个 Skill 到底会检查什么
learner-project-storyteller 的定位不是“项目包装器”，更接近一个项目沉淀助手。
按照 Skill 的设计，它默认会检查与任务相关的几类材料。
1. 项目结构和已有文档
包括：
- 目录结构；
- README；
- 技术 Spec；
- 接口文档；
- 设计文档；
- 运行说明。
这些材料主要帮助建立业务背景、模块边界和项目整体结构。
2. 工作区和 Git 信息
包括：
- 当前工作区改动；
- 暂存区改动；
- 近期相关提交；
- Git diff。
Git 信息能够帮助区分：
- 哪些内容是最近完成的；
- 哪些文件与本次任务相关；
- 功能是新增、修改还是修复；
- 项目是否保留了开发过程记录。
如果还没有提交 Git，也可以使用，但提交记录这一类证据会暂时缺失，不能被写成已经存在。
3. 关键代码和业务链路
包括：
- 关键入口；
- 核心业务流程；
- 配置；
- 数据模型；
- 接口实现；
- 模块之间的调用关系。
重点不是把整个仓库逐行解释，而是找到与本次任务相关的核心链路。
如果项目很大，应该明确限定范围，否则总结结果可能混入无关模块。
4. 测试、构建和运行材料
包括：
- 测试文件；
- 测试命令；
- 构建结果；
- 启动方式；
- 接口调用示例；
- 运行说明。
需要注意：工具可以检查仓库中的测试和已有结果，但它不会凭空证明一个没有执行过的测试，也不会自动生成真实的线上数据。
5. 日志、截图和验收记录
如果仓库中存在以下材料，也可以作为补充证据：
- 日志；
- 截图；
- 性能数据；
- 验收记录；
- 测试环境结果。
如果证据不在仓库中，也可以由开发者主动提供，但应明确标记为“用户提供证据”，并说明来源。
四、最终会产出哪些项目材料
默认情况下，结果会整理到：
docs/project-retrospectives/
通常包含以下 5 类文档。
1. 项目技术沉淀
它解决的是：
“这个项目到底是什么？系统怎么工作？我做了什么？”
内容可以包括：
- 一句话项目定位；
- 业务背景和用户问题；
- 个人负责范围及团队协作边界；
- 技术栈和模块划分；
- 系统架构；
- 一条端到端核心链路；
- 关键接口和数据模型；
- 技术决策、替代方案与取舍；
- 测试、构建、运行和验收证据；
- 当前限制、风险和后续计划；
- 证据索引和待补充信息。
2. 问题复盘
它解决的是：
“你遇到过什么问题？是怎么解决的？”
复盘不应该只写“问题已解决”，而要还原排查过程：
现象 → 影响 → 定位思路 → 根因 → 解决方案 → 验证 → 经验
这比简单写“修复了一个 Bug”更有价值，因为它能体现你的判断过程和排错能力。
3. 面试讲解稿
根据项目事实，整理出不同长度的表达版本：
- 30 秒版本：项目是什么、你负责什么、结果如何；
- 1 分钟版本：补充背景、方案、个人贡献和难点；
- 3 分钟版本：展开架构、核心链路、关键取舍、问题排查和验证。
同时，还应标注：
- 哪些地方可以使用第一人称；
- 哪些内容属于团队成果；
- 哪些指标需要自己补充；
- 哪些结论不能夸大。
4. 面试追问清单
追问不应停留在“你用了什么技术”，而要覆盖项目真正可能被深挖的地方：
- 业务与需求；
- 架构与模块边界；
- 核心接口与数据流；
- 数据模型与一致性；
- 性能、并发和容量；
- 异常处理与安全；
- 测试、发布和监控；
- 技术取舍与替代方案；
- 个人贡献和团队协作。
无法从代码和材料中确认的回答，不能直接伪造成确定结论，而应该输出：
回答思路 + 学员待补充事实
5. 简历项目描述
通常包括：
- 项目标题；
- 一句话定位；
- 技术栈；
- 3～5 条项目描述；
- 量化成果占位；
- 每条描述对应的代码或测试证据；
- 无法证明时的保守写法。
比较可靠的句式是：
动作 + 技术方案 + 解决的问题 + 结果
如果没有真实指标，就不要写“性能提升 50%”“响应时间降低 80%”这类数字。
可以改写为：
基于现有接口和数据模型完成某功能，实现了某业务链路，并通过指定测试命令验证核心场景。
如果确实有数据，则应该补充数据来源，例如压测脚本、日志或验收记录。
五、如何正确使用：不要只说“帮我总结项目”
一句“帮我总结项目”信息量太少。
更好的做法，是提前告诉工具五件事：
项目名称：
本次任务：
我负责的模块：
目标岗位：
重点技术点：
例如：
项目名称：LexAgent
本次任务：前端页面与 Go 后端业务接口联调
我负责的模块：请先根据代码分析，再让我确认
目标岗位：后端开发 / AI 应用开发
重点技术点：前后端接口、鉴权、数据持久化、异常处理
这样做的好处是，沉淀结果更容易围绕真实目标展开，也能减少把整个项目所有内容混在一起的情况。
场景一：开发完成后立即沉淀
登录功能已经开发完成，请根据当前代码和提交记录，帮我沉淀这次任务。重点说明登录流程、鉴权方案、我负责的内容、测试方式和遇到的问题。
场景二：准备导师验收
当前项目的前后端 MVP 已经跑通，准备给导师验收。请检查当前仓库，生成一份项目技术沉淀和验收说明，并列出目前还没有证据证明的内容。
场景三：准备后端面试
我下周要参加后端开发面试，请根据当前项目代码整理 30 秒、1 分钟和 3 分钟讲解稿，并列出面试官可能追问的架构、接口、数据库、并发、异常处理和测试问题。
场景四：只总结一个任务
只总结本次“文档上传与解析”任务，不要总结其他模块。请重点检查 py-ai/mcp_server/、相关提交和测试文件。
限定范围非常重要。项目越大，越应该明确“总结什么”和“不要总结什么”。
六、一条可以直接复制的完整提示词
下面这段提示词，适合第一次使用时直接复制：
我刚完成当前项目中的一个开发任务，现在需要把它沉淀下来，方便以后复习、给导师验收和参加面试。
请按以下步骤执行：
1. 检查当前仓库的 README、技术文档、相关代码、git diff、近期提交和测试；
2. 先判断本次任务的实际范围和我的个人贡献，不确定的地方列出来让我确认；
3. 生成以下材料：
- 项目技术沉淀；
- 问题复盘；
- 30 秒、1 分钟、3 分钟面试讲解稿；
- 面试追问清单；
- 简历项目描述；
4. 将文档保存到 docs/project-retrospectives/；
5. 每个关键结论尽量标注对应的文件、代码位置、提交、测试或其他证据；
6. 将内容区分为“已确认”“合理推断”“待补充”；
7. 没有证据支持的指标、成果、个人贡献和上线情况不要编造，统一放到待补充信息中；
8. 明确区分我个人负责的内容、团队共同完成的内容和其他成员负责的内容；
9. 最后告诉我生成了哪些文件、哪些内容已经确认、还需要我补充什么。
项目名称：【填写项目名称】
本次任务：【填写任务名称】
我负责的内容：【填写个人负责模块；不确定就写“请根据代码分析后让我确认”】
目标岗位：【填写目标岗位】
重点技术点：【填写希望重点复习的技术点】
如果信息不完整，可以补充：
信息不完整的地方先生成初稿，但必须集中列在“待确认信息”中，不要把推断写成事实。
如果不希望读取整个仓库，可以这样限定：
只检查 backend/、frontend/、相关测试目录和最近两次相关提交，不要读取其他目录。
如果需要核对结论，可以继续追问：
请不要直接改文档，先逐项核对刚才的结论。每个结论都列出对应文件、代码位置或提交记录；无法证明的内容改成待确认。
七、生成文档后，别忘了做这三步
工具生成材料，不代表你已经准备好面试。
真正的沉淀应该以你的复核和练习结束。
第一步：先检查个人贡献
逐句确认：
这件事是不是我做的？
我能不能说清楚怎么做的？
如果面试官追问，我能不能打开对应代码？
如果某项工作是团队共同完成的，就不要全部写成个人成果。
可以明确区分：
- 我负责后端接口；
- 另一位同学负责前端页面；
- 数据库表结构由团队共同确定；
- 部署由导师或其他成员完成。
这不是削弱项目，而是让经历更加可信。
第二步：再检查证据
重点核对：
- 文件路径是否真实存在；
- 测试命令是否实际执行过；
- 测试结果是否有来源；
- 指标是否有压测、日志或验收记录；
- “已实现”和“计划实现”是否混在一起；
- 是否包含密钥、内部地址或不应公开的敏感信息。
尤其要警惕简历中的量化表达。
没有真实数据时，不要为了让项目显得更厉害而补数字。一个没有夸张指标、但能讲清楚实现和验证过程的项目，通常比一份经不起追问的“高性能系统”更可靠。
第三步：进行口头演练
先不要看文档，尝试回答五个问题：
这个项目解决什么问题？
你负责什么？
最难的问题是什么？
你为什么选择这个方案？
你怎么验证它有效？
然后再打开面试讲解稿，对比自己漏掉了哪些技术细节。
接着可以让 Comate 模拟面试官：
请根据刚才生成的面试追问清单，逐个向我提问。一次只问一个问题，等我回答后指出回答中缺少的技术细节，不要直接替我回答。
这样做的目标不是背稿，而是让你能够沿着“问题—方案—实现—验证”的顺序自然表达。
八、它不能替你完成什么
为了避免误解，有几件事需要提前说清楚。
1. 它不能替你确认没有留下的事实
如果个人贡献没有写在代码、提交或文档中，工具无法仅凭仓库准确判断“哪些是你做的”。
你仍然需要补充：
- 自己负责的模块；
- 自己做出的技术决策；
- 团队成员的分工；
- 不在仓库中的验收或压测结果。
2. 它不能把推断变成证据
从代码结构中可以做出合理推断，但推断不等于事实。
例如：
- 从配置文件推断系统支持某种运行方式；
- 从测试文件推断某个场景被覆盖；
- 从提交内容推断某项功能在某次提交中完成。
这些都应该保留依据，必要时标记为“推断”，不能写成已经验证的结果。
3. 它不能替你创造性能指标
没有压测报告，就不要写响应时间；没有用户数据，就不要写用户量；没有准确率评估，就不要写准确率提升。
可以保留占位：
在【待补充数据】规模下，将【待补充指标】从【原值】优化至【结果】。
但在真正放入简历之前，必须用真实数据替换，或者改成不含虚假数字的保守表达。
4. 它不能替你进行口头表达
它可以提供讲解稿和追问清单，但最终能否讲清楚，仍然取决于你是否理解项目。
如果你无法打开对应代码、解释技术取舍、说明验证方法，那么再漂亮的文档也无法替代真实掌握。
九、把项目沉淀当作开发流程的一部分
很多人把项目总结放在面试前，结果只能依靠记忆补齐细节。
更好的节奏是：
任务完成
→ 保留 Git 提交
→ 记录关键问题
→ 保存测试与运行证据
→ 生成项目沉淀
→ 复核个人贡献
→ 进行口头演练
每完成一个相对完整的任务，就整理一次。
这样做有三个好处：
- 离开发现场更近，细节不容易丢失；
- 能及时发现测试和文档中的缺口；
- 面试前不需要从零开始回忆整个项目。
项目沉淀也不应该只服务于面试，它同样可以用于：
- 导师阶段性验收；
- 项目答辩；
- 团队交接；
- 个人技术复盘；
- 后续简历更新；
- 下一次类似任务的方案参考。
结语：代码是结果，证据链才是你的项目故事
开发完成，通常只是任务结束的第一步。
真正能帮助你复习、验收和面试的，不只是仓库里有多少代码，而是你能否回答：
- 为什么做这个项目；
- 这次任务解决了什么问题；
- 哪些工作是你完成的；
- 核心链路如何运行；
- 技术方案为什么这样选择；
- 出现问题时如何定位；
- 用什么证据证明它真的完成；
- 如果重新做一次，你会如何改进。
learner-project-storyteller 的价值，不在于把经历包装成一个更厉害的故事，而在于帮助你把真实开发过程整理成一条可回溯、可复核、可练习的链路。
开发完成后不要只留下代码，要留下：
代码为什么这样写，问题怎么解决，结果如何证明，面试怎么讲。
从今天开始，每做完一个任务，除了提交代码，也给自己留下这份技术证据。
如果这篇文章对你有帮助，欢迎收藏、转发给正在准备面试或项目验收的同学。
也欢迎在评论区分享：
你最难讲清楚的是项目背景、技术方案，还是个人贡献？
