refactor: add narrative-style.md and talk.md for improved documentation on skill packages and development scenarios

This commit is contained in:
liuzhengdong
2026-04-15 13:06:56 +08:00
parent 52e4d1b123
commit 6a5abcb3a4
2 changed files with 56 additions and 0 deletions
+30
View File
@@ -0,0 +1,30 @@
# 顶层介绍文档怎么写
写 SKILL.md 开头、README 开头、一个系统的总入口介绍这种东西的时候,顺序很重要:
1. 先讲场景
2. 再讲针对场景做了什么
3. 最后一句话带过每个组成部分管什么
到这里就够了。
举个例子,介绍 easysdd 的时候不要上来就"easysdd 是 Easy Spec-Driven Development,本项目的规约驱动开发工作流,核心原则有五条……"。这种写法读完不知道这玩意儿解决什么问题,也不知道自己该不该用。
换成这样:
> 开发里经常碰到两种场景,一个是日常加功能,一个是修 BUG。另外还有个老问题,是 AI 老忘事。
>
> 针对这两种场景和一个问题,做了三套技能包:
> - feature——走顺日常开发
> - issue——走顺修 BUG
> - compound——用来在前两者里攒经验
读者立刻知道为什么有这东西、由什么组成、各管什么。
AI 默认写不出第二种,是因为它脑子里的模板是"技术规范文档"——要完备、要列规则、要有 checklist、结尾要有总结。
但顶层介绍的职责不是完备,是让人 30 秒内抓住主线,决定要不要继续读、去哪里读。规则、例外、模板这些都该下沉到子文档。
写之前先在脑子里放一个具体的人,想 TA 读完这段后下一步要做什么决定,照着这个写就行。
+26
View File
@@ -0,0 +1,26 @@
在开发中经常遇到的两种场景,
1.日常特性开发场景
2.问题解决场景
还有一种常见的问题,就是AI频繁遗忘的问题。
针对这2种场景和一个问题,EasySDD 针对性地开发了三套技能包。
1. feature 技能包 - 用于走顺日常开发场景
2. issue 技能包 - 用于走顺出现BUG的场景
3. compound 技能包 - 用于在前两种场景中积累知识,从而越走越顺。
### feature 技能包
应对日常开发场景,其实与superpowers、gsd等框架并无太大的区别,也是brainstorm -> design -> implement -> acceptance这样的流程。
### issue 技能包
### compound 技能包
此技能包并非独立的流程,而是贯通在前两种场景中的技能,分别为tricks/decisions/compound...
### 辅助技能包
libdoc/guidedoc/onboarding