mirror of
https://github.com/codestable/CodeStable.git
synced 2026-09-19 09:03:09 +08:00
Refactor project structure and naming conventions from easysdd to codestable
- Updated SKILL.md files to reflect new naming conventions and project structure. - Changed references from easysdd to codestable in various documentation files. - Adjusted paths for requirements, roadmap, and tricks to align with the new structure. - Ensured consistency across all related documents and references.
This commit is contained in:
liuzhengdong
@@ -1,2 +1,2 @@
|
||||
1. 不同的技能之间不要相互耦合，即 A 技能在非必须情况下不要看 B 技能。
|
||||
2. skill 是独立安装单元，运行时每个 skill 只能看到自己包内的文件。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**——skill 之间没有共享的文件系统父目录。跨 skill 共享的参考文档必须走"工作项目"这一层：由 `easysdd-onboarding` 从技能包复制到项目的 `easysdd/reference/`，其他 skill 用项目相对路径 `easysdd/reference/xxx.md` 读取。要改共享口径时改 `easysdd-onboarding/reference/` 下的模板，新项目 onboarding 时带上新版本。
|
||||
2. skill 是独立安装单元，运行时每个 skill 只能看到自己包内的文件。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**——skill 之间没有共享的文件系统父目录。跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `codestable/reference/`，其他 skill 用项目相对路径 `codestable/reference/xxx.md` 读取。要改共享口径时改 `cs-onboard/reference/` 下的模板，新项目 onboarding 时带上新版本。
|
||||
@@ -1,4 +1,4 @@
|
||||
# EasySDD
|
||||
# CodeStable
|
||||
|
||||
> 厌倦了 OpenSpec 太简单、Oh-My-OpenAgent 太复杂、SuperPowers 缺约束，我从 0 写了一套简单轻巧、但**自洽闭环**的 AI 工作流。
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
我一直在自己开发一套 Harness Agent（[源码](https://github.com/liuzhengdongfortest/MA)）。一开始就是 VibeCoding，我写设计、AI 写代码改 bug，挺顺利的。直到有一天 Codex 反复解决不了一个并不复杂的问题，反复在同一个地方失败，我意识到项目得有一套工作流来约束，才能继续推进。
|
||||
|
||||
调研了一圈：OpenSpec 太简单，没有复利工程，生成的 spec 抽象到人根本没法读；SuperPowers 没有流程约束，不知道该用哪个；Oh-My-OpenAgent 又太重。没一个用着顺手的，所以自己写了 EasySDD。
|
||||
调研了一圈：OpenSpec 太简单，没有复利工程，生成的 spec 抽象到人根本没法读；SuperPowers 没有流程约束，不知道该用哪个；Oh-My-OpenAgent 又太重。没一个用着顺手的，所以自己写了 CodeStable。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,7 +23,7 @@ AI 辅助开发里有几类场景反复出现——加新功能、修 bug、沉
|
||||
- 上次遇到过的问题下次又遇到一遍
|
||||
- AI 一次输出几百行代码才让人 review，等发现方向不对已经很难中止
|
||||
|
||||
EasySDD 把这几类场景各配一套子技能，产物放进统一的目录结构、带统一的 YAML frontmatter，互相之间可以检索引用。
|
||||
CodeStable 把这几类场景各配一套子技能，产物放进统一的目录结构、带统一的 YAML frontmatter，互相之间可以检索引用。
|
||||
|
||||
---
|
||||
|
||||
@@ -31,61 +31,61 @@ EasySDD 把这几类场景各配一套子技能，产物放进统一的目录结
|
||||
|
||||
### 讨论层：想法还模糊时的统一入口
|
||||
|
||||
- **`easysdd-brainstorm`** — 用一两轮对话做分诊：case 1（已经够清楚，直接 feature-design）、case 2（小需求方向定了，在 feature 里继续讨论并落 `{slug}-brainstorm.md`）、case 3（大需求装不进一个 feature，移交给 roadmap）。brainstorm 自己不产出 design 也不做拆解——它只决定这次讨论该去哪个下游
|
||||
- **`cs-brainstorm`** — 用一两轮对话做分诊：case 1（已经够清楚，直接 feature-design）、case 2（小需求方向定了，在 feature 里继续讨论并落 `{slug}-brainstorm.md`）、case 3（大需求装不进一个 feature，移交给 roadmap）。brainstorm 自己不产出 design 也不做拆解——它只决定这次讨论该去哪个下游
|
||||
|
||||
### 做事：从想法到上线，从报告到修好
|
||||
|
||||
- **`easysdd-feature`** — 新功能，`(brainstorm 可选) → design → implement → acceptance`
|
||||
- **`easysdd-issue`** — 修 bug，`report → analyze → fix`
|
||||
- **`cs-feat`** — 新功能，`(brainstorm 可选) → design → implement → acceptance`
|
||||
- **`cs-issue`** — 修 bug，`report → analyze → fix`
|
||||
|
||||
两类都不直接让 AI 写代码，而是先产出 spec（功能方案 / 问题分析），用户 review 后再动手，代码和 doc 一起交付。针对的是 AI 默认会出的三类问题：术语冲突、范围失控、改完不留存档。
|
||||
|
||||
阶段之间有人工 checkpoint，上一阶段的退出条件没满足就不开始下一阶段。两种例外：issue 根因一眼确定时跳过 analyze 直接 fix；feature 范围很小时走 `easysdd-feature-fastforward`，写完 spec 直接进实现。
|
||||
阶段之间有人工 checkpoint，上一阶段的退出条件没满足就不开始下一阶段。两种例外：issue 根因一眼确定时跳过 analyze 直接 fix；feature 范围很小时走 `cs-feat-ff`，写完 spec 直接进实现。
|
||||
|
||||
### 沉淀：这次的产出变成下次的输入
|
||||
|
||||
这是 EasySDD 最核心的一部分。四个子技能共用 `easysdd/compound/` 目录，按记录内容的性质分：
|
||||
这是 CodeStable 最核心的一部分。四个子技能共用 `codestable/compound/` 目录，按记录内容的性质分：
|
||||
|
||||
- **`easysdd-learning`** — 回顾"做 X 时踩了 Y 这个坑"
|
||||
- **`easysdd-tricks`** — 处方"以后做 X 就这样做"
|
||||
- **`easysdd-decisions`** — 规定"全项目今后都按 X 来"
|
||||
- **`easysdd-explore`** — 存档"调查了 X 问题，看到代码里是这样的"
|
||||
- **`cs-learn`** — 回顾"做 X 时踩了 Y 这个坑"
|
||||
- **`cs-trick`** — 处方"以后做 X 就这样做"
|
||||
- **`cs-decide`** — 规定"全项目今后都按 X 来"
|
||||
- **`cs-explore`** — 存档"调查了 X 问题，看到代码里是这样的"
|
||||
|
||||
**归档之后怎么召回？** EasySDD 只在需要的时候召回。`easysdd-feature-design` 起草设计前会显式去搜 compound 目录，`easysdd-issue-analyze` 分析 bug 时也会显式去查找。feature 和 issue 过程中积累的知识就这样反哺到下一次设计里，越往后越顺。
|
||||
**归档之后怎么召回？** CodeStable 只在需要的时候召回。`cs-feat-design` 起草设计前会显式去搜 compound 目录，`cs-issue-analyze` 分析 bug 时也会显式去查找。feature 和 issue 过程中积累的知识就这样反哺到下一次设计里，越往后越顺。
|
||||
|
||||
### 辅助：周边工具
|
||||
|
||||
- **`easysdd-onboarding`** — 把新仓库接入 easysdd 目录结构，空仓库和已有零散文档的仓库都能接
|
||||
- **`easysdd-requirements`** — 起草或刷新 `easysdd/requirements/` 下的需求文档（"为什么要有这个能力"，只记现状）
|
||||
- **`easysdd-architecture`** — 架构一站式：起草新架构文档 / 刷新已有文档 / 做架构体检（design 自洽 / design↔代码一致 / architecture 目录多份文档间一致），只记现状
|
||||
- **`easysdd-roadmap`** — 把装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单，作为后续多次 feature 流程的种子和排期依据；独立于需求 / 架构档案
|
||||
- **`easysdd-guidedoc`** — 写给外部读者的开发者指南 / 用户指南
|
||||
- **`easysdd-libdoc`** — 为库的公开 API 逐条目生成参考文档
|
||||
- **`cs-onboard`** — 把新仓库接入 CodeStable 目录结构，空仓库和已有零散文档的仓库都能接
|
||||
- **`cs-req`** — 起草或刷新 `codestable/requirements/` 下的需求文档（"为什么要有这个能力"，只记现状）
|
||||
- **`cs-arch`** — 架构一站式：起草新架构文档 / 刷新已有文档 / 做架构体检（design 自洽 / design↔代码一致 / architecture 目录多份文档间一致），只记现状
|
||||
- **`cs-roadmap`** — 把装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单，作为后续多次 feature 流程的种子和排期依据；独立于需求 / 架构档案
|
||||
- **`cs-guide`** — 写给外部读者的开发者指南 / 用户指南
|
||||
- **`cs-libdoc`** — 为库的公开 API 逐条目生成参考文档
|
||||
|
||||
---
|
||||
|
||||
## 场景路由
|
||||
|
||||
仓库里还没有 `easysdd/` 目录，先用 `easysdd-onboarding` 初始化目录结构。之后按场景选子技能。
|
||||
仓库里还没有 `codestable/` 目录，先用 `cs-onboard` 初始化目录结构。之后按场景选子技能。
|
||||
|
||||
| 场景 | 子技能 |
|
||||
|---|---|
|
||||
| 想法还模糊 / "有个想法没想清楚" / "先聊聊" | `easysdd-brainstorm` |
|
||||
| 新功能 / 新能力 | `easysdd-feature` |
|
||||
| BUG / 异常 / 文档错误 | `easysdd-issue` |
|
||||
| 读代码、提问调研 | `easysdd-explore` |
|
||||
| 补 / 更新需求文档 | `easysdd-requirements` |
|
||||
| 补 / 更新 / 检查架构文档 | `easysdd-architecture` |
|
||||
| 大需求拆解 / 排期规划 | `easysdd-roadmap` |
|
||||
| 技术选型 / 约束 / 规约 | `easysdd-decisions` |
|
||||
| 踩坑回顾、经验总结 | `easysdd-learning` |
|
||||
| 可复用的编程模式、库用法 | `easysdd-tricks` |
|
||||
| 开发者指南 / 用户指南 | `easysdd-guidedoc` |
|
||||
| 库 API 参考 | `easysdd-libdoc` |
|
||||
| 想法还模糊 / "有个想法没想清楚" / "先聊聊" | `cs-brainstorm` |
|
||||
| 新功能 / 新能力 | `cs-feat` |
|
||||
| BUG / 异常 / 文档错误 | `cs-issue` |
|
||||
| 读代码、提问调研 | `cs-explore` |
|
||||
| 补 / 更新需求文档 | `cs-req` |
|
||||
| 补 / 更新 / 检查架构文档 | `cs-arch` |
|
||||
| 大需求拆解 / 排期规划 | `cs-roadmap` |
|
||||
| 技术选型 / 约束 / 规约 | `cs-decide` |
|
||||
| 踩坑回顾、经验总结 | `cs-learn` |
|
||||
| 可复用的编程模式、库用法 | `cs-trick` |
|
||||
| 开发者指南 / 用户指南 | `cs-guide` |
|
||||
| 库 API 参考 | `cs-libdoc` |
|
||||
|
||||
---
|
||||
|
||||
## EasySDD 跟其他框架不一样在哪
|
||||
## CodeStable 跟其他框架不一样在哪
|
||||
|
||||
### 四层分离：需求 / 架构 / 规划 / 特性
|
||||
|
||||
@@ -93,7 +93,7 @@ EasySDD 把这几类场景各配一套子技能，产物放进统一的目录结
|
||||
|
||||
### 架构文档永远跟得上代码
|
||||
|
||||
每做完一个 feature，acceptance 阶段会自动把这次的变更合进 `easysdd/architecture/` 下对应的架构文档。下次再有人（或 AI）想理解系统现在的样子，有一份跟代码保持同步的入口。`easysdd-architecture` 还能反过来做一致性检查，把 design 和代码对不齐的地方列出来。
|
||||
每做完一个 feature，acceptance 阶段会自动把这次的变更合进 `codestable/architecture/` 下对应的架构文档。下次再有人（或 AI）想理解系统现在的样子，有一份跟代码保持同步的入口。`cs-arch` 还能反过来做一致性检查，把 design 和代码对不齐的地方列出来。
|
||||
|
||||
### 术语归一
|
||||
|
||||
@@ -105,7 +105,7 @@ design 完成以后，模型会生成一份 yaml 格式的 checklist，而不是
|
||||
|
||||
### 共享口径集中管
|
||||
|
||||
目录结构、frontmatter 字段、checklist 生命周期、commit 约定这些跨技能共用的东西，统一放在项目的 `easysdd/reference/` 下，由 onboarding 一次性复制过来。要改口径改模板，新项目 onboarding 自动带上新版本。
|
||||
目录结构、frontmatter 字段、checklist 生命周期、commit 约定这些跨技能共用的东西，统一放在项目的 `codestable/reference/` 下，由 onboarding 一次性复制过来。要改口径改模板，新项目 onboarding 自动带上新版本。
|
||||
|
||||
---
|
||||
|
||||
@@ -135,18 +135,18 @@ design 完成以后，模型会生成一份 yaml 格式的 checklist，而不是
|
||||
## 怎么用
|
||||
|
||||
```bash
|
||||
npx skills add https://github.com/liuzhengdongfortest/easysdd
|
||||
npx skills add https://github.com/liuzhengdongfortest/CodeStable
|
||||
```
|
||||
|
||||
进项目后对 Claude 说：
|
||||
|
||||
> 「在这个项目里初始化 easysdd」
|
||||
> 「在这个项目里初始化 CodeStable」
|
||||
|
||||
然后开始第一件事：
|
||||
|
||||
> 「我要做 X 功能，走 easysdd-feature 流程」
|
||||
> 「我要做 X 功能，走 cs-feat 流程」
|
||||
>
|
||||
> 「这里有个 bug，走 easysdd-issue 流程」
|
||||
> 「这里有个 bug，走 cs-issue 流程」
|
||||
|
||||
不知道用哪个子技能也没关系，把场景描述清楚，Claude 会按上面的路由表自己选。
|
||||
|
||||
@@ -154,9 +154,9 @@ npx skills add https://github.com/liuzhengdongfortest/easysdd
|
||||
|
||||
## 最后
|
||||
|
||||
也不要全依赖 EasySDD。框架虽好不能解决所有情况。我自己只在特性复杂度足够高的时候才走完整流程——你既然约束了 AI 按流程办事，token 是会多消耗一些的。一般的小 UI 调整我直接截图 vibe 就行。一个完整 feature 走完，Claude Code 的 Opus 大概要 200k 左右的上下文。
|
||||
也不要全依赖 CodeStable。框架虽好不能解决所有情况。我自己只在特性复杂度足够高的时候才走完整流程——你既然约束了 AI 按流程办事，token 是会多消耗一些的。一般的小 UI 调整我直接截图 vibe 就行。一个完整 feature 走完，Claude Code 的 Opus 大概要 200k 左右的上下文。
|
||||
|
||||
GitHub：<https://github.com/liuzhengdongfortest/EasySDD>
|
||||
GitHub：<https://github.com/liuzhengdongfortest/CodeStable>
|
||||
|
||||
---
|
||||
|
||||
|
||||
+21
-21
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: easysdd-architecture
|
||||
description: 项目架构中心的一站式技能——起草新架构文档、刷新已有架构文档、或做一次架构体检。根据用户说的话自动判断模式：`new`（起草）/ `update`（按代码最新状态刷新）/ `check`（只看不改，出问题清单）。check 再分三个子目标：一份 feature design 自洽、design 和代码对得上、`easysdd/architecture/` 下多份文档之间对得上。单目标规则——一次只动一份文档或只查一个目标。触发场景：用户说"补一份架构 doc"、"起草架构文档"、"刷新 architecture 目录"、"把这个模块结构写下来"、"做架构检查"、"design 内部一致吗"、"方案和代码对得上吗"、"architecture 文件夹里几份文档有没有打架"，或 feature-design / feature-acceptance / implement 阶段发现需要先做一次架构动作再继续。
|
||||
name: cs-arch
|
||||
description: 项目架构中心的一站式技能——起草新架构文档、刷新已有架构文档、或做一次架构体检。根据用户说的话自动判断模式：`new`（起草）/ `update`（按代码最新状态刷新）/ `check`（只看不改，出问题清单）。check 再分三个子目标：一份 feature design 自洽、design 和代码对得上、`codestable/architecture/` 下多份文档之间对得上。单目标规则——一次只动一份文档或只查一个目标。触发场景：用户说"补一份架构 doc"、"起草架构文档"、"刷新 architecture 目录"、"把这个模块结构写下来"、"做架构检查"、"design 内部一致吗"、"方案和代码对得上吗"、"architecture 文件夹里几份文档有没有打架"，或 feature-design / feature-acceptance / implement 阶段发现需要先做一次架构动作再继续。
|
||||
---
|
||||
|
||||
# easysdd-architecture
|
||||
# cs-arch
|
||||
|
||||
`easysdd/architecture/` 是项目的"地图"——feature-design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。这份地图不会自己长出来，也不会自己保持准确——有人在合适的时候起草、刷新、体检。本技能就是这三件事的统一入口。
|
||||
`codestable/architecture/` 是项目的"地图"——feature-design 写方案前读它定位、issue-analyze 做根因时读它理解模块边界、新人读它知道系统大致长什么样。这份地图不会自己长出来，也不会自己保持准确——有人在合适的时候起草、刷新、体检。本技能就是这三件事的统一入口。
|
||||
|
||||
**architecture 是累积的、自给自足的系统地图**。它不是某一次 feature 的详细方案，而是所有已落地 feature 沉淀下来的"系统现在长什么样"的总图。读者打开它应该能看懂系统整体结构，而不需要频繁跳回某份历史 design 才能补齐理解。design 是临时的增量详细稿，架构里稳定下来的名词 / 编排 / 约束由 acceptance 阶段提炼回这里；design 文件本身归档，只在追究具体决策细节时才翻。
|
||||
|
||||
**architecture 只记现状，不记计划**。默认只在 feature-acceptance 阶段跟着代码同步更新，必要时才由本技能主动 new / update。**不写"未来会加什么层"、"下一步打算拆出 X 模块"**——那些属于 `easysdd-roadmap` 的规划层。用户抛出"我想重构成 X 架构"这种目标态描述时，先走 roadmap 拆成若干 feature，每次 feature acceptance 把实际达到的阶段性结构提炼回 architecture。
|
||||
**architecture 只记现状，不记计划**。默认只在 feature-acceptance 阶段跟着代码同步更新，必要时才由本技能主动 new / update。**不写"未来会加什么层"、"下一步打算拆出 X 模块"**——那些属于 `cs-roadmap` 的规划层。用户抛出"我想重构成 X 架构"这种目标态描述时，先走 roadmap 拆成若干 feature，每次 feature acceptance 把实际达到的阶段性结构提炼回 architecture。
|
||||
|
||||
这意味着 architecture 的详略判据是"够不够让读者不跳转就读懂系统"——不是"写得越少越好"，也不是"把 design 里所有细节都搬过来"。系统里稳定、跨 feature 可见的那一层要写全；某个模块内部的循环、辅助函数、一次性实现决定不进来。
|
||||
|
||||
@@ -22,7 +22,7 @@ description: 项目架构中心的一站式技能——起草新架构文档、
|
||||
|
||||
下面整套规则就是为了不让这几种情况发生。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。
|
||||
> 文档结构模板、check 覆盖项清单、报告格式看同目录 `reference.md`。
|
||||
|
||||
---
|
||||
@@ -45,12 +45,12 @@ description: 项目架构中心的一站式技能——起草新架构文档、
|
||||
|
||||
每次只跑一个模式，且该模式内只锁定一个目标：
|
||||
|
||||
- `new`：起草一份新架构文档（`easysdd/architecture/{type}-{slug}.md`，或更新 `DESIGN.md` 本身）
|
||||
- `new`：起草一份新架构文档（`codestable/architecture/{type}-{slug}.md`，或更新 `DESIGN.md` 本身）
|
||||
- `update`：按代码最新状态 + 用户新素材刷新一份已有架构文档
|
||||
- `check`：三个子目标之一
|
||||
- `design-internal` — 一份 feature design 文档内部一致性
|
||||
- `design-vs-code` — 一份 feature design 与代码的一致性
|
||||
- `architecture-folder-internal` — `easysdd/architecture/` 下多份架构文档之间的一致性
|
||||
- `architecture-folder-internal` — `codestable/architecture/` 下多份架构文档之间的一致性
|
||||
|
||||
为什么不允许一次做多件？起草时一次吐多份 AI 稿用户 review 不过来；检查时三个子目标的视角和读取材料完全不同，同时做会导致每边都不深、问题混在一起说不清责任。用户提多个目标就让 TA 选一个，其余留到下次。
|
||||
|
||||
@@ -86,9 +86,9 @@ Phase 6：落盘（new/update）或 等用户拍板下一步（check）
|
||||
|
||||
共同必读：
|
||||
|
||||
- `easysdd/reference/shared-conventions.md`
|
||||
- `easysdd/architecture/DESIGN.md`（总入口）
|
||||
- `easysdd/architecture/` 下的其他架构文档（判断要不要互相引用、有没有重复）
|
||||
- `codestable/reference/shared-conventions.md`
|
||||
- `codestable/architecture/DESIGN.md`（总入口）
|
||||
- `codestable/architecture/` 下的其他架构文档（判断要不要互相引用、有没有重复）
|
||||
|
||||
**new / update 额外必读**（见 `reference.md` 的"读取清单"）：
|
||||
|
||||
@@ -102,7 +102,7 @@ Phase 6：落盘（new/update）或 等用户拍板下一步（check）
|
||||
|
||||
- `design-internal` / `design-vs-code`：方案 doc 全文 + 架构中心目录相关文档
|
||||
- `design-vs-code` 再额外：与 design 第 2/3 节直接对应的代码文件
|
||||
- `architecture-folder-internal`：用户圈定的那几份 `easysdd/architecture/**/*.md`（或某个 type 下的全部同类文档） + 索引 + 顺藤摸到的被引用文档（不扩展到代码）
|
||||
- `architecture-folder-internal`：用户圈定的那几份 `codestable/architecture/**/*.md`（或某个 type 下的全部同类文档） + 索引 + 顺藤摸到的被引用文档（不扩展到代码）
|
||||
|
||||
### Phase 3：执行
|
||||
|
||||
@@ -126,9 +126,9 @@ Phase 6：落盘（new/update）或 等用户拍板下一步（check）
|
||||
|
||||
**new 模式**：
|
||||
|
||||
- 写入 `easysdd/architecture/{type}-{slug}.md`（命名规则见 `easysdd/reference/shared-conventions.md` 第 0 节），frontmatter `status: current`、`last_reviewed` 填当天
|
||||
- 写入 `codestable/architecture/{type}-{slug}.md`（命名规则见 `codestable/reference/shared-conventions.md` 第 0 节），frontmatter `status: current`、`last_reviewed` 填当天
|
||||
- **同类聚合检查**（落盘前必跑）：按 shared-conventions 的"架构 doc 的分组规则"判断本次落盘后某个 type 在 `architecture/` 根目录是否达到 ≥6 份——命中阈值就把这类全部搬进 `architecture/{type}/` 子目录、去掉文件名前缀、同步改 `DESIGN.md` 所有相关链接；搬迁清单必须在 Phase 5 一并给用户 review
|
||||
- **索引更新**：打开 `easysdd/architecture/DESIGN.md` 加对新文档的引用链接——new 模式下**必定**要加，不加等于写了没人会读；DESIGN.md 改动同样给用户 review，不要偷偷改
|
||||
- **索引更新**：打开 `codestable/architecture/DESIGN.md` 加对新文档的引用链接——new 模式下**必定**要加，不加等于写了没人会读；DESIGN.md 改动同样给用户 review，不要偷偷改
|
||||
|
||||
**update 模式**：
|
||||
|
||||
@@ -183,13 +183,13 @@ Phase 6：落盘（new/update）或 等用户拍板下一步（check）
|
||||
|
||||
| 方向 | 关系 |
|
||||
|---|---|
|
||||
| `easysdd-requirements` 配合 | requirement 描述"为什么要有这个能力"、本技能描述"用什么结构实现"；architecture doc 的 frontmatter `implements` 反向链到承载的 req slug |
|
||||
| `easysdd-feature-design` 上游 | design 写到"本 feature 和哪块架构对接"时读本技能产出的 doc；design 写完后可触发 check 模式做一次自洽体检 |
|
||||
| `easysdd-feature-acceptance` 下游 | 验收阶段实际去更新本技能产出的 doc（acceptance 自己做归并，不回调本技能 new/update）；想确认实现和 design 对得上时触发 check 模式 `design-vs-code` |
|
||||
| `easysdd-decisions` 配合 | 拍板一条架构决策后，本技能 `update` 可把引用补进相关架构 doc 的第 4 节 |
|
||||
| `easysdd-issue-analyze` 读者 | 根因分析阶段读本技能产出的 doc 定位模块边界 |
|
||||
| `easysdd-onboarding` 创建者 | onboarding 阶段建 `DESIGN.md` 占位，之后由本技能填实 / 扩充 |
|
||||
| `easysdd-roadmap` 配合 | architecture 记"系统现在长什么样"，roadmap 记"接下来打算怎么把它推到下一步"。roadmap 起草时会读本技能产出的 doc 理解现状，但不改它；"目标态架构"属于规划，不进 architecture doc |
|
||||
| `cs-req` 配合 | requirement 描述"为什么要有这个能力"、本技能描述"用什么结构实现"；architecture doc 的 frontmatter `implements` 反向链到承载的 req slug |
|
||||
| `cs-feat-design` 上游 | design 写到"本 feature 和哪块架构对接"时读本技能产出的 doc；design 写完后可触发 check 模式做一次自洽体检 |
|
||||
| `cs-feat-accept` 下游 | 验收阶段实际去更新本技能产出的 doc（acceptance 自己做归并，不回调本技能 new/update）；想确认实现和 design 对得上时触发 check 模式 `design-vs-code` |
|
||||
| `cs-decide` 配合 | 拍板一条架构决策后，本技能 `update` 可把引用补进相关架构 doc 的第 4 节 |
|
||||
| `cs-issue-analyze` 读者 | 根因分析阶段读本技能产出的 doc 定位模块边界 |
|
||||
| `cs-onboard` 创建者 | onboarding 阶段建 `DESIGN.md` 占位，之后由本技能填实 / 扩充 |
|
||||
| `cs-roadmap` 配合 | architecture 记"系统现在长什么样"，roadmap 记"接下来打算怎么把它推到下一步"。roadmap 起草时会读本技能产出的 doc 理解现状，但不改它；"目标态架构"属于规划，不进 architecture doc |
|
||||
|
||||
---
|
||||
|
||||
|
||||
+12
-12
@@ -1,6 +1,6 @@
|
||||
# easysdd-architecture 参考模板
|
||||
# cs-arch 参考模板
|
||||
|
||||
本文件提供 `easysdd-architecture` 使用的详细模板和清单。SKILL.md 只保留流程骨架，具体格式、覆盖项、报告模板都在这里。
|
||||
本文件提供 `cs-arch` 使用的详细模板和清单。SKILL.md 只保留流程骨架，具体格式、覆盖项、报告模板都在这里。
|
||||
|
||||
---
|
||||
|
||||
@@ -18,7 +18,7 @@ status: current | draft | outdated
|
||||
last_reviewed: YYYY-MM-DD
|
||||
tags: []
|
||||
depends_on: [] # 其他 architecture doc 的 slug，可选
|
||||
implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requirements/` 下），可空——纯基础设施 / 工具层没有对应 requirement 是正常的
|
||||
implements: [] # 这块架构承载的 requirement slug 列表（`codestable/requirements/` 下），可空——纯基础设施 / 工具层没有对应 requirement 是正常的
|
||||
---
|
||||
```
|
||||
|
||||
@@ -55,7 +55,7 @@ implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requ
|
||||
不是决策全文，是**引用**——每条一两行：
|
||||
|
||||
- 结论一句话
|
||||
- 引用：`easysdd/compound/YYYY-MM-DD-decision-{slug}.md` 或用户原话出处
|
||||
- 引用：`codestable/compound/YYYY-MM-DD-decision-{slug}.md` 或用户原话出处
|
||||
- 为什么引用到这份架构 doc 里（和本模块的关系）
|
||||
|
||||
没有已落档的决策就省略本节，或记 `TODO: 某决定应沉淀为 decision`。
|
||||
@@ -92,7 +92,7 @@ implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requ
|
||||
1. **每个结构化断言能不能锚到代码？**——"A 模块通过 X 调用 B"、"Y 持有 Z 的状态"、"所有写入经 W"——每一条在文档的"代码锚点"节或节内注释里能不能给出 `file:line` 支撑？锚不到的断言要么删掉、要么标 `TODO: 待确认` 交给用户。
|
||||
2. **有没有替用户拍板？**——"关键决策"节里的条目是"引用已有 decision + 简述原文结论" / "引用用户素材里用户说过的原话"，还是 AI 自己编的选型理由？后者一律不许进文档——停下来问用户。
|
||||
3. **有没有变成代码复述？**——每节至少一句话说"为什么这么分"，没有这一句的节基本就是 `ls` 贴文字。
|
||||
4. **术语冲突检查做了吗？**——新引入的架构术语做一遍 grep（代码、`easysdd/architecture/` 下所有文档、`easysdd/compound/`）。冲突了就换名字或在第 0 节明确"本文里 X 指 Y，和代码里的 X' 不是一个东西"。
|
||||
4. **术语冲突检查做了吗？**——新引入的架构术语做一遍 grep（代码、`codestable/architecture/` 下所有文档、`codestable/compound/`）。冲突了就换名字或在第 0 节明确"本文里 X 指 Y，和代码里的 X' 不是一个东西"。
|
||||
5. **是否和现有 architecture / decision 冲突？**——写的过程中如果发现和某条 decision 或其他架构文档描述的事实对不上，不许"写自己的那版"，要么引用那条、要么停下来问用户"是不是那条也该更新了"。
|
||||
6. **单节长度**——每节超过 1 屏就该砍或拆。架构文档是给人快速定位的，不是用来读一遍的。
|
||||
7. **update 模式专项**：本次新加 / 改动的段落是否都有对应的代码变化作为依据？纯凭空"加一句听起来更完整的描述"是内容飘离实际的开端。
|
||||
@@ -121,14 +121,14 @@ implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requ
|
||||
5. **改动边界一致性**——design 第 3 节声明的改动范围，代码有没有越界或漏实现
|
||||
6. **推进结果一致性**——design 第 3 节每步的退出信号，对应代码状态可验证吗
|
||||
|
||||
### 3.3 architecture-folder-internal（`easysdd/architecture/` 下多份文档之间一致性）
|
||||
### 3.3 architecture-folder-internal（`codestable/architecture/` 下多份文档之间一致性）
|
||||
|
||||
1. **术语一致性**——多份文档对同一概念的称呼是否统一，有没有同义词漂移或同名异义
|
||||
2. **模块边界一致性**——A 文档说某职责归模块 X，B 文档里是不是也这么说；有没有两份文档都声称自己拥有同一块职责
|
||||
3. **跨文引用有效性**——文档里 `see xxx.md` / `定义见 yyy.md` 这类引用，目标文件和目标小节真的存在吗
|
||||
4. **接口 / 契约对齐**——多份文档涉及同一接口 / 类型时，签名、字段、语义是否一致
|
||||
5. **依赖关系闭环**——A 文档声明依赖 B 提供的能力，B 文档里真的暴露了该能力吗；有没有单向悬空依赖
|
||||
6. **同类聚合与命名**——同 type 文档是否遵循 `{type}-{slug}.md`，根目录某 type 已 ≥6 份是否还在平铺（参照 `easysdd/reference/shared-conventions.md`）
|
||||
6. **同类聚合与命名**——同 type 文档是否遵循 `{type}-{slug}.md`，根目录某 type 已 ≥6 份是否还在平铺（参照 `codestable/reference/shared-conventions.md`）
|
||||
|
||||
---
|
||||
|
||||
@@ -154,9 +154,9 @@ implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requ
|
||||
|
||||
## 3. 观察项（范围外，不动手）
|
||||
|
||||
读 `easysdd/architecture/` 时若发现下列结构性问题，列在这里交给用户决定是否另起工作流处理：
|
||||
读 `codestable/architecture/` 时若发现下列结构性问题，列在这里交给用户决定是否另起工作流处理：
|
||||
|
||||
- 某个 type 在根目录已 ≥6 份仍平铺（违反 shared-conventions 的同类聚合规则，应触发 `easysdd-architecture` 的 `update` 模式搬迁）
|
||||
- 某个 type 在根目录已 ≥6 份仍平铺（违反 shared-conventions 的同类聚合规则，应触发 `cs-arch` 的 `update` 模式搬迁）
|
||||
- 文件名没遵循 `{type}-{slug}.md`，未来无法聚合
|
||||
- 其他和本次检查目标无关、但顺带看到的不合理点
|
||||
|
||||
@@ -184,7 +184,7 @@ implements: [] # 这块架构承载的 requirement slug 列表（`easysdd/requ
|
||||
## 5. compound 检索命令（new / update 用）
|
||||
|
||||
```bash
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active --query "{模块关键词}"
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{模块关键词}"
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --query "{模块关键词}"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active --query "{模块关键词}"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{模块关键词}"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --query "{模块关键词}"
|
||||
```
|
||||
|
||||
+20
-20
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-brainstorm
|
||||
name: cs-brainstorm
|
||||
description: 想法还模糊时的讨论入口——先通过一两轮对话做分诊，判断这次讨论最终该进哪个下游：已经足够清楚就直接 feature-design、小需求方向已定就在 feature 里继续讨论并落 `{slug}-brainstorm.md`、大需求装不进一个 feature 就交给 roadmap 拆解。AI 的角色是思考伙伴，不是记录员——挖用户真正想解决的问题、带方案来时主动评估、必要时提替代方向。触发场景：用户说"有个想法还没想清楚"、"先 brainstorm 一下"、"我想做点什么但还模糊"、"聊一聊这块"、"功能方向还在摇摆"，或者用户带着具体方案但想先听听别的想法。不处理 bug（走 issue）和重构（走 refactor）。
|
||||
---
|
||||
|
||||
# easysdd-brainstorm
|
||||
# cs-brainstorm
|
||||
|
||||
brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这次讨论的终点应该落在哪——是一份 feature design、一份 roadmap，还是聊两句就发现已经够清楚可以直接去 design。本技能先用一两轮对话做分诊，然后把讨论交给合适的下游。
|
||||
|
||||
@@ -12,7 +12,7 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
- **brainstorm 是创意空间，不是审计关卡**。在这里探索、质疑、改变主意、聊着聊着发现真正想做的是另一件事——都正常。约束和落地细节留给下游技能。
|
||||
- **AI 是思考伙伴，不是记录员**。用户来这一步是想被挑战、被启发，不是来被一条条问题填表的。如果你只是把用户的话整理一遍写下来，那这一步就白做了。
|
||||
|
||||
> 共享路径和命名约定看 `easysdd/reference/shared-conventions.md`。
|
||||
> 共享路径和命名约定看 `codestable/reference/shared-conventions.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -22,9 +22,9 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
|
||||
| 情况 | 特征 | 出口 |
|
||||
|---|---|---|
|
||||
| **case 1：其实已经够清楚** | 能一句话说出"做什么 / 为谁做 / 怎么算成功 / 明确不做什么"，不需要再 explore | 直接 `easysdd-feature-design`（本技能不落盘，告知用户后停下） |
|
||||
| **case 2：小需求，方向定但细节模糊** | 知道要解决什么问题、大致做哪块，但对真问题是什么 / 用什么方式解 / 边界在哪还摇摆；一个 feature 能装下 | 在 `easysdd/features/{feature}/` 里讨论并落 `{slug}-brainstorm.md`，之后进 `easysdd-feature-design` |
|
||||
| **case 3：大需求，还只有一个词** | 说的是"我想要一个 X 系统 / 一套 Y 能力"，能预见到拆出来会是多个 feature，或者连最小闭环都还说不清 | `easysdd-roadmap`（本技能不落盘，把讨论移交） |
|
||||
| **case 1：其实已经够清楚** | 能一句话说出"做什么 / 为谁做 / 怎么算成功 / 明确不做什么"，不需要再 explore | 直接 `cs-feat-design`（本技能不落盘，告知用户后停下） |
|
||||
| **case 2：小需求，方向定但细节模糊** | 知道要解决什么问题、大致做哪块，但对真问题是什么 / 用什么方式解 / 边界在哪还摇摆；一个 feature 能装下 | 在 `codestable/features/{feature}/` 里讨论并落 `{slug}-brainstorm.md`，之后进 `cs-feat-design` |
|
||||
| **case 3：大需求，还只有一个词** | 说的是"我想要一个 X 系统 / 一套 Y 能力"，能预见到拆出来会是多个 feature，或者连最小闭环都还说不清 | `cs-roadmap`（本技能不落盘，把讨论移交） |
|
||||
|
||||
判错 case 不是灾难——**允许升降级**。在 case 2 里聊着聊着发现其实是 case 3（范围越聊越大），或者 case 3 聊着聊着发现用户真正要的只是一个小 feature（范围收窄），当场告诉用户切换出口，不要硬着头皮继续。
|
||||
|
||||
@@ -34,13 +34,13 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
|
||||
五件事，每次都做：
|
||||
|
||||
1. **扫一眼仓库**——第一次提问之前完成这几件：读 `AGENTS.md` + `easysdd/architecture/DESIGN.md`；Glob `easysdd/features/` 已有目录；Glob `easysdd/roadmap/` 已有子目录；Grep 用户描述里的关键词（防术语冲突）；搜 `easysdd/compound/` 看有没有相关的踩坑记录（`--filter doc_type=learning`）。扫完在对话里简短报告发现，让用户知道你不是凭空在跟 TA 聊。
|
||||
2. **是不是接续之前的工作**——`easysdd/features/` 下有名字相近的 `{slug}-brainstorm.md` 吗？`easysdd/roadmap/` 下有名字相近的子目录吗？
|
||||
1. **扫一眼仓库**——第一次提问之前完成这几件：读 `AGENTS.md` + `codestable/architecture/DESIGN.md`；Glob `codestable/features/` 已有目录；Glob `codestable/roadmap/` 已有子目录；Grep 用户描述里的关键词（防术语冲突）；搜 `codestable/compound/` 看有没有相关的踩坑记录（`--filter doc_type=learning`）。扫完在对话里简短报告发现，让用户知道你不是凭空在跟 TA 聊。
|
||||
2. **是不是接续之前的工作**——`codestable/features/` 下有名字相近的 `{slug}-brainstorm.md` 吗？`codestable/roadmap/` 下有名字相近的子目录吗？
|
||||
- 没有 → 当新讨论
|
||||
- 有 `{slug}-brainstorm.md`，内容是对话中断留下的 → 读完简短汇报"上次聊到了 {选定方向 / 最后那个话题}，接着聊还是推翻重来？"
|
||||
- 有同名 `{slug}-design.md` → 告诉用户 design 已经开了，是不是走错入口
|
||||
- 有同名 roadmap 子目录 → 告诉用户这块已经在 roadmap 里跟进，是不是要推进具体子 feature
|
||||
3. **确认这是新功能 brainstorm**——bug 走 `easysdd-issue`，重构走 `easysdd-refactor`。走错入口比拒绝触发还坏。
|
||||
3. **确认这是新功能 brainstorm**——bug 走 `cs-issue`，重构走 `cs-refactor`。走错入口比拒绝触发还坏。
|
||||
4. **开场判 case**（下一节展开）——这是本技能的核心动作。
|
||||
5. **如果你已经能替用户写出 design 第 1 节需求摘要的初稿**——老实告诉用户"我感觉你已经够清楚了，直接进 feature-design 更省事"，也就是当场判 case 1。揽下不属于自己的活是本阶段最大的反模式。
|
||||
|
||||
@@ -82,7 +82,7 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
|
||||
动作：
|
||||
|
||||
1. 告诉用户"这块你已经想清楚了：{AI 一句话复述做什么 / 为谁 / 怎么算成功 / 明确不做}。建议直接走 `easysdd-feature-design`——brainstorm 对你没增量价值"
|
||||
1. 告诉用户"这块你已经想清楚了：{AI 一句话复述做什么 / 为谁 / 怎么算成功 / 明确不做}。建议直接走 `cs-feat-design`——brainstorm 对你没增量价值"
|
||||
2. 本技能**不落盘**——没产出 `{slug}-brainstorm.md`，也不建 feature 目录（design 阶段会建）
|
||||
3. 停下来，等用户触发 design
|
||||
|
||||
@@ -90,16 +90,16 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
|
||||
### case 2：小需求，在 feature 里继续讨论
|
||||
|
||||
进入当前阶段 0 对话模式。按"怎么聊（case 2 展开）"一节的姿态往下推进，收敛后落盘 `easysdd/features/{feature}/{slug}-brainstorm.md`。
|
||||
进入当前阶段 0 对话模式。按"怎么聊（case 2 展开）"一节的姿态往下推进，收敛后落盘 `codestable/features/{feature}/{slug}-brainstorm.md`。
|
||||
|
||||
### case 3：大需求，移交给 roadmap
|
||||
|
||||
动作：
|
||||
|
||||
1. 告诉用户"这块听起来是多个 feature 的集合，单个 feature 装不下。brainstorm 对这种规模的讨论不是好入口——`easysdd-roadmap` 会做拆解和依赖梳理，我现在把讨论交给它比较合适"
|
||||
1. 告诉用户"这块听起来是多个 feature 的集合，单个 feature 装不下。brainstorm 对这种规模的讨论不是好入口——`cs-roadmap` 会做拆解和依赖梳理，我现在把讨论交给它比较合适"
|
||||
2. 把已经聊到的信息做一句话汇总（真问题 / 大致范围 / 已经提到的可能子模块），方便 roadmap 技能接手不用重来
|
||||
3. 本技能**不落盘**——`roadmap new` 模式会自己建 `easysdd/roadmap/{slug}/` 目录和主文档，不需要 brainstorm 预留产物
|
||||
4. 告诉用户下一步触发 `easysdd-roadmap`
|
||||
3. 本技能**不落盘**——`roadmap new` 模式会自己建 `codestable/roadmap/{slug}/` 目录和主文档，不需要 brainstorm 预留产物
|
||||
4. 告诉用户下一步触发 `cs-roadmap`
|
||||
|
||||
为什么不在本技能里做大需求讨论？大需求的讨论价值几乎全在"拆成几块 / 依赖怎么走 / 最小闭环选哪条"，这套思考 roadmap 自己带——单独在 brainstorm 里聊一轮会和 roadmap 重复做一遍。
|
||||
|
||||
@@ -146,7 +146,7 @@ brainstorm 是"讨论层"的统一入口。用户开口时，AI 并不知道这
|
||||
|
||||
## case 2 落盘
|
||||
|
||||
收敛动作完成后写 brainstorm note 到 `easysdd/features/{feature}/{slug}-brainstorm.md`。
|
||||
收敛动作完成后写 brainstorm note 到 `codestable/features/{feature}/{slug}-brainstorm.md`。
|
||||
|
||||
### feature 目录怎么建
|
||||
|
||||
@@ -185,7 +185,7 @@ tags: [...]
|
||||
{选定方向 2-3 句重述 + 粗粒度轮廓（核心行为、明显不做、最大未知）。遗留给 design 的问题直接列在这里}
|
||||
```
|
||||
|
||||
frontmatter 字段口径跟 design / acceptance 共用一组（`doc_type` / `feature` / `status` / `summary` / `tags`），看 `easysdd/reference/shared-conventions.md` 第 1 节。
|
||||
frontmatter 字段口径跟 design / acceptance 共用一组（`doc_type` / `feature` / `status` / `summary` / `tags`），看 `codestable/reference/shared-conventions.md` 第 1 节。
|
||||
|
||||
仓库扫描发现、术语冲突提示、learning 文档引用这类备注按需加在末尾，不另开 section。
|
||||
|
||||
@@ -195,11 +195,11 @@ frontmatter 字段口径跟 design / acceptance 共用一组（`doc_type` / `fea
|
||||
|
||||
按 case 各自的退出动作：
|
||||
|
||||
- **case 1**：告诉用户"直接触发 `easysdd-feature-design`"，不落盘，结束
|
||||
- **case 2**：收敛动作完成后主动问"这块够清楚了，可以进 design 了吗？"，用户确认后落盘 `{slug}-brainstorm.md`，告诉用户下一步触发 `easysdd-feature-design`
|
||||
- **case 3**：告诉用户"这次讨论移交给 `easysdd-roadmap` 做拆解"，带上已聊到的要点一句话汇总，不落盘，结束
|
||||
- **case 1**：告诉用户"直接触发 `cs-feat-design`"，不落盘，结束
|
||||
- **case 2**：收敛动作完成后主动问"这块够清楚了，可以进 design 了吗？"，用户确认后落盘 `{slug}-brainstorm.md`，告诉用户下一步触发 `cs-feat-design`
|
||||
- **case 3**：告诉用户"这次讨论移交给 `cs-roadmap` 做拆解"，带上已聊到的要点一句话汇总，不落盘，结束
|
||||
|
||||
**别自己顺手开始写 design 或 roadmap**——阶段间的人工 checkpoint 是 easysdd 整套流程的硬约束。告诉用户下一步触发对应技能就够了。
|
||||
**别自己顺手开始写 design 或 roadmap**——阶段间的人工 checkpoint 是 CodeStable 整套流程的硬约束。告诉用户下一步触发对应技能就够了。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+11
-11
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-decisions
|
||||
name: cs-decide
|
||||
description: 把项目里已经拍板的技术选型、架构决定、长期约束、编码规约记成可检索的永久性文档。六个月后没人记得为什么当初选了 X，但有了决策文档，下次改动之前至少能先读懂背景。四种类型：tech-stack（用什么工具 / 库 / 框架）、architecture（系统怎么组织）、constraint（什么不允许做）、convention（什么统一这样做）。触发场景：feature-design 或 issue-analyze 后做出重要选择时主动推送，或用户说"记录决定"、"归档技术选型"、"ADR"、"记录这条约束"、"把规约写下来"。只归档已拍板的决定，讨论中的方案不归档。
|
||||
---
|
||||
|
||||
# easysdd-decisions
|
||||
# cs-decide
|
||||
|
||||
项目里"有意做出的选择"——技术选型、架构决定、长期约束、编码规约——特别容易丢失。它不会触发报错、没人会注意到它消失了，但消失的代价很具体：
|
||||
|
||||
@@ -13,7 +13,7 @@ description: 把项目里已经拍板的技术选型、架构决定、长期约
|
||||
|
||||
本工作流的职责就是让每一条重要的"已经决定了"都有完整存档：**是什么、为什么、考虑过什么替代方案、后果是什么**。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。本技能的产物写入 `easysdd/compound/`，文件命名 `YYYY-MM-DD-decision-{slug}.md`，frontmatter 带 `doc_type: decision`。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。本技能的产物写入 `codestable/compound/`，文件命名 `YYYY-MM-DD-decision-{slug}.md`，frontmatter 带 `doc_type: decision`。
|
||||
|
||||
---
|
||||
|
||||
@@ -59,7 +59,7 @@ description: 把项目里已经拍板的技术选型、架构决定、长期约
|
||||
|
||||
### Phase 1.5：查重叠与意图分流（必做）
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
按 `codestable/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
|
||||
- 用户话里含"改 / 更新 / 推翻 / 某条决策 / 某个选型"或明确指向某份旧决策 → 直接走**更新或 supersede** 路径。决策文档的特性是：**结论本身变更几乎总要 supersede**（旧结论要留痕，不能原地覆盖）；只是补背景 / 替代方案 / 影响描述时才走"更新已有条目"
|
||||
- 否则用下面"搜索工具"按 `category` + 关键词查一遍，命中相近旧决策时把候选列给用户，让用户选：更新 / supersede / 确实不同主题
|
||||
@@ -84,7 +84,7 @@ description: 把项目里已经拍板的技术选型、架构决定、长期约
|
||||
|
||||
### Phase 4：归档
|
||||
|
||||
- 新建路径：文件写入 `easysdd/compound/`，命名 `YYYY-MM-DD-decision-{slug}.md`，frontmatter 顶部带 `doc_type: decision`（见 `reference.md`）
|
||||
- 新建路径：文件写入 `codestable/compound/`，命名 `YYYY-MM-DD-decision-{slug}.md`，frontmatter 顶部带 `doc_type: decision`（见 `reference.md`）
|
||||
- 更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补 `updated: YYYY-MM-DD`
|
||||
- supersede 路径：按 `shared-conventions.md` §6 第 5 条处理；旧文档 `status=superseded` 并加 `superseded-by`（和本技能守护规则 #2 一致）
|
||||
- 写完后报告完整文件路径
|
||||
@@ -93,24 +93,24 @@ description: 把项目里已经拍板的技术选型、架构决定、长期约
|
||||
|
||||
写完后检查这两项，有则提示用户（**不自作主张改文件**——这两个文件都是高影响入口）：
|
||||
|
||||
1. `easysdd/architecture/DESIGN.md` 的"关键架构决定"节是否应该引用这条决策——`architecture` 或 `tech-stack` 类型通常应该
|
||||
1. `codestable/architecture/DESIGN.md` 的"关键架构决定"节是否应该引用这条决策——`architecture` 或 `tech-stack` 类型通常应该
|
||||
2. `AGENTS.md` 的"禁止事项"或"代码规范"节是否应该追加这条约束——`constraint` 或 `convention` 类型通常应该
|
||||
|
||||
---
|
||||
|
||||
## 搜索工具
|
||||
|
||||
> 完整语法和示例见 `easysdd/reference/tools.md`。本节只列 decisions 特有的典型查询。
|
||||
> 完整语法和示例见 `codestable/reference/tools.md`。本节只列 decisions 特有的典型查询。
|
||||
|
||||
```bash
|
||||
# 列出所有当前有效的决策
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active
|
||||
|
||||
# 按类型 + 状态组合筛选
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter category=constraint --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter category=constraint --filter status=active
|
||||
|
||||
# 归档后查重叠
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --query "{关键词}" --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --query "{关键词}" --json
|
||||
```
|
||||
|
||||
---
|
||||
@@ -123,7 +123,7 @@ python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=dec
|
||||
|
||||
## 守护规则
|
||||
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `easysdd/reference/shared-conventions.md` 第 6 节。本技能特有或细化的规则：
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `codestable/reference/shared-conventions.md` 第 6 节。本技能特有或细化的规则：
|
||||
|
||||
1. **只归档已拍板的决定**——讨论中的方案不归档；"也许我们应该用 X"不归档
|
||||
2. **status=superseded 不等于删除**——被取代的决策保留原文，加 `superseded-by` 字段，正文顶部加一行"**[已取代]** 见 {新文档 slug}"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# decisions 参考模板
|
||||
|
||||
本文件提供 `easysdd-decisions` 使用的 frontmatter、正文模板和示例。
|
||||
本文件提供 `cs-decide` 使用的 frontmatter、正文模板和示例。
|
||||
|
||||
## 1. frontmatter
|
||||
|
||||
@@ -17,7 +17,7 @@ tags: []
|
||||
---
|
||||
```
|
||||
|
||||
文件名：`easysdd/compound/YYYY-MM-DD-decision-{slug}.md`。
|
||||
文件名：`codestable/compound/YYYY-MM-DD-decision-{slug}.md`。
|
||||
|
||||
## 2. 正文模板
|
||||
|
||||
|
||||
+12
-12
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: easysdd-explore
|
||||
description: 对仓库做一次定向代码探索，把"提问 → 读代码 → 得结论"的过程沉淀为可检索证据，下次同类问题直接复用。三种类型：question（围绕一个具体问题查代码并给结论）、module-overview（梳理某模块结构 / 边界 / 入口 / 依赖）、spike（对多个可能方向做轻量技术探查，不做最终决策）。触发场景：用户说"先 explore 一下"、"这个仓库里 X 怎么实现"、"快速熟悉这个模块"、"把探索结果存档"。和 learning / tricks / decisions 怎么区分看 `easysdd/reference/system-overview.md`。
|
||||
name: cs-explore
|
||||
description: 对仓库做一次定向代码探索，把"提问 → 读代码 → 得结论"的过程沉淀为可检索证据，下次同类问题直接复用。三种类型：question（围绕一个具体问题查代码并给结论）、module-overview（梳理某模块结构 / 边界 / 入口 / 依赖）、spike（对多个可能方向做轻量技术探查，不做最终决策）。触发场景：用户说"先 explore 一下"、"这个仓库里 X 怎么实现"、"快速熟悉这个模块"、"把探索结果存档"。和 learning / tricks / decisions 怎么区分看 `codestable/reference/system-overview.md`。
|
||||
---
|
||||
|
||||
# easysdd-explore
|
||||
# cs-explore
|
||||
|
||||
同一个问题第一次花两小时查代码，第二次应该五分钟内找到答案——前提是第一次做完留下了证据化的记录。easysdd-explore 就是把一次完整的"提问 → 读代码 → 得结论"过程沉淀成可检索的探索文档。
|
||||
同一个问题第一次花两小时查代码，第二次应该五分钟内找到答案——前提是第一次做完留下了证据化的记录。cs-explore 就是把一次完整的"提问 → 读代码 → 得结论"过程沉淀成可检索的探索文档。
|
||||
|
||||
---
|
||||
|
||||
@@ -18,7 +18,7 @@ description: 对仓库做一次定向代码探索，把"提问 → 读代码 →
|
||||
|
||||
本技能只负责"看到了什么"的证据化记录。如果用户的意图其实是别的（拍板、处方、修 bug），让用户按场景选对应子技能，不要在这里自作主张接过去。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。本技能的产物写入 `easysdd/compound/`，文件命名 `YYYY-MM-DD-explore-{slug}.md`，frontmatter 带 `doc_type: explore`。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。本技能的产物写入 `codestable/compound/`，文件命名 `YYYY-MM-DD-explore-{slug}.md`，frontmatter 带 `doc_type: explore`。
|
||||
|
||||
---
|
||||
|
||||
@@ -58,7 +58,7 @@ description: 对仓库做一次定向代码探索，把"提问 → 读代码 →
|
||||
|
||||
### Phase 1.5：查重叠与意图分流（必做）
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
按 `codestable/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
|
||||
- 用户话里含"更新 / 复查 / 某次 explore / 这个模块之前探过"或明确指向某份旧 explore → 直接走**更新或 supersede** 路径。explore 的特性是：**代码已经变了导致旧结论失效**时，旧文档标 `status=outdated` 并新建一份（supersede）；只是补证据 / 收紧结论但核心结论未变时走"更新已有条目"
|
||||
- 否则用下面"搜索工具"按关键词 / 模块查一遍，命中相近旧 explore 时先读它，能直接回答就告诉用户"已有一份可用的 explore 在 {路径}，是要复用还是重新探一遍？"
|
||||
@@ -83,7 +83,7 @@ description: 对仓库做一次定向代码探索，把"提问 → 读代码 →
|
||||
|
||||
### Phase 4：归档
|
||||
|
||||
- 新建路径：写入 `easysdd/compound/`，命名 `YYYY-MM-DD-explore-{slug}.md`，frontmatter 顶部带 `doc_type: explore`（见 `reference.md`）
|
||||
- 新建路径：写入 `codestable/compound/`，命名 `YYYY-MM-DD-explore-{slug}.md`，frontmatter 顶部带 `doc_type: explore`（见 `reference.md`）
|
||||
- 更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补 `updated: YYYY-MM-DD`
|
||||
- supersede 路径：按 `shared-conventions.md` §6 第 5 条处理；旧文档改 `status=outdated` 并加 `superseded-by`
|
||||
|
||||
@@ -95,14 +95,14 @@ description: 对仓库做一次定向代码探索，把"提问 → 读代码 →
|
||||
|
||||
## 搜索工具
|
||||
|
||||
> 完整语法和示例见 `easysdd/reference/tools.md`。本节只列 explore 特有的典型查询。
|
||||
> 完整语法和示例见 `codestable/reference/tools.md`。本节只列 explore 特有的典型查询。
|
||||
|
||||
```bash
|
||||
# 按类型筛选
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --filter type=module-overview --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter type=module-overview --filter status=active
|
||||
|
||||
# 归档后查重叠
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{关键词}" --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{关键词}" --json
|
||||
```
|
||||
|
||||
---
|
||||
@@ -113,14 +113,14 @@ python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=exp
|
||||
- [ ] 速答节已给出核心结论（结论前置，不埋在证据之后）
|
||||
- [ ] 关键证据 3-8 条，每条标注文件:行号，并说明支撑哪个结论
|
||||
- [ ] 涉及多模块协作或 module-overview / spike 类型时，速答节有 Mermaid 图
|
||||
- [ ] 文档已归档到 `easysdd/compound/`，文件名为 `YYYY-MM-DD-explore-{slug}.md`
|
||||
- [ ] 文档已归档到 `codestable/compound/`，文件名为 `YYYY-MM-DD-explore-{slug}.md`
|
||||
- [ ] 已给出后续建议（路由到哪个子工作流）
|
||||
|
||||
---
|
||||
|
||||
## 守护规则
|
||||
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `easysdd/reference/shared-conventions.md` 第 6 节。本技能特有的反模式：
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `codestable/reference/shared-conventions.md` 第 6 节。本技能特有的反模式：
|
||||
|
||||
- 不读代码直接给结论
|
||||
- 证据只写"看起来像"，不写文件:行号
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# explore 参考模板
|
||||
|
||||
本文件提供 `easysdd-explore` 使用的 frontmatter、正文结构和写作说明。
|
||||
本文件提供 `cs-explore` 使用的 frontmatter、正文结构和写作说明。
|
||||
|
||||
## 1. frontmatter
|
||||
|
||||
@@ -18,7 +18,7 @@ confidence: high | medium | low
|
||||
---
|
||||
```
|
||||
|
||||
文件名：`easysdd/compound/YYYY-MM-DD-explore-{slug}.md`。
|
||||
文件名：`codestable/compound/YYYY-MM-DD-explore-{slug}.md`。
|
||||
|
||||
## 2. 正文结构
|
||||
|
||||
|
||||
+21
-21
@@ -1,22 +1,22 @@
|
||||
---
|
||||
name: easysdd-feature-acceptance
|
||||
description: feature 流程的阶段 3——做完整验收闭环。四件事：一是逐层对照 {slug}-design.md 核对实现有没有走样，发现偏差就当场修不是写在报告里"记一下"；二是把这个 feature 归并到项目的整体架构文档里；三是如果本次 feature 改变了对应 requirement 的用户故事或边界，把 requirement doc 也回写一次；四是如果本 feature 从 roadmap 条目起头，把 roadmap items.yaml 对应条目改成 done 并同步主文档。最后产出一份 {slug}-acceptance.md 作为整套流程的闭环凭证。前置依赖 easysdd-feature-implement 已完成。触发场景：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。
|
||||
name: cs-feat-accept
|
||||
description: feature 流程的阶段 3——做完整验收闭环。四件事：一是逐层对照 {slug}-design.md 核对实现有没有走样，发现偏差就当场修不是写在报告里"记一下"；二是把这个 feature 归并到项目的整体架构文档里；三是如果本次 feature 改变了对应 requirement 的用户故事或边界，把 requirement doc 也回写一次；四是如果本 feature 从 roadmap 条目起头，把 roadmap items.yaml 对应条目改成 done 并同步主文档。最后产出一份 {slug}-acceptance.md 作为整套流程的闭环凭证。前置依赖 cs-feat-impl 已完成。触发场景：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。
|
||||
---
|
||||
|
||||
# easysdd-feature-acceptance
|
||||
# cs-feat-accept
|
||||
|
||||
到这一步代码已经写完了，但流程没结束。这一阶段做四件事，缺一不可：
|
||||
|
||||
1. **核对实现有没有偏离方案**——逐层对照 `{slug}-design.md` 的四个节，发现偏差当场修，**不是在报告里"记一下"**就过去
|
||||
2. **把 feature 归并到整体架构**——对照方案 doc 第 4 节，实际去更新架构中心目录下的相关 doc
|
||||
3. **把变化回写到 requirement**——对照方案 doc frontmatter 的 `requirement` 字段，如果本次实现改变了对应 req 的用户故事 / 边界 / pitch 表述，触发 `easysdd-requirements` update 把 req doc 一起刷新（纯重构无 req 的 feature 跳过这步）
|
||||
4. **把完成状态回写到 roadmap**——如果方案 doc frontmatter 有 `roadmap` / `roadmap_item` 字段，本阶段**必须**改 `easysdd/roadmap/{roadmap}/{roadmap}-items.yaml` 对应条目 `status` 为 `done`，并同步主文档子 feature 清单。没有这两个字段（feature 没从 roadmap 起头）就跳过这步
|
||||
3. **把变化回写到 requirement**——对照方案 doc frontmatter 的 `requirement` 字段，如果本次实现改变了对应 req 的用户故事 / 边界 / pitch 表述，触发 `cs-req` update 把 req doc 一起刷新（纯重构无 req 的 feature 跳过这步）
|
||||
4. **把完成状态回写到 roadmap**——如果方案 doc frontmatter 有 `roadmap` / `roadmap_item` 字段，本阶段**必须**改 `codestable/roadmap/{roadmap}/{roadmap}-items.yaml` 对应条目 `status` 为 `done`，并同步主文档子 feature 清单。没有这两个字段（feature 没从 roadmap 起头）就跳过这步
|
||||
|
||||
为什么这四件事都重要？只做第一件，新功能加进去了但项目级架构 doc 还说着老结构，下一个 feature 的设计阶段读到的就是过期信息。漏掉第二件，可能把"实现已经偏离方案"的事实掩埋——架构 doc 写得很漂亮，代码却不是那么回事。漏掉第三件，对外讲这系统"能做什么"的那份文档会慢慢和实际能力脱节，下一个用户来看的时候对不上。漏掉第四件，roadmap 规划层和实际进度脱节——主文档说这条还没做、items.yaml 还是 `planned`，但代码和 req 已经上线，下次要推进 roadmap 下一条的人会重复跑流程。
|
||||
|
||||
验收报告是工作流的闭环凭证。**没产出报告 = 工作流未完成**。这条不是仪式——后人查"上次这个功能到底验收时确认了哪些行为"，没有报告就只能去翻 git diff 重新推断。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md` 第 0 节。
|
||||
|
||||
---
|
||||
|
||||
@@ -65,7 +65,7 @@ git status / 最近提交里能看到本功能的代码改动。没看到就是
|
||||
|
||||
### 3. {slug}-checklist.yaml 状态
|
||||
|
||||
`{slug}-checklist.yaml` 的生命周期看 `easysdd/reference/shared-conventions.md`。本阶段只核对并更新 `checks` 一段：
|
||||
`{slug}-checklist.yaml` 的生命周期看 `codestable/reference/shared-conventions.md`。本阶段只核对并更新 `checks` 一段：
|
||||
|
||||
- 文件存在，`feature` 字段跟当前 feature 目录一致
|
||||
- `steps` 所有条目 status 为 `done`（有 `pending` 说明 implement 没完成，先退回）
|
||||
@@ -87,7 +87,7 @@ git status / 最近提交里能看到本功能的代码改动。没看到就是
|
||||
|
||||
## 验收报告模板
|
||||
|
||||
逐节填写，**别跳节**。报告路径在 feature 目录下，跟 `{slug}-design.md` 聚合（具体位置看 `easysdd/reference/shared-conventions.md` 第 0 节）。
|
||||
逐节填写，**别跳节**。报告路径在 feature 目录下，跟 `{slug}-design.md` 聚合（具体位置看 `codestable/reference/shared-conventions.md` 第 0 节）。
|
||||
|
||||
```markdown
|
||||
# {功能名称} 验收报告
|
||||
@@ -203,7 +203,7 @@ Fastforward design 方案没有挂载点清单的话，在本节补一次现场
|
||||
- [ ] 有对应 req，但本次实现没改变能力的用户视角：写一句"req-{slug} 用户故事 / 边界未变，无需更新"
|
||||
- [ ] 有对应 req，且本次实现改变了 req 的边界 / 用户故事 / pitch 表述：
|
||||
- 需要更新的内容：{描述}
|
||||
- 已更新：✓（触发 `easysdd-requirements` update 模式实际执行）/ 未更新（理由：{具体理由}）
|
||||
- 已更新：✓（触发 `cs-req` update 模式实际执行）/ 未更新（理由：{具体理由}）
|
||||
|
||||
和架构归并一样，这是**实际写文件的动作**，不是自评"应该不需要改"。
|
||||
|
||||
@@ -213,15 +213,15 @@ Fastforward design 方案没有挂载点清单的话，在本节补一次现场
|
||||
|
||||
- [ ] 两个字段都为空（feature 未从 roadmap 起头）：跳过本节，写一句"本 feature 非 roadmap 起头，无回写"
|
||||
- [ ] 两个字段都有值：
|
||||
- 打开 `easysdd/roadmap/{roadmap}/{roadmap}-items.yaml`
|
||||
- 打开 `codestable/roadmap/{roadmap}/{roadmap}-items.yaml`
|
||||
- 找到 `slug: {roadmap_item}` 的条目，核对 `status` 当前为 `in-progress`、`feature` 为当前 feature 目录名——不对就停下来找原因（design 阶段漏了回写？有人手工改过？）
|
||||
- 把 `status` 改为 `done`
|
||||
- 用 `python easysdd/tools/validate-yaml.py --file {path} --yaml-only` 校验
|
||||
- 用 `python codestable/tools/validate-yaml.py --file {path} --yaml-only` 校验
|
||||
- 打开 `{roadmap}-roadmap.md` 主文档，找到第 3 节子 feature 清单里对应 `{roadmap_item}` 那条，把显示状态同步为 `done`（勾选状态、对应 feature 目录名两处保持和 items.yaml 一致）
|
||||
- 已更新：✓（回写位置：items.yaml + 主文档）
|
||||
- [ ] 两个字段不一致（只填了一个）：停下来补齐或澄清，不做回写
|
||||
|
||||
衔接协议的完整定义看 `easysdd/reference/shared-conventions.md` 第 2.5 节。
|
||||
衔接协议的完整定义看 `codestable/reference/shared-conventions.md` 第 2.5 节。
|
||||
|
||||
和架构归并、requirement 回写一样，这是**实际写文件的动作**，不是自评。
|
||||
|
||||
@@ -242,7 +242,7 @@ Fastforward design 方案没有挂载点清单的话，在本节补一次现场
|
||||
2. 第 3 节（测试约束）——逐条对照，涉及类型系统的让 typecheck 跑一遍，涉及单测 / 集成的让测试跑一遍
|
||||
3. 第 4 节（术语）——用 Grep，把命中数和位置写进报告
|
||||
4. 第 5 节（架构归并）——读完方案 doc 第 4 节后逐项执行。"整体不影响架构"一句话带过是反模式，要么找出影响在哪、要么明确写"X 节列出的某项确认无影响（理由）"
|
||||
5. 第 6 节（requirement 回写）——对照方案 frontmatter 的 `requirement` 判断要不要更新对应 req；和架构归并同规则，有变化就触发 `easysdd-requirements` update 实际执行
|
||||
5. 第 6 节（requirement 回写）——对照方案 frontmatter 的 `requirement` 判断要不要更新对应 req；和架构归并同规则，有变化就触发 `cs-req` update 实际执行
|
||||
6. 第 7 节（roadmap 回写）——对照方案 frontmatter 的 `roadmap` / `roadmap_item`，有值就改 items.yaml 对应条目为 `done` 并同步主文档；无值跳过
|
||||
7. 第 8 节（遗留）——把实现阶段攒下的"顺手发现"和已知限制都记进来
|
||||
|
||||
@@ -271,7 +271,7 @@ Fastforward design 方案没有挂载点清单的话，在本节补一次现场
|
||||
|
||||
## 收尾提交
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
|
||||
按 `codestable/reference/shared-conventions.md` 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
|
||||
|
||||
- **提交范围**：功能代码 + 方案 doc + 验收报告 + 本次实际更新过的架构 doc + 本次实际更新过的 requirement doc + 本次实际改过的 roadmap items.yaml / 主文档。代码交付要带文档，否则下次做 feature 的人查不到上下文。
|
||||
- 提交是收尾推荐序列的最后一环（见下文"退出后"）——前面那几项问完，再回到提交。
|
||||
@@ -280,20 +280,20 @@ Fastforward design 方案没有挂载点清单的话，在本节补一次现场
|
||||
|
||||
## 退出后
|
||||
|
||||
告诉用户："验收报告已就绪，架构文档已归并，easysdd-feature 工作流走完。后续如发现 BUG，走 issue 修复工作流（不再回到本工作流）。"
|
||||
告诉用户："验收报告已就绪，架构文档已归并，cs-feat 工作流走完。后续如发现 BUG，走 issue 修复工作流（不再回到本工作流）。"
|
||||
|
||||
然后按 `easysdd/reference/shared-conventions.md` 第 3 节的收尾推荐顺序，逐项一句话提示（用户说"不用"立刻跳过）：
|
||||
然后按 `codestable/reference/shared-conventions.md` 第 3 节的收尾推荐顺序，逐项一句话提示（用户说"不用"立刻跳过）：
|
||||
|
||||
1. 本次 feature 暴露出值得复用的坑点或经验 → "需要沉淀一条 learning 文档吗？（走 `easysdd-learning`，会写入 `easysdd/compound/`）"
|
||||
2. 引入了超出单个功能的长期约束 / 技术选型 → "需要把这条决定归档吗？（走 `easysdd-decisions`）"
|
||||
3. 方案 doc 第 2 节有接口变更 / 第 1 节有用户可见行为变更 → "需要更新开发者或用户指南吗？（走 `easysdd-guidedoc`）"
|
||||
4. 新增 / 修改了库公开接口（组件、函数、命令等） → "需要更新库 API 参考文档吗？（走 `easysdd-libdoc`）"
|
||||
1. 本次 feature 暴露出值得复用的坑点或经验 → "需要沉淀一条 learning 文档吗？（走 `cs-learn`，会写入 `codestable/compound/`）"
|
||||
2. 引入了超出单个功能的长期约束 / 技术选型 → "需要把这条决定归档吗？（走 `cs-decide`）"
|
||||
3. 方案 doc 第 2 节有接口变更 / 第 1 节有用户可见行为变更 → "需要更新开发者或用户指南吗？（走 `cs-guide`）"
|
||||
4. 新增 / 修改了库公开接口（组件、函数、命令等） → "需要更新库 API 参考文档吗？（走 `cs-libdoc`）"
|
||||
5. 最后问一次是否需要代为提交本次代码和文档（scoped-commit）。用户同意时，按收尾提交规则执行到 commit 完成。
|
||||
|
||||
可以建议：
|
||||
|
||||
- 提交时把方案 doc + 验收报告 + 更新后的架构 doc 当作同一次提交的一部分
|
||||
- 验收报告里"遗留"的后续优化点真要做的话另开新一轮 easysdd-feature 流程，不要在现有 PR 里塞
|
||||
- 验收报告里"遗留"的后续优化点真要做的话另开新一轮 cs-feat 流程，不要在现有 PR 里塞
|
||||
|
||||
---
|
||||
|
||||
|
||||
+18
-18
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: easysdd-feature-design
|
||||
name: cs-feat-design
|
||||
description: feature 流程的阶段 1——为新功能起草一份方案文件，作为后续实现和验收的唯一输入。先收集证据（读架构、读相关代码、grep 防术语冲突、查归档），然后一次性写出完整初稿（含 YAML frontmatter + 三层结构 + 测试设计），交给用户整体 review，迭代到拍板。拍板后从 {slug}-design.md 里抽出 {slug}-checklist.yaml 给后面两个阶段用。触发场景："开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已经知道做什么、为谁做、怎么算成功。
|
||||
---
|
||||
|
||||
# easysdd-feature-design
|
||||
# cs-feat-design
|
||||
|
||||
这一阶段的产出是一份方案文件 `{slug}-design.md`，加上从中抽出的行动清单 `{slug}-checklist.yaml`。这两份东西后面会被两个阶段消费——implement 照着推进、acceptance 照着核对，所以这里写错或写漏，下游就跟着错。
|
||||
|
||||
> 共享路径和命名约定看 `easysdd/reference/shared-conventions.md`。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。
|
||||
> 共享路径和命名约定看 `codestable/reference/shared-conventions.md`。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。
|
||||
|
||||
本阶段有三个入口：
|
||||
|
||||
@@ -24,7 +24,7 @@ description: feature 流程的阶段 1——为新功能起草一份方案文件
|
||||
动作：
|
||||
|
||||
1. **和用户快速对齐两件事**——一句话需求概要 + 敲定 slug（小写字母、数字、连字符；`user-auth`、`export-csv` 这种）。日期取当天（frontmatter 用 `currentDate` 即可）。feature 目录命名是 `YYYY-MM-DD-{slug}`。
|
||||
2. **创建 `easysdd/features/{YYYY-MM-DD}-{slug}/` 目录**。
|
||||
2. **创建 `codestable/features/{YYYY-MM-DD}-{slug}/` 目录**。
|
||||
3. **写一份空的 `{slug}-intent.md`** 作为草稿骨架，内容就是下面这段：
|
||||
|
||||
```markdown
|
||||
@@ -62,7 +62,7 @@ description: feature 流程的阶段 1——为新功能起草一份方案文件
|
||||
|
||||
## 从 roadmap 条目起头
|
||||
|
||||
触发：用户说"开始做 roadmap 里的 {子 feature slug}"、"推进 {roadmap-slug} 的下一条"，或指向 `easysdd/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 里某条 `planned` 条目。
|
||||
触发：用户说"开始做 roadmap 里的 {子 feature slug}"、"推进 {roadmap-slug} 的下一条"，或指向 `codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 里某条 `planned` 条目。
|
||||
|
||||
动作：
|
||||
|
||||
@@ -81,10 +81,10 @@ description: feature 流程的阶段 1——为新功能起草一份方案文件
|
||||
- 找到 `slug: {roadmap_item}` 的条目
|
||||
- `status: planned` → `in-progress`
|
||||
- `feature: null` → `feature: YYYY-MM-DD-{slug}`（feature 目录名）
|
||||
- 用 `python easysdd/tools/validate-yaml.py --file {path} --yaml-only` 校验
|
||||
- 用 `python codestable/tools/validate-yaml.py --file {path} --yaml-only` 校验
|
||||
6. **汇报**：告诉用户 roadmap 已回写，下一步进 implement 阶段
|
||||
|
||||
完整衔接协议看 `easysdd/reference/shared-conventions.md` 第 2.5 节。
|
||||
完整衔接协议看 `codestable/reference/shared-conventions.md` 第 2.5 节。
|
||||
|
||||
---
|
||||
|
||||
@@ -169,17 +169,17 @@ design 的产出要被 implement 照着推进、被 acceptance 照着核对—
|
||||
|
||||
#### 必做 4 条
|
||||
|
||||
1. **续作检查**——Glob `easysdd/features/{feature}/{slug}-design.md` / `{slug}-intent.md` / `{slug}-brainstorm.md`：
|
||||
1. **续作检查**——Glob `codestable/features/{feature}/{slug}-design.md` / `{slug}-intent.md` / `{slug}-brainstorm.md`：
|
||||
- 有 `{slug}-intent.md`：当作用户方案输入读入，不再重复问已讲清的部分，只追问没覆盖的角落
|
||||
- 有 `{slug}-brainstorm.md`：当作对话沉淀输入读入
|
||||
- design 文件不存在、或只有空模板 / frontmatter → 当新建处理
|
||||
- design `status=draft` 且各节基本完整 → 上次写完没 review，跳到本流程"5. 整体 review"
|
||||
- design 部分节缺失 → 只补缺失节，汇报"上次写到第 X 节，补齐剩下的统一给你 review"
|
||||
- design `status=approved` → 不要默默覆盖，问用户接着改还是另起 slug
|
||||
2. **读 architecture**——架构总入口 `easysdd/architecture/DESIGN.md` + 索引 + 与需求相关的子系统架构 doc。重点看已有的**名词**（能不能复用 / 会不会冲突）和**跨层纪律**（本 feature 要遵守什么）。不读直接动手大概率写出脱离实际的方案。
|
||||
3. **对齐 requirement**——到 `easysdd/requirements/` Glob + grep：
|
||||
2. **读 architecture**——架构总入口 `codestable/architecture/DESIGN.md` + 索引 + 与需求相关的子系统架构 doc。重点看已有的**名词**（能不能复用 / 会不会冲突）和**跨层纪律**（本 feature 要遵守什么）。不读直接动手大概率写出脱离实际的方案。
|
||||
3. **对齐 requirement**——到 `codestable/requirements/` Glob + grep：
|
||||
- 已有对应 req：slug 记进方案 frontmatter 的 `requirement` 字段；动笔前读一遍 req 的"用户故事"和"边界"两节，方案不能冲突
|
||||
- 没有对应 req，但本 feature 新增 / 改变用户可感能力：**停下来**，提示用户先触发 `easysdd-requirements` 起草或更新 req
|
||||
- 没有对应 req，但本 feature 新增 / 改变用户可感能力：**停下来**，提示用户先触发 `cs-req` 起草或更新 req
|
||||
- 纯内部重构 / 技术债 / 工具链：frontmatter `requirement` 留空，第 1 节写"本 feature 不新增能力，无对应 requirement"
|
||||
4. **读需求相关的现有代码**——具体读哪些文件由需求线索决定。这是方案能和现有代码接得上的前提。
|
||||
|
||||
@@ -189,20 +189,20 @@ design 的产出要被 implement 照着推进、被 acceptance 照着核对—
|
||||
|
||||
- **术语 grep 防冲突**
|
||||
- 触发：本 feature 要引入的关键概念名看起来没在代码 / 架构 / 历史 feature 里见过
|
||||
- 动作：grep 覆盖代码 + `easysdd/architecture/` + 所有 feature 方案文件。冲突了换名，或在第 0 节明确"本文里 X 指 Y，和代码里的 X' 不是一回事"
|
||||
- 动作：grep 覆盖代码 + `codestable/architecture/` + 所有 feature 方案文件。冲突了换名，或在第 0 节明确"本文里 X 指 Y，和代码里的 X' 不是一回事"
|
||||
- **复杂度档位对齐**
|
||||
- 触发：需求里出现可能偏离默认档位的信号——"对外 SDK"（可读性从 team 升到 public）、"高并发 / 低延迟"（性能从 reasonable 升到 budgeted）、"纯探索脚本 / 一次性工具"（健壮性从 L2 降到 L1）
|
||||
- 动作：打开 `easysdd/reference/code-dimensions.md`，按场景匹配默认组合，把偏离点和理由列给用户确认。确认后写进第 1 节"复杂度档位"子节，**只记偏离默认的维度**
|
||||
- 动作：打开 `codestable/reference/code-dimensions.md`，按场景匹配默认组合，把偏离点和理由列给用户确认。确认后写进第 1 节"复杂度档位"子节，**只记偏离默认的维度**
|
||||
- 无信号：第 1 节写一句"本 feature 走 {场景} 默认档位，无偏离"，不必打开档位表
|
||||
- **grep 找"叫法不同的类似模块"**
|
||||
- 触发：直觉本 feature "可能已经有人做过但命名不同"——常见于通用工具、抽象能力、跨模块功能
|
||||
- 动作：grep 几个同义词找候选模块，确认要不要扩展已有实现而不是另起一份
|
||||
- **归档检索**
|
||||
- 触发：关键词明显像以前沉淀过的东西（某决策、某坑、某探索结论、某历史 feature）
|
||||
- 动作：先一把搜 `python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{关键词}"`，命中后按 `doc_type=decision/trick/learning/explore` 过滤细看；历史 feature 同理——`python easysdd/tools/search-yaml.py --dir easysdd/features --filter doc_type=feature-design --query "{关键词}"`
|
||||
- 动作：先一把搜 `python codestable/tools/search-yaml.py --dir codestable/compound --query "{关键词}"`，命中后按 `doc_type=decision/trick/learning/explore` 过滤细看；历史 feature 同理——`python codestable/tools/search-yaml.py --dir codestable/features --filter doc_type=feature-design --query "{关键词}"`
|
||||
- 命中后优先复用，方案文件里记下引用来源
|
||||
|
||||
详细规则看 `easysdd/reference/shared-conventions.md` 第 5 节。
|
||||
详细规则看 `codestable/reference/shared-conventions.md` 第 5 节。
|
||||
|
||||
### 2. 想清楚这功能该放在哪儿
|
||||
|
||||
@@ -257,7 +257,7 @@ AI 在这一步默认会翻的车是**不思考就往眼前最顺手的文件里
|
||||
|
||||
### 6. 生成 {slug}-checklist.yaml
|
||||
|
||||
方案确认后，从 `{slug}-design.md` 里抽出行动清单，落到同目录 `{slug}-checklist.yaml`。这份清单的生命周期看 `easysdd/reference/shared-conventions.md`：本阶段负责生成，implement 只推进 `steps`，acceptance 只核对 `checks`。三个阶段各管一段，互不越界——这样每个阶段都能从 yaml 上看出自己的工作进度。
|
||||
方案确认后，从 `{slug}-design.md` 里抽出行动清单，落到同目录 `{slug}-checklist.yaml`。这份清单的生命周期看 `codestable/reference/shared-conventions.md`：本阶段负责生成，implement 只推进 `steps`，acceptance 只核对 `checks`。三个阶段各管一段，互不越界——这样每个阶段都能从 yaml 上看出自己的工作进度。
|
||||
|
||||
`{slug}-design.md` 和 `{slug}-checklist.yaml` 的完整模板、frontmatter 示例、节锚点、提取格式都在同目录 `reference.md` 里。本技能只保留提取原则：
|
||||
|
||||
@@ -310,9 +310,9 @@ AI 在这一步默认会翻的车是**不思考就往眼前最顺手的文件里
|
||||
- [ ] 用户确认通过后，frontmatter 的 `status` 改成了 `approved`
|
||||
- [ ] `{slug}-checklist.yaml` 已从 `{slug}-design.md` 抽出生成，且通过 `validate-yaml.py` 校验
|
||||
- [ ] `{slug}-checklist.yaml` 的 steps 条目数和第 3 节"实现提示"里推进顺序子节一致
|
||||
- [ ] 如果本 feature 从 roadmap 条目起头：frontmatter 带 `roadmap` / `roadmap_item` 字段；`easysdd/roadmap/{roadmap}/{roadmap}-items.yaml` 里对应条目 `status` 已改为 `in-progress`、`feature` 已填为 feature 目录名，且 yaml 已通过 `validate-yaml.py` 校验
|
||||
- [ ] 如果本 feature 从 roadmap 条目起头：frontmatter 带 `roadmap` / `roadmap_item` 字段；`codestable/roadmap/{roadmap}/{roadmap}-items.yaml` 里对应条目 `status` 已改为 `in-progress`、`feature` 已填为 feature 目录名，且 yaml 已通过 `validate-yaml.py` 校验
|
||||
|
||||
文件路径：方案文件在 `easysdd/features/{feature}/` 下；feature 目录不存在就在这一步建。命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节。
|
||||
文件路径：方案文件在 `codestable/features/{feature}/` 下；feature 目录不存在就在这一步建。命名约定看 `codestable/reference/shared-conventions.md` 第 0 节。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# feature-design 参考模板
|
||||
|
||||
本文件提供 `easysdd-feature-design` 使用的 `{slug}-design.md` / `{slug}-checklist.yaml` 参考格式。
|
||||
本文件提供 `cs-feat-design` 使用的 `{slug}-design.md` / `{slug}-checklist.yaml` 参考格式。
|
||||
|
||||
## 1. {slug}-design.md frontmatter
|
||||
|
||||
@@ -19,9 +19,9 @@ tags: [auth, email, login]
|
||||
|
||||
必填字段：`doc_type`、`feature`、`status`、`summary`、`tags`。
|
||||
|
||||
`requirement` 字段：填本 feature 对应的 requirement slug（`easysdd/requirements/{slug}.md` 去掉 `.md` 后缀）。纯重构 / 技术债 / 工具链改造类 feature 不新增用户可感能力，允许留空，但要在第 1 节"决策与约束"里明确写"本 feature 不新增能力，无对应 requirement"。
|
||||
`requirement` 字段：填本 feature 对应的 requirement slug（`codestable/requirements/{slug}.md` 去掉 `.md` 后缀）。纯重构 / 技术债 / 工具链改造类 feature 不新增用户可感能力，允许留空，但要在第 1 节"决策与约束"里明确写"本 feature 不新增能力，无对应 requirement"。
|
||||
|
||||
`roadmap` / `roadmap_item` 字段：只在本 feature 从 roadmap 条目起头时填，两个要么都填要么都空。填了的话 acceptance 阶段会据此自动回写 `easysdd/roadmap/{roadmap}/{roadmap}-items.yaml`。直接起 feature（未经 roadmap）不填这两个字段。
|
||||
`roadmap` / `roadmap_item` 字段：只在本 feature 从 roadmap 条目起头时填，两个要么都填要么都空。填了的话 acceptance 阶段会据此自动回写 `codestable/roadmap/{roadmap}/{roadmap}-items.yaml`。直接起 feature（未经 roadmap）不填这两个字段。
|
||||
|
||||
## 2. 顶层节锚点
|
||||
|
||||
@@ -65,7 +65,7 @@ checks:
|
||||
|
||||
- 需求摘要：做什么、为谁、成功标准、明确不做什么
|
||||
- 挂载点清单：逐条列出本 feature 往项目哪些位置挂入（新增 / 修改的路由、模块导入、配置项、数据库字段和表、定时任务、事件订阅、公共 UI 注入点、特性开关等）。每条格式：`{挂载位置}：{具体文件或配置 key} — {动作：新增 / 修改}`。粒度达到"照这份清单逆向可以完整拔除"。没有外部挂载的纯内部改动也要写一句说明
|
||||
- 复杂度档位：**只记偏离默认组合的维度**（默认组合在 `easysdd/reference/code-dimensions.md` 末尾的"常用默认组合"表里）。每条格式：`{维度名} = {档位}（偏离默认 {默认档位} 的原因：……）`。全部走默认时写一句"本 feature 走 {场景} 默认档位，无偏离"即可，不抄档位表。
|
||||
- 复杂度档位：**只记偏离默认组合的维度**（默认组合在 `codestable/reference/code-dimensions.md` 末尾的"常用默认组合"表里）。每条格式：`{维度名} = {档位}（偏离默认 {默认档位} 的原因：……）`。全部走默认时写一句"本 feature 走 {场景} 默认档位，无偏离"即可，不抄档位表。
|
||||
- 关键决策：选型/取舍/硬约束/被拒方案
|
||||
- 前置依赖（仅在步骤 3 评估出"目标文件结构性问题需要先解决"时写）：列出当前 feature 推进所必须先完成的独立 feature / 改动，以及"等前置完成后再推进"的状态
|
||||
- 主流程概述：正常路径 + 关键异常/边界
|
||||
|
||||
+17
-17
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: easysdd-feature-fastforward
|
||||
description: feature 流程的超轻量通道——不写 design、不写 checklist、不做分阶段 review，就让 AI 像平时一样直接动手写代码，但在动手前先告诉它项目里的 easysdd 知识库在哪、怎么搜，让它写出来的代码踩过的坑更少、和项目约定更一致。触发场景：用户说"快速模式"、"fastforward"、"别那么多步骤"、"直接开干"、"帮我做个 xxx"且需求小到不值得走 design 流程。
|
||||
name: cs-feat-ff
|
||||
description: feature 流程的超轻量通道——不写 design、不写 checklist、不做分阶段 review，就让 AI 像平时一样直接动手写代码，但在动手前先告诉它项目里的 CodeStable 知识库在哪、怎么搜，让它写出来的代码踩过的坑更少、和项目约定更一致。触发场景：用户说"快速模式"、"fastforward"、"别那么多步骤"、"直接开干"、"帮我做个 xxx"且需求小到不值得走 design 流程。
|
||||
---
|
||||
|
||||
# easysdd-feature-fastforward
|
||||
# cs-feat-ff
|
||||
|
||||
用户说"帮我做个 xxx"而且需求小的时候，本来 AI 就会直接动手写——这个技能**不改变这件事**。它只做一件事：在 AI 动手之前，把项目里已经沉淀的 easysdd 知识指给它，让它按需去搜，写出来的代码就能比裸写多一层保护。
|
||||
用户说"帮我做个 xxx"而且需求小的时候，本来 AI 就会直接动手写——这个技能**不改变这件事**。它只做一件事：在 AI 动手之前，把项目里已经沉淀的 CodeStable 知识指给它，让它按需去搜，写出来的代码就能比裸写多一层保护。
|
||||
|
||||
所以这个技能非常轻。没有 design doc、没有 checklist、没有验收清单、不需要用户确认。看完这份指引，该读代码读代码，该写代码写代码。
|
||||
|
||||
@@ -15,33 +15,33 @@ description: feature 流程的超轻量通道——不写 design、不写 checkl
|
||||
|
||||
项目里可能已经有前人沉淀的经验、决定、探索结果。写代码之前先按需搜一下，命中就省一堆坑。
|
||||
|
||||
### `easysdd/compound/` — 经验沉淀
|
||||
### `codestable/compound/` — 经验沉淀
|
||||
|
||||
放 learning（踩过的坑）/ trick（好用的做法）/ decision（拍板的技术决定）/ explore（定向调研结论）四类文档。文件名带 `doc_type`，可以按 type 和标签过滤。
|
||||
|
||||
```bash
|
||||
# 当前任务相关的踩坑记录
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --query "关键词"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --query "关键词"
|
||||
|
||||
# 看有没有相关的技术决定约束了这块怎么写
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --query "关键词"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --query "关键词"
|
||||
|
||||
# 看有没有现成的做法可以抄
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --query "关键词"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --query "关键词"
|
||||
```
|
||||
|
||||
### `easysdd/architecture/` — 架构全景
|
||||
### `codestable/architecture/` — 架构全景
|
||||
|
||||
`DESIGN.md` 是总入口，子系统拆到同目录下的其他 md 文件里。改到跨模块的东西前先看一眼相关子系统文档，避免违反既定边界。直接 `Read` 就行。
|
||||
|
||||
### `easysdd/tools/` — 共享脚本
|
||||
### `codestable/tools/` — 共享脚本
|
||||
|
||||
- `search-yaml.py` — YAML frontmatter 搜索（上面示范过），支持 `--filter`、`--query`、`--sort-by`
|
||||
- `validate-yaml.py` — YAML 语法校验，如果写了带 frontmatter 的文件就跑一下
|
||||
|
||||
用法细节在 `easysdd/reference/tools.md`。
|
||||
用法细节在 `codestable/reference/tools.md`。
|
||||
|
||||
### `easysdd/reference/` — 共享口径
|
||||
### `codestable/reference/` — 共享口径
|
||||
|
||||
- `shared-conventions.md` — feature / issue / compound 的目录结构、命名、元数据字段约定
|
||||
- `tools.md` — 上面两个脚本的完整用法
|
||||
@@ -127,16 +127,16 @@ python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=tri
|
||||
- 往 `utils.ts` / `helpers.ts` 这种万能 util 里继续堆东西
|
||||
- 要新起一个概念名（类型 / 函数 / 关键变量）时，先 `grep` 看有没有同名或近义的命名
|
||||
|
||||
完整清单看 `easysdd/reference/shared-conventions.md` 第 7 节（代码质量反射检查）。
|
||||
完整清单看 `codestable/reference/shared-conventions.md` 第 7 节（代码质量反射检查）。
|
||||
|
||||
---
|
||||
|
||||
## 不做什么
|
||||
|
||||
- **不写 design doc**——这是 fastforward 的整个意义所在。要 design 就去 `easysdd-feature-design`
|
||||
- **不写 design doc**——这是 fastforward 的整个意义所在。要 design 就去 `cs-feat-design`
|
||||
- **不写 checklist / acceptance**——同上
|
||||
- **不跟用户确认方案**——用户让你做小功能就是不想等你开会
|
||||
- **不在 `easysdd/` 里留下新文件**——除非写代码过程中发现了值得沉淀的坑或技巧，那另起一次对话用 `easysdd-learning` / `easysdd-tricks` 去写
|
||||
- **不在 `codestable/` 里留下新文件**——除非写代码过程中发现了值得沉淀的坑或技巧，那另起一次对话用 `cs-learn` / `cs-trick` 去写
|
||||
|
||||
---
|
||||
|
||||
@@ -146,10 +146,10 @@ python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=tri
|
||||
|
||||
- 改动涉及 3 个以上子系统
|
||||
- 发现需要引入新术语或和现有术语冲突
|
||||
- 要动 `easysdd/architecture/` 里既定的模块边界
|
||||
- 要动 `codestable/architecture/` 里既定的模块边界
|
||||
- 用户追加的要求让范围翻倍
|
||||
|
||||
切回完整流程的方式：触发 `easysdd-feature-design` 技能，从 design 阶段重新走。已经写了一部分代码没关系，在 design 里标注"已部分实现"即可。
|
||||
切回完整流程的方式：触发 `cs-feat-design` 技能，从 design 阶段重新走。已经写了一部分代码没关系，在 design 里标注"已部分实现"即可。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: easysdd-feature-implement
|
||||
name: cs-feat-impl
|
||||
description: feature 流程的阶段 2——按 {slug}-design.md 的推进顺序写代码，写完用统一格式做完成汇报给用户 review。前提是 {slug}-design.md 已经 approved（标准 design 含测试设计，或 fastforward design 含验收标准），并且同目录下有 {slug}-checklist.yaml。触发场景：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。实现中遇到方案没覆盖到的情况（新概念、范围外文件、需要打补丁分支）要主动停下来回到方案谈，不要硬冲。
|
||||
---
|
||||
|
||||
# easysdd-feature-implement
|
||||
# cs-feat-impl
|
||||
|
||||
到这一步用户已经在方案上签过字了，你的活是把方案变成代码。听起来直白，但实际容易出问题的不是写代码本身，而是**实现路上发现方案没覆盖到的情况时怎么办**——硬冲下去就把方案当摆设了，停下来回去谈又觉得麻烦。下面整套规则就是为了让"停下来"成为默认动作。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节。到这一步 feature 目录已经由 brainstorm 或 design 创建好。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md` 第 0 节。到这一步 feature 目录已经由 brainstorm 或 design 创建好。
|
||||
|
||||
---
|
||||
|
||||
@@ -65,15 +65,15 @@ description: feature 流程的阶段 2——按 {slug}-design.md 的推进顺序
|
||||
- 第 2 节（验收标准）每条可验证（操作步骤 + 期待结果）
|
||||
- 第 3 节（推进步骤）步骤明确，有退出信号
|
||||
|
||||
任一项不达标就停下来，告诉用户先回 `easysdd-feature-design` 补齐。原因是方案漏的项实现时一定要现场补——而现场补意味着用户没在方案上把过关，等于绕过了 checkpoint。
|
||||
任一项不达标就停下来，告诉用户先回 `cs-feat-design` 补齐。原因是方案漏的项实现时一定要现场补——而现场补意味着用户没在方案上把过关，等于绕过了 checkpoint。
|
||||
|
||||
### 2. {slug}-checklist.yaml 在不在、能不能用
|
||||
|
||||
`{slug}-checklist.yaml` 的生命周期看 `easysdd/reference/shared-conventions.md`。本阶段只消费并推进 `steps` 这一段：
|
||||
`{slug}-checklist.yaml` 的生命周期看 `codestable/reference/shared-conventions.md`。本阶段只消费并推进 `steps` 这一段：
|
||||
|
||||
- 文件存在，`feature` 字段跟当前 feature 目录一致
|
||||
- `steps` 列表非空，每条 status 为 `pending`（接续上次中断时部分会是 `done`，正常）
|
||||
- 不存在 → 停下来，让用户回 `easysdd-feature-design` 生成
|
||||
- 不存在 → 停下来，让用户回 `cs-feat-design` 生成
|
||||
|
||||
### 3. 把上下文读全
|
||||
|
||||
@@ -129,7 +129,7 @@ Fastforward design 没有正式的术语表，但同样的姿态适用：写到
|
||||
|
||||
### 代码质量反射检查
|
||||
|
||||
除了上面"不跳步 / 不改方案外 / 术语守护 / 不打补丁分支"这几条流程约束，还有一组针对代码质量的反射检查——看 `easysdd/reference/shared-conventions.md` 第 7 节。
|
||||
除了上面"不跳步 / 不改方案外 / 术语守护 / 不打补丁分支"这几条流程约束，还有一组针对代码质量的反射检查——看 `codestable/reference/shared-conventions.md` 第 7 节。
|
||||
|
||||
核心思路：**不是"超过 N 行必须拆"，而是"遇到 X 情况就停下来问自己"**。每条都对应一个 AI 默认会走进去的坑——往一个已经很长的文件里继续追加、往一个已经很重的类里再加方法、函数做的事越来越多但没拆、写 `if 这类用户特殊处理` 补丁分支、复制粘贴、加第 4+ 个参数、往万能 util 里堆东西。写代码过程中触发就停。
|
||||
|
||||
@@ -201,7 +201,7 @@ Fastforward design 没有正式的术语表，但同样的姿态适用：写到
|
||||
|
||||
## 退出后
|
||||
|
||||
告诉用户："所有步骤完成，方案 doc 已同步。下一步是阶段 3：验收闭环。可以触发 easysdd-feature-acceptance 技能。"
|
||||
告诉用户："所有步骤完成，方案 doc 已同步。下一步是阶段 3：验收闭环。可以触发 cs-feat-accept 技能。"
|
||||
|
||||
别自己顺手开始写验收报告——验收阶段需要独立的 checklist 节奏，提前进入会让验收的把关性失效。
|
||||
|
||||
|
||||
+30
-30
@@ -1,19 +1,19 @@
|
||||
---
|
||||
name: easysdd-feature
|
||||
name: cs-feat
|
||||
description: 做新功能开发时进入这套子流程——把"加个 X 能力"从模糊想法走到验收闭环，中间有方案文件做存档，AI 和用户后面回头都能查到当时怎么想的、为什么这样定的。触发场景偏向新增能力（"做新功能"、"加个 X"、"实现 XX"），不处理已有代码的 bug。本技能只做路由，根据已有产物决定下一步走 brainstorm / design / fastforward / implement / acceptance 中的哪一个。
|
||||
---
|
||||
|
||||
# easysdd-feature
|
||||
# cs-feat
|
||||
|
||||
新功能开发是 easysdd 里走得最完整的一条流程。AI 直接拿到需求就写代码，三个老问题会反复出现——名字跟原代码对不上、改着改着改出范围、改完不留存档。这条流程在"需求"和"代码"之间塞了一份方案文件，让两边都有个交接点。
|
||||
新功能开发是 CodeStable 里走得最完整的一条流程。AI 直接拿到需求就写代码，三个老问题会反复出现——名字跟原代码对不上、改着改着改出范围、改完不留存档。这条流程在"需求"和"代码"之间塞了一份方案文件，让两边都有个交接点。
|
||||
|
||||
整套流程是这样的：
|
||||
|
||||
```
|
||||
(想法还模糊时先去 easysdd-brainstorm 做分诊) → 方案设计（含测试设计）→ 分步实现 → 验收闭环
|
||||
(想法还模糊时先去 cs-brainstorm 做分诊) → 方案设计（含测试设计）→ 分步实现 → 验收闭环
|
||||
```
|
||||
|
||||
brainstorm 本身不在 feature 流程内部——它是讨论层的统一入口，会先分诊：你是 case 1（其实已经够清楚，直接进 design）、case 2（小需求方向定了，在 feature 里继续讨论并落 `{slug}-brainstorm.md`）、还是 case 3（大需求装不进一个 feature，移交给 `easysdd-roadmap` 拆解）。只有 case 2 才会真的在 `easysdd/features/{feature}/` 里产出 brainstorm note。
|
||||
brainstorm 本身不在 feature 流程内部——它是讨论层的统一入口，会先分诊：你是 case 1（其实已经够清楚，直接进 design）、case 2（小需求方向定了，在 feature 里继续讨论并落 `{slug}-brainstorm.md`）、还是 case 3（大需求装不进一个 feature，移交给 `cs-roadmap` 拆解）。只有 case 2 才会真的在 `codestable/features/{feature}/` 里产出 brainstorm note。
|
||||
|
||||
本技能本身不写代码、不写文档，只做一件事：看一下当前 feature 走到哪一步了，告诉用户该触发哪个子技能。
|
||||
|
||||
@@ -21,10 +21,10 @@ brainstorm 本身不在 feature 流程内部——它是讨论层的统一入口
|
||||
|
||||
## 文件放哪儿
|
||||
|
||||
整套 feature 流程的产物都聚在 `easysdd/features/` 下，每个 feature 一个独立目录：
|
||||
整套 feature 流程的产物都聚在 `codestable/features/` 下，每个 feature 一个独立目录：
|
||||
|
||||
```
|
||||
easysdd/
|
||||
codestable/
|
||||
└── features/
|
||||
└── {feature}/
|
||||
├── {slug}-brainstorm.md ← 阶段 0 的产物（可选，仅 brainstorm 判为 case 2 时才落盘）
|
||||
@@ -39,7 +39,7 @@ easysdd/
|
||||
- 日期取**首次创建当天**，定了就不动——后续 slug 改了，日期前缀也保持原样
|
||||
- slug 用小写字母、数字、连字符，简短能一眼看出做的是什么（`user-auth`、`export-csv` 这种）
|
||||
|
||||
为什么所有产物聚在一个目录？这样以后回头查"上次那个导出 CSV 的功能当时怎么决定的"，brainstorm、design、acceptance 都在一处，不用东找西找。这也是为什么 feature 和 issue 的产物分别放在 `easysdd/features/` 和 `easysdd/issues/`——两类问题的归档逻辑不一样，混在一起后面找东西会乱。
|
||||
为什么所有产物聚在一个目录？这样以后回头查"上次那个导出 CSV 的功能当时怎么决定的"，brainstorm、design、acceptance 都在一处，不用东找西找。这也是为什么 feature 和 issue 的产物分别放在 `codestable/features/` 和 `codestable/issues/`——两类问题的归档逻辑不一样，混在一起后面找东西会乱。
|
||||
|
||||
如果实现 feature 时顺手发现了一个 bug，正确做法是把它记成新的 issue，**不要在 feature 的 PR 里偷偷修**。混着改会让验收时分不清"这次新增的范围到底是哪些"，后面回头看也找不到为什么改了那行代码。
|
||||
|
||||
@@ -49,14 +49,14 @@ easysdd/
|
||||
|
||||
| 阶段 | 子技能 | 产出 | 谁主导 |
|
||||
|---|---|---|---|
|
||||
| 0 brainstorm（可选，独立入口） | `easysdd-brainstorm` | case 2 时产出 {slug}-brainstorm.md；case 1 / 3 不落盘 | AI 做思考伙伴，用户拍板 |
|
||||
| 1 方案设计 | `easysdd-feature-design` | {slug}-design.md + {slug}-checklist.yaml | AI 起草，用户整体 review |
|
||||
| 2 分步实现 | `easysdd-feature-implement` | 代码 + 阶段汇报 | AI 按方案执行 |
|
||||
| 3 验收闭环 | `easysdd-feature-acceptance` | {slug}-acceptance.md | AI 逐层核对，用户终审 |
|
||||
| 0 brainstorm（可选，独立入口） | `cs-brainstorm` | case 2 时产出 {slug}-brainstorm.md；case 1 / 3 不落盘 | AI 做思考伙伴，用户拍板 |
|
||||
| 1 方案设计 | `cs-feat-design` | {slug}-design.md + {slug}-checklist.yaml | AI 起草，用户整体 review |
|
||||
| 2 分步实现 | `cs-feat-impl` | 代码 + 阶段汇报 | AI 按方案执行 |
|
||||
| 3 验收闭环 | `cs-feat-accept` | {slug}-acceptance.md | AI 逐层核对，用户终审 |
|
||||
|
||||
阶段之间有人工 checkpoint。为什么要这样卡？一是让用户在每个阶段结束时有一次明确的把关机会，二是防止 AI 一口气从需求跑到代码、跑出来用户才发现走偏了。所以默认情况下，上一个阶段没拿到用户明确放行，下一个阶段就别开始。
|
||||
|
||||
阶段 0 是可选的，且是 feature 流程的**外部入口**——`easysdd-brainstorm` 同时服务 feature 和 roadmap。只有想法明显模糊时才走；已经能清楚说出"做什么、为谁做、怎么算成功"时直接从阶段 1 开始。brainstorm 判为 case 3（大需求）时讨论会被移交给 `easysdd-roadmap`，不再回到 feature 流程——等 roadmap 拆出子 feature 之后，每条子 feature 才会从 `easysdd-feature-design` 的"从 roadmap 条目起头"入口进来。
|
||||
阶段 0 是可选的，且是 feature 流程的**外部入口**——`cs-brainstorm` 同时服务 feature 和 roadmap。只有想法明显模糊时才走；已经能清楚说出"做什么、为谁做、怎么算成功"时直接从阶段 1 开始。brainstorm 判为 case 3（大需求）时讨论会被移交给 `cs-roadmap`，不再回到 feature 流程——等 roadmap 拆出子 feature 之后，每条子 feature 才会从 `cs-feat-design` 的"从 roadmap 条目起头"入口进来。
|
||||
|
||||
### Fastforward 模式
|
||||
|
||||
@@ -66,7 +66,7 @@ easysdd/
|
||||
用户说需求 → AI 写一份精简 {slug}-design.md（包含验收标准）→ 用户一次确认 → 直接实现
|
||||
```
|
||||
|
||||
触发：用户说"快速模式"、"fastforward"、"直接开干"、"别那么多步骤"这一类，去 `easysdd-feature-fastforward`。
|
||||
触发：用户说"快速模式"、"fastforward"、"直接开干"、"别那么多步骤"这一类，去 `cs-feat-ff`。
|
||||
|
||||
fastforward 的 `{slug}-design.md` 跟标准流程共用同一个 feature 目录，frontmatter 也一致，只是正文压成 4 节（需求摘要 + 设计方案 + 验收标准 + 推进步骤）。验收标准在这里就要写好，不留占位——因为后面 acceptance 阶段会直接从这里抽。
|
||||
|
||||
@@ -76,22 +76,22 @@ fastforward 的 `{slug}-design.md` 跟标准流程共用同一个 feature 目录
|
||||
|
||||
## 路由：用户现在该走哪个子技能
|
||||
|
||||
进入本技能后，先 Glob 一下 `easysdd/features/` 看已经有哪些产物。**不要只听用户口头描述**——用户说"设计写完了"不一定真完整，自己读一遍才有数。
|
||||
进入本技能后，先 Glob 一下 `codestable/features/` 看已经有哪些产物。**不要只听用户口头描述**——用户说"设计写完了"不一定真完整，自己读一遍才有数。
|
||||
|
||||
| 当前状态 | 触发哪个子技能 |
|
||||
|---|---|
|
||||
| 想法模糊，说不清真问题 / 边界 / 不做什么 | `easysdd-brainstorm`（判断方法见下） |
|
||||
| 想法清晰（知道做什么、为谁、怎么算成功） | `easysdd-feature-design` |
|
||||
| 用户说"开一个新需求 / 起个草稿 / 新建一个 feature"，想自己写半成品方案 | `easysdd-feature-design` 的"初始化模式"（建目录 + 空 `{slug}-intent.md`，让用户填完再回来） |
|
||||
| 用户主动说"先 brainstorm 一下"、"有个想法没想清楚" | `easysdd-brainstorm` |
|
||||
| `{slug}-intent.md` 已存在且填好，用户说可以进设计了 | `easysdd-feature-design`（读 intent 作输入） |
|
||||
| 用户说"快速模式"、"fastforward"等 | `easysdd-feature-fastforward` |
|
||||
| `{slug}-brainstorm.md` 已存在，用户说可以进设计了 | `easysdd-feature-design` |
|
||||
| `{slug}-design.md` 已 approved、代码还没动 | `easysdd-feature-implement` |
|
||||
| fastforward `{slug}-design.md` 已确认 | `easysdd-feature-implement` |
|
||||
| 代码已写完，要做验收 | `easysdd-feature-acceptance` |
|
||||
| 用户说的是"我想要一个 X 系统"这种大需求 | 转 `easysdd-brainstorm` 分诊（大概率判为 case 3 → `easysdd-roadmap`） |
|
||||
| roadmap 里某条子 feature 该启动了 | `easysdd-feature-design` 的"从 roadmap 条目起头"入口 |
|
||||
| 想法模糊，说不清真问题 / 边界 / 不做什么 | `cs-brainstorm`（判断方法见下） |
|
||||
| 想法清晰（知道做什么、为谁、怎么算成功） | `cs-feat-design` |
|
||||
| 用户说"开一个新需求 / 起个草稿 / 新建一个 feature"，想自己写半成品方案 | `cs-feat-design` 的"初始化模式"（建目录 + 空 `{slug}-intent.md`，让用户填完再回来） |
|
||||
| 用户主动说"先 brainstorm 一下"、"有个想法没想清楚" | `cs-brainstorm` |
|
||||
| `{slug}-intent.md` 已存在且填好，用户说可以进设计了 | `cs-feat-design`（读 intent 作输入） |
|
||||
| 用户说"快速模式"、"fastforward"等 | `cs-feat-ff` |
|
||||
| `{slug}-brainstorm.md` 已存在，用户说可以进设计了 | `cs-feat-design` |
|
||||
| `{slug}-design.md` 已 approved、代码还没动 | `cs-feat-impl` |
|
||||
| fastforward `{slug}-design.md` 已确认 | `cs-feat-impl` |
|
||||
| 代码已写完，要做验收 | `cs-feat-accept` |
|
||||
| 用户说的是"我想要一个 X 系统"这种大需求 | 转 `cs-brainstorm` 分诊（大概率判为 case 3 → `cs-roadmap`） |
|
||||
| roadmap 里某条子 feature 该启动了 | `cs-feat-design` 的"从 roadmap 条目起头"入口 |
|
||||
| 不确定 `{slug}-design.md` 是否完整 | 自己读一遍，按上面对号入座 |
|
||||
|
||||
### 怎么判断用户该不该走阶段 0
|
||||
@@ -108,7 +108,7 @@ fastforward 的 `{slug}-design.md` 跟标准流程共用同一个 feature 目录
|
||||
|
||||
两者都是 design 的前置，区别在**谁在主导收敛**：
|
||||
|
||||
- brainstorm：用户脑子里还模糊，希望通过对话想清楚，AI 问用户答。**注意**：brainstorm 是独立入口，会先分诊；判为 case 3（大需求）时讨论会被移交给 `easysdd-roadmap`，不会回到 feature 流程。只有 case 2（小需求）才产出 `{slug}-brainstorm.md`
|
||||
- brainstorm：用户脑子里还模糊，希望通过对话想清楚，AI 问用户答。**注意**：brainstorm 是独立入口，会先分诊；判为 case 3（大需求）时讨论会被移交给 `cs-roadmap`，不会回到 feature 流程。只有 case 2（小需求）才产出 `{slug}-brainstorm.md`
|
||||
- intent：用户自己已经想好大致做法（比如一段 100 字的描述 + 相关数据结构），只是懒得口述，直接写成 `{slug}-intent.md` 给 AI 读
|
||||
|
||||
用户说"开一个新需求"这种模糊触发时，默认问一句"你想先聊清楚（brainstorm）还是自己写草稿（intent）？"，别自己挑一个推进。
|
||||
@@ -126,7 +126,7 @@ fastforward 的 `{slug}-design.md` 跟标准流程共用同一个 feature 目录
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `easysdd/reference/system-overview.md` — easysdd 体系总览和场景路由
|
||||
- `easysdd/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、{slug}-checklist.yaml 生命周期
|
||||
- `codestable/reference/system-overview.md` — CodeStable 体系总览和场景路由
|
||||
- `codestable/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、{slug}-checklist.yaml 生命周期
|
||||
- `AGENTS.md` — 全项目代码规范，feature 实现时同样遵守
|
||||
- 项目架构总入口 — 方案设计阶段需要查
|
||||
|
||||
+14
-14
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-guidedoc
|
||||
name: cs-guide
|
||||
description: 给项目写或更新对外的指南文档——开发者指南（dev-guide，给贡献者 / 集成方 / 下游开发者读）和用户指南（user-guide，给终端用户读）。产物落到项目 docs/ 目录，跟代码一起维护，可被搜索工具检索。和 libdoc 的区别：guidedoc 是任务导向（"如何用 X 做 Y"），libdoc 是参考导向（"X 的每个零件长什么样"）。触发场景：用户说"写文档"、"开发者指南"、"用户指南"，或 feature-acceptance 收尾时主动推送。
|
||||
---
|
||||
|
||||
# easysdd-guidedoc
|
||||
# cs-guide
|
||||
|
||||
代码解决问题，文档让别人能用它解决问题。spec 文件记录了"做了什么、为什么这么做"，但下游开发者和终端用户不需要、也不应该读 spec——他们需要的是面向自己角色的、可发布的指南。
|
||||
|
||||
@@ -28,7 +28,7 @@ guidedoc 就是从 spec 和代码出发，写成读者真正能用的指南。
|
||||
|
||||
| 情境 | 说明 |
|
||||
|---|---|
|
||||
| feature-acceptance 结束 | 按 `easysdd/reference/shared-conventions.md` 主动推：方案 doc 第 2 节（接口契约）有变更就问"需要更新 dev-guide 吗？"，方案 doc 第 1 节（用户可见行为）有变更就问"需要更新 user-guide 吗？" |
|
||||
| feature-acceptance 结束 | 按 `codestable/reference/shared-conventions.md` 主动推：方案 doc 第 2 节（接口契约）有变更就问"需要更新 dev-guide 吗？"，方案 doc 第 1 节（用户可见行为）有变更就问"需要更新 user-guide 吗？" |
|
||||
| 用户主动触发 | "写文档"、"guidedoc"、"补一份开发者指南" |
|
||||
| onboarding 完成后 | 新仓库可触发本工作流补全基础文档骨架 |
|
||||
|
||||
@@ -38,7 +38,7 @@ guidedoc 就是从 spec 和代码出发，写成读者真正能用的指南。
|
||||
|
||||
## 涉及路径
|
||||
|
||||
guidedoc 产物**不在 `easysdd/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。
|
||||
guidedoc 产物**不在 `codestable/` 下**——指南是面向外部读者的可发布产物，和 spec 工件分开。
|
||||
|
||||
- dev-guide → `docs/dev/{slug}.md`
|
||||
- user-guide → `docs/user/{slug}.md`
|
||||
@@ -48,8 +48,8 @@ guidedoc 产物**不在 `easysdd/` 下**——指南是面向外部读者的可
|
||||
检索已有指南：
|
||||
|
||||
```
|
||||
python easysdd/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
|
||||
python easysdd/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}
|
||||
python codestable/tools/search-yaml.py --dir docs/dev --filter doc_type=dev-guide --filter status=current
|
||||
python codestable/tools/search-yaml.py --dir docs/user --filter doc_type=user-guide --filter component={feature-slug}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -175,13 +175,13 @@ A: ...
|
||||
|
||||
| 来源 | 关系 |
|
||||
|---|---|
|
||||
| `easysdd-feature-acceptance` | 验收后按 `shared-conventions.md` 主动推：接口变更推 dev-guide，用户可见行为变更推 user-guide |
|
||||
| `easysdd-feature-design` | 方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源 |
|
||||
| `easysdd-onboarding` | 新仓库接入后可补全基础文档骨架 |
|
||||
| `easysdd-architecture` (check 模式) | 检测到 design 与代码不一致时，对应 guide 应同步标 `outdated` |
|
||||
| `easysdd-decisions` | dev-guide 引用的技术选型应来自 decisions，不独立发明 |
|
||||
| `easysdd-tricks` | dev-guide 用法示例若与 tricks 重合，交叉引用而不重复写 |
|
||||
| `easysdd-libdoc` | guide 引用 libdoc 条目做详细参考；libdoc 是零件参考，guidedoc 是任务教程 |
|
||||
| `cs-feat-accept` | 验收后按 `shared-conventions.md` 主动推：接口变更推 dev-guide，用户可见行为变更推 user-guide |
|
||||
| `cs-feat-design` | 方案第 2 节是 dev-guide 主要信息源；第 1 节是 user-guide 主要信息源 |
|
||||
| `cs-onboard` | 新仓库接入后可补全基础文档骨架 |
|
||||
| `cs-arch` (check 模式) | 检测到 design 与代码不一致时，对应 guide 应同步标 `outdated` |
|
||||
| `cs-decide` | dev-guide 引用的技术选型应来自 decisions，不独立发明 |
|
||||
| `cs-trick` | dev-guide 用法示例若与 tricks 重合，交叉引用而不重复写 |
|
||||
| `cs-libdoc` | guide 引用 libdoc 条目做详细参考；libdoc 是零件参考，guidedoc 是任务教程 |
|
||||
|
||||
---
|
||||
|
||||
@@ -192,4 +192,4 @@ A: ...
|
||||
- ❌ guide 写完 `status` 还是 `draft`——落盘必须改 `current`
|
||||
- ❌ 代码已更新，相关 guide 还是 `current`——应标 `outdated` 并推送更新
|
||||
- ❌ dev-guide 和 user-guide 内容高度重叠——重叠说明其中一份定位有误
|
||||
- ❌ 用 guide 存放 spec 信息（不变量、测试约束、根因分析）——这类内容属于 `easysdd/`
|
||||
- ❌ 用 guide 存放 spec 信息（不变量、测试约束、根因分析）——这类内容属于 `codestable/`
|
||||
|
||||
+11
-11
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: easysdd-issue-analyze
|
||||
description: issue 流程的阶段 2——读问题报告 + 读代码，找到真正的根因并评估修复风险，最后给用户 2-3 种修复方案选项让 TA 拍板。这一阶段**不是开始改代码**——分析完先给用户看结论，用户确认方案后才进阶段 3。前置依赖 easysdd-issue-report 已完成。触发场景：用户说"分析这个 bug"、"找根因"、"定位问题"，且 issue 目录下已有 {slug}-report.md。
|
||||
name: cs-issue-analyze
|
||||
description: issue 流程的阶段 2——读问题报告 + 读代码，找到真正的根因并评估修复风险，最后给用户 2-3 种修复方案选项让 TA 拍板。这一阶段**不是开始改代码**——分析完先给用户看结论，用户确认方案后才进阶段 3。前置依赖 cs-issue-report 已完成。触发场景：用户说"分析这个 bug"、"找根因"、"定位问题"，且 issue 目录下已有 {slug}-report.md。
|
||||
---
|
||||
|
||||
# easysdd-issue-analyze
|
||||
# cs-issue-analyze
|
||||
|
||||
到这一步用户已经把问题描述清楚了，你的活是**通过实际读代码找到根因**——不是在脑子里推断、不是在报告基础上猜。读代码是这一阶段的核心动作，跳过它写出来的分析没价值。
|
||||
|
||||
分析完不是直接动手——给用户看 2-3 种修复方案，让 TA 选。原因：根因往往有多种修法，影响面、副作用、改动范围各不相同，这是用户该拍板的事，不是 AI 该替 TA 决定的。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节和 `easysdd-issue` 的"文件放哪儿"节。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"节。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,9 +17,9 @@ description: issue 流程的阶段 2——读问题报告 + 读代码，找到
|
||||
|
||||
### 1. 问题报告存在且已确认
|
||||
|
||||
读 issue 目录下的 `{slug}-report.md`，确认 frontmatter 有 `doc_type=issue-report` 且 `status=confirmed`，5 节都有内容。不完整或 status 不是 confirmed 就先回 `easysdd-issue-report`。
|
||||
读 issue 目录下的 `{slug}-report.md`，确认 frontmatter 有 `doc_type=issue-report` 且 `status=confirmed`，5 节都有内容。不完整或 status 不是 confirmed 就先回 `cs-issue-report`。
|
||||
|
||||
如果 `easysdd-issue-report` 已判定走标准路径，本阶段按标准路径完成根因分析，不再二次改判快速通道。
|
||||
如果 `cs-issue-report` 已判定走标准路径，本阶段按标准路径完成根因分析，不再二次改判快速通道。
|
||||
|
||||
### 2. 断点恢复
|
||||
|
||||
@@ -33,9 +33,9 @@ description: issue 流程的阶段 2——读问题报告 + 读代码，找到
|
||||
- 问题报告全文
|
||||
- `AGENTS.md`
|
||||
- 报告里提到的相关文件（用 Glob / Grep 找，别只凭 report 里的描述）
|
||||
- `easysdd/architecture/DESIGN.md`（如果涉及跨模块问题）
|
||||
- **归档检索（按需）**——只在问题涉及的模块曾有归档记录时才搜（目录为空或与问题无关就跳过）。统一搜 `easysdd/compound/`，按需用 `doc_type` 过滤：
|
||||
- 一把搜：`python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{issue 关键词}"`
|
||||
- `codestable/architecture/DESIGN.md`（如果涉及跨模块问题）
|
||||
- **归档检索（按需）**——只在问题涉及的模块曾有归档记录时才搜（目录为空或与问题无关就跳过）。统一搜 `codestable/compound/`，按需用 `doc_type` 过滤：
|
||||
- 一把搜：`python codestable/tools/search-yaml.py --dir codestable/compound --query "{issue 关键词}"`
|
||||
- 只看技巧：追加 `--filter doc_type=trick --filter status=active` —— 命中则在分析开头标注引用
|
||||
- 只看探索：追加 `--filter doc_type=explore` —— 命中则标注历史探索结论
|
||||
- 只看经验（pitfall）：追加 `--filter doc_type=learning --filter track=pitfall` —— 命中则标注历史 pitfall
|
||||
@@ -99,7 +99,7 @@ description: issue 流程的阶段 2——读问题报告 + 读代码，找到
|
||||
|
||||
## 根因分析模板
|
||||
|
||||
分析完写进文件（路径见 `easysdd-issue` 的"文件放哪儿"节）：
|
||||
分析完写进文件（路径见 `cs-issue` 的"文件放哪儿"节）：
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -192,7 +192,7 @@ tags: []
|
||||
|
||||
## 退出后
|
||||
|
||||
告诉用户："根因分析已就绪，方案已确认。下一步是阶段 3：修复验证。可以触发 `easysdd-issue-fix` 技能开始修复。"
|
||||
告诉用户："根因分析已就绪，方案已确认。下一步是阶段 3：修复验证。可以触发 `cs-issue-fix` 技能开始修复。"
|
||||
|
||||
别自己顺手开始改代码——理由跟其他阶段一样：跨阶段无停顿地往下跑会让用户来不及把关。
|
||||
|
||||
|
||||
+17
-17
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: easysdd-issue-fix
|
||||
description: issue 流程的阶段 3——按已确认根因和方案定点修复代码，验证效果，写 {slug}-fix-note.md 落档。这是 issue 工作流的收尾——没有验证闭环 = 工作流未完成。两个入口：标准路径从 easysdd-issue-analyze 触发（已有 {slug}-analysis.md），快速通道从 easysdd-issue-report 直接触发（无 {slug}-analysis.md，根因在 report 阶段已被 AI 读代码确定）。触发场景：用户说"开始修 bug"、"按分析修"、"动手改代码"。修复时只动方案声明的文件，不顺手优化、不引入新抽象——这些动作都会让范围扩散到不可追溯。
|
||||
name: cs-issue-fix
|
||||
description: issue 流程的阶段 3——按已确认根因和方案定点修复代码，验证效果，写 {slug}-fix-note.md 落档。这是 issue 工作流的收尾——没有验证闭环 = 工作流未完成。两个入口：标准路径从 cs-issue-analyze 触发（已有 {slug}-analysis.md），快速通道从 cs-issue-report 直接触发（无 {slug}-analysis.md，根因在 report 阶段已被 AI 读代码确定）。触发场景：用户说"开始修 bug"、"按分析修"、"动手改代码"。修复时只动方案声明的文件，不顺手优化、不引入新抽象——这些动作都会让范围扩散到不可追溯。
|
||||
---
|
||||
|
||||
# easysdd-issue-fix
|
||||
# cs-issue-fix
|
||||
|
||||
到这一步根因和方案已经确定（标准路径在 `{slug}-analysis.md` 里、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。
|
||||
|
||||
听起来直白，但 fix 阶段最容易出问题的不是改代码本身，而是**改的过程中冒出的"顺手"冲动**——顺手优化一下、顺手重构一点、顺手加个抽象。每一项单独看都说得通，但合在一个 PR 里就让别人分不清"这次到底为了修 bug 改了什么"。下面所有规则的目的都是让这种冲动停下来。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节和 `easysdd-issue` 的"文件放哪儿"节。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"节。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,12 +23,12 @@ description: issue 流程的阶段 3——按已确认根因和方案定点修
|
||||
- 问题报告全文
|
||||
- 根因分析第 1 节定位到的所有代码文件
|
||||
- `AGENTS.md`
|
||||
- 沉淀目录里与本 issue 相关的记录（统一搜 `easysdd/compound/`，按需用 `doc_type` 过滤）：
|
||||
- 查技巧：`python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter status=active --query "{issue 关键词}"`——确认修复方式不违背已有库用法 / 模式建议
|
||||
- 查探索：`python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{issue 关键词}"`——确认修复点与已有证据不冲突
|
||||
- 沉淀目录里与本 issue 相关的记录（统一搜 `codestable/compound/`，按需用 `doc_type` 过滤）：
|
||||
- 查技巧：`python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active --query "{issue 关键词}"`——确认修复方式不违背已有库用法 / 模式建议
|
||||
- 查探索：`python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{issue 关键词}"`——确认修复点与已有证据不冲突
|
||||
3. **确认修复起点**——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手
|
||||
|
||||
### 快速通道入口（无 {slug}-analysis.md，从 easysdd-issue-report 直接触发）
|
||||
### 快速通道入口（无 {slug}-analysis.md，从 cs-issue-report 直接触发）
|
||||
|
||||
进入这个入口时，AI 在 report 阶段已经读过代码并对根因有把握。
|
||||
|
||||
@@ -36,7 +36,7 @@ description: issue 流程的阶段 3——按已确认根因和方案定点修
|
||||
2. **给出修复方案**——改哪里、怎么改（一两句话即可，不写成完整分析文档）
|
||||
3. **等用户明确说"对，就这样改"后才动手**——不允许"我觉得对，直接改了"
|
||||
4. 读 `AGENTS.md`
|
||||
5. **补搜沉淀目录**——快速通道也要用 `search-yaml.py --dir easysdd/compound` 查一遍，`--filter doc_type=trick` 看同类技巧，`--filter doc_type=explore` 避免误把已知边界条件当成新问题
|
||||
5. **补搜沉淀目录**——快速通道也要用 `search-yaml.py --dir codestable/compound` 查一遍，`--filter doc_type=trick` 看同类技巧，`--filter doc_type=explore` 避免误把已知边界条件当成新问题
|
||||
|
||||
---
|
||||
|
||||
@@ -62,7 +62,7 @@ description: issue 流程的阶段 3——按已确认根因和方案定点修
|
||||
|
||||
### 代码质量反射检查
|
||||
|
||||
修 bug 看似动作小，但 AI 写修复代码时一样会漂——在已经很长的文件里再塞一段特殊处理、在已经很重的类里再加一个方法、为了绕开某种边界情况加一个 `if` 分支。反射检查见 `easysdd/reference/shared-conventions.md` 第 7 节。
|
||||
修 bug 看似动作小，但 AI 写修复代码时一样会漂——在已经很长的文件里再塞一段特殊处理、在已经很重的类里再加一个方法、为了绕开某种边界情况加一个 `if` 分支。反射检查见 `codestable/reference/shared-conventions.md` 第 7 节。
|
||||
|
||||
issue-fix 下这一节要比 feature-implement 更谨慎：**触发了反射信号但结论是"该拆"时，默认不在本次 PR 里做**——按"改动最小化"的逻辑记成顺手发现，另开工作收拾。唯一例外是"不拆就没法干净地修这个 bug"，那就停下来跟用户明确"修这个 bug 的前置是 {重构动作}，要不要合进来还是拆出去单独做"。
|
||||
|
||||
@@ -96,7 +96,7 @@ issue-fix 下这一节要比 feature-implement 更谨慎：**触发了反射信
|
||||
|
||||
## 写 {slug}-fix-note.md
|
||||
|
||||
验证通过后在 issue 目录下建 `{slug}-fix-note.md`（位置见 `easysdd-issue` 的"文件放哪儿"节），记录本次修复的完整闭环。标准路径模板和快速通道模板都在同目录 `reference.md`。
|
||||
验证通过后在 issue 目录下建 `{slug}-fix-note.md`（位置见 `cs-issue` 的"文件放哪儿"节），记录本次修复的完整闭环。标准路径模板和快速通道模板都在同目录 `reference.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -113,7 +113,7 @@ issue-fix 下这一节要比 feature-implement 更谨慎：**触发了反射信
|
||||
|
||||
## 收尾提交
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
|
||||
按 `codestable/reference/shared-conventions.md` 第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：
|
||||
|
||||
- **提交范围**：修复代码、`{slug}-fix-note.md`，以及本次确实一并更新的 `{slug}-report.md` / `{slug}-analysis.md`
|
||||
- 修复闭环后告诉用户"修复验证已完成，`{slug}-fix-note.md` 已落盘"，紧接着问是否需要 commit
|
||||
@@ -124,18 +124,18 @@ issue-fix 下这一节要比 feature-implement 更谨慎：**触发了反射信
|
||||
|
||||
告诉用户："issue 修复完成，工作流闭环。问题报告（{slug}-report.md）+ 根因分析（{slug}-analysis.md）+ 修复记录（{slug}-fix-note.md）已存档。"
|
||||
|
||||
然后按 `easysdd/reference/shared-conventions.md` 第 3 节"issue-fix"收尾推荐顺序各问一句话（用户说"不用"立刻跳过）：
|
||||
然后按 `codestable/reference/shared-conventions.md` 第 3 节"issue-fix"收尾推荐顺序各问一句话（用户说"不用"立刻跳过）：
|
||||
|
||||
1. 这次修复暴露了值得复用的坑点 / 经验 → "需要把这个坑沉淀成 learning 文档吗？（走 `easysdd-learning`，会写入 `easysdd/compound/`）"
|
||||
2. 这次修复沉淀出了长期约束、规约或技术决定 → "需要把这条决定归档吗？（走 `easysdd-decisions`）"
|
||||
1. 这次修复暴露了值得复用的坑点 / 经验 → "需要把这个坑沉淀成 learning 文档吗？（走 `cs-learn`，会写入 `codestable/compound/`）"
|
||||
2. 这次修复沉淀出了长期约束、规约或技术决定 → "需要把这条决定归档吗？（走 `cs-decide`）"
|
||||
3. 最后补问一次是否需要代为提交本次修复。用户同意时按收尾提交规则执行到 commit 完成。
|
||||
|
||||
可以建议：
|
||||
|
||||
- 把 issue 目录下的文件和代码改动放在同一次提交里，方便日后追溯
|
||||
- "顺手发现"的后续 issue 另开一轮 `easysdd-issue-report` 处理，别在这个 PR 里塞
|
||||
- "顺手发现"的后续 issue 另开一轮 `cs-issue-report` 处理，别在这个 PR 里塞
|
||||
|
||||
如果修复过程中发现问题实际上是功能缺失（不是 bug），建议用户另开 `easysdd-feature` 工作流处理，别在 issue 工作流里偷偷做新功能。
|
||||
如果修复过程中发现问题实际上是功能缺失（不是 bug），建议用户另开 `cs-feat` 工作流处理，别在 issue 工作流里偷偷做新功能。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# issue-fix 参考模板
|
||||
|
||||
本文件提供 `easysdd-issue-fix` 使用的修复汇报模板、日志调试脚手架和 `{slug}-fix-note.md` 模板。
|
||||
本文件提供 `cs-issue-fix` 使用的修复汇报模板、日志调试脚手架和 `{slug}-fix-note.md` 模板。
|
||||
|
||||
## 1. 修复汇报模板
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
5. 清理日志打点
|
||||
6. 以修订后的根因重新进入修复流程
|
||||
|
||||
如果经过 2 轮日志调试仍未定位到根因，建议回到 `easysdd-issue-analyze`。
|
||||
如果经过 2 轮日志调试仍未定位到根因，建议回到 `cs-issue-analyze`。
|
||||
|
||||
### 用户取日志提示词
|
||||
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: easysdd-issue-report
|
||||
name: cs-issue-report
|
||||
description: issue 流程的阶段 1——通过对话把用户脑子里的问题落成可复现、可追溯的 {slug}-report.md。AI 在这里只问"看到了什么、怎么复现、应该怎样"，不替用户猜根因（那是阶段 2 的事）。同时这一阶段是判断走快速通道还是标准路径的唯一正式判定点：根据用户描述先读一下相关代码，能一眼定位且改动小就直接告知用户走快速通道。触发场景：用户说"提个 issue"、"记录这个 bug"、"我发现一个问题"。issue 工作流的起点，无前置依赖。
|
||||
---
|
||||
|
||||
# easysdd-issue-report
|
||||
# cs-issue-report
|
||||
|
||||
这一阶段做两件事：把用户脑子里的问题落成结构化记录，顺便判断这个问题该走标准路径还是快速通道。
|
||||
|
||||
写报告的部分有一条核心原则：**只记现象不记根因**。用户开始说"我觉得是 XX 组件的问题"时——记下"用户怀疑 XX 组件"作为线索，但不要顺着聊根因。根因要在阶段 2 通过实际读代码确认，不靠脑子里的猜测。混进根因猜测的报告会带偏阶段 2 的分析方向，让分析人围着错误线索绕。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md` 第 0 节和 `easysdd-issue` 的"文件放哪儿"节。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md` 第 0 节和 `cs-issue` 的"文件放哪儿"节。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,17 +17,17 @@ description: issue 流程的阶段 1——通过对话把用户脑子里的问
|
||||
|
||||
### 1. 确认是 bug 不是新功能需求
|
||||
|
||||
如果用户描述的是"想加一个 X 功能"，告诉他走 `easysdd-feature` 工作流。
|
||||
如果用户描述的是"想加一个 X 功能"，告诉他走 `cs-feat` 工作流。
|
||||
|
||||
### 2. 看有没有相关 issue 目录
|
||||
|
||||
Glob `easysdd/issues/` 下的子目录，看有没有同类问题已经记录过。有的话先和用户确认是新建还是更新已有 report。
|
||||
Glob `codestable/issues/` 下的子目录，看有没有同类问题已经记录过。有的话先和用户确认是新建还是更新已有 report。
|
||||
|
||||
### 3. 快速通道判断（这是唯一正式判定点）
|
||||
|
||||
根据用户描述的线索先**读一下相关代码**（用 Grep / Read 定位），判断能不能一眼确定根因：
|
||||
|
||||
- **能**——根因明确（能给出 `{文件}:{行号}`）、修复改动小（1-2 处）、无跨模块影响风险 → 告诉用户："我已经看到问题所在，可以走快速通道：直接告知根因和修复方案，你确认后我立刻修，修完你验证，然后只写一份 `{slug}-fix-note.md`。" 用户同意后触发 `easysdd-issue-fix`（快速通道模式）。
|
||||
- **能**——根因明确（能给出 `{文件}:{行号}`）、修复改动小（1-2 处）、无跨模块影响风险 → 告诉用户："我已经看到问题所在，可以走快速通道：直接告知根因和修复方案，你确认后我立刻修，修完你验证，然后只写一份 `{slug}-fix-note.md`。" 用户同意后触发 `cs-issue-fix`（快速通道模式）。
|
||||
- **不能**——根因有多个候选 / 不确定 / 需要更多复现信息 → 继续走下面的标准路径，做完整问题报告。进入标准路径后默认不再二次改判。
|
||||
|
||||
### 4. 确定 issue 目录名
|
||||
@@ -93,7 +93,7 @@ Glob `easysdd/issues/` 下的子目录，看有没有同类问题已经记录过
|
||||
|
||||
## 问题报告模板
|
||||
|
||||
回答完后写进文件（路径见 `easysdd-issue` 的"文件放哪儿"节）：
|
||||
回答完后写进文件（路径见 `cs-issue` 的"文件放哪儿"节）：
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -160,7 +160,7 @@ tags: []
|
||||
|
||||
## 退出后
|
||||
|
||||
告诉用户："问题报告已就绪。下一步是阶段 2：根因分析。可以触发 `easysdd-issue-analyze` 技能开始分析。"
|
||||
告诉用户："问题报告已就绪。下一步是阶段 2：根因分析。可以触发 `cs-issue-analyze` 技能开始分析。"
|
||||
|
||||
别自己顺手开始分析根因——阶段间的人工 checkpoint 是工作流的硬约束。
|
||||
|
||||
|
||||
+18
-18
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-issue
|
||||
name: cs-issue
|
||||
description: 修 bug 时进入这套子流程——把"发现了问题"从口头描述走到验证修复的闭环，中间留下问题报告、根因分析、修复记录三份文件。这条流程在"看到问题"和"动手改代码"之间加了一层缓冲，避免常见的几种翻车：脑子里的问题描述改完就消失、没分析根因就动手只改了表面、修复范围扩散没法追溯、改完没验证不知道改对了没。本技能只做路由，根据已有产物决定走 report / analyze / fix 中的哪一个。问题简单一眼能定位的会走快速通道，跳过中间两步只留 fix-note。
|
||||
---
|
||||
|
||||
# easysdd-issue
|
||||
# cs-issue
|
||||
|
||||
修 bug 直觉上是"找到错的地方改了就完事"，但这个直觉路径反复制造同样的麻烦：
|
||||
|
||||
@@ -24,10 +24,10 @@ issue 工作流在"看到问题"和"动手改代码"之间塞了一道缓冲：
|
||||
|
||||
## 文件放哪儿
|
||||
|
||||
整套 issue 流程的产物聚在 `easysdd/issues/` 下，每个 issue 一个独立目录：
|
||||
整套 issue 流程的产物聚在 `codestable/issues/` 下，每个 issue 一个独立目录：
|
||||
|
||||
```
|
||||
easysdd/
|
||||
codestable/
|
||||
└── issues/
|
||||
└── {issue}/
|
||||
├── {slug}-report.md ← 阶段 1 的问题报告
|
||||
@@ -40,7 +40,7 @@ easysdd/
|
||||
- 日期取**发现 / 提报问题当天**，定了不动
|
||||
- slug 用小写字母、数字、连字符，能一眼看出是什么问题（`auth-token-leak`、`null-pointer-on-empty-list` 这种）
|
||||
|
||||
为什么所有产物聚在一起？跟 feature 一样的逻辑——后人查"上次那个 bug 当时怎么定位的"，三份文件都在一处不用东找。issue 和 feature 的目录分别在 `easysdd/issues/` 和 `easysdd/features/`，别交叉。
|
||||
为什么所有产物聚在一起？跟 feature 一样的逻辑——后人查"上次那个 bug 当时怎么定位的"，三份文件都在一处不用东找。issue 和 feature 的目录分别在 `codestable/issues/` 和 `codestable/features/`，别交叉。
|
||||
|
||||
`{slug}-fix-note.md` 是阶段 3 的**必出产物**——无论修复简单还是复杂都要写。修复记录不是仪式，是回溯凭证：没有它，下次类似问题来了你只能从 git log 里反推当时改了什么。
|
||||
|
||||
@@ -54,9 +54,9 @@ easysdd/
|
||||
|
||||
| 阶段 | 子技能 | 主导者 | 产出 |
|
||||
|---|---|---|---|
|
||||
| 1 问题报告 | `easysdd-issue-report` | 用户描述，AI 引导结构化 | `{slug}-report.md` |
|
||||
| 2 根因分析 | `easysdd-issue-analyze` | AI 读代码分析，用户确认 | `{slug}-analysis.md` |
|
||||
| 3 修复验证 | `easysdd-issue-fix` | AI 按分析定点修复，用户验证 | 代码修复 + `{slug}-fix-note.md` + 收尾提交确认 |
|
||||
| 1 问题报告 | `cs-issue-report` | 用户描述，AI 引导结构化 | `{slug}-report.md` |
|
||||
| 2 根因分析 | `cs-issue-analyze` | AI 读代码分析，用户确认 | `{slug}-analysis.md` |
|
||||
| 3 修复验证 | `cs-issue-fix` | AI 按分析定点修复，用户验证 | 代码修复 + `{slug}-fix-note.md` + 收尾提交确认 |
|
||||
|
||||
阶段间有人工 checkpoint，理由跟 feature 一样：让用户在每个阶段结束有一次明确把关，防止 AI 一口气从问题跑到代码、跑出来用户才发现走偏。
|
||||
|
||||
@@ -76,7 +76,7 @@ AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修
|
||||
|
||||
只产出一份 `{slug}-fix-note.md`，省掉 `{slug}-report.md` 和 `{slug}-analysis.md`。
|
||||
|
||||
**判定口径**：是否进快速通道由 `easysdd-issue-report` 的启动检查做唯一正式判定。一旦进入标准路径并确认 `{slug}-report.md`，后续阶段默认不再二次改判——避免 report / analyze / fix 三个阶段对路径各说各话。
|
||||
**判定口径**：是否进快速通道由 `cs-issue-report` 的启动检查做唯一正式判定。一旦进入标准路径并确认 `{slug}-report.md`，后续阶段默认不再二次改判——避免 report / analyze / fix 三个阶段对路径各说各话。
|
||||
|
||||
什么时候**不能**走快速通道：
|
||||
|
||||
@@ -89,17 +89,17 @@ AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修
|
||||
|
||||
## 路由：用户现在该走哪个子技能
|
||||
|
||||
进入本技能后先 Glob `easysdd/issues/`，看有没有相关的 issue 目录。**不要只听用户口头描述**——自己读已有文件才有数。
|
||||
进入本技能后先 Glob `codestable/issues/`，看有没有相关的 issue 目录。**不要只听用户口头描述**——自己读已有文件才有数。
|
||||
|
||||
| 当前状态 | 触发哪个子技能 |
|
||||
|---|---|
|
||||
| 刚发现问题，还没有任何文件 | `easysdd-issue-report`（在那里判断走标准还是快速） |
|
||||
| `{slug}-report.md` 已存在，没有 `{slug}-analysis.md` | `easysdd-issue-analyze` |
|
||||
| `{slug}-analysis.md` 已存在，代码还没改 | `easysdd-issue-fix` |
|
||||
| 代码已改，还没修复验证记录 | `easysdd-issue-fix`（走验证环节） |
|
||||
| 刚发现问题，还没有任何文件 | `cs-issue-report`（在那里判断走标准还是快速） |
|
||||
| `{slug}-report.md` 已存在，没有 `{slug}-analysis.md` | `cs-issue-analyze` |
|
||||
| `{slug}-analysis.md` 已存在，代码还没改 | `cs-issue-fix` |
|
||||
| 代码已改，还没修复验证记录 | `cs-issue-fix`（走验证环节） |
|
||||
| 不确定 | 自己读已有文件，按上表对号入座 |
|
||||
|
||||
如果用户描述的是**新功能需求而不是 bug**，告诉用户走 `easysdd-feature` 工作流，本工作流不适用。
|
||||
如果用户描述的是**新功能需求而不是 bug**，告诉用户走 `cs-feat` 工作流，本工作流不适用。
|
||||
|
||||
---
|
||||
|
||||
@@ -114,7 +114,7 @@ AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `easysdd/reference/system-overview.md` — easysdd 体系总览和场景路由
|
||||
- `easysdd/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、收尾提交规则
|
||||
- `codestable/reference/system-overview.md` — CodeStable 体系总览和场景路由
|
||||
- `codestable/reference/shared-conventions.md` — 跨阶段共享口径、目录结构、收尾提交规则
|
||||
- `AGENTS.md` — 全项目代码规范，issue 修复时同样遵守
|
||||
- `easysdd/architecture/DESIGN.md` — 架构总入口，做根因分析时可能要查
|
||||
- `codestable/architecture/DESIGN.md` — 架构总入口，做根因分析时可能要查
|
||||
|
||||
+15
-15
@@ -1,20 +1,20 @@
|
||||
---
|
||||
name: easysdd-learning
|
||||
name: cs-learn
|
||||
description: 把这次工作里踩过的坑或发现的好做法沉淀成可检索的 learning 文档，下次同类事来了 AI 和人都能查到。两条轨道：坑点轨道（pitfall）记录"本来应该好但没好"的经历——bug、配置陷阱、环境问题、集成失败；知识轨道（knowledge）记录"以后默认这样做"的发现——最佳实践、工作流改进、可复用模式。触发场景：feature-acceptance 或 issue-fix 收尾时主动推送询问，或用户说"沉淀知识"、"learning"、"document learnings"、"把这次经验记下来"。spec 记的是做了什么，learning 记的是踩了什么 / 学了什么——两者互补不替代。
|
||||
---
|
||||
|
||||
# easysdd-learning
|
||||
# cs-learn
|
||||
|
||||
每次做 feature 或修 issue 都会留下 spec 文件——`{slug}-design.md` / `{slug}-fix-note.md` 这些。但 spec 记录的是"做了什么"和"怎么做的"，**不会记录"踩了什么坑"和"发现了什么更好的做法"**。
|
||||
|
||||
没有沉淀的团队总在重复解决同一个问题。第一次解决一个问题需要研究，记下来后下次几分钟就够。easysdd-learning 就是给每次非 trivial 的工程实践补一张"学习卡"。
|
||||
没有沉淀的团队总在重复解决同一个问题。第一次解决一个问题需要研究，记下来后下次几分钟就够。cs-learn 就是给每次非 trivial 的工程实践补一张"学习卡"。
|
||||
|
||||
两条轨道：
|
||||
|
||||
- **坑点轨道**（pitfall）：记录遇到的问题、根因、解法，防止下次再掉进同一个坑
|
||||
- **知识轨道**（knowledge）：记录发现的最佳实践、工作流改进、可复用模式
|
||||
|
||||
两者都写入沉淀目录 `easysdd/compound/`（与其他沉淀子技能共享一个目录，分类规则看 `easysdd/reference/shared-conventions.md` 第 1 节"归档类文档"），格式统一，可被未来的 AI 和人类检索。本技能产出的文档在 frontmatter 里带 `doc_type: learning`，文件名形如 `YYYY-MM-DD-learning-{slug}.md`（日期打头、类型段固定为 `learning`），这是本技能在共享目录里的身份标识。
|
||||
两者都写入沉淀目录 `codestable/compound/`（与其他沉淀子技能共享一个目录，分类规则看 `codestable/reference/shared-conventions.md` 第 1 节"归档类文档"），格式统一，可被未来的 AI 和人类检索。本技能产出的文档在 frontmatter 里带 `doc_type: learning`，文件名形如 `YYYY-MM-DD-learning-{slug}.md`（日期打头、类型段固定为 `learning`），这是本技能在共享目录里的身份标识。
|
||||
|
||||
---
|
||||
|
||||
@@ -24,8 +24,8 @@ description: 把这次工作里踩过的坑或发现的好做法沉淀成可检
|
||||
|
||||
| 情境 | 说明 |
|
||||
|---|---|
|
||||
| 完成一个 feature 工作流 | `easysdd-feature-acceptance` 按 `easysdd/reference/shared-conventions.md` 主动问"要记录这次的学习点吗？" |
|
||||
| 完成一个 issue 工作流 | `easysdd-issue-fix` 按 `easysdd/reference/shared-conventions.md` 主动问"要把这个坑记录下来吗？" |
|
||||
| 完成一个 feature 工作流 | `cs-feat-accept` 按 `codestable/reference/shared-conventions.md` 主动问"要记录这次的学习点吗？" |
|
||||
| 完成一个 issue 工作流 | `cs-issue-fix` 按 `codestable/reference/shared-conventions.md` 主动问"要把这个坑记录下来吗？" |
|
||||
| 用户主动触发 | "记录一下"、"沉淀知识"、"learning"、"document learnings" 等 |
|
||||
| 解决了一次性难题 | 不在 feature / issue 工作流内，但花了大量时间才解决的工程问题 |
|
||||
|
||||
@@ -57,7 +57,7 @@ description: 把这次工作里踩过的坑或发现的好做法沉淀成可检
|
||||
|
||||
### Phase 1.5：查重叠与意图分流（必做）
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
按 `codestable/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
|
||||
- 用户话里含"改 / 更新 / 补充 / 某条 learning"或明确指向某份旧文档 → 直接走**更新已有条目**路径
|
||||
- 否则用下面"搜索工具"里 `--filter tags~=` 或 `--query` 查一遍本次主题 / 组件，命中相近旧文档时把候选列给用户，让用户选：更新 / supersede / 确实不同主题
|
||||
@@ -91,37 +91,37 @@ description: 把这次工作里踩过的坑或发现的好做法沉淀成可检
|
||||
|
||||
### Phase 4：归档
|
||||
|
||||
- 新建路径：写入 `easysdd/compound/`，文件命名 `YYYY-MM-DD-learning-{slug}.md`（日期取**归档当天**，不是问题发生当天），frontmatter 顶部带 `doc_type: learning`（见 `reference.md`）
|
||||
- 新建路径：写入 `codestable/compound/`，文件命名 `YYYY-MM-DD-learning-{slug}.md`（日期取**归档当天**，不是问题发生当天），frontmatter 顶部带 `doc_type: learning`（见 `reference.md`）
|
||||
- 更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补 `updated: YYYY-MM-DD`
|
||||
- supersede 路径：按 `shared-conventions.md` §6 第 5 条处理新旧两份文件
|
||||
- 写完后报告完整文件路径
|
||||
|
||||
### Phase 5：可发现性检查
|
||||
|
||||
写完后检查 `AGENTS.md` 或 `CLAUDE.md` 里有没有指引 AI 查阅 `easysdd/compound/` 沉淀目录的说明。**没有就提示用户是否要加一行**——别自作主张改文件，只提示，由用户决定。理由是 AGENTS.md 这种入口文件改动影响整个团队对 AI 的指引方式，用户该拍板。
|
||||
写完后检查 `AGENTS.md` 或 `CLAUDE.md` 里有没有指引 AI 查阅 `codestable/compound/` 沉淀目录的说明。**没有就提示用户是否要加一行**——别自作主张改文件，只提示，由用户决定。理由是 AGENTS.md 这种入口文件改动影响整个团队对 AI 的指引方式，用户该拍板。
|
||||
|
||||
---
|
||||
|
||||
## 搜索工具
|
||||
|
||||
> 完整语法和示例见 `easysdd/reference/tools.md`。本节只列 learning 特有的典型查询。
|
||||
> 完整语法和示例见 `codestable/reference/tools.md`。本节只列 learning 特有的典型查询。
|
||||
|
||||
```bash
|
||||
# 按轨道筛选坑点
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter track=pitfall --filter severity=high
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter track=pitfall --filter severity=high
|
||||
|
||||
# 按组件查相关学习点
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter component~={组件名}
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter component~={组件名}
|
||||
|
||||
# 归档后查重叠
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter tags~={主要 tag} --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter tags~={主要 tag} --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 守护规则
|
||||
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `easysdd/reference/shared-conventions.md` 第 6 节。本技能特有规则：
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `codestable/reference/shared-conventions.md` 第 6 节。本技能特有规则：
|
||||
|
||||
1. **不混入 spec**——learning 文档不是 spec，不放进 `features/` 或 `issues/`；spec 文档也不放进 `easysdd/compound/`
|
||||
1. **不混入 spec**——learning 文档不是 spec，不放进 `features/` 或 `issues/`；spec 文档也不放进 `codestable/compound/`
|
||||
2. **只认自己的 doc_type**——只读写 `doc_type: learning` 的文档，不感知 `compound/` 目录里其他 doc_type 的文档
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# learning 参考模板
|
||||
|
||||
本文件提供 `easysdd-learning` 的两条轨道模板和示例。产出文档写入 `easysdd/compound/`，文件名 `YYYY-MM-DD-learning-{slug}.md`。
|
||||
本文件提供 `cs-learn` 的两条轨道模板和示例。产出文档写入 `codestable/compound/`，文件名 `YYYY-MM-DD-learning-{slug}.md`。
|
||||
|
||||
## 1. 坑点轨道（pitfall）
|
||||
|
||||
|
||||
+9
-9
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-libdoc
|
||||
name: cs-libdoc
|
||||
description: 给库的公开表面（组件、函数、命令等）逐条目生成参考文档，带清单追踪，支持单条目和批量两种模式。和 guidedoc 的根本区别：guidedoc 教你怎么用、libdoc 告诉你每个零件长什么样；guidedoc 信息源是方案 doc + 用户知识，libdoc 信息源是源码本身。触发场景：用户说"写 API 文档"、"组件文档"、"libdoc"、"给每个组件写份文档"，或 feature-acceptance 后发现新增了库公开接口。
|
||||
---
|
||||
|
||||
# easysdd-libdoc
|
||||
# cs-libdoc
|
||||
|
||||
guidedoc 教你"怎么用 X 做 Y"，libdoc 告诉你"X 的每个零件长什么样、怎么配"。两者性质完全不同，写法、信息源、粒度都不一样。
|
||||
|
||||
@@ -40,7 +40,7 @@ guidedoc 写错可能是表达不清，libdoc 写错就是错——因为它的
|
||||
|
||||
## 涉及路径
|
||||
|
||||
libdoc 产物**不在 `easysdd/` 下**——API 参考是面向外部读者的可发布产物。
|
||||
libdoc 产物**不在 `codestable/` 下**——API 参考是面向外部读者的可发布产物。
|
||||
|
||||
- 条目文档 → `docs/api/{slug}.md`
|
||||
- 条目清单 → `docs/api/manifest.yaml`
|
||||
@@ -116,11 +116,11 @@ libdoc 产物**不在 `easysdd/` 下**——API 参考是面向外部读者的
|
||||
|
||||
| 来源 | 关系 |
|
||||
|---|---|
|
||||
| `easysdd-feature-acceptance` | 验收后若新增/修改库公开接口 → 推送"需要更新 libdoc 吗？" |
|
||||
| `easysdd-guidedoc` | guide 引用 libdoc 做详细参考；libdoc "相关条目"链回 guide |
|
||||
| `easysdd-architecture` (check 模式) | 它检测到接口变更但 libdoc 未同步时，会把对应条目标成 `outdated`，本技能 Phase 3 据此处理 |
|
||||
| `easysdd-feature-design` | 方案第 2 节可作 libdoc 补充信息源（但**以源码为准**） |
|
||||
| `easysdd-tricks` | libdoc "注意事项"与 tricks 重合时交叉引用而不重复写 |
|
||||
| `cs-feat-accept` | 验收后若新增/修改库公开接口 → 推送"需要更新 libdoc 吗？" |
|
||||
| `cs-guide` | guide 引用 libdoc 做详细参考；libdoc "相关条目"链回 guide |
|
||||
| `cs-arch` (check 模式) | 它检测到接口变更但 libdoc 未同步时，会把对应条目标成 `outdated`，本技能 Phase 3 据此处理 |
|
||||
| `cs-feat-design` | 方案第 2 节可作 libdoc 补充信息源（但**以源码为准**） |
|
||||
| `cs-trick` | libdoc "注意事项"与 tricks 重合时交叉引用而不重复写 |
|
||||
|
||||
---
|
||||
|
||||
@@ -159,7 +159,7 @@ libdoc 产物**不在 `easysdd/` 下**——API 参考是面向外部读者的
|
||||
- ❌ 没读源码就写 API 参考——libdoc 的核心价值是准确反映源码
|
||||
- ❌ 复制上一个条目改改名字算下一个——必然漏掉微妙差异
|
||||
- ❌ 批量模式跳过样板确认——50 篇全白写
|
||||
- ❌ 把 spec 信息（不变量、测试约束）写进 libdoc——属于 `easysdd/`
|
||||
- ❌ 把 spec 信息（不变量、测试约束）写进 libdoc——属于 `codestable/`
|
||||
- ❌ libdoc 和 guidedoc 内容高度重叠——重叠说明其中一份定位有误
|
||||
- ❌ `manifest.yaml` 直接删行——改 `status: skipped` 并写 note
|
||||
- ❌ 源码接口不存在却在文档里写了——以源码为事实源，不编造
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# libdoc 参考模板
|
||||
|
||||
本文件提供 `easysdd-libdoc` 使用的 manifest、条目文档模板和源码提取清单。
|
||||
本文件提供 `cs-libdoc` 使用的 manifest、条目文档模板和源码提取清单。
|
||||
|
||||
## 1. `manifest.yaml` 格式
|
||||
|
||||
|
||||
+58
-49
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: easysdd-onboarding
|
||||
description: 把一个新仓库或有零散文档的仓库接入 easysdd 体系。两条路径自动判断：空仓库路径（仓库内无任何 spec 类文档也没有 easysdd/ 目录）从零搭骨架；迁移路径（仓库内已有零散文档或部分 easysdd/ 结构）先做审计报告 + 迁移映射方案，由用户逐一确认后落盘。本技能只做"搭骨架"和"归旧档"两件事，骨架搭好后各子工作流就能直接运行。触发场景：用户说"在这个项目里用 easysdd"、"搭 easysdd 结构"、"初始化 easysdd"、"迁移到 easysdd"。
|
||||
name: cs-onboard
|
||||
description: 把一个新仓库或有零散文档的仓库接入 CodeStable 体系。两条路径自动判断：空仓库路径（仓库内无任何 spec 类文档也没有 codestable/ 目录）从零搭骨架；迁移路径（仓库内已有零散文档或部分 codestable/ 结构）先做审计报告 + 迁移映射方案，由用户逐一确认后落盘。本技能只做"搭骨架"和"归旧档"两件事，骨架搭好后各子工作流就能直接运行。触发场景：用户说"在这个项目里用 CodeStable"、"搭 CodeStable 结构"、"初始化 CodeStable"、"迁移到 CodeStable"。
|
||||
---
|
||||
|
||||
# easysdd-onboarding
|
||||
# cs-onboard
|
||||
|
||||
把一个仓库**接入 easysdd 工作流体系**——无论它是一张白纸，还是已经有零散文档的仓库。本技能只做两件事：**搭骨架**、**归旧档**。骨架搭好之后各子工作流（feature / issue / compound 等）即可直接在其上运行，不再需要解释目录在哪里。
|
||||
把一个仓库**接入 CodeStable 工作流体系**——无论它是一张白纸，还是已经有零散文档的仓库。本技能只做两件事：**搭骨架**、**归旧档**。骨架搭好之后各子工作流（feature / issue / compound 等）即可直接在其上运行，不再需要解释目录在哪里。
|
||||
|
||||
---
|
||||
|
||||
@@ -13,8 +13,8 @@ description: 把一个新仓库或有零散文档的仓库接入 easysdd 体系
|
||||
|
||||
| 路径 | 适用情况 | 产出 |
|
||||
|---|---|---|
|
||||
| **空仓库路径** | 仓库内无任何 spec 类文档，也没有 `easysdd/` 目录 | 完整的 `easysdd/` 目录骨架 + 必要的骨架文件 |
|
||||
| **迁移路径** | 仓库内已有零散文档、`docs/` 目录、架构文档、设计稿，或部分 `easysdd/` 结构 | 审计报告 + 迁移映射方案（用户逐一确认）+ 落盘 |
|
||||
| **空仓库路径** | 仓库内无任何 spec 类文档，也没有 `codestable/` 目录 | 完整的 `codestable/` 目录骨架 + 必要的骨架文件 |
|
||||
| **迁移路径** | 仓库内已有零散文档、`docs/` 目录、架构文档、设计稿，或部分 `codestable/` 结构 | 审计报告 + 迁移映射方案（用户逐一确认）+ 落盘 |
|
||||
|
||||
启动后**先做一次扫描自动判断**，不要让用户自己选——TA 大概率不知道项目里现在有哪些文档。扫描结果模糊（比如只有一个 README）就明说判断依据并问用户确认。
|
||||
|
||||
@@ -22,14 +22,14 @@ description: 把一个新仓库或有零散文档的仓库接入 easysdd 体系
|
||||
|
||||
## 涉及的路径
|
||||
|
||||
> onboarding 完成后，共享路径与命名约定的权威版本是项目里的 `easysdd/reference/shared-conventions.md`——由本技能从技能包里复制过去。下面只列 onboarding 需要创建或检查的骨架文件。
|
||||
> onboarding 完成后，共享路径与命名约定的权威版本是项目里的 `codestable/reference/shared-conventions.md`——由本技能从技能包里复制过去。下面只列 onboarding 需要创建或检查的骨架文件。
|
||||
|
||||
### 标准骨架（目标状态）
|
||||
|
||||
onboarding 完成后仓库里应该存在以下骨架：
|
||||
|
||||
```
|
||||
easysdd/
|
||||
codestable/
|
||||
├── requirements/ ← 需求聚合根（空目录，.gitkeep）："为什么要有这个能力"（只记现状）
|
||||
├── architecture/
|
||||
│ └── DESIGN.md ← 架构总入口骨架（首次创建时为占位模板）："用什么结构实现"（只记现状）
|
||||
@@ -46,7 +46,7 @@ easysdd/
|
||||
└── maintainer-notes.md ← 断点恢复、扩展点、维护规则
|
||||
```
|
||||
|
||||
`AGENTS.md` 在项目根目录，**不在 `easysdd/` 里**。onboarding 会检查它存不存在，不存在时提醒用户但**不代替用户写**——AGENTS.md 的内容高度项目相关，必须由人来填。缺少 `AGENTS.md` 不阻塞 onboarding 完成，但后续 feature / issue / acceptance 阶段启动前用户需要补齐它，或明确接受当前仓库暂时没有项目级硬约束入口。
|
||||
`AGENTS.md` 在项目根目录，**不在 `codestable/` 里**。onboarding 会检查它存不存在，不存在时提醒用户但**不代替用户写**——AGENTS.md 的内容高度项目相关，必须由人来填。缺少 `AGENTS.md` 不阻塞 onboarding 完成，但后续 feature / issue / acceptance 阶段启动前用户需要补齐它，或明确接受当前仓库暂时没有项目级硬约束入口。
|
||||
|
||||
---
|
||||
|
||||
@@ -54,19 +54,28 @@ easysdd/
|
||||
|
||||
启动时做下面这些扫描，**先扫再说话**，不要空口问问题：
|
||||
|
||||
1. **检查 `easysdd/` 目录是否存在**
|
||||
1. **检查 `codestable/` 目录是否存在**
|
||||
- 不存在：空仓库路径候选
|
||||
- 存在但不完整：迁移路径（部分补齐）
|
||||
|
||||
1.5. **检查旧 `easysdd/` 目录是否存在**（2026 年改名遗留）
|
||||
|
||||
CodeStable 的旧名是 easysdd，2026 年整体改名后项目目录从 `easysdd/` 改成 `codestable/`。发现仓库里有 `easysdd/` 目录（而没有 `codestable/`）时**停下来提示用户迁移**：
|
||||
|
||||
> 检测到旧版 `easysdd/` 目录（CodeStable 前身）。建议直接 `git mv easysdd codestable` 把目录名迁过来，原目录下的文件结构完全一致、frontmatter 字段也完全兼容，rename 后直接可用。要我帮你执行吗？
|
||||
|
||||
用户同意 → 执行 `git mv easysdd codestable`，然后继续按"迁移路径"处理（这时候 `codestable/` 已经存在、内容也完整，只需要补齐可能缺失的共享资产 `tools/` 和 `reference/`）。
|
||||
用户想保留旧目录不迁 → 告诉他 CodeStable 子技能只读 `codestable/` 路径，旧 `easysdd/` 下的产物不会被读到；继续按空仓库路径走新骨架。
|
||||
|
||||
2. **Glob 全仓库的 `.md` 文件**（排除 `node_modules/`、`.git/`），重点看：
|
||||
- 根目录下的 `DESIGN.md`、`ARCHITECTURE.md`、`SPEC.md`、`README.md`
|
||||
- `docs/`、`doc/`、`design/`、`spec/`、`wiki/` 等目录下的文件
|
||||
- 现有 `easysdd/` 下已有哪些文件
|
||||
- 现有 `codestable/` 下已有哪些文件
|
||||
|
||||
3. **检查 `AGENTS.md` 是否存在**（根目录）
|
||||
|
||||
4. **汇报扫描结论**——一段话说清楚：
|
||||
- 找到了哪些可能和 easysdd 体系相关的文档（列文件路径）
|
||||
- 找到了哪些可能和 CodeStable 体系相关的文档（列文件路径）
|
||||
- 判断走哪条路径，以及判断依据
|
||||
- 有哪些不确定项需要用户确认
|
||||
|
||||
@@ -77,7 +86,7 @@ easysdd/
|
||||
### 适用条件
|
||||
|
||||
- 仓库内没有任何 spec 类文档（或只有 `README.md`）
|
||||
- `easysdd/` 目录不存在
|
||||
- `codestable/` 目录不存在
|
||||
|
||||
### 执行步骤
|
||||
|
||||
@@ -92,14 +101,14 @@ easysdd/
|
||||
|
||||
按下面顺序执行，每步完成后继续，**不等用户逐步确认**——骨架是整体一次性的，逐步确认反而打断节奏：
|
||||
|
||||
- `easysdd/requirements/.gitkeep`
|
||||
- `easysdd/architecture/DESIGN.md`（填入占位模板，见同目录 `reference.md`）
|
||||
- `easysdd/roadmap/.gitkeep`
|
||||
- `easysdd/features/.gitkeep`
|
||||
- `easysdd/issues/.gitkeep`
|
||||
- `easysdd/compound/.gitkeep`
|
||||
- `easysdd/tools/`（用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录拷贝本技能包 `easysdd-onboarding/tools/` 下的所有文件，**不要 Read 再 Write**）
|
||||
- `easysdd/reference/`（同上，整目录拷贝本技能包 `easysdd-onboarding/reference/`——这是所有 easysdd 子技能在运行时共享参考文档的唯一方式）
|
||||
- `codestable/requirements/.gitkeep`
|
||||
- `codestable/architecture/DESIGN.md`（填入占位模板，见同目录 `reference.md`）
|
||||
- `codestable/roadmap/.gitkeep`
|
||||
- `codestable/features/.gitkeep`
|
||||
- `codestable/issues/.gitkeep`
|
||||
- `codestable/compound/.gitkeep`
|
||||
- `codestable/tools/`（用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录拷贝本技能包 `cs-onboard/tools/` 下的所有文件，**不要 Read 再 Write**）
|
||||
- `codestable/reference/`（同上，整目录拷贝本技能包 `cs-onboard/reference/`——这是所有 CodeStable 子技能在运行时共享参考文档的唯一方式）
|
||||
|
||||
> **落盘用 shell 命令整目录覆盖**，不要 `Read` 一个文件再 `Write` 一个文件——这两个目录是机器共享资产，Read+Write 链路容易截断大文件、改缩进、吃空行，还慢还费 token。迁移路径步骤 4 里给了具体命令示例，空仓库路径也照着执行。
|
||||
|
||||
@@ -107,7 +116,7 @@ easysdd/
|
||||
|
||||
如果根目录没有 `AGENTS.md`：
|
||||
|
||||
> `AGENTS.md` 还不存在。它是 easysdd 所有子工作流的"项目硬约束入口"——记录代码规范、已知坑、禁止事项。建议现在创建一个最小版本。你想现在填，还是之后自己创建？
|
||||
> `AGENTS.md` 还不存在。它是 CodeStable 所有子工作流的"项目硬约束入口"——记录代码规范、已知坑、禁止事项。建议现在创建一个最小版本。你想现在填，还是之后自己创建？
|
||||
|
||||
用户选"现在填"：提供最小模板（见同目录 `reference.md`），引导用户填写关键字段后保存。
|
||||
用户选"之后"：记录在汇报里，告诉用户"下次触发 feature/issue 工作流前记得补上"。
|
||||
@@ -116,10 +125,10 @@ easysdd/
|
||||
|
||||
列出建了哪些文件，告诉用户：
|
||||
|
||||
> easysdd 骨架已就绪。现在可以：
|
||||
> - 开始一个新功能：触发 `easysdd-feature` 技能
|
||||
> - 报告一个问题：触发 `easysdd-issue` 技能
|
||||
> - 沉淀知识：触发 `easysdd-learning` 技能
|
||||
> CodeStable 骨架已就绪。现在可以：
|
||||
> - 开始一个新功能：触发 `cs-feat` 技能
|
||||
> - 报告一个问题：触发 `cs-issue` 技能
|
||||
> - 沉淀知识：触发 `cs-learn` 技能
|
||||
|
||||
---
|
||||
|
||||
@@ -127,7 +136,7 @@ easysdd/
|
||||
|
||||
### 适用条件
|
||||
|
||||
仓库内有零散的 spec 类文档、设计文档、或部分 `easysdd/` 结构。
|
||||
仓库内有零散的 spec 类文档、设计文档、或部分 `codestable/` 结构。
|
||||
|
||||
### 执行步骤
|
||||
|
||||
@@ -135,10 +144,10 @@ easysdd/
|
||||
|
||||
把扫描结果整理成一张映射表，展示给用户：
|
||||
|
||||
| 现有文件 | 推测内容类型 | 建议归入 easysdd 位置 | 置信度 |
|
||||
| 现有文件 | 推测内容类型 | 建议归入 CodeStable 位置 | 置信度 |
|
||||
|---|---|---|---|
|
||||
| `docs/DESIGN.md` | 项目架构文档 | `easysdd/architecture/DESIGN.md` | 高 |
|
||||
| `docs/feature-auth.md` | 某功能的设计稿 | `easysdd/features/YYYY-MM-DD-auth/auth-design.md` | 中 |
|
||||
| `docs/DESIGN.md` | 项目架构文档 | `codestable/architecture/DESIGN.md` | 高 |
|
||||
| `docs/feature-auth.md` | 某功能的设计稿 | `codestable/features/YYYY-MM-DD-auth/auth-design.md` | 中 |
|
||||
| `SPEC.md` | 功能需求文档？ | 需用户确认 | 低 |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
@@ -157,9 +166,9 @@ easysdd/
|
||||
|
||||
高置信度的映射不需要逐条问，但要在汇报里列出来，让用户有机会反对。理由是高置信度的判断也可能错，但逐条问会让节奏失控——汇报里列出来等于给了用户一次复审机会但不打断流程。
|
||||
|
||||
**步骤 3：处理"中途写了一半"的 easysdd 文档**
|
||||
**步骤 3：处理"中途写了一半"的 CodeStable 文档**
|
||||
|
||||
如果 `easysdd/` 已部分存在：
|
||||
如果 `codestable/` 已部分存在：
|
||||
|
||||
- 检查已有目录是否符合命名规范（`YYYY-MM-DD-{slug}` 格式）
|
||||
- 检查已有文件是否有内容（空文件 vs 有内容）
|
||||
@@ -170,9 +179,9 @@ easysdd/
|
||||
|
||||
对照上面的标准骨架，把**用户确认迁移方案后仍然缺失**的目录和文件补齐。已有内容的目录不要覆盖，只补空缺。
|
||||
|
||||
**`easysdd/tools/` 和 `easysdd/reference/` 一律用技能包里的新版本覆盖**——不管项目里的旧版本看起来有没有被改过。
|
||||
**`codestable/tools/` 和 `codestable/reference/` 一律用技能包里的新版本覆盖**——不管项目里的旧版本看起来有没有被改过。
|
||||
|
||||
- 这两个目录是**技能包维护的共享资产**，权威源头在 `easysdd-onboarding/tools/` 和 `easysdd-onboarding/reference/`，项目里的只是一份落盘副本
|
||||
- 这两个目录是**技能包维护的共享资产**，权威源头在 `cs-onboard/tools/` 和 `cs-onboard/reference/`，项目里的只是一份落盘副本
|
||||
- 技能包升级后（比如修了 bug、加了字段、改了脚本），onboarding 再跑一次的目的之一就是把旧副本刷新到新版本，留着旧版本会让后续子技能按过时口径工作
|
||||
- 覆盖前在汇报里列出被覆盖的文件清单，让用户知道发生了什么；如果用户明确说过"我改过 tools/xxx.py 请保留"，才例外保留并在汇报里标红
|
||||
|
||||
@@ -184,12 +193,12 @@ easysdd/
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
cp -rf <技能包路径>/easysdd-onboarding/tools/. easysdd/tools/
|
||||
cp -rf <技能包路径>/easysdd-onboarding/reference/. easysdd/reference/
|
||||
cp -rf <技能包路径>/cs-onboard/tools/. codestable/tools/
|
||||
cp -rf <技能包路径>/cs-onboard/reference/. codestable/reference/
|
||||
|
||||
# Windows PowerShell
|
||||
Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\tools\* easysdd\tools\
|
||||
Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\reference\* easysdd\reference\
|
||||
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\tools\* CodeStable\tools\
|
||||
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\reference\* CodeStable\reference\
|
||||
```
|
||||
|
||||
错误做法（不要这样做）：
|
||||
@@ -198,11 +207,11 @@ Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\reference\* easy
|
||||
- ❌ 一个文件一个文件地 `cp`——多一步就多一个出错点
|
||||
- ❌ 先比 diff 再决定拷不拷——这两个目录的规则就是"无条件覆盖"，比 diff 是白费力
|
||||
|
||||
技能包路径一般就是当前 skill 的安装目录（比如 `~/.claude/skills/easysdd-onboarding/` 或插件目录下的对应位置）。不确定就先 `ls` 定位一下，再执行拷贝。拷完跑一次 `ls easysdd/tools/ easysdd/reference/` 验证文件都在。
|
||||
技能包路径一般就是当前 skill 的安装目录（比如 `~/.claude/skills/cs-onboard/` 或插件目录下的对应位置）。不确定就先 `ls` 定位一下，再执行拷贝。拷完跑一次 `ls codestable/tools/ codestable/reference/` 验证文件都在。
|
||||
|
||||
**步骤 5：处理不迁移的文件**
|
||||
|
||||
用户选择"跳过"的文件：**不移动、不删除、不重命名**，在汇报里标注"保留原位（未纳入 easysdd 体系）"。绝对不允许未经确认就移动或删除任何已有文件——理由很简单：onboarding 的入口只允许 AI 整理而不允许 AI 替用户做删除决定，删错了恢复成本极高。
|
||||
用户选择"跳过"的文件：**不移动、不删除、不重命名**，在汇报里标注"保留原位（未纳入 CodeStable 体系）"。绝对不允许未经确认就移动或删除任何已有文件——理由很简单：onboarding 的入口只允许 AI 整理而不允许 AI 替用户做删除决定，删错了恢复成本极高。
|
||||
|
||||
**步骤 6：AGENTS.md 提醒**（同空仓库路径步骤 3）
|
||||
|
||||
@@ -225,9 +234,9 @@ Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\reference\* easy
|
||||
|
||||
## 退出条件
|
||||
|
||||
- [ ] `easysdd/` 目录骨架完整（八个子目录都存在：`requirements/`、`architecture/`、`roadmap/`、`features/`、`issues/`、`compound/`、`tools/`、`reference/`）
|
||||
- [ ] `easysdd/tools/` 和 `easysdd/reference/` 下的共享脚本和参考文档已从本技能包复制过去（子技能在运行时必须能读到这些文件）
|
||||
- [ ] `easysdd/architecture/DESIGN.md` 已建（哪怕是占位内容）
|
||||
- [ ] `codestable/` 目录骨架完整（八个子目录都存在：`requirements/`、`architecture/`、`roadmap/`、`features/`、`issues/`、`compound/`、`tools/`、`reference/`）
|
||||
- [ ] `codestable/tools/` 和 `codestable/reference/` 下的共享脚本和参考文档已从本技能包复制过去（子技能在运行时必须能读到这些文件）
|
||||
- [ ] `codestable/architecture/DESIGN.md` 已建（哪怕是占位内容）
|
||||
- [ ] 迁移路径：每一条映射都有明确处理结果（迁移 / 保留原位）
|
||||
- [ ] 迁移路径：没有未经用户确认就移动的文件
|
||||
- [ ] `AGENTS.md` 状态已明确（存在 / 用户知道需要补）
|
||||
@@ -240,10 +249,10 @@ Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\reference\* easy
|
||||
- **未经用户确认就移动或删除已有文件**——迁移路径的核心原则是用户拍板，不是 AI 自作主张
|
||||
- **替用户填写 AGENTS.md 的实质内容**——AGENTS.md 里的规范和禁忌必须项目 owner 来定，AI 只提供模板和引导
|
||||
- **建完骨架后立刻开始某个 feature/issue**——onboarding 的职责是"搭环境"，不是"开始干活"，做完骨架就结束
|
||||
- **把 AGENTS.md 建到 `easysdd/` 里**——AGENTS.md 是根目录文件，不属于 `easysdd/` 下
|
||||
- **把 AGENTS.md 建到 `codestable/` 里**——AGENTS.md 是根目录文件，不属于 `codestable/` 下
|
||||
- **把低置信度的映射也直接执行**——置信度低 = 必须问，不问直接迁是在替用户做判断
|
||||
- **遇到部分存在的 `easysdd/` 结构就全部覆盖重建**——除 `tools/` 和 `reference/` 外，有内容的文件不允许覆盖，只补空缺
|
||||
- **对 `easysdd/tools/` 和 `easysdd/reference/` 也走"不覆盖"保守策略**——正好相反，这两个目录必须用技能包里的新版本覆盖旧版本，否则技能升级后用户项目会停留在过时脚本和过时口径上
|
||||
- **遇到部分存在的 `codestable/` 结构就全部覆盖重建**——除 `tools/` 和 `reference/` 外，有内容的文件不允许覆盖，只补空缺
|
||||
- **对 `codestable/tools/` 和 `codestable/reference/` 也走"不覆盖"保守策略**——正好相反，这两个目录必须用技能包里的新版本覆盖旧版本，否则技能升级后用户项目会停留在过时脚本和过时口径上
|
||||
- **用 Read + Write 手工"搬运"文件内容**——必须用 `cp -rf` / `Copy-Item -Recurse -Force` 整目录覆盖。Read+Write 会截断长文件、吃掉空行、改缩进，而且一个个搬容易漏、容易慢、容易费 token
|
||||
- **Glob 时忘记排除 `node_modules/`、`.git/`**——这会让扫描结果充斥噪声，判断路径会出错
|
||||
|
||||
@@ -251,7 +260,7 @@ Copy-Item -Recurse -Force <技能包路径>\easysdd-onboarding\reference\* easy
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `easysdd/reference/system-overview.md` — easysdd 体系总览和场景路由(由 onboarding 从技能包 reference/ 一次性复制到项目)
|
||||
- `easysdd/reference/shared-conventions.md` — onboarding 落盘后，目录结构和共享口径的权威版本在这里
|
||||
- `codestable/reference/system-overview.md` — CodeStable 体系总览和场景路由(由 onboarding 从技能包 reference/ 一次性复制到项目)
|
||||
- `codestable/reference/shared-conventions.md` — onboarding 落盘后，目录结构和共享口径的权威版本在这里
|
||||
- `AGENTS.md` — 全项目硬约束入口，onboarding 完成后所有子工作流都会读它
|
||||
- `easysdd/architecture/DESIGN.md` — onboarding 产出的架构总入口骨架，方案设计阶段会读它
|
||||
- `codestable/architecture/DESIGN.md` — onboarding 产出的架构总入口骨架，方案设计阶段会读它
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# onboarding 参考模板
|
||||
|
||||
本文件提供 `easysdd-onboarding` 使用的骨架模板。
|
||||
本文件提供 `cs-onboard` 使用的骨架模板。
|
||||
|
||||
## 1. `easysdd/architecture/DESIGN.md` 占位模板
|
||||
## 1. `codestable/architecture/DESIGN.md` 占位模板
|
||||
|
||||
```markdown
|
||||
# {项目名} 架构总入口
|
||||
@@ -26,7 +26,7 @@
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
本文件是 AI 协作的项目级硬约束入口。所有 easysdd 子工作流默认遵守本文件的所有规则。
|
||||
本文件是 AI 协作的项目级硬约束入口。所有 CodeStable 子工作流默认遵守本文件的所有规则。
|
||||
|
||||
## 代码规范
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
写代码前先确认每个维度的档位。没明说的走默认，偏离默认的地方要标出来让用户确认。
|
||||
|
||||
这份文档是 easysdd 子技能共享的口径，被 design / fastforward / issue-fix 等阶段引用。项目内的权威副本在 `easysdd/reference/code-dimensions.md`，由 `easysdd-onboarding` 从技能包释放。
|
||||
这份文档是 CodeStable 子技能共享的口径，被 design / fastforward / issue-fix 等阶段引用。项目内的权威副本在 `codestable/reference/code-dimensions.md`，由 `cs-onboard` 从技能包释放。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# easysdd 维护者说明
|
||||
# CodeStable 维护者说明
|
||||
|
||||
本文件由 `easysdd-onboarding` 复制到项目的 `easysdd/reference/maintainer-notes.md`。维护 easysdd 技能家族时需要反复查阅、但不适合放在各子技能正文里的说明。
|
||||
本文件由 `cs-onboard` 复制到项目的 `codestable/reference/maintainer-notes.md`。维护 CodeStable 技能家族时需要反复查阅、但不适合放在各子技能正文里的说明。
|
||||
|
||||
---
|
||||
|
||||
@@ -23,7 +23,7 @@ AI 对话随时可能中断（token 超限、网络断开、用户换设备）
|
||||
|
||||
### 新增子工作流
|
||||
|
||||
新工作流定型后，在 `easysdd-onboarding/reference/system-overview.md` 的"技能分成四部分"和"场景路由"表里加一段索引，并登记新的目录位置。
|
||||
新工作流定型后，在 `cs-onboard/reference/system-overview.md` 的"技能分成四部分"和"场景路由"表里加一段索引，并登记新的目录位置。
|
||||
|
||||
### 跨阶段新约束
|
||||
|
||||
@@ -35,11 +35,11 @@ AI 对话随时可能中断（token 超限、网络断开、用户换设备）
|
||||
|
||||
### 共享术语表
|
||||
|
||||
如果 easysdd 自己形成了稳定共享术语，应优先沉淀成共享 reference，而不是散落在多个子技能里重复定义。
|
||||
如果 CodeStable 自己形成了稳定共享术语，应优先沉淀成共享 reference，而不是散落在多个子技能里重复定义。
|
||||
|
||||
### 跨工作流状态一览
|
||||
|
||||
目前查看"项目当前有几个 feature 在进行中、几个 issue 未关闭"仍需要手动查询。未来如要补 `status.py` 或 `easysdd/STATUS.md`，先在 `shared-conventions.md` 登记方向，再实现。
|
||||
目前查看"项目当前有几个 feature 在进行中、几个 issue 未关闭"仍需要手动查询。未来如要补 `status.py` 或 `codestable/STATUS.md`，先在 `shared-conventions.md` 登记方向，再实现。
|
||||
|
||||
---
|
||||
|
||||
@@ -47,4 +47,4 @@ AI 对话随时可能中断（token 超限、网络断开、用户换设备）
|
||||
|
||||
- 每次扩展都要同步更新 `system-overview.md` 索引和相关子技能
|
||||
- 不允许只在某个子技能里加东西而不在 `system-overview.md` 登记
|
||||
- 共享说明优先放 `easysdd/reference/`，不要散落在各子技能里
|
||||
- 共享说明优先放 `codestable/reference/`，不要散落在各子技能里
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
doc_type: requirement-example
|
||||
description: 一份好的 requirement doc 长什么样——供 easysdd-requirements 起草时参考，也供项目成员扫一眼对齐风格
|
||||
description: 一份好的 requirement doc 长什么样——供 cs-req 起草时参考，也供项目成员扫一眼对齐风格
|
||||
---
|
||||
|
||||
# requirement 文档示例
|
||||
|
||||
下面这份示例取自 easysdd 自己的能力（修 bug 时的探索分析流），用来展示一份好的 requirement doc 的**语气、结构、颗粒度**。新项目做 onboarding 时随包落盘，之后写自己的 requirement 可以直接照着改。
|
||||
下面这份示例取自 CodeStable 自己的能力（修 bug 时的探索分析流），用来展示一份好的 requirement doc 的**语气、结构、颗粒度**。新项目做 onboarding 时随包落盘，之后写自己的 requirement 可以直接照着改。
|
||||
|
||||
---
|
||||
|
||||
@@ -30,7 +30,7 @@ pitch: 修 bug 时先让 AI 探索和分析，再动手改
|
||||
status: current
|
||||
last_reviewed: 2026-04-21
|
||||
implemented_by:
|
||||
- arch-easysdd-issue
|
||||
- arch-cs-issue
|
||||
tags: [debug, ai-assist]
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# easysdd 共享口径
|
||||
# CodeStable 共享口径
|
||||
|
||||
本文件由 `easysdd-onboarding` 复制到项目的 `easysdd/reference/shared-conventions.md`。所有 easysdd 子技能在运行时用**项目相对路径** `easysdd/reference/shared-conventions.md` 引用本文件——这是跨子技能共享但不适合堆在单个技能里的规范的唯一权威版本。
|
||||
本文件由 `cs-onboard` 复制到项目的 `codestable/reference/shared-conventions.md`。所有 CodeStable 子技能在运行时用**项目相对路径** `codestable/reference/shared-conventions.md` 引用本文件——这是跨子技能共享但不适合堆在单个技能里的规范的唯一权威版本。
|
||||
|
||||
skill 本身不共享文件系统（每个 skill 是独立安装单元），所以共享口径不能放在某个 skill 内部被别的 skill 引用。放在"工作项目"里，对所有 skill 都可达。
|
||||
|
||||
@@ -8,23 +8,23 @@ skill 本身不共享文件系统（每个 skill 是独立安装单元），所
|
||||
|
||||
## 0. 目录结构与路径命名
|
||||
|
||||
onboarding 完成后，项目里应当存在如下骨架（`easysdd-onboarding` 负责搭建）：
|
||||
onboarding 完成后，项目里应当存在如下骨架（`cs-onboard` 负责搭建）：
|
||||
|
||||
```
|
||||
easysdd/
|
||||
codestable/
|
||||
├── requirements/ 需求中心目录（"为什么要有这个能力"，只记现状）
|
||||
│ └── {slug}.md 一个能力一份，扁平（由 easysdd-requirements 产出）
|
||||
│ └── {slug}.md 一个能力一份，扁平（由 cs-req 产出）
|
||||
├── architecture/ 架构中心目录（"用什么结构实现"，只记现状）
|
||||
│ ├── DESIGN.md 架构总入口（索引 + 关键架构决定）
|
||||
│ └── {slug}.md 子系统 / 模块架构 doc（由 easysdd-architecture 产出）
|
||||
│ └── {slug}.md 子系统 / 模块架构 doc（由 cs-arch 产出）
|
||||
├── roadmap/ 规划层目录（"接下来打算怎么走"，独立于现状档案）
|
||||
│ └── {slug}/ 一个大需求一个子目录（由 easysdd-roadmap 产出）
|
||||
│ └── {slug}/ 一个大需求一个子目录（由 cs-roadmap 产出）
|
||||
│ ├── {slug}-roadmap.md 主文档（背景 / 拆解 / 排期思路）
|
||||
│ ├── {slug}-items.yaml 机器可读的子 feature 清单，acceptance 回写状态
|
||||
│ └── drafts/ 可选，草稿 / 调研 / 讨论
|
||||
├── features/ feature spec 聚合根
|
||||
│ └── YYYY-MM-DD-{slug}/ 每个 feature 一个目录
|
||||
│ ├── {slug}-brainstorm.md （可选，由 easysdd-brainstorm 判为 case 2 时产出）
|
||||
│ ├── {slug}-brainstorm.md （可选，由 cs-brainstorm 判为 case 2 时产出）
|
||||
│ ├── {slug}-design.md
|
||||
│ ├── {slug}-checklist.yaml
|
||||
│ └── {slug}-acceptance.md
|
||||
@@ -48,30 +48,30 @@ easysdd/
|
||||
|
||||
### 命名规则
|
||||
|
||||
- 需求文档：`easysdd/requirements/{slug}.md`（长效能力清单，不带日期前缀，扁平不分组）
|
||||
- roadmap 目录：`easysdd/roadmap/{slug}/`（一个大需求一个子目录，不带日期前缀，平铺不嵌套）
|
||||
- feature 目录：`easysdd/features/YYYY-MM-DD-{slug}/`，日期用创建当天
|
||||
- issue 目录：`easysdd/issues/YYYY-MM-DD-{slug}/`，日期用报告当天
|
||||
- refactor 目录：`easysdd/refactors/YYYY-MM-DD-{slug}/`，日期用首次扫描当天
|
||||
- 沉淀类文档：`easysdd/compound/YYYY-MM-DD-{doc_type}-{slug}.md`，日期用**归档当天**（不是问题发生当天）
|
||||
- 架构文档：`easysdd/architecture/{type}-{slug}.md`（长效地图，不带日期前缀）；总入口始终叫 `DESIGN.md`
|
||||
- `AGENTS.md` 在项目根目录，**不在 `easysdd/` 里**
|
||||
- 需求文档：`codestable/requirements/{slug}.md`（长效能力清单，不带日期前缀，扁平不分组）
|
||||
- roadmap 目录：`codestable/roadmap/{slug}/`（一个大需求一个子目录，不带日期前缀，平铺不嵌套）
|
||||
- feature 目录：`codestable/features/YYYY-MM-DD-{slug}/`，日期用创建当天
|
||||
- issue 目录：`codestable/issues/YYYY-MM-DD-{slug}/`，日期用报告当天
|
||||
- refactor 目录：`codestable/refactors/YYYY-MM-DD-{slug}/`，日期用首次扫描当天
|
||||
- 沉淀类文档：`codestable/compound/YYYY-MM-DD-{doc_type}-{slug}.md`，日期用**归档当天**（不是问题发生当天）
|
||||
- 架构文档：`codestable/architecture/{type}-{slug}.md`（长效地图，不带日期前缀）；总入口始终叫 `DESIGN.md`
|
||||
- `AGENTS.md` 在项目根目录，**不在 `codestable/` 里**
|
||||
|
||||
### 架构 doc 的分组规则（同类聚合）
|
||||
|
||||
`easysdd/architecture/` 下的 doc 用文件名**第一段**（首个连字符之前）作为类型标记：`ui-chat.md` 和 `ui-events.md` 同属 `ui` 类，`api-routing.md` 自成 `api` 类。所以**所有架构 doc 命名必须遵循 `{type}-{slug}.md`**——只有一份且预计长期独占的，也要带个合理的 type 段（如 `cli-entry.md` 而非 `entry.md`），否则未来同类出现时统计不到、聚合不了。
|
||||
`codestable/architecture/` 下的 doc 用文件名**第一段**（首个连字符之前）作为类型标记：`ui-chat.md` 和 `ui-events.md` 同属 `ui` 类，`api-routing.md` 自成 `api` 类。所以**所有架构 doc 命名必须遵循 `{type}-{slug}.md`**——只有一份且预计长期独占的，也要带个合理的 type 段（如 `cli-entry.md` 而非 `entry.md`），否则未来同类出现时统计不到、聚合不了。
|
||||
|
||||
**触发条件**：某个 type 在 `easysdd/architecture/` 根目录下达到或超过 **6 份**文档时（即新加第 6 份的那一次操作），把这一类全部收进同名子目录。
|
||||
**触发条件**：某个 type 在 `codestable/architecture/` 根目录下达到或超过 **6 份**文档时（即新加第 6 份的那一次操作），把这一类全部收进同名子目录。
|
||||
|
||||
**收入子目录后的命名**：去掉 type 前缀。`ui-chat.md` → `ui/chat.md`、`ui-open-files-tree.md` → `ui/open-files-tree.md`。子目录里不再带 `ui-` 前缀。
|
||||
|
||||
**只升不降**：文档因删除回到 ≤5 份也不折回平铺，避免反复改一堆引用。
|
||||
|
||||
**触发时谁负责**：`easysdd-architecture` 的 `new` / `update` 模式在 Phase 6 落盘前主动检查；命中阈值时这次操作要把"本次新加 / 改的这份 + 已有同类全部"一起搬迁，并同步改 `DESIGN.md` 里所有相关链接（搬迁本身要在 Phase 5 一并给用户 review，不偷偷做）。`check` 模式不主动搬迁，但读 `architecture/` 时若发现某 type 已 ≥6 仍平铺，在报告末尾列为观察项交给用户。
|
||||
**触发时谁负责**：`cs-arch` 的 `new` / `update` 模式在 Phase 6 落盘前主动检查；命中阈值时这次操作要把"本次新加 / 改的这份 + 已有同类全部"一起搬迁，并同步改 `DESIGN.md` 里所有相关链接（搬迁本身要在 Phase 5 一并给用户 review，不偷偷做）。`check` 模式不主动搬迁，但读 `architecture/` 时若发现某 type 已 ≥6 仍平铺，在报告末尾列为观察项交给用户。
|
||||
|
||||
### 要改目录结构
|
||||
|
||||
改 `easysdd-onboarding/reference/shared-conventions.md` 这个模板，新项目 onboarding 时会带上新版本。已有项目需要手动同步 `easysdd/reference/shared-conventions.md`。
|
||||
改 `cs-onboard/reference/shared-conventions.md` 这个模板，新项目 onboarding 时会带上新版本。已有项目需要手动同步 `codestable/reference/shared-conventions.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -90,7 +90,7 @@ easysdd/
|
||||
|
||||
### 归档类文档
|
||||
|
||||
- `learning` / `trick` / `decision` / `explore` 四个子技能的产物**统一写入 `easysdd/compound/` 目录**
|
||||
- `learning` / `trick` / `decision` / `explore` 四个子技能的产物**统一写入 `codestable/compound/` 目录**
|
||||
- 每个文档必须在 frontmatter 顶部带 `doc_type` 字段（`learning` / `trick` / `decision` / `explore`），作为跨子技能的归属判定
|
||||
- 文件名统一用 `YYYY-MM-DD-{doc_type}-{slug}.md`——日期打头、`doc_type` 段在中间，`ls` 按名字排序就按归档日期排好；要按类型筛就 grep 中间那段
|
||||
- 各子技能在 `doc_type` 之外保留自己的专属 frontmatter（learning 的 `track`、trick 的 `type`、decision 的 `category`、explore 的 `type`）
|
||||
@@ -113,8 +113,8 @@ easysdd/
|
||||
## 2. {slug}-checklist.yaml 生命周期
|
||||
|
||||
- `{slug}-checklist.yaml` 是 feature 工作流的唯一执行清单
|
||||
- 由 `easysdd-feature-design` 在 `{slug}-design.md` 确认通过后一次生成
|
||||
- `easysdd-feature-fastforward` **不生成** checklist（也不写 design doc / acceptance），它是跳过 spec 流程、直接让 AI 写代码的超轻量通道，只做动手前的知识检索引导
|
||||
- 由 `cs-feat-design` 在 `{slug}-design.md` 确认通过后一次生成
|
||||
- `cs-feat-ff` **不生成** checklist（也不写 design doc / acceptance），它是跳过 spec 流程、直接让 AI 写代码的超轻量通道，只做动手前的知识检索引导
|
||||
|
||||
### design 的职责
|
||||
|
||||
@@ -142,41 +142,41 @@ easysdd/
|
||||
|
||||
## 2.5 roadmap ↔ feature 衔接协议
|
||||
|
||||
`easysdd/roadmap/{slug}/{slug}-items.yaml` 是"规划层"和"feature 执行层"之间的唯一接口。三个技能共同读写它——**不算跨 skill 耦合**，是 skill 都读写项目共享产物，和都读写 `easysdd/features/` 同理。
|
||||
`codestable/roadmap/{slug}/{slug}-items.yaml` 是"规划层"和"feature 执行层"之间的唯一接口。三个技能共同读写它——**不算跨 skill 耦合**，是 skill 都读写项目共享产物，和都读写 `codestable/features/` 同理。
|
||||
|
||||
### items.yaml 的状态机
|
||||
|
||||
```
|
||||
planned → in-progress （easysdd-feature-design 启动 feature 时改）
|
||||
in-progress → done （easysdd-feature-acceptance 验收完成时改）
|
||||
planned → dropped （easysdd-roadmap update 模式，用户决定不做时改）
|
||||
planned → in-progress （cs-feat-design 启动 feature 时改）
|
||||
in-progress → done （cs-feat-accept 验收完成时改）
|
||||
planned → dropped （cs-roadmap update 模式，用户决定不做时改）
|
||||
```
|
||||
|
||||
`done` 和 `dropped` 是终态。需要回退重做的要新加一条 slug 略改的条目，不要改终态。
|
||||
|
||||
### easysdd-roadmap 的职责
|
||||
### cs-roadmap 的职责
|
||||
|
||||
- 生成和维护 `{slug}-roadmap.md` 主文档和 `{slug}-items.yaml` 的结构
|
||||
- 把 `planned` 条目改 `dropped`（用户决定放弃时）
|
||||
- 不改 `in-progress` / `done` 状态——那两类跃迁由 feature 技能负责
|
||||
|
||||
### easysdd-feature-design 的职责
|
||||
### cs-feat-design 的职责
|
||||
|
||||
从 roadmap 条目起头 feature 时：
|
||||
|
||||
1. 在 `{slug}-design.md` frontmatter 加两个字段：`roadmap: {roadmap-slug}` + `roadmap_item: {子 feature slug}`
|
||||
2. 打开 `easysdd/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml`，把对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名（`YYYY-MM-DD-{slug}`）
|
||||
2. 打开 `codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml`，把对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名（`YYYY-MM-DD-{slug}`）
|
||||
3. 校验 yaml 语法
|
||||
|
||||
直接起 feature（不从 roadmap 来）时两个字段留空或省略，不触发任何 roadmap 写操作。
|
||||
|
||||
### easysdd-feature-acceptance 的职责
|
||||
### cs-feat-accept 的职责
|
||||
|
||||
验收流程走到收尾时：
|
||||
|
||||
1. 读 `{slug}-design.md` frontmatter 的 `roadmap` / `roadmap_item` 字段
|
||||
2. 字段为空 → 跳过 roadmap 回写
|
||||
3. 字段有值 → 打开 `easysdd/roadmap/{roadmap}/{roadmap}-items.yaml`，把 `roadmap_item` 对应条目 `status` 改为 `done`
|
||||
3. 字段有值 → 打开 `codestable/roadmap/{roadmap}/{roadmap}-items.yaml`，把 `roadmap_item` 对应条目 `status` 改为 `done`
|
||||
4. 同步主文档 `{roadmap}-roadmap.md` 子 feature 清单里对应行的显示状态（保持两份一致）
|
||||
5. 校验 yaml 语法
|
||||
|
||||
@@ -194,18 +194,18 @@ items.yaml 每份里只有一条 `minimal_loop: true`，标记"这条做完后
|
||||
|
||||
收尾时按顺序判断是否要推荐：
|
||||
|
||||
1. `easysdd-learning`：沉淀经验
|
||||
2. `easysdd-decisions`：记录长期约束/选型
|
||||
3. `easysdd-guidedoc`：更新开发者/用户指南
|
||||
4. `easysdd-libdoc`：更新公开 API 参考
|
||||
1. `cs-learn`：沉淀经验
|
||||
2. `cs-decide`：记录长期约束/选型
|
||||
3. `cs-guide`：更新开发者/用户指南
|
||||
4. `cs-libdoc`：更新公开 API 参考
|
||||
5. `scoped-commit`
|
||||
|
||||
### issue-fix
|
||||
|
||||
收尾时按顺序判断是否要推荐：
|
||||
|
||||
1. `easysdd-learning`：记录坑点
|
||||
2. `easysdd-decisions`：如修复暴露出长期约束
|
||||
1. `cs-learn`：记录坑点
|
||||
2. `cs-decide`：如修复暴露出长期约束
|
||||
3. `scoped-commit`
|
||||
|
||||
### 推荐动作的统一规则
|
||||
@@ -233,25 +233,25 @@ feature-acceptance 和 issue-fix 走完后要把本次产物提交为一个 comm
|
||||
|
||||
## 5. 归档检索规则
|
||||
|
||||
feature-design / issue-analyze / issue-fix 在动手前要到 `easysdd/compound/` 里搜已有的沉淀：
|
||||
feature-design / issue-analyze / issue-fix 在动手前要到 `codestable/compound/` 里搜已有的沉淀：
|
||||
|
||||
- 总是先搜 `architecture/` 和 `compound/` 两个目录
|
||||
- 在 `compound/` 里用 `doc_type` 字段按需过滤（learning / trick / decision / explore）
|
||||
- 搜到的结果只作为参考输入，不盲目套用——可能已过期（`status=outdated`）或不适合当前上下文
|
||||
- 搜到和当前方向冲突的 decision → 必须在方案 / 分析里正面回应"为什么仍然要这么做"或调整方向
|
||||
|
||||
子技能只补充本阶段的具体查询命令。完整搜索语法看 `easysdd/reference/tools.md`。
|
||||
子技能只补充本阶段的具体查询命令。完整搜索语法看 `codestable/reference/tools.md`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 归档类子技能共享守护规则
|
||||
|
||||
`easysdd-learning` / `easysdd-tricks` / `easysdd-decisions` / `easysdd-explore` 四个子技能共享下面这组规则。各子技能的正文只写本技能特有反模式，通用规则看这里：
|
||||
`cs-learn` / `cs-trick` / `cs-decide` / `cs-explore` 四个子技能共享下面这组规则。各子技能的正文只写本技能特有反模式，通用规则看这里：
|
||||
|
||||
1. **只增不删**——已归档的文档除非被明确取代（`status=superseded`），否则不删除；理由丢失的成本极高
|
||||
2. **宁缺毋滥**——用户说不出理由的节直接省略，不要 AI 编造听起来合理的内容
|
||||
3. **不替用户写实质内容**——AI 负责起草结构和串联语言，实质结论必须来自用户或可追溯的代码证据
|
||||
4. **可发现性检查**——写完后检查 `AGENTS.md` / `CLAUDE.md` 里有没有指引 AI 查阅 `easysdd/compound/`，没有就**提示**用户（不替用户改）
|
||||
4. **可发现性检查**——写完后检查 `AGENTS.md` / `CLAUDE.md` 里有没有指引 AI 查阅 `codestable/compound/`，没有就**提示**用户（不替用户改）
|
||||
5. **起草前先查重叠，而不是归档后**——动手写之前就用 `search-yaml.py --query` 查语义相近的旧文档。有命中就把候选列给用户，让用户在三条路径里选一条：
|
||||
- **更新已有条目**（默认优先）：沿用原文件名和原创建日期，**不新建文件**；修改正文相关节，在 frontmatter 补 `updated: YYYY-MM-DD`（归档当天）；变更超出小修的话在文末加一段"YYYY-MM-DD 更新"简述改了什么
|
||||
- **supersede 已有条目**：旧文档保留原文，把 `status` 改成 `superseded`，加 `superseded-by: {新文档文件名}`，正文顶部加一行 `**[已取代]** 见 {新文档 slug}`；然后新建文档，frontmatter 带 `supersedes: {旧文档文件名}`
|
||||
@@ -264,7 +264,7 @@ feature-design / issue-analyze / issue-fix 在动手前要到 `easysdd/compound/
|
||||
|
||||
## 7. 写代码时的反射检查
|
||||
|
||||
`easysdd-feature-implement` 和 `easysdd-issue-fix` 共用的一组代码质量反射检查。AI 默认会往"大函数 / 大文件 / god class / 处处特殊分支"这些方向漂，这一节的目的是把漂移截在发生的那一刻。
|
||||
`cs-feat-impl` 和 `cs-issue-fix` 共用的一组代码质量反射检查。AI 默认会往"大函数 / 大文件 / god class / 处处特殊分支"这些方向漂，这一节的目的是把漂移截在发生的那一刻。
|
||||
|
||||
**不是阈值，是触发器**。不是"超过 N 行必须拆"——硬数字会诱发为拆而拆，把自然聚合的代码切碎。这里每一条都是"遇到 X 情况就停下来问自己"的反射动作。
|
||||
|
||||
|
||||
@@ -1,62 +1,62 @@
|
||||
# easysdd 体系总览
|
||||
# CodeStable 体系总览
|
||||
|
||||
本文档介绍 easysdd 工作流家族整体——有哪些子技能、各管什么场景、产物怎么组织。无论是 AI 在运行时读到这个文件，还是人打开来看，都能对整个体系有个完整印象。
|
||||
本文档介绍 CodeStable 工作流家族整体——有哪些子技能、各管什么场景、产物怎么组织。无论是 AI 在运行时读到这个文件，还是人打开来看，都能对整个体系有个完整印象。
|
||||
|
||||
AI 辅助开发里，有几类场景会反复出现——加新功能、修 bug、遇到值得沉淀的经验、做技术选型、摸新模块的代码、接入新仓库。每种场景如果每次从零处理，都会出各自的典型问题：AI 给功能起的术语跟老代码冲突、bug 改完没人记得当时怎么诊断的、上周刚踩过的坑下周又踩一遍。
|
||||
|
||||
easysdd 把这几类场景各配一套子技能，产物放进统一的目录结构、带统一的 YAML frontmatter,互相之间可以检索引用。
|
||||
CodeStable 把这几类场景各配一套子技能，产物放进统一的目录结构、带统一的 YAML frontmatter,互相之间可以检索引用。
|
||||
|
||||
|
||||
## 技能分成四部分
|
||||
|
||||
**做事**——从一段模糊想法走到上线的功能、或者从一份错误报告走到修好的 bug:
|
||||
|
||||
- `easysdd-feature` — 新功能,brainstorm → design → implement → acceptance
|
||||
- `easysdd-issue` — 修 bug,report → analyze → fix
|
||||
- `easysdd-refactor` — 代码优化(行为不变、结构/性能/可读性变),scan → design → apply
|
||||
- `cs-feat` — 新功能,brainstorm → design → implement → acceptance
|
||||
- `cs-issue` — 修 bug,report → analyze → fix
|
||||
- `cs-refactor` — 代码优化(行为不变、结构/性能/可读性变),scan → design → apply
|
||||
|
||||
两类都不直接让 AI 写代码,而是先产出 spec(功能方案 / 问题分析),用户 review 后再动手,代码和 doc 一起交付。针对的是术语冲突、范围失控、改完不留存档这三种 AI 默认会出的问题。
|
||||
|
||||
**沉淀**——把做事过程产生的知识存下来,下次遇到同类问题直接复用:
|
||||
|
||||
- `easysdd-learning` — 回顾"做 X 时踩了 Y 这个坑"
|
||||
- `easysdd-tricks` — 处方"以后做 X 就这样做"
|
||||
- `easysdd-decisions` — 规定"全项目今后都按 X 来"
|
||||
- `easysdd-explore` — 存档"调查了 X 问题,看到代码里是这样的"
|
||||
- `cs-learn` — 回顾"做 X 时踩了 Y 这个坑"
|
||||
- `cs-trick` — 处方"以后做 X 就这样做"
|
||||
- `cs-decide` — 规定"全项目今后都按 X 来"
|
||||
- `cs-explore` — 存档"调查了 X 问题,看到代码里是这样的"
|
||||
|
||||
**讨论层**——想法还模糊时的统一入口,不直接产出设计或代码:
|
||||
|
||||
- `easysdd-brainstorm` — 和用户对话做分诊:case 1(已经够清楚,直接 feature-design)、case 2(小需求,在 feature 里继续讨论并落 `{slug}-brainstorm.md`)、case 3(大需求,移交给 roadmap)
|
||||
- `cs-brainstorm` — 和用户对话做分诊:case 1(已经够清楚,直接 feature-design)、case 2(小需求,在 feature 里继续讨论并落 `{slug}-brainstorm.md`)、case 3(大需求,移交给 roadmap)
|
||||
|
||||
**辅助**——围着前几类转的周边工具:
|
||||
|
||||
- `easysdd-onboarding` — 把新仓库接入 easysdd 目录结构
|
||||
- `easysdd-requirements` — 起草或刷新 `easysdd/requirements/` 下的需求文档("为什么要有这个能力",只记现状)
|
||||
- `easysdd-architecture` — 架构相关一站式:起草新架构文档 / 刷新已有文档 / 做架构体检(含 design 自洽 / design↔代码一致 / architecture 目录多份文档间一致)。architecture 只记现状
|
||||
- `easysdd-roadmap` — 把一块装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单,作为后续多次 feature 流程的种子和排期依据;独立于需求 / 架构档案
|
||||
- `easysdd-guidedoc` — 写给外部读者的开发者指南 / 用户指南
|
||||
- `easysdd-libdoc` — 为库的公开 API 逐条目生成参考文档
|
||||
- `cs-onboard` — 把新仓库接入 CodeStable 目录结构
|
||||
- `cs-req` — 起草或刷新 `codestable/requirements/` 下的需求文档("为什么要有这个能力",只记现状)
|
||||
- `cs-arch` — 架构相关一站式:起草新架构文档 / 刷新已有文档 / 做架构体检(含 design 自洽 / design↔代码一致 / architecture 目录多份文档间一致)。architecture 只记现状
|
||||
- `cs-roadmap` — 把一块装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单,作为后续多次 feature 流程的种子和排期依据;独立于需求 / 架构档案
|
||||
- `cs-guide` — 写给外部读者的开发者指南 / 用户指南
|
||||
- `cs-libdoc` — 为库的公开 API 逐条目生成参考文档
|
||||
|
||||
|
||||
## 场景路由
|
||||
|
||||
仓库里还没有 `easysdd/` 目录,先用 `easysdd-onboarding` 搭骨架。
|
||||
仓库里还没有 `codestable/` 目录,先用 `cs-onboard` 搭骨架。
|
||||
|
||||
| 场景 | 子技能 |
|
||||
|---|---|
|
||||
| 想法还模糊 / "有个想法没想清楚" / "先聊聊" | `easysdd-brainstorm`(分诊后路由到 design / feature-brainstorm 落盘 / roadmap) |
|
||||
| 新功能 / 新能力 | `easysdd-feature` |
|
||||
| BUG / 异常 / 文档错误 | `easysdd-issue` |
|
||||
| 代码优化 / 重构 / 重写(行为不变) | `easysdd-refactor` |
|
||||
| 摸代码、提问调研 | `easysdd-explore` |
|
||||
| 补 / 更新需求文档 | `easysdd-requirements` |
|
||||
| 补 / 更新 / 检查架构文档 | `easysdd-architecture` |
|
||||
| 大需求拆解 / 排期规划 | `easysdd-roadmap` |
|
||||
| 技术选型 / 约束 / 规约 | `easysdd-decisions` |
|
||||
| 踩坑回顾、经验总结 | `easysdd-learning` |
|
||||
| 可复用的编程模式、库用法 | `easysdd-tricks` |
|
||||
| 开发者指南 / 用户指南 | `easysdd-guidedoc` |
|
||||
| 库 API 参考 | `easysdd-libdoc` |
|
||||
| 想法还模糊 / "有个想法没想清楚" / "先聊聊" | `cs-brainstorm`(分诊后路由到 design / feature-brainstorm 落盘 / roadmap) |
|
||||
| 新功能 / 新能力 | `cs-feat` |
|
||||
| BUG / 异常 / 文档错误 | `cs-issue` |
|
||||
| 代码优化 / 重构 / 重写(行为不变) | `cs-refactor` |
|
||||
| 摸代码、提问调研 | `cs-explore` |
|
||||
| 补 / 更新需求文档 | `cs-req` |
|
||||
| 补 / 更新 / 检查架构文档 | `cs-arch` |
|
||||
| 大需求拆解 / 排期规划 | `cs-roadmap` |
|
||||
| 技术选型 / 约束 / 规约 | `cs-decide` |
|
||||
| 踩坑回顾、经验总结 | `cs-learn` |
|
||||
| 可复用的编程模式、库用法 | `cs-trick` |
|
||||
| 开发者指南 / 用户指南 | `cs-guide` |
|
||||
| 库 API 参考 | `cs-libdoc` |
|
||||
|
||||
完整的操作手册、退出条件、和其他工作流的关系,各子技能里讲。
|
||||
|
||||
@@ -65,12 +65,12 @@ easysdd 把这几类场景各配一套子技能，产物放进统一的目录结
|
||||
|
||||
learning / trick / decision / explore 都是存档文档类型,区别在记录内容的性质:
|
||||
|
||||
- 回顾某次做 X 时发现了 Y —— `easysdd-learning`(产出 `doc_type: learning`)
|
||||
- 以后做 X 就这样做的处方 —— `easysdd-tricks`(产出 `doc_type: trick`)
|
||||
- 全项目今后都得遵守的规定 —— `easysdd-decisions`(产出 `doc_type: decision`)
|
||||
- 调查了一个问题,留份证据 —— `easysdd-explore`(产出 `doc_type: explore`)
|
||||
- 回顾某次做 X 时发现了 Y —— `cs-learn`(产出 `doc_type: learning`)
|
||||
- 以后做 X 就这样做的处方 —— `cs-trick`(产出 `doc_type: trick`)
|
||||
- 全项目今后都得遵守的规定 —— `cs-decide`(产出 `doc_type: decision`)
|
||||
- 调查了一个问题,留份证据 —— `cs-explore`(产出 `doc_type: explore`)
|
||||
|
||||
四者共用 `easysdd/compound/` 目录,靠 frontmatter 的 `doc_type` 字段和文件名中间的类型段(`YYYY-MM-DD-{doc_type}-{slug}.md`)区分。每个子技能只认自己的 `doc_type`,不读写别家产物——**"A 和 B 有什么不同"这种判断由本节负责,子技能里不再重复**。
|
||||
四者共用 `codestable/compound/` 目录,靠 frontmatter 的 `doc_type` 字段和文件名中间的类型段(`YYYY-MM-DD-{doc_type}-{slug}.md`)区分。每个子技能只认自己的 `doc_type`,不读写别家产物——**"A 和 B 有什么不同"这种判断由本节负责,子技能里不再重复**。
|
||||
|
||||
|
||||
## 现状档案 vs 规划档案 vs 单次动作
|
||||
@@ -90,19 +90,19 @@ feature 走 brainstorm(可选) → design → implement → acceptance,issue 走
|
||||
|
||||
AI 最常见的问题是一口气铺几百行代码才让人看——等发现问题已经很难中止。阶段间的人工 checkpoint 就是为了早一步中止。每个 checkpoint 具体检查什么,对应子技能里讲。
|
||||
|
||||
例外两种:issue 根因一眼确定时走快速通道,跳过 analyze 直接 fix;feature 范围小时走 `easysdd-feature-fastforward`,写完 spec 直接进实现。
|
||||
例外两种:issue 根因一眼确定时走快速通道,跳过 analyze 直接 fix;feature 范围小时走 `cs-feat-ff`,写完 spec 直接进实现。
|
||||
|
||||
|
||||
## 进一步参考
|
||||
|
||||
- `easysdd/reference/shared-conventions.md` — 目录结构、YAML frontmatter 口径、`{slug}-checklist.yaml` 生命周期、收尾 commit 约定、归档类共享规则
|
||||
- `easysdd/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法
|
||||
- `easysdd/reference/maintainer-notes.md` — 断点恢复、新增子工作流的登记
|
||||
- `codestable/reference/shared-conventions.md` — 目录结构、YAML frontmatter 口径、`{slug}-checklist.yaml` 生命周期、收尾 commit 约定、归档类共享规则
|
||||
- `codestable/reference/tools.md` — `search-yaml.py` / `validate-yaml.py` 用法
|
||||
- `codestable/reference/maintainer-notes.md` — 断点恢复、新增子工作流的登记
|
||||
|
||||
目录结构(requirements/、architecture/、roadmap/、features/、issues/、compound/、tools/、reference/)的权威定义在 `shared-conventions.md`。要改目录先改那里——方法是改 `easysdd-onboarding/reference/shared-conventions.md` 这个模板,新项目 onboarding 时会带上新版本。
|
||||
目录结构(requirements/、architecture/、roadmap/、features/、issues/、compound/、tools/、reference/)的权威定义在 `shared-conventions.md`。要改目录先改那里——方法是改 `cs-onboard/reference/shared-conventions.md` 这个模板,新项目 onboarding 时会带上新版本。
|
||||
|
||||
|
||||
## 相关
|
||||
|
||||
- `AGENTS.md` — 全项目代码规范和已知坑
|
||||
- `easysdd/architecture/DESIGN.md` — 项目架构总入口
|
||||
- `codestable/architecture/DESIGN.md` — 项目架构总入口
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# easysdd 工具用法参考
|
||||
# CodeStable 工具用法参考
|
||||
|
||||
本文件由 `easysdd-onboarding` 复制到项目的 `easysdd/reference/tools.md`，所有 easysdd 子技能用项目相对路径 `easysdd/reference/tools.md` 引用。
|
||||
本文件由 `cs-onboard` 复制到项目的 `codestable/reference/tools.md`，所有 CodeStable 子技能用项目相对路径 `codestable/reference/tools.md` 引用。
|
||||
|
||||
`easysdd/tools/` 下共享脚本的完整用法参考。子技能里只写本技能特有的 1-2 行典型查询；完整语法和示例看这里。
|
||||
`codestable/tools/` 下共享脚本的完整用法参考。子技能里只写本技能特有的 1-2 行典型查询；完整语法和示例看这里。
|
||||
|
||||
---
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
### 基本语法
|
||||
|
||||
```bash
|
||||
python easysdd/tools/search-yaml.py --dir {目录} [--filter key=value]... [--query "全文关键词"] [--sort-by FIELD [--order asc|desc]] [--full] [--json]
|
||||
python codestable/tools/search-yaml.py --dir {目录} [--filter key=value]... [--query "全文关键词"] [--sort-by FIELD [--order asc|desc]] [--full] [--json]
|
||||
```
|
||||
|
||||
### filter 语法
|
||||
@@ -29,56 +29,56 @@ python easysdd/tools/search-yaml.py --dir {目录} [--filter key=value]... [--qu
|
||||
|
||||
### 常用命令
|
||||
|
||||
沉淀类文档统一在 `easysdd/compound/`，用 `doc_type` 字段区分四个子技能的产物，内部还有各自的细分字段：
|
||||
沉淀类文档统一在 `codestable/compound/`，用 `doc_type` 字段区分四个子技能的产物，内部还有各自的细分字段：
|
||||
|
||||
```bash
|
||||
# 按 doc_type 筛选
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter status=active
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter status=active
|
||||
|
||||
# doc_type + 子技能内部细分字段
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter track=pitfall
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter category=constraint
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter type=pattern
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --filter type=question
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter track=pitfall
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter category=constraint
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter type=pattern
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter type=question
|
||||
|
||||
# 按 tag（列表元素包含匹配）
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter tags~=prisma
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter tags~=prisma
|
||||
|
||||
# 全文搜索
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "shadow database"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --query "shadow database"
|
||||
|
||||
# 按领域/框架/语言筛选
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter area=frontend
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter framework~=vue
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter language=typescript
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter area=frontend
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter framework~=vue
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter language=typescript
|
||||
|
||||
# 搜索 feature 方案 doc
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/features --filter doc_type=feature-design --filter status=approved
|
||||
python codestable/tools/search-yaml.py --dir codestable/features --filter doc_type=feature-design --filter status=approved
|
||||
|
||||
# 输出控制
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active --full
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter tags~=llm --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active --full
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter tags~=llm --json
|
||||
|
||||
# 按时间排序
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --sort-by date --order desc # 最近归档的在前
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/library-docs --sort-by last_reviewed --order asc # 最久没 review 的在前（找陈旧文档）
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/guides --filter status=current --sort-by last_reviewed --order asc
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --sort-by date --order desc # 最近归档的在前
|
||||
python codestable/tools/search-yaml.py --dir codestable/library-docs --sort-by last_reviewed --order asc # 最久没 review 的在前（找陈旧文档）
|
||||
python codestable/tools/search-yaml.py --dir codestable/guides --filter status=current --sort-by last_reviewed --order asc
|
||||
```
|
||||
|
||||
### 典型使用场景
|
||||
|
||||
| 场景 | 命令建议 |
|
||||
|---|---|
|
||||
| feature-design 开始前查已有归档 | 搜 `easysdd/compound` 目录，按 `--query "{关键词}"` 全文搜；要分类看就加 `--filter doc_type={learning\|trick\|decision\|explore}` |
|
||||
| issue-analyze 根因分析前查历史 | 搜 `easysdd/compound` `--filter doc_type=learning --filter track=pitfall`、再搜 `--filter doc_type=trick --filter type=library`，按相关组件/框架过滤 |
|
||||
| 归档落盘后查重叠 | 搜 `easysdd/compound --query "{关键词}" --json`，看有无语义重叠 |
|
||||
| 新人了解项目规约 | `--dir easysdd/compound --filter doc_type=decision --filter status=active` |
|
||||
| 按技术栈浏览技巧 | `--dir easysdd/compound --filter doc_type=trick --filter language={语言} --filter status=active` |
|
||||
| feature-design 开始前查已有归档 | 搜 `codestable/compound` 目录，按 `--query "{关键词}"` 全文搜；要分类看就加 `--filter doc_type={learning\|trick\|decision\|explore}` |
|
||||
| issue-analyze 根因分析前查历史 | 搜 `codestable/compound` `--filter doc_type=learning --filter track=pitfall`、再搜 `--filter doc_type=trick --filter type=library`，按相关组件/框架过滤 |
|
||||
| 归档落盘后查重叠 | 搜 `codestable/compound --query "{关键词}" --json`，看有无语义重叠 |
|
||||
| 新人了解项目规约 | `--dir codestable/compound --filter doc_type=decision --filter status=active` |
|
||||
| 按技术栈浏览技巧 | `--dir codestable/compound --filter doc_type=trick --filter language={语言} --filter status=active` |
|
||||
| 找最久没 review 的库文档 / 指南 | `--dir {目录} --filter status=current --sort-by last_reviewed --order asc` |
|
||||
| 看最近沉淀了哪些经验 | `--dir easysdd/compound --filter doc_type=learning --sort-by date --order desc` |
|
||||
| 看最近沉淀了哪些经验 | `--dir codestable/compound --filter doc_type=learning --sort-by date --order desc` |
|
||||
|
||||
---
|
||||
|
||||
@@ -88,11 +88,11 @@ YAML 语法校验工具。用于验证 frontmatter 语法和必填字段。
|
||||
|
||||
```bash
|
||||
# 校验单个文件的 YAML 语法
|
||||
python easysdd/tools/validate-yaml.py --file {文件路径} --yaml-only
|
||||
python codestable/tools/validate-yaml.py --file {文件路径} --yaml-only
|
||||
|
||||
# 校验必填字段
|
||||
python easysdd/tools/validate-yaml.py --file {文件路径} --require doc_type --require status
|
||||
python codestable/tools/validate-yaml.py --file {文件路径} --require doc_type --require status
|
||||
|
||||
# 批量校验目录下所有文件
|
||||
python easysdd/tools/validate-yaml.py --dir {目录} --require doc_type --require status
|
||||
python codestable/tools/validate-yaml.py --dir {目录} --require doc_type --require status
|
||||
```
|
||||
|
||||
@@ -10,24 +10,24 @@ Filter syntax (--filter flag, repeatable, AND logic):
|
||||
key~=value Substring match on a string field, or element-in for list fields
|
||||
|
||||
Usage examples:
|
||||
# Search easysdd/compound (learning / trick / decision / explore docs share this dir)
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter track=pitfall
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter tags~=prisma
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active --full
|
||||
# Search codestable/compound (learning / trick / decision / explore docs share this dir)
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter track=pitfall
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter tags~=prisma
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active --full
|
||||
|
||||
# Full-text search in body + frontmatter values
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "shadow database"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --query "shadow database"
|
||||
|
||||
# JSON output for AI agent consumption
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=learning --filter track=knowledge --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter track=knowledge --json
|
||||
|
||||
# Sort by a frontmatter date field (works on any ISO-8601 date string, YAML date, or sortable value)
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/library-docs --sort-by last_reviewed --order asc # oldest first (stalest)
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --sort-by date --order desc # newest first
|
||||
python codestable/tools/search-yaml.py --dir codestable/library-docs --sort-by last_reviewed --order asc # oldest first (stalest)
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --sort-by date --order desc # newest first
|
||||
|
||||
# Works on any yaml-frontmatter markdown directory
|
||||
python easysdd/tools/search-yaml.py --dir docs/decisions --filter status=accepted
|
||||
python easysdd/tools/search-yaml.py --dir content/posts --filter tags~=python --query "asyncio"
|
||||
python codestable/tools/search-yaml.py --dir docs/decisions --filter status=accepted
|
||||
python codestable/tools/search-yaml.py --dir content/posts --filter tags~=python --query "asyncio"
|
||||
"""
|
||||
|
||||
import argparse
|
||||
|
||||
@@ -11,20 +11,20 @@ Designed for AI agent use: structured output, exit code reflects pass/fail,
|
||||
no required external dependencies (falls back to builtin parser if PyYAML unavailable).
|
||||
|
||||
Usage examples:
|
||||
# Validate all .md files under easysdd/features
|
||||
python easysdd/tools/validate-yaml.py --dir easysdd/features
|
||||
# Validate all .md files under codestable/features
|
||||
python codestable/tools/validate-yaml.py --dir codestable/features
|
||||
|
||||
# Validate a single file
|
||||
python easysdd/tools/validate-yaml.py --file easysdd/features/2026-04-11-auth/auth-design.md
|
||||
python codestable/tools/validate-yaml.py --file codestable/features/2026-04-11-auth/auth-design.md
|
||||
|
||||
# Check that required fields exist in frontmatter
|
||||
python easysdd/tools/validate-yaml.py --dir easysdd/features --require doc_type --require status
|
||||
python codestable/tools/validate-yaml.py --dir codestable/features --require doc_type --require status
|
||||
|
||||
# JSON output for programmatic consumption
|
||||
python easysdd/tools/validate-yaml.py --dir docs/api --json
|
||||
python codestable/tools/validate-yaml.py --dir docs/api --json
|
||||
|
||||
# Validate the libdoc manifest
|
||||
python easysdd/tools/validate-yaml.py --file docs/api/manifest.yaml --yaml-only
|
||||
python codestable/tools/validate-yaml.py --file docs/api/manifest.yaml --yaml-only
|
||||
"""
|
||||
|
||||
import argparse
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-refactor-fastforward
|
||||
name: cs-refactor-ff
|
||||
description: refactor 流程的超轻量通道——改动明显小到不值得走完整 scan → design → apply 三阶段时用。AI 直接识别 1-3 条低风险优化点、和用户一次确认、按经典方法原地改、跑测试自证。不写 scan 清单、不写 design、不拆多步 HUMAN 验证。触发场景：用户说"快速重构"、"小重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"，且改动范围明显在单函数 / 单组件局部、有测试可自证。
|
||||
---
|
||||
|
||||
# easysdd-refactor-fastforward
|
||||
# cs-refactor-ff
|
||||
|
||||
用户说"优化一下这个函数"而改动明显很小（单个函数变长了、一个组件里抽个 composable、一段重复代码合并）时，走完整三阶段太重。fastforward 做一件事：让 AI 像平时一样直接改，但守住 refactor 的底线——行为等价、引用经典方法、跑测试自证。
|
||||
|
||||
@@ -13,7 +13,7 @@ description: refactor 流程的超轻量通道——改动明显小到不值得
|
||||
|
||||
## 入场 3 条硬检查（不过就退出到完整流程）
|
||||
|
||||
开写前问自己 3 件事，任一不过就退到 `easysdd-refactor` 走完整流程：
|
||||
开写前问自己 3 件事，任一不过就退到 `cs-refactor` 走完整流程：
|
||||
|
||||
1. **行为真的不变吗？** 用户描述里夹带了"顺便支持 X / 改成 Y"——这是行为改动，不是 refactor，让用户拆出去走 feature / issue
|
||||
2. **范围真的小吗？** 超过 1 个文件、或单文件超过 100 行改动、或预计改动点超过 3 处——退到完整流程
|
||||
@@ -73,9 +73,9 @@ fastforward 不读完整方法库，但要守住："每一处改动都能对应
|
||||
|
||||
## 文件产出
|
||||
|
||||
默认**不在 `easysdd/refactors/` 下建目录**——fastforward 的价值就在不留存档。
|
||||
默认**不在 `codestable/refactors/` 下建目录**——fastforward 的价值就在不留存档。
|
||||
|
||||
例外：用户明确说"这次小重构要留个记录"——建一个 `easysdd/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md`，内容就是上面那句汇报再加一段"做了什么 / 为什么"。不写 design，不写 checklist。
|
||||
例外：用户明确说"这次小重构要留个记录"——建一个 `codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md`，内容就是上面那句汇报再加一段"做了什么 / 为什么"。不写 design，不写 checklist。
|
||||
|
||||
---
|
||||
|
||||
@@ -90,7 +90,7 @@ fastforward 不读完整方法库，但要守住："每一处改动都能对应
|
||||
- 用户追加 "顺便改一下 X" 带入行为改动
|
||||
- 改完 AI 自证失败（测试挂了）且不是简单修正能搞定
|
||||
|
||||
切回方式：触发 `easysdd-refactor`，从 scan 阶段开始。已改的部分要么提交保留、要么 `git restore` 回到干净状态再扫，看用户决定。
|
||||
切回方式：触发 `cs-refactor`，从 scan 阶段开始。已改的部分要么提交保留、要么 `git restore` 回到干净状态再扫，看用户决定。
|
||||
|
||||
---
|
||||
|
||||
@@ -115,6 +115,6 @@ fastforward 不读完整方法库，但要守住："每一处改动都能对应
|
||||
|
||||
## 相关
|
||||
|
||||
- `easysdd-refactor/SKILL.md` — 完整 refactor 流程，复杂时切过来
|
||||
- `easysdd-refactor/reference/methods.md` — 完整方法库（fastforward 用户想查也可以翻，但执行不依赖它）
|
||||
- `easysdd/reference/system-overview.md` — easysdd 体系总览
|
||||
- `cs-refactor/SKILL.md` — 完整 refactor 流程，复杂时切过来
|
||||
- `cs-refactor/reference/methods.md` — 完整方法库（fastforward 用户想查也可以翻，但执行不依赖它）
|
||||
- `codestable/reference/system-overview.md` — CodeStable 体系总览
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: easysdd-refactor
|
||||
name: cs-refactor
|
||||
description: 做代码优化时进入这套子流程——处理"行为不变、结构变"的工作（结构 / 性能 / 可读性），把单模块内部的优化从"AI 胡乱重构"改成"先扫出清单、和用户逐条确认、按方法库分步执行、每步人工放行"。触发场景：用户说"优化一下 / 重构 / 重写 / 拆一下 / 性能不行 / 代码太长"这类，且不夹带行为改动。不处理新需求（走 feature）、不处理 bug（走 issue）、不处理跨模块架构重划（走 architecture + decisions）。
|
||||
---
|
||||
|
||||
# easysdd-refactor
|
||||
# cs-refactor
|
||||
|
||||
AI 自己重构代码有两个稳定的失败模式：一是不知道模块的真实需求和约束，改出来的东西功能不等价；二是一次吞掉的范围超过上下文承载，改到后面忘了前面的约束。这条流程在"想优化"和"动手改"之间塞了一份扫描清单 + 方法库，让 AI 只接自己能稳定做对的活，剩下的老实停下来让路。
|
||||
|
||||
@@ -19,7 +19,7 @@ scan（扫出优化点清单）→ design（和用户定做哪几条、按什么
|
||||
|
||||
## Fastforward 模式（小重构走这里）
|
||||
|
||||
改动明显很小——单函数、单组件、1-3 处优化、有测试可自证、不需要 HUMAN 目视——走完整三阶段太重。触发 `easysdd-refactor-fastforward`：AI 直接识别、一次对齐、原地改、跑测试自证，不产出 scan / design / checklist。
|
||||
改动明显很小——单函数、单组件、1-3 处优化、有测试可自证、不需要 HUMAN 目视——走完整三阶段太重。触发 `cs-refactor-ff`：AI 直接识别、一次对齐、原地改、跑测试自证，不产出 scan / design / checklist。
|
||||
|
||||
触发信号：用户说"小重构"、"快速重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"。
|
||||
|
||||
@@ -37,10 +37,10 @@ scan（扫出优化点清单）→ design（和用户定做哪几条、按什么
|
||||
|
||||
## 文件放哪儿
|
||||
|
||||
refactor 产物聚在 `easysdd/refactors/` 下，每次独立目录：
|
||||
refactor 产物聚在 `codestable/refactors/` 下，每次独立目录：
|
||||
|
||||
```
|
||||
easysdd/
|
||||
codestable/
|
||||
└── refactors/
|
||||
└── {YYYY-MM-DD}-{slug}/
|
||||
├── {slug}-scan.md ← 阶段 1 产出的优化点清单
|
||||
@@ -237,10 +237,10 @@ refactor: {YYYY-MM-DD}-{slug}
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `easysdd/reference/system-overview.md` — easysdd 体系总览
|
||||
- `easysdd-refactor-fastforward/SKILL.md` — 小重构超轻量通道
|
||||
- `codestable/reference/system-overview.md` — CodeStable 体系总览
|
||||
- `cs-refactor-ff/SKILL.md` — 小重构超轻量通道
|
||||
- `reference/scan-checklist-format.md` — scan 清单条目的字段、顺序、硬约束、反模式样本
|
||||
- `reference/refusal-routing.md` — scan 前置检查 7 条 + 路由表 + 拒绝输出格式
|
||||
- `reference/methods.md` — 重构方法库（L1-L4 四层分类，统一字段）
|
||||
- `easysdd/reference/shared-conventions.md` — 跨工作流共享口径
|
||||
- `codestable/reference/shared-conventions.md` — 跨工作流共享口径
|
||||
- 项目架构总入口 — scan 前需要翻一下，确认模块边界在哪
|
||||
|
||||
@@ -13,7 +13,7 @@ scan 开始之前跑一遍 7 条前置检查。任何一条命中，**中止 sca
|
||||
**为什么停**：refactor 的底线是行为等价。混着做，验证"只动结构"就没法进行——改完出问题分不清是重构引入的还是新能力引入的。
|
||||
|
||||
**路由**：
|
||||
> 这次描述里有"{具体触发词}"，属于行为改动，不在 refactor 范围内。建议拆成两件事：行为改动走 `easysdd-feature`（新能力）或 `easysdd-issue`（bug 修），结构改动走 refactor。拆完再回来。
|
||||
> 这次描述里有"{具体触发词}"，属于行为改动，不在 refactor 范围内。建议拆成两件事：行为改动走 `cs-feat`（新能力）或 `cs-issue`（bug 修），结构改动走 refactor。拆完再回来。
|
||||
|
||||
---
|
||||
|
||||
@@ -51,8 +51,8 @@ scan 开始之前跑一遍 7 条前置检查。任何一条命中，**中止 sca
|
||||
|
||||
**路由**：
|
||||
> 扫描时发现主要问题是跨模块的：{具体描述，如"UserForm 和 UserProfile 都在复制 validateEmail 逻辑"}。这不是单模块 refactor 能解决的，需要先走：
|
||||
> 1. `easysdd-architecture` 更新模块边界图
|
||||
> 2. `easysdd-decisions` 记下新的依赖原则
|
||||
> 1. `cs-arch` 更新模块边界图
|
||||
> 2. `cs-decide` 记下新的依赖原则
|
||||
> 3. 回来拆成若干单模块 refactor 任务落地
|
||||
>
|
||||
> 现在开单模块 scan 意义不大。
|
||||
@@ -71,7 +71,7 @@ scan 开始之前跑一遍 7 条前置检查。任何一条命中，**中止 sca
|
||||
|
||||
**路由**：
|
||||
> 扫出来的候选点主要是风格口味（命名/引号/格式）。这类问题正确的处理方式不是 refactor，而是：
|
||||
> 1. `easysdd-decisions` 拍板一个风格规约
|
||||
> 1. `cs-decide` 拍板一个风格规约
|
||||
> 2. 在 ESLint / Prettier / 类似工具里加对应规则
|
||||
> 3. 跑一次 `--fix` 自动修全项目
|
||||
>
|
||||
@@ -111,7 +111,7 @@ scan 开始之前跑一遍 7 条前置检查。任何一条命中，**中止 sca
|
||||
|
||||
**路由**：
|
||||
> 目前范围涉及 {N 个文件 / M 行}，超过单次 scan 的上限。建议先做一件事再回来：
|
||||
> - 如果模块内部本来就该拆分 → 先走 `easysdd-architecture` 做整体切分
|
||||
> - 如果模块内部本来就该拆分 → 先走 `cs-arch` 做整体切分
|
||||
> - 如果范围可缩 → 和用户一起挑一个子集（"就看 {具体组件/文件}"），下次再扫别的部分
|
||||
>
|
||||
> 一次扫一小块比一次扫全貌更能产出可决策的清单。
|
||||
|
||||
+23
-23
@@ -1,13 +1,13 @@
|
||||
---
|
||||
name: easysdd-requirements
|
||||
description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档——用**用户故事 + 平铺语言**描述一个能力"因什么而产生、如何解决、边界在哪"，让非技术读者也能扫一眼看懂系统突出的地方。和 architecture 分层：requirement 是"问题空间"（为什么要有这个能力），architecture 是"解空间"（用什么结构实现它）。两种模式：new（从零起草一份新需求 doc）、update（按新素材或实现变化刷新已有 doc）。单目标规则——一次只动一份文档。触发场景：用户说"补一份需求 doc"、"把这块能力的需求写下来"、"更新 requirements 目录"，或 feature-design 阶段发现本次要实现的能力还没有对应的 requirement。
|
||||
name: cs-req
|
||||
description: 为项目起草或更新 `codestable/requirements/` 下的需求文档——用**用户故事 + 平铺语言**描述一个能力"因什么而产生、如何解决、边界在哪"，让非技术读者也能扫一眼看懂系统突出的地方。和 architecture 分层：requirement 是"问题空间"（为什么要有这个能力），architecture 是"解空间"（用什么结构实现它）。两种模式：new（从零起草一份新需求 doc）、update（按新素材或实现变化刷新已有 doc）。单目标规则——一次只动一份文档。触发场景：用户说"补一份需求 doc"、"把这块能力的需求写下来"、"更新 requirements 目录"，或 feature-design 阶段发现本次要实现的能力还没有对应的 requirement。
|
||||
---
|
||||
|
||||
# easysdd-requirements
|
||||
# cs-req
|
||||
|
||||
`easysdd/requirements/` 是项目的"能力清单"——每份文档描述**一个能力因什么问题而产生、怎么解决、边界在哪**，写成人话，非技术读者也能扫一眼看懂。架构文档讲"怎么搭"，需求文档讲"为什么要有这个"。两者分开记录的好处是：单独讨论需求时不被实现细节干扰，单独讨论架构时也不被产品视角牵着走。
|
||||
`codestable/requirements/` 是项目的"能力清单"——每份文档描述**一个能力因什么问题而产生、怎么解决、边界在哪**，写成人话，非技术读者也能扫一眼看懂。架构文档讲"怎么搭"，需求文档讲"为什么要有这个"。两者分开记录的好处是：单独讨论需求时不被实现细节干扰，单独讨论架构时也不被产品视角牵着走。
|
||||
|
||||
**requirement 是现状档案，不是计划档案**。只描述"这个能力现在已经存在、边界长这样"。默认只在 feature-acceptance 时跟着代码一起刷新（feature 实现改了边界 / 用户故事，回写到 req），必要时才由本技能主动 update 模式更新。**不记"打算做什么"、不记"下一步会加什么"**——那些属于 `easysdd-roadmap` 的规划层。用户说"我想要 X 能力"但 X 还没做出来时，不要在这里开新 req——要么能力已经在做且需要先把目标态写下来指导实现（走 roadmap 拆解 + 后续 feature-acceptance 回写 req），要么直接走 roadmap。
|
||||
**requirement 是现状档案，不是计划档案**。只描述"这个能力现在已经存在、边界长这样"。默认只在 feature-acceptance 时跟着代码一起刷新（feature 实现改了边界 / 用户故事，回写到 req），必要时才由本技能主动 update 模式更新。**不记"打算做什么"、不记"下一步会加什么"**——那些属于 `cs-roadmap` 的规划层。用户说"我想要 X 能力"但 X 还没做出来时，不要在这里开新 req——要么能力已经在做且需要先把目标态写下来指导实现（走 roadmap 拆解 + 后续 feature-acceptance 回写 req），要么直接走 roadmap。
|
||||
|
||||
需求文档的价值在于**扫一眼就能抓到重点**——用户故事在最前面、痛点和解法各一段短的、边界用列表。AI 写需求文档最容易出的几种问题都会破坏"扫一眼就抓到重点"这个特性：
|
||||
|
||||
@@ -18,8 +18,8 @@ description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档
|
||||
|
||||
下面整套规则就是为了不让这四种情况发生。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。
|
||||
> 一份样例文档看 `easysdd/reference/requirement-example.md`——起草前读一遍对齐语气。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。
|
||||
> 一份样例文档看 `codestable/reference/requirement-example.md`——起草前读一遍对齐语气。
|
||||
|
||||
---
|
||||
|
||||
@@ -31,11 +31,11 @@ description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档
|
||||
|
||||
不适用：
|
||||
|
||||
- 用户要写的是"这个系统技术上怎么搭" → 转 `easysdd-architecture`
|
||||
- 用户要写的是单次 feature 的方案 → 转 `easysdd-feature-design`
|
||||
- 用户要拍板一条长期规约 / 选型 → 转 `easysdd-decisions`
|
||||
- 用户要写外部读者的"怎么用" → 转 `easysdd-guidedoc`
|
||||
- 用户抛出一块大需求想拆成几轮做（"我想要一个 X 系统"）→ 转 `easysdd-roadmap`——那是规划层，不往 req 里塞"待做能力"
|
||||
- 用户要写的是"这个系统技术上怎么搭" → 转 `cs-arch`
|
||||
- 用户要写的是单次 feature 的方案 → 转 `cs-feat-design`
|
||||
- 用户要拍板一条长期规约 / 选型 → 转 `cs-decide`
|
||||
- 用户要写外部读者的"怎么用" → 转 `cs-guide`
|
||||
- 用户抛出一块大需求想拆成几轮做（"我想要一个 X 系统"）→ 转 `cs-roadmap`——那是规划层，不往 req 里塞"待做能力"
|
||||
|
||||
---
|
||||
|
||||
@@ -43,7 +43,7 @@ description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档
|
||||
|
||||
每次只动一份文档，二选一：
|
||||
|
||||
- **new**：起草一份新需求文档（`easysdd/requirements/{slug}.md`）
|
||||
- **new**：起草一份新需求文档（`codestable/requirements/{slug}.md`）
|
||||
- **update**：按新素材 / 实现变化刷新一份已有需求文档
|
||||
|
||||
为什么不允许一次写多份？需求文档的价值在于**每份都被读过**——一次吐多份 AI 起草稿，用户没精力逐份仔细 review，最后要么全部粗糙合入、要么全部放着不看。
|
||||
@@ -71,17 +71,17 @@ description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档
|
||||
共同必读：
|
||||
|
||||
- `AGENTS.md`
|
||||
- `easysdd/requirements/` 下的其他需求文档（判断"这份要不要和它们互相引用"、"有没有和哪份重复")
|
||||
- `codestable/requirements/` 下的其他需求文档（判断"这份要不要和它们互相引用"、"有没有和哪份重复")
|
||||
- 用户提供的素材（口述、产品想法、用户反馈、已有 feature 方案里散落的需求描述）
|
||||
|
||||
按情况读：
|
||||
|
||||
- 可能承载这个能力的 architecture doc（`easysdd/architecture/`）——用于 `implemented_by` 字段
|
||||
- 可能承载这个能力的 architecture doc（`codestable/architecture/`）——用于 `implemented_by` 字段
|
||||
- 和本能力相关的已有 feature 方案（了解这个能力最近是怎么演进的）
|
||||
- 相关的 compound 沉淀（explore / decision 里可能记过这块能力的背景）：
|
||||
|
||||
```bash
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{能力关键词}"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --query "{能力关键词}"
|
||||
```
|
||||
|
||||
**update 模式额外必读**：当前版本文档全文 + 该文档 `last_reviewed` 之后相关实现的变化（`git log` 粗扫 `implemented_by` 里那些 architecture doc 对应的代码模块即可）。
|
||||
@@ -110,9 +110,9 @@ description: 为项目起草或更新 `easysdd/requirements/` 下的需求文档
|
||||
|
||||
### Phase 6：落盘 + 索引更新
|
||||
|
||||
- new 模式：写入 `easysdd/requirements/{slug}.md`，frontmatter `status: current`，`last_reviewed` 填当天
|
||||
- new 模式：写入 `codestable/requirements/{slug}.md`，frontmatter `status: current`，`last_reviewed` 填当天
|
||||
- update 模式：覆盖已有文件，`last_reviewed` 更新为当天；如果结构性改动大，在文档末尾 `变更日志` 节加一条"YYYY-MM-DD：{一句话描述}"
|
||||
- **索引更新**：如果 `easysdd/requirements/` 下有 `README.md` 或索引文件，顺带加一行链接。没有就不强求——requirements 目前扁平，`ls` 本身就是索引
|
||||
- **索引更新**：如果 `codestable/requirements/` 下有 `README.md` 或索引文件，顺带加一行链接。没有就不强求——requirements 目前扁平，`ls` 本身就是索引
|
||||
|
||||
---
|
||||
|
||||
@@ -198,11 +198,11 @@ tags: []
|
||||
|
||||
| 方向 | 关系 |
|
||||
|---|---|
|
||||
| `easysdd-architecture` 配合 | requirement 描述"为什么要有"、architecture 描述"怎么搭"；architecture doc 的 frontmatter 里用 `implements: [req-slug]` 反向链到承载的需求 |
|
||||
| `easysdd-feature-design` 上游 | feature 要新增 / 修改一个能力时，先确认对应 requirement 存在或触发本技能新建；纯重构 / 技术债的 feature 不强制要 req |
|
||||
| `easysdd-feature-acceptance` 下游 | 验收时发现 feature 改变了某个能力的边界或用户故事 → 触发本技能 `update` 模式刷新对应 req（现状档案跟着代码同步的主路径） |
|
||||
| `easysdd-roadmap` 配合 | req 记"这个能力现在是什么"，roadmap 记"打算怎么把它继续推进 / 从无到有做出来"。roadmap 拆解过程里如果发现缺 req，让用户先触发本技能；roadmap 不改 req |
|
||||
| `easysdd-onboarding` 创建者 | onboarding 阶段建 `easysdd/requirements/` 空目录，之后由本技能填实 |
|
||||
| `cs-arch` 配合 | requirement 描述"为什么要有"、architecture 描述"怎么搭"；architecture doc 的 frontmatter 里用 `implements: [req-slug]` 反向链到承载的需求 |
|
||||
| `cs-feat-design` 上游 | feature 要新增 / 修改一个能力时，先确认对应 requirement 存在或触发本技能新建；纯重构 / 技术债的 feature 不强制要 req |
|
||||
| `cs-feat-accept` 下游 | 验收时发现 feature 改变了某个能力的边界或用户故事 → 触发本技能 `update` 模式刷新对应 req（现状档案跟着代码同步的主路径） |
|
||||
| `cs-roadmap` 配合 | req 记"这个能力现在是什么"，roadmap 记"打算怎么把它继续推进 / 从无到有做出来"。roadmap 拆解过程里如果发现缺 req，让用户先触发本技能；roadmap 不改 req |
|
||||
| `cs-onboard` 创建者 | onboarding 阶段建 `codestable/requirements/` 空目录，之后由本技能填实 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
+27
-27
@@ -1,33 +1,33 @@
|
||||
---
|
||||
name: easysdd-roadmap
|
||||
description: 把一块"大到不能当单个 feature 做"的需求拆成一份带依赖和状态的子 feature 清单，放在独立的 `easysdd/roadmap/{slug}/` 目录里——作为后续多次 feature 流程的种子和排期依据。两种模式：new（从一个大需求起草新 roadmap）、update（刷新已有 roadmap：加条目、改依赖、重排顺序、标 drop）。和 requirements / architecture 的分工——那两者记"系统现在是什么"，roadmap 记"接下来打算怎么走"。触发场景：用户说"我想要一个 X 系统"、"帮我把这块需求拆一下"、"排一下这个大需求"、"开一份 roadmap"，或 feature-design 阶段发现需求太大塞不进一个 feature。
|
||||
name: cs-roadmap
|
||||
description: 把一块"大到不能当单个 feature 做"的需求拆成一份带依赖和状态的子 feature 清单，放在独立的 `codestable/roadmap/{slug}/` 目录里——作为后续多次 feature 流程的种子和排期依据。两种模式：new（从一个大需求起草新 roadmap）、update（刷新已有 roadmap：加条目、改依赖、重排顺序、标 drop）。和 requirements / architecture 的分工——那两者记"系统现在是什么"，roadmap 记"接下来打算怎么走"。触发场景：用户说"我想要一个 X 系统"、"帮我把这块需求拆一下"、"排一下这个大需求"、"开一份 roadmap"，或 feature-design 阶段发现需求太大塞不进一个 feature。
|
||||
---
|
||||
|
||||
# easysdd-roadmap
|
||||
# cs-roadmap
|
||||
|
||||
`easysdd/roadmap/` 是项目的"规划层"——每个子目录承载一块大需求，里面的主文档把它拆成一串带依赖关系的子 feature 种子，feature 流程一次消费一条。
|
||||
`codestable/roadmap/` 是项目的"规划层"——每个子目录承载一块大需求，里面的主文档把它拆成一串带依赖关系的子 feature 种子，feature 流程一次消费一条。
|
||||
|
||||
**为什么单独一层**：requirements 和 architecture 记录"系统现在长什么样"（现状档案，默认只在 feature-acceptance 时跟着代码同步更新）。"接下来打算做 A、然后做 B、A 完了才能做 C"这种规划信息塞进那两者会把"是什么"和"打算怎么做"混起来——discussion 里查不到系统真实能力，计划改一下又得回头改两份现状文档。roadmap 独立目录，改起来不牵连现状档案。
|
||||
|
||||
**为什么是文件夹不是单文件**：大需求拆解过程里会产生草稿、调研笔记、方案对比、白板照片转述这类材料，塞进一份 md 会变得很乱、又舍不得删。给每个 roadmap 一个子目录，主文档负责对外口径，旁边 `drafts/` 随便堆。
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。主文档和 items 清单的完整模板看同目录 `reference.md`。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。主文档和 items 清单的完整模板看同目录 `reference.md`。
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 用户描述了一个"一眼看出做不完"的大需求（"加个权限系统"、"做一套通知中心"、"接入 SSO")，塞进单个 feature 不合适
|
||||
- 从 `easysdd-brainstorm` 判为 case 3 之后移交过来，本技能接着做拆解（brainstorm 只做分诊，不做拆解）
|
||||
- 从 `cs-brainstorm` 判为 case 3 之后移交过来，本技能接着做拆解（brainstorm 只做分诊，不做拆解）
|
||||
- 已有 roadmap 需要加新子 feature、改依赖关系、调整顺序、标废弃
|
||||
- feature-design 阶段发现本次要做的事实际是多个 feature 的集合，需要先退回来拆
|
||||
|
||||
不适用：
|
||||
|
||||
- 单个 feature 能装下的需求 → 直接 `easysdd-feature`
|
||||
- 用户要描述一个能力"是什么、边界在哪" → `easysdd-requirements`
|
||||
- 用户要描述系统"结构怎么搭" → `easysdd-architecture`
|
||||
- 用户要拍板一条长期规约 / 选型 → `easysdd-decisions`
|
||||
- 单个 feature 能装下的需求 → 直接 `cs-feat`
|
||||
- 用户要描述一个能力"是什么、边界在哪" → `cs-req`
|
||||
- 用户要描述系统"结构怎么搭" → `cs-arch`
|
||||
- 用户要拍板一条长期规约 / 选型 → `cs-decide`
|
||||
|
||||
---
|
||||
|
||||
@@ -53,7 +53,7 @@ description: 把一块"大到不能当单个 feature 做"的需求拆成一份
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
easysdd/roadmap/{slug}/
|
||||
codestable/roadmap/{slug}/
|
||||
├── {slug}-roadmap.md # 主文档（对外口径：背景 / 范围 / 子 feature 清单 / 排期思路）
|
||||
├── {slug}-items.yaml # 机器可读清单（feature-design 读、feature-acceptance 回写）
|
||||
└── drafts/ # 可选，调研 / 讨论 / 草稿
|
||||
@@ -81,15 +81,15 @@ easysdd/roadmap/{slug}/
|
||||
|
||||
- `AGENTS.md`
|
||||
- 用户提供的素材（口述、产品想法、白板转述、相关 issue）
|
||||
- `easysdd/roadmap/` 下其他 roadmap（防止和已有大需求重复或冲突）
|
||||
- `easysdd/requirements/` 相关 req doc（这块能力的需求写下来没？写了的话拆解要对齐）
|
||||
- `easysdd/architecture/` 相关 doc（系统现在长什么样，影响拆解顺序）
|
||||
- `codestable/roadmap/` 下其他 roadmap（防止和已有大需求重复或冲突）
|
||||
- `codestable/requirements/` 相关 req doc（这块能力的需求写下来没？写了的话拆解要对齐）
|
||||
- `codestable/architecture/` 相关 doc（系统现在长什么样，影响拆解顺序）
|
||||
|
||||
按情况读：
|
||||
|
||||
- 相关的 compound 沉淀（decision / explore / learning）：
|
||||
```bash
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --query "{大需求关键词}"
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --query "{大需求关键词}"
|
||||
```
|
||||
- 已有 feature 方案里和这块相关的（可能已经有人做了一部分）
|
||||
|
||||
@@ -112,7 +112,7 @@ easysdd/roadmap/{slug}/
|
||||
|
||||
用户 review 前自己先跑一遍，汇报处理结果：
|
||||
|
||||
1. **每条子 feature 的 slug 是不是规范**？（英文小写连字符，不和已有 feature 目录冲突 → grep `easysdd/features/` 确认）
|
||||
1. **每条子 feature 的 slug 是不是规范**？（英文小写连字符，不和已有 feature 目录冲突 → grep `codestable/features/` 确认）
|
||||
2. **每条描述是不是一句话能讲清楚**？讲不清就是拆得还不够或者 scope 太模糊
|
||||
3. **依赖关系是不是 DAG**？有没有谁指向自己、或 A→B→A 的回环
|
||||
4. **最小闭环是不是真的最小**？第一条做完能独立给用户演示点什么？做不到就还不够小
|
||||
@@ -127,7 +127,7 @@ easysdd/roadmap/{slug}/
|
||||
### Phase 6：落盘
|
||||
|
||||
- `new` 模式：
|
||||
- 建 `easysdd/roadmap/{slug}/` 目录
|
||||
- 建 `codestable/roadmap/{slug}/` 目录
|
||||
- 写入 `{slug}-roadmap.md`，frontmatter `status: active`、`created` / `last_reviewed` 填当天
|
||||
- 写入 `{slug}-items.yaml`，每条 `status: planned`、`feature: null`
|
||||
- 用 `validate-yaml.py --file {slug}-items.yaml --yaml-only` 校验
|
||||
@@ -146,17 +146,17 @@ easysdd/roadmap/{slug}/
|
||||
|
||||
当用户说"开始做 roadmap 里的 {子 feature slug}"时：
|
||||
|
||||
1. `easysdd-feature-design`（或 fastforward / brainstorm）起 feature 目录
|
||||
1. `cs-feat-design`（或 fastforward / brainstorm）起 feature 目录
|
||||
2. design frontmatter 带两个字段：`roadmap: {roadmap-slug}` + `roadmap_item: {子 feature slug}`
|
||||
3. design 流程同时把 `easysdd/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名（`YYYY-MM-DD-{slug}`）
|
||||
3. design 流程同时把 `codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 对应条目 `status` 改为 `in-progress`、`feature` 填为 feature 目录名（`YYYY-MM-DD-{slug}`）
|
||||
|
||||
这一步的职责在 feature-design 技能里，不在本技能里。
|
||||
|
||||
### acceptance 自动回写
|
||||
|
||||
`easysdd-feature-acceptance` 走到收尾时，如果 design frontmatter 有 `roadmap` 字段，就去 `easysdd/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 把对应 `roadmap_item` 的 `status` 改为 `done`。同时在主文档的子 feature 清单里把对应行的勾选状态同步。
|
||||
`cs-feat-accept` 走到收尾时，如果 design frontmatter 有 `roadmap` 字段，就去 `codestable/roadmap/{roadmap-slug}/{roadmap-slug}-items.yaml` 把对应 `roadmap_item` 的 `status` 改为 `done`。同时在主文档的子 feature 清单里把对应行的勾选状态同步。
|
||||
|
||||
这一步的职责在 feature-acceptance 技能里，不在本技能里。roadmap 文档本身是项目产物，任何 skill 都可以按 items.yaml 的 schema 读写——**这不算 skill 间耦合**，和各 skill 都读写 `easysdd/features/` 是一回事。
|
||||
这一步的职责在 feature-acceptance 技能里，不在本技能里。roadmap 文档本身是项目产物，任何 skill 都可以按 items.yaml 的 schema 读写——**这不算 skill 间耦合**，和各 skill 都读写 `codestable/features/` 是一回事。
|
||||
|
||||
### roadmap 本身的生命周期
|
||||
|
||||
@@ -194,12 +194,12 @@ easysdd/roadmap/{slug}/
|
||||
|
||||
| 方向 | 关系 |
|
||||
|---|---|
|
||||
| `easysdd-requirements` 配合 | req 记"为什么要有这个能力"，roadmap 记"打算怎么分步把它做出来"。大需求下可能有多份 req；拆解过程中发现缺 req 就提示用户先触发本技能之前跑 `easysdd-requirements` |
|
||||
| `easysdd-architecture` 配合 | architecture 记"系统现在长什么样"，roadmap 记"接下来想把它变成什么样的若干步"。拆解时要读 architecture 理解现状，但不改它 |
|
||||
| `easysdd-feature` 下游 | roadmap 里每条子 feature 都是未来一次 feature 流程的种子；feature 从 roadmap 起头时在 design frontmatter 带 `roadmap` / `roadmap_item` 字段 |
|
||||
| `easysdd-feature-acceptance` 回写方 | acceptance 走完时自动改 items.yaml 对应条目为 `done`，本技能只定义格式不负责回写 |
|
||||
| `easysdd-onboarding` 创建者 | onboarding 建 `easysdd/roadmap/` 空目录 |
|
||||
| `easysdd-brainstorm` 上游 | brainstorm 判为 case 3 时把讨论移交给本技能，并带上已聊到的真问题 / 大致范围 / 可能子模块做一句话汇总。本技能不重复做分诊，直接进拆解 |
|
||||
| `cs-req` 配合 | req 记"为什么要有这个能力"，roadmap 记"打算怎么分步把它做出来"。大需求下可能有多份 req；拆解过程中发现缺 req 就提示用户先触发本技能之前跑 `cs-req` |
|
||||
| `cs-arch` 配合 | architecture 记"系统现在长什么样"，roadmap 记"接下来想把它变成什么样的若干步"。拆解时要读 architecture 理解现状，但不改它 |
|
||||
| `cs-feat` 下游 | roadmap 里每条子 feature 都是未来一次 feature 流程的种子；feature 从 roadmap 起头时在 design frontmatter 带 `roadmap` / `roadmap_item` 字段 |
|
||||
| `cs-feat-accept` 回写方 | acceptance 走完时自动改 items.yaml 对应条目为 `done`，本技能只定义格式不负责回写 |
|
||||
| `cs-onboard` 创建者 | onboarding 建 `codestable/roadmap/` 空目录 |
|
||||
| `cs-brainstorm` 上游 | brainstorm 判为 case 3 时把讨论移交给本技能，并带上已聊到的真问题 / 大致范围 / 可能子模块做一句话汇总。本技能不重复做分诊，直接进拆解 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# easysdd-roadmap 参考模板
|
||||
# cs-roadmap 参考模板
|
||||
|
||||
本文件提供 `easysdd-roadmap` 使用的主文档和 items.yaml 参考格式。SKILL.md 只保留流程骨架，具体格式在这里。
|
||||
本文件提供 `cs-roadmap` 使用的主文档和 items.yaml 参考格式。SKILL.md 只保留流程骨架，具体格式在这里。
|
||||
|
||||
---
|
||||
|
||||
@@ -75,7 +75,7 @@ related_architecture: [] # 相关 architecture doc slug 列表，可空
|
||||
|
||||
起草或刷新过程中发现、但本 roadmap 不处理的事情，交给用户决定：
|
||||
|
||||
- 发现 `easysdd/architecture/X.md` 里对 Y 的描述已经过时，建议另起 architecture update
|
||||
- 发现 `codestable/architecture/X.md` 里对 Y 的描述已经过时，建议另起 architecture update
|
||||
- 发现 requirement-Z 的边界和本 roadmap 第 3 条冲突，建议先对齐 req
|
||||
- ...
|
||||
|
||||
@@ -135,7 +135,7 @@ dropped （终态，不删除条目，保留历史）
|
||||
### 校验
|
||||
|
||||
```bash
|
||||
python easysdd/tools/validate-yaml.py --file easysdd/roadmap/{slug}/{slug}-items.yaml --yaml-only
|
||||
python codestable/tools/validate-yaml.py --file codestable/roadmap/{slug}/{slug}-items.yaml --yaml-only
|
||||
```
|
||||
|
||||
---
|
||||
@@ -146,10 +146,10 @@ python easysdd/tools/validate-yaml.py --file easysdd/roadmap/{slug}/{slug}-items
|
||||
|
||||
- [ ] 这条能独立走完一次 feature 流程（design / implement / acceptance）吗？走不通就继续拆或合并
|
||||
- [ ] 这条做完后能单独验证吗？能不能写出一句"完成后 {具体可观测现象}"
|
||||
- [ ] 这条的 slug 和 `easysdd/features/` 下已有目录冲突吗？grep 过了吗
|
||||
- [ ] 这条的 slug 和 `codestable/features/` 下已有目录冲突吗？grep 过了吗
|
||||
- [ ] 依赖关系讲得清具体理由吗？"B 需要 A 提供的 {具体产物}" 这种
|
||||
- [ ] 最小闭环那条真是"最窄的端到端路径"吗？还是只是"最容易的一条"
|
||||
- [ ] 有没有条目其实应该是 requirement 变化而不是 feature？（比如"把 XX 能力的边界改一下"）那种转 `easysdd-requirements`
|
||||
- [ ] 有没有条目其实应该是 requirement 变化而不是 feature？（比如"把 XX 能力的边界改一下"）那种转 `cs-req`
|
||||
|
||||
---
|
||||
|
||||
|
||||
+13
-13
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: easysdd-tricks
|
||||
description: 把"要做这类事，正确做法是这样"的可复用编程模式 / 库用法 / 技术技巧整理成处方性参考库，feature-design 和 issue-analyze 阶段按需检索复用。三种类型：pattern（设计模式、编程惯用法）、library（某个库 / 框架的用法和坑）、technique（具体操作技巧 / 命令配方）。触发场景：用户说"记录一个技巧"、"这个用法值得记"、"tricks"、"记录库用法"，或 feature-design / issue-analyze 阶段发现值得沉淀的技巧时主动推送。和 learning / decisions / explore 怎么区分看 `easysdd/reference/system-overview.md`。
|
||||
name: cs-trick
|
||||
description: 把"要做这类事，正确做法是这样"的可复用编程模式 / 库用法 / 技术技巧整理成处方性参考库，feature-design 和 issue-analyze 阶段按需检索复用。三种类型：pattern（设计模式、编程惯用法）、library（某个库 / 框架的用法和坑）、technique（具体操作技巧 / 命令配方）。触发场景：用户说"记录一个技巧"、"这个用法值得记"、"tricks"、"记录库用法"，或 feature-design / issue-analyze 阶段发现值得沉淀的技巧时主动推送。和 learning / decisions / explore 怎么区分看 `codestable/reference/system-overview.md`。
|
||||
---
|
||||
|
||||
# easysdd-tricks
|
||||
# cs-trick
|
||||
|
||||
easysdd-tricks 是面向问题的**处方性参考库**，回答一个问题：**要做 X，经过验证的正确做法是什么？**不需要触发事件，任何时候发现值得沉淀的模式或用法都可以直接写。
|
||||
cs-trick 是面向问题的**处方性参考库**，回答一个问题：**要做 X，经过验证的正确做法是什么？**不需要触发事件，任何时候发现值得沉淀的模式或用法都可以直接写。
|
||||
|
||||
典型内容：
|
||||
|
||||
@@ -13,7 +13,7 @@ easysdd-tricks 是面向问题的**处方性参考库**，回答一个问题：*
|
||||
- 某个库 / 框架的核心 API 用法 + 已知坑
|
||||
- 某类操作（调试、部署、数据处理……）的命令配方
|
||||
|
||||
> 共享路径与命名约定看 `easysdd/reference/shared-conventions.md`。本技能的产物写入 `easysdd/compound/`，文件命名 `YYYY-MM-DD-trick-{slug}.md`，frontmatter 带 `doc_type: trick`。
|
||||
> 共享路径与命名约定看 `codestable/reference/shared-conventions.md`。本技能的产物写入 `codestable/compound/`，文件命名 `YYYY-MM-DD-trick-{slug}.md`，frontmatter 带 `doc_type: trick`。
|
||||
|
||||
---
|
||||
|
||||
@@ -60,7 +60,7 @@ easysdd-tricks 是面向问题的**处方性参考库**，回答一个问题：*
|
||||
|
||||
### Phase 1.5：查重叠与意图分流（必做）
|
||||
|
||||
按 `easysdd/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
按 `codestable/reference/shared-conventions.md` §6 第 5 / 6 条执行：
|
||||
|
||||
- 用户话里含"改 / 更新 / 修订 / 补充 / 某条 trick"或明确指向某份旧文档 → 直接走**更新已有条目**路径，不进新建流程；搜索只是确认定位到哪一条
|
||||
- 否则用下面"搜索工具"里的 `--query` 查一遍 `topic`，命中语义相近的旧文档时把候选列给用户，让用户选：更新 / supersede / 确实不同主题后再走 Phase 2
|
||||
@@ -115,37 +115,37 @@ easysdd-tricks 是面向问题的**处方性参考库**，回答一个问题：*
|
||||
|
||||
### Phase 5：归档
|
||||
|
||||
- 新建路径：文件写入 `easysdd/compound/`，命名 `YYYY-MM-DD-trick-{slug}.md`，frontmatter 顶部带 `doc_type: trick`（见 `reference.md`）
|
||||
- 新建路径：文件写入 `codestable/compound/`，命名 `YYYY-MM-DD-trick-{slug}.md`，frontmatter 顶部带 `doc_type: trick`（见 `reference.md`）
|
||||
- 更新路径：写回 Phase 1.5 定位到的原文件，frontmatter 补 `updated: YYYY-MM-DD`
|
||||
- supersede 路径：按 `shared-conventions.md` §6 第 5 条处理新旧两份文件
|
||||
- 写完后报告完整文件路径
|
||||
|
||||
### Phase 6：可发现性检查
|
||||
|
||||
写完后检查 `AGENTS.md` 或 `CLAUDE.md` 里是否有指引 AI 查阅 `easysdd/compound/` 沉淀目录的说明。**没有就提示用户是否要加一行**——别自作主张改文件，只提示，由用户决定。
|
||||
写完后检查 `AGENTS.md` 或 `CLAUDE.md` 里是否有指引 AI 查阅 `codestable/compound/` 沉淀目录的说明。**没有就提示用户是否要加一行**——别自作主张改文件，只提示，由用户决定。
|
||||
|
||||
---
|
||||
|
||||
## 搜索工具
|
||||
|
||||
> 完整语法和示例见 `easysdd/reference/tools.md`。本节只列 tricks 特有的典型查询。
|
||||
> 完整语法和示例见 `codestable/reference/tools.md`。本节只列 tricks 特有的典型查询。
|
||||
|
||||
```bash
|
||||
# 按类型 + 框架筛选
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter type=library --filter framework~={库名}
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter type=library --filter framework~={库名}
|
||||
|
||||
# 按技术栈浏览
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter language=typescript --filter status=active
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter language=typescript --filter status=active
|
||||
|
||||
# 归档后查重叠
|
||||
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --query "{关键词}" --json
|
||||
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --query "{关键词}" --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 守护规则
|
||||
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `easysdd/reference/shared-conventions.md` 第 6 节。本技能特有或细化规则：
|
||||
> 归档类工作流共享守护规则（只增不删、宁缺毋滥、不替用户写、可发现性、归档后查重叠）见 `codestable/reference/shared-conventions.md` 第 6 节。本技能特有或细化规则：
|
||||
|
||||
1. **只归档已验证的做法**——"也许应该这样做"不归档；文档内容必须是用户或 AI 确认过有效的
|
||||
2. **必须调查代码仓**——用户没贴代码不等于不需要看，Phase 2 代码调查不可跳过。示例代码优先用项目真实代码，不凭空编写
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# tricks 参考模板
|
||||
|
||||
本文件提供 `easysdd-tricks` 使用的技巧文档模板和示例。
|
||||
本文件提供 `cs-trick` 使用的技巧文档模板和示例。
|
||||
|
||||
## 1. frontmatter
|
||||
|
||||
@@ -19,7 +19,7 @@ superseded-by: {可选}
|
||||
---
|
||||
```
|
||||
|
||||
文件名：`easysdd/compound/YYYY-MM-DD-trick-{slug}.md`。
|
||||
文件名：`codestable/compound/YYYY-MM-DD-trick-{slug}.md`。
|
||||
|
||||
## 2. 正文模板
|
||||
|
||||
|
||||
Reference in New Issue
Block a user