关于 eli5
这项写作技能面向不熟悉代码的技术读者,帮助准确解释规范或变更。它强调贯穿始终的具体场景、术语定义,以及对架构变化的明确说明。
主要功能
- 01贯穿始终的具体场景
- 02技术术语定义
- 03用伪代码说明控制流
- 04变更前后的数据流
- 05架构变化清单
- 06指定章节结构
适用场景
- 01向新贡献者解释代码变更
- 02记录行为与数据流
- 03说明迁移和兼容性
安装
复制下面的命令,在终端中运行。
$
npx skills add https:/ / github.com/ dzhng/ skills --skill eli5安装后在 Claude Code 中输入/eli5确认已加载。
详细介绍
五岁小孩也能看懂
将引用的规范或变更转化为技术读者能理解的准确心智模型,即使他们并不熟悉代码。语言通俗,精度完整:简化讲述方式,但绝不改变事实。
语体
其他技能会在输出需要让不了解工作背景的人也能读懂时引用这里。读者具备技术背景——伪代码和精确的论断都没问题——但他们没有读过任何代码,也没有读过本次会话中的任何消息:没有差异、没有记录,也不知道工作过程中创造的任何术语。撰写 ELI5 意味着:
- 从头到尾讲述一个具体场景——触发事件、当前会发生什么,以及变更(或尚未实现的替代方案)会如何处理——而不是抽象地描述特性。
- 在术语第一次出现时就解释每一个专业术语;绝不依赖规范、代码或会话中创造的标签。
- 使用小而具体的示例,但不要用类比取代精确的论断。
- 解释控制流、顺序或时序时,优先使用伪代码。用散文描述“何时触发”听起来似乎合理,却会掩盖逻辑缺口;五行伪代码能让判断条件一目了然,也能让读者发现你遗漏的情况。伪代码应写出判断逻辑,而不是实现细节——写条件及其顺序,而非真实函数签名。判断是否需要伪代码的标准:如果你的散文中出现了“仅当”“之前”“除非”或“一旦”,读者却仍说不清第二次调用时会发生什么。
- 测试标准:不看差异、规范或记录,文本也能独立成立。如果读者还得问“这部分是什么意思”,就不合格。
工作流
- 阅读完整的引用材料;如果单靠规范无法确定行为,就检查当前负责人。当没有指定材料时,解释会话中当前的变更(工作树或分支差异)。区分当前已存在的内容与仅处于提议阶段的内容。
- 结合用户或运维层面的后果解释问题,包括当前设计为何会导致该问题。
- 将解决方案描述为一个简单的变更前后数据流。按职责介绍每个组件,而不是按文件名或内部符号介绍。
- 全面列出架构和持久化契约的变更:新增、修改、删除、重置,以及明确保持不变的内容。如果游标或线格式切换会影响已存储的数据或读取方,也要说明。没有架构变更时,明确说明。
输出
按以下顺序使用这些标题:
问题解决方案架构变更
最后用一个简短句子说明用户会注意到什么变化。
规则
- 先说明行为和边界;只有在实现名称能帮助厘清职责或契约时才提及。
- 区分规范记录与派生索引、缓存、摘要及展示分组。
- 明确指出破坏性重置、迁移要求、兼容性行为、最终一致性和有意的数据丢失。
- 不要因为架构变更属于运维层面或对用户不可见,就将其省略。
评论
支持 Markdown