mcpField
E
eli5

eli5

github.com/dzhng开发1.4k245 次安装今天更新
代码仓库

关于 eli5

这项写作技能面向不熟悉代码的技术读者,帮助准确解释规范或变更。它强调贯穿始终的具体场景、术语定义,以及对架构变化的明确说明。

主要功能

  1. 01贯穿始终的具体场景
  2. 02技术术语定义
  3. 03用伪代码说明控制流
  4. 04变更前后的数据流
  5. 05架构变化清单
  6. 06指定章节结构

适用场景

  1. 01向新贡献者解释代码变更
  2. 02记录行为与数据流
  3. 03说明迁移和兼容性

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/dzhng/skills --skill eli5

安装后在 Claude Code 中输入/eli5确认已加载。

详细介绍

五岁小孩也能看懂

将引用的规范或变更转化为技术读者能理解的准确心智模型,即使他们并不熟悉代码。语言通俗,精度完整:简化讲述方式,但绝不改变事实。

语体

其他技能会在输出需要让不了解工作背景的人也能读懂时引用这里。读者具备技术背景——伪代码和精确的论断都没问题——但他们没有读过任何代码,也没有读过本次会话中的任何消息:没有差异、没有记录,也不知道工作过程中创造的任何术语。撰写 ELI5 意味着:

  • 从头到尾讲述一个具体场景——触发事件、当前会发生什么,以及变更(或尚未实现的替代方案)会如何处理——而不是抽象地描述特性。
  • 在术语第一次出现时就解释每一个专业术语;绝不依赖规范、代码或会话中创造的标签。
  • 使用小而具体的示例,但不要用类比取代精确的论断。
  • 解释控制流、顺序或时序时,优先使用伪代码。用散文描述“何时触发”听起来似乎合理,却会掩盖逻辑缺口;五行伪代码能让判断条件一目了然,也能让读者发现你遗漏的情况。伪代码应写出判断逻辑,而不是实现细节——写条件及其顺序,而非真实函数签名。判断是否需要伪代码的标准:如果你的散文中出现了“仅当”“之前”“除非”或“一旦”,读者却仍说不清第二次调用时会发生什么。
  • 测试标准:不看差异、规范或记录,文本也能独立成立。如果读者还得问“这部分是什么意思”,就不合格。

工作流

  1. 阅读完整的引用材料;如果单靠规范无法确定行为,就检查当前负责人。当没有指定材料时,解释会话中当前的变更(工作树或分支差异)。区分当前已存在的内容与仅处于提议阶段的内容。
  2. 结合用户或运维层面的后果解释问题,包括当前设计为何会导致该问题。
  3. 将解决方案描述为一个简单的变更前后数据流。按职责介绍每个组件,而不是按文件名或内部符号介绍。
  4. 全面列出架构和持久化契约的变更:新增、修改、删除、重置,以及明确保持不变的内容。如果游标或线格式切换会影响已存储的数据或读取方,也要说明。没有架构变更时,明确说明。

输出

按以下顺序使用这些标题:

  1. 问题
  2. 解决方案
  3. 架构变更

最后用一个简短句子说明用户会注意到什么变化。

规则

  • 先说明行为和边界;只有在实现名称能帮助厘清职责或契约时才提及。
  • 区分规范记录与派生索引、缓存、摘要及展示分组。
  • 明确指出破坏性重置、迁移要求、兼容性行为、最终一致性和有意的数据丢失。
  • 不要因为架构变更属于运维层面或对用户不可见,就将其省略。

评论

支持 Markdown