liuzhengdong
5e965d27a4
- Updated easysdd-feature documentation to enhance descriptions, clarify workflow stages, and improve directory organization. - Added new guidelines for routing user actions within the easysdd-feature skill. - Revised writing-to-explain skill to emphasize teaching over commanding, improving guidance for AI-generated content. - Introduced a new document, what-is-skills.md, to explain the purpose and structure of skills in the Claude Code environment.
10 KiB
name, description
| name | description |
|---|---|
| easysdd-feature-design | feature 流程的阶段 1——为新功能起草一份方案文件，作为后续实现和验收的唯一输入。先收集证据（读架构、读相关代码、grep 防术语撞车、查归档），然后一次性写出完整初稿（含 YAML frontmatter + 三层结构 + 测试设计），交给用户整体 review，迭代到拍板。拍板后从 design.md 里抽出 checklist.yaml 给后面两个阶段用。触发场景："开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已经知道做什么、为谁做、怎么算成功。 |
easysdd-feature-design
这一阶段的产出是一份方案文件 design.md，加上从中抽出的行动清单 checklist.yaml。这两份东西后面会被两个阶段消费——implement 照着推进、acceptance 照着核对，所以这里写错或写漏，下游就跟着错。
共享的路径和命名约定看根技能
easysdd第二节。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。
理解这个角色之后，下面有三件事要先搞清楚——为什么这么写、按什么顺序做、退出的标准是什么。
方案文件是给人扫的，不是给人读的
整个 design 的写作风格都围绕这个原则。读者打开 design.md 是想 5 分钟内抓到要点，需要细节时知道去哪查——不是要逐字精读。这条原则推出几条具体做法：
- 每节超过 1 屏就该砍或拆。一屏装不下意味着读者会失去定位感。
- 术语先锁死。所有新增术语在动笔前做一遍 grep，覆盖代码、架构中心目录、所有 feature 的方案文件。术语撞车的代价是后面别人查代码找错地方——预防的成本远低于事后理顺的成本。
- 示例优先于定义。接口行为先用具体示例（API 用输入→输出，组件用 Props→渲染 / Events 示例），复杂时再补正式类型。读者看到具体输入输出比看一段抽象描述更快建立模型。
- 推进按"功能可见度"走，不按代码文件顺序。先做最小闭环（一条端到端能跑通的路径），再叠细节。这样每一步都能独立验证，途中发现走偏也只损失一步。
- 新逻辑默认放新文件。新增的内聚逻辑单元默认建独立文件，而不是往已有文件追加。改动计划里每条都标"新建文件"或"追加到已有文件（理由）"。原因是文件越大越难分清职责，往老文件加东西会让后人查 git blame 时把不相关的改动也读一遍。
- 同一条信息只在最自然的位置出现一次。重复表述会让读者反复确认"这两条是不是同一件事"，比缺一条还烦。
- 流程归流程，模板归模板。先按下文流程走完再按模板填内容，不要边写边切流程。
流程：什么时候做什么
1. 启动检查
进入这一阶段先过这几条，没过别动笔：
-
需求输入是否清晰——确认至少有用户目标、核心行为、成功标准、明确不做这四项。缺了就先补；用户自己也说不清就回退到 brainstorm。
-
是否已有同名方案文件——存在的话先确认是接着改还是新建。
-
读前置资料——动笔前必读
AGENTS.md、项目架构总入口、架构索引、与需求相关的现有代码和子系统架构 doc。读这一步是为了让你写的方案和现有代码能接得上，不读直接动手大概率写出脱离实际的方案。 -
归档检索——值不值得搜、优先搜哪些目录，规则在根技能
easysdd第五节约束 7。本阶段至少考虑这几个目录：- 技巧库：
python easysdd/tools/search-yaml.py --dir easysdd/tricks --filter status=active --query "{关键词}" - 探索归档：
python easysdd/tools/search-yaml.py --dir easysdd/explores --query "{关键词}" - 知识沉淀：
python easysdd/tools/search-yaml.py --dir easysdd/learnings --query "{关键词}" - 决策归档：
python easysdd/tools/search-yaml.py --dir easysdd/decisions --filter status=active --query "{关键词}" - 已有 feature 方案：
python easysdd/tools/search-yaml.py --dir easysdd/features --filter doc_type=feature-design --query "{关键词}"
命中后优先复用，并在方案文件里记下引用来源——这样后人看到这份方案能顺着引用一路追回去。
- 技巧库：
-
断点恢复——
design.md已经存在且有部分内容时：status=draft且各节基本完整 → 上次写完了还没 review，跳到整体 review 步骤- 部分节缺失 → 汇报"上次方案写到第 X 节，我补齐剩下的再统一给你 review"，只补缺失的，不重写已完成的
2. 着陆区评估
启动检查里读过目标代码后，动笔前再做一次快速判断：新功能要落地的文件 / 模块能不能干净地接住这次改动？
看几个维度：目标文件行数、职责数量、与新功能的耦合方式。涉及前端时还要看组件树层级是不是过深、状态归属是不是清晰（本地 state / props 传递 / 全局 store）。
按严重程度分流：
| 情况 | 处理 |
|---|---|
| 健康，直接加 | 正常推进，不用额外动作 |
| 需要微重构（extract file / extract function） | 纳入第 3 节推进顺序的第 1 步，scope 锁死为"只搬不改行为"，退出信号是"搬完后既有功能不变" |
| 需要架构级变更（职责重划分、模块拆合、接口重新设计） | 在第 1 节记为前置依赖，建议拆成独立 feature 先解决；当前 feature 暂缓或标"等前置完成后再推进" |
为什么要做这一步？硬塞功能进一个本来就长得不健康的文件，得到的是一个更长更不健康的文件，下一次改动就更难。提前把"该不该先重构"放到台面上，让用户做决定，而不是 AI 偷偷在 PR 里夹带。
评估结论写进方案文件第 3 节"改动计划"开头（具体格式见同目录 reference.md）。"健康，直接加"的情况不用写——只在有动作时才记。
3. 一次性起草
按下文三层模板一次写出完整初稿，不要分批让用户先看半成品。初稿的 YAML frontmatter 里 status 写 draft。
为什么不分批？分批 review 的问题是用户每次只看到局部，发现不了"第 1 节的范围跟第 3 节的推进步骤对不上"这种跨节问题。只有完整初稿摆出来，用户才能扫到全局一致性。
4. 整体 review
向用户发一次整体 review 提示。用户对任意部分提修改意见，你按意见改完再次确认，反复直到用户明确"方案可以了"。用户放行后把 frontmatter 的 status 从 draft 改成 approved。
5. 生成 checklist.yaml
方案确认后，从 design.md 里抽出行动清单，落到同目录 checklist.yaml。这份清单的生命周期看 easysdd/reference/shared-conventions.md：本阶段负责生成，implement 只推进 steps，acceptance 只核对 checks。三个阶段各管一段，互不越界——这样每个阶段都能从 yaml 上看出自己的工作进度。
design.md 和 checklist.yaml 的完整模板、frontmatter 示例、节锚点、提取格式都在同目录 reference.md 里。本技能只保留提取原则：
steps：从第 3 节"推进顺序"逐步抽，一步一条checks：从这几处综合抽——- 第 1 节"明确不做"的每条 → 范围守护检查项
- 第 2 节关键接口契约 → 接口一致性检查项
- 第 3 节测试设计的每条测试约束 → 测试验证检查项
落盘后用 validate-yaml.py --file {checklist.yaml 路径} --yaml-only 校验语法。
6. 退出
按下文退出条件清单核对完，引导用户进入阶段 2 实现。
模板和格式
design.md / checklist.yaml 的完整参考拆到了同目录 reference.md：
- YAML frontmatter 示例
- 顶层节锚点要求
checklist.yaml完整格式与状态语义- 第 0-4 节各自该写什么
本技能只保留流程层面的约束：按那份参考一次性起草完整初稿，不分批吐半成品。
整体 review 的提示词同样在 reference.md。规则不变：只发一次整体 review，不要逐节拆开确认。
退出条件
用户整体 review 通过，并且下面这些都满足：
- 做过术语 grep 防撞车并记录结果
- YAML frontmatter 存在，
doc_type/feature/status/summary/tags都填了 - 需求摘要含"不做什么"，且后文没有偷偷扩范围
- 记录了关键决策和被拒方案
- 每个关键接口有具体示例（API：输入→输出；组件：Props→渲染 / Events），覆盖正常路径和主要错误路径
- 示例通过注释标了来源位置（文件路径 + 函数 / 组件名）
- 推进步骤 4-8 步，每步可独立验证
- 测试设计按功能点组织，每个功能点都有测试约束 / 验证方式 / 关键用例骨架
- 记录了高风险实现约束
- 用户确认通过后，frontmatter 的
status改成了approved checklist.yaml已从 design.md 抽出生成，且通过validate-yaml.py校验checklist.yaml的 steps 条目数和第 3 节推进顺序一致
文件路径：方案文件在 easysdd/features/{feature}/ 下；feature 目录不存在就在这一步建。命名约定看根技能 easysdd 第二节。
容易踩的坑
下面这些是过去反复出现的反模式，遇到就停一下问自己是不是又掉进去了：
- 没读
AGENTS.md和相关架构文档就动笔——写出来的方案大概率跟现有代码对不上 - 术语没做防撞车检查——撞了之后 git blame 找原因要花十倍时间
- 用散文描述接口行为，没给具体示例——读者建不起模型，review 时没法判断
- 把契约层写成全字段百科——已经存在且不变的接口别重复抄
- 强行画图——模块就 ≤ 2 个、调用又是线性的，画图反而模糊重点
- 推进步骤拆得太细（>8 步）——细到每步都没什么独立价值
- 只给半份文档让用户先 review——用户看不出全局一致性
- 在需求摘要或改动计划里偷偷扩范围——后面验收时对不上