writing-to-explain
writing-to-explain
能把复杂的东西讲得让人看懂的作者——费曼、Paul Graham、Julia Evans、Polya、Carl Sagan——脑子里都有一个共同的姿态:
我懂的这件事,读者不懂。我的活不是展示我懂了什么,而是用读者脑子里已经有的材料,在 TA 脑子里搭一个差不多的理解。
这是翻译者的姿态,不是讲台上的姿态。翻译者脑子里装着两端——原文的含义和目标语言读者能接住的表达——两端之间搭桥。AI 默认只顾一端:它把自己脑子里的知识结构工整地铺出来(完备、分类、列规则、给正反例),然后就完了。读者看完脑子里其实没建起那个理解,因为没人帮 TA 搭桥。
下面几节讲大师们搭桥时具体在做什么动作。
从读者已经在的地方开始
费曼讲物理,第一句不是"力等于质量乘加速度",是"想象你手里拿着一杯水……"。Paul Graham 写创业随笔,开头不是"创业公司是……",是他上周跟朋友吃饭时冒出来的一句话。Julia Evans 写 debug,开头是"昨天我遇到了一个奇怪的 bug"。Sagan 讲宇宙,开头是"如果你把地球 46 亿年的历史压缩成一年……"。
他们都从读者生活里的场景或具体事件切入——不是因为懒得写定义,是因为读者需要一个锚点,新概念才挂得上去。话题的形式起点(定义、分类、历史背景)通常不是读者的锚点,是这个领域内部的约定起点。
具体动作:动笔前问自己"读者翻开这篇文章之前,脑子里最相关的那件事是什么?"——从那件事开始写第一段。
More from liuzhengdongfortest/easysdd
easysdd-feature-acceptance
feature 流程的阶段 3——做完整验收闭环。三件事:一是逐层对照 {slug}-design.md 核对实现有没有走样,发现偏差就当场修不是写在报告里"记一下";二是把这个 feature 归并到项目的整体架构文档里;三是如果本次 feature 改变了对应 requirement 的用户故事或边界,把 requirement doc 也回写一次。最后产出一份 {slug}-acceptance.md 作为整套流程的闭环凭证。前置依赖 easysdd-feature-implement 已完成。触发场景:用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。
98easysdd-feature-fastforward
feature 流程的超轻量通道——不写 design、不写 checklist、不做分阶段 review,就让 AI 像平时一样直接动手写代码,但在动手前先告诉它项目里的 easysdd 知识库在哪、怎么搜,让它写出来的代码踩过的坑更少、和项目约定更一致。触发场景:用户说"快速模式"、"fastforward"、"别那么多步骤"、"直接开干"、"帮我做个 xxx"且需求小到不值得走 design 流程。
98easysdd
easysdd 工作流家族的根技能——介绍工作流体系并把用户路由到正确子技能。触发场景:用户提到"easysdd"、"sdd"、"规约驱动"、"怎么用这套流程"、"我该用哪个技能"、"从哪开始",或描述了新功能但还没决定切入阶段。已知意图(brainstorm/设计/实现/验收/BUG/探索等)优先触发对应子技能而非本技能。
97easysdd-feature-design
feature 流程的阶段 1——为新功能起草一份方案文件,作为后续实现和验收的唯一输入。先收集证据(读架构、读相关代码、grep 防术语冲突、查归档),然后一次性写出完整初稿(含 YAML frontmatter + 三层结构 + 测试设计),交给用户整体 review,迭代到拍板。拍板后从 {slug}-design.md 里抽出 {slug}-checklist.yaml 给后面两个阶段用。触发场景:"开始设计方案"、"写 design doc"、"准备实现 XX",前提是已经知道做什么、为谁做、怎么算成功。
97easysdd-feature
做新功能开发时进入这套子流程——把"加个 X 能力"从模糊想法走到验收闭环,中间有方案文件做存档,AI 和用户后面回头都能查到当时怎么想的、为什么这样定的。触发场景偏向新增能力("做新功能"、"加个 X"、"实现 XX"),不处理已有代码的 bug。本技能只做路由,根据已有产物决定下一步走 brainstorm / design / fastforward / implement / acceptance 中的哪一个。
97easysdd-feature-implement
feature 流程的阶段 2——按 {slug}-design.md 的推进顺序写代码,写完用统一格式做完成汇报给用户 review。前提是 {slug}-design.md 已经 approved(标准 design 含测试设计,或 fastforward design 含验收标准),并且同目录下有 {slug}-checklist.yaml。触发场景:用户说"方案确认了开始实现"、"按方案写代码"、"开工"。实现中遇到方案没覆盖到的情况(新概念、范围外文件、需要打补丁分支)要主动停下来回到方案谈,不要硬冲。
96