mirror of
https://github.com/codestable/CodeStable.git
synced 2026-09-19 09:03:09 +08:00
refactor: add narrative-style.md and talk.md for improved documentation on skill packages and development scenarios
This commit is contained in:
@@ -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 读完这段后下一步要做什么决定,照着这个写就行。
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user