coding-session-to-tutorial

实战案例转教程

把一段原始的实战记录（可以很乱、很碎、有弯路）转化为其他程序员可以直接学习和复用的教程。

这个技能的核心价值：你解决问题用了 1 小时，教程让下一个人 10 分钟搞定。

---

执行流程（每次必走）

第 1 步：读取和整理输入

接受以下任意形式的输入：

• 终端命令和输出（粘贴即可，不需要整理）
• 一段对话描述（「我先试了 A，不行，然后试了 B，还是不行，最后用 C 解决了」）
• 截图描述（「截图里显示的是 xxx 报错」）
• 多种形式混合

不要催用户整理输入。你来整理。

从输入中提取：

1. 问题是什么（现象 + 报错/数据）
2. 初步假设是什么（用户当时以为是什么原因）
3. 尝试过哪些方法（包括走过的弯路）
4. 最终解法
5. 有没有预防/验证步骤

只提取素材明确支持的事实。不得为了补齐叙事而推测用户的初步假设、弯路、AI 分析过程、耗时、次数或最终结果。素材未提供的字段标记为“未提供 / 待确认”，或在不影响教程成立时省略。

如果信息明显不够（不知道问题是什么，或不知道最终怎么解决的），只问 1 个最关键的缺失问题，不要问多个。

---

第 2 步：确认教程定位

在开始写之前，向用户确认一件事（简短即可）：

「这篇教程准备放在哪里？」

• A. 公众号文章（更偏叙事，情感节奏）
• B. 个人网站/Wiki（完整技术记录，干货为主）
• C. 内部沉淀（团队内部，注重可复用性）

不同定位影响叙事详细程度，但结构一致。如果用户没有明确偏好，默认 B（完整技术记录）。

---

第 3 步：按模板生成教程初稿

引用 references/tutorial-template.md，生成完整的教程初稿。

强制要求：

1. 初步假设有证据才写：用户说过或日志能支持时，忠实保留；没有就不补造。
2. 真实弯路必须保留：素材里确实发生过的失败尝试不能删；素材没有弯路时，不得为了故事性强行添加。
3. AI 协作方式按证据写：只记录素材能确认的“给了什么 → AI 怎么分析 → 实际结果”；不完整就标注缺口，不代替用户回忆。
4. 通用清单必须用 checkbox + 命令块格式，不能写叙述句
5. 方法论要升维，从「这次的步骤」升到「下次遇到类似问题的思维框架」

---

第 4 步：质量自检

生成初稿后，对照 references/writing-principles.md 里的「常见错误清单」过一遍：

[ ] 素材若包含弯路，是否完整保留；素材若不包含，是否没有强行补造
[ ] AI 协作部分是否只写了证据支持的「给了什么 → AI 怎么分析 → 实际结果」
[ ] 通用清单里是否有分支（情况 A / 情况 B）而不是只有一条路
[ ] 方法论是否升维了（不是步骤复述，是可迁移思维框架）
[ ] 所有命令是否都在代码块里
[ ] 时间、大小、次数等具体数字是否全部来自素材；没有数据时是否保守表述或标记待补充
[ ] 是否无虚构的第一人称经历、报错、对话、命令、用户反馈或验证结果

有不符合的，直接修改初稿，不要列出来问用户。

---

第 5 步：输出 + 后续推荐

输出完整教程初稿后，附一段简短的后续建议：

---
📌 后续建议：

这篇教程初稿已经可以发布。如需进一步加工：

- 想提升文章的「人味」和传播力 → 用 kangjian-skill 做风格润色
- 想生成配套的短视频脚本 → 用 content-creator 工作流 D
- 想拆解成小红书笔记 → 用 content-creator 工作流 F
- 想直接发公众号 → 用 baoyu-post-to-wechat

如果这篇内容还需要一个更好的「内容角度」定位（比如想做成系列），可以把这篇初稿交给 ai-programming-topic-planner 来规划角度。

---

输出格式规范

标题格式：# AI 编程实战：[问题动词短语] 导言格式：> [一句话定位] 代码块：全部用 ```bash ``` 或对应语言标注 checkbox 清单：全用 - [ ] 格式 阶段标题：有耗时记录时用 ### 第 N 阶段：[名称]（约 X 分钟）；无记录时用 ### 第 N 阶段：[名称]，不补造时间。

---

判断是否需要补充信息

以下情况需要主动问用户（只问最关键的那一个）：