| 分组 | 技能 | 用途 |
|---|
| 根入口 | cs | 统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它 |
| 接入 | cs-onboard | 把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库 |
| 需求 & 架构 | cs-req | 整理 / 沉淀原始需求文档 |
cs-arch | 起草或更新 codestable/architecture/ 下的架构文档 |
| 路线图 | cs-roadmap | 承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单 |
| 讨论入口 | cs-brainstorm | 想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap |
| 特性流程 | cs-feat | 新特性子流程入口 |
cs-feat-design | 起草 {slug}-design.md 作为后续唯一输入 |
cs-feat-impl | 按 design 的推进顺序写代码 |
cs-feat-accept | 逐层对照 design 核对实现，做完整验收闭环 |
cs-feat-ff | 超轻量通道：不写 design、不分阶段，让 AI 直接做 |
| 问题流程 | cs-issue | 问题修复子流程入口 |
cs-issue-report | 把脑子里的问题落成可复现、可追溯的 report |
cs-issue-analyze | 找根因、评估修复风险、给方案 |
cs-issue-fix | 定点修复 + 验证 + 写 fix-note |
| 重构流程 | cs-refactor | (beta) 重构主流程 |
cs-refactor-ff | (beta) 轻量重构通道 |
| 知识沉淀 | cs-learn | 把踩过的坑 / 好做法沉淀成 learning 文档 |
cs-trick | 把可复用的编程模式 / 库用法整理成处方性参考 |
cs-decide | 把已拍板的技术选型、架构决定、长期约束记成永久文档 |
| 探索 & 文档 | cs-explore | 定向代码探索，把"提问 → 读代码 → 得结论"沉淀成证据 |
cs-guide / cs-libdoc | 对外的开发者指南 / 库参考文档 |
---
## 工作流示意
CodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：
```
═══════════════════════════════════════════════════════════════════════
根入口 · 路由 （任何时刻都可以调用）
───────────────────────────────────────────────────────────────────────
cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能
（本身不做事，只做分诊和提示）
═══════════════════════════════════════════════════════════════════════
│
┌───────────────┼───────────────┐
▼ ▼ ▼
（未接入） （已接入） （想了解体系）
走阶段 0 直达 1~4 层 / 横切 给速读
│
▼
═══════════════════════════════════════════════════════════════════════
阶段 0 · 接入 （只在新项目跑一次）
───────────────────────────────────────────────────────────────────────
cs-onboard ──▶ 生成 codestable/ 骨架 + 释放 reference/、tools/
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 1 层 · 长效档案（"系统现在长什么样"，只记现状）
───────────────────────────────────────────────────────────────────────
cs-req ──▶ codestable/requirements/{slug}.md
cs-arch ──▶ codestable/architecture/ARCHITECTURE.md
└─ {type}-{slug}.md（子系统）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要）
───────────────────────────────────────────────────────────────────────
cs-roadmap ──▶ codestable/roadmap/{slug}/
把一个"我想要 X 系统"做成完整的事前规划：
① 概设 —— 拆成哪几个模块 / 组件
② 架构层详设 —— 模块间接口契约 / 共享协议
③ 子 feature —— 把方案分解成多条可执行的 feature
② 是 feature-design 的硬约束输入
（小需求可跳过本层，直接进第 3 层）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游）
───────────────────────────────────────────────────────────────────────
┌── case 1 已经够清楚 ──▶ cs-feat-design
cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md）
└── case 3 大需求只有一个词 ─▶ cs-roadmap
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 3 层 · 执行流程（按事件类型选一条进入）
───────────────────────────────────────────────────────────────────────
▸ 事件：新增能力 ┌──────────┐
cs-feat-design ──▶ cs-feat-impl ──▶ cs-feat-accept │ features │
cs-feat-ff ──(轻量直通车，跳过 design/accept)─▶ │ /YYYY-…/ │
└──────────┘
▸ 事件：修复缺陷 ┌──────────┐
cs-issue-report ──▶ cs-issue-analyze ──▶ cs-issue-fix│ issues │
│ /YYYY-…/ │
└──────────┘
▸ 事件：代码腐化（beta） ┌──────────┐
cs-refactor / cs-refactor-ff │refactors │
│ /YYYY-…/ │
└──────────┘
═══════════════════════════════════════════════════════════════════════
│
▼ 任意阶段觉得"这个值得记下来"都能触发 ▼
═══════════════════════════════════════════════════════════════════════
横切层 · 知识沉淀（复利工程）
───────────────────────────────────────────────────────────────────────
cs-learn ──▶ ┐
cs-trick ──▶ ├─▶ codestable/compound/YYYY-MM-DD-{doc_type}-{slug}.md
cs-decide ──▶ │ doc_type ∈ { learning, trick, decision, explore }
cs-explore ──▶ ┘
↑
下一次 cs-arch / cs-feat-design / cs-issue-analyze
会回头读 compound/，让经验在新工作里被复用
═══════════════════════════════════════════════════════════════════════
```
**怎么读这张图：**
- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入
- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流
- **横切层是飞轮**：任何流程跑完发现"这事值得记下来"都可以触发沉淀，沉淀的产物又会被下一次同类工作读到——这是 CodeStable "复利"的物理实现
---
## 运行时结构
`/cs-onboard` 跑完后，会在你的项目根下生成一个 `codestable/` 目录——这是 CodeStable 所有产物的聚合根，也是各个子技能在运行时**唯一**会读写的工作区。
```
你的项目/
├── codestable/
│ ├── requirements/ # 需求实体（"为什么要有这个能力"）
│ │ └── {slug}.md # 一个能力一份，扁平不分组
│ │
│ ├── architecture/ # 架构实体（"用什么结构实现"）
│ │ ├── ARCHITECTURE.md # 架构总入口 / 索引
│ │ └── {type}-{slug}.md # 子系统架构 doc（同类 ≥6 份自动收进子目录）
│ │
│ ├── roadmap/ # 路线图（"接下来打算怎么走"）
│ │ └── {slug}/
│ │ ├── {slug}-roadmap.md # 主文档：背景 / 拆解 / 排期
│ │ ├── {slug}-items.yaml # 机器可读子 feature 清单，acceptance 回写状态
│ │ └── drafts/ # 可选：草稿 / 调研
│ │
│ ├── features/ # 特性流程聚合根
│ │ └── YYYY-MM-DD-{slug}/ # 一个 feature 一个目录
│ │ ├── {slug}-brainstorm.md # 可选（cs-brainstorm 产出）
│ │ ├── {slug}-design.md # 方案（cs-feat-design）
│ │ ├── {slug}-checklist.yaml # 推进清单（impl 跑、accept 回写）
│ │ └── {slug}-acceptance.md # 验收报告（cs-feat-accept）
│ │
│ ├── issues/ # 问题流程聚合根
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-report.md # 问题报告
│ │ ├── {slug}-analysis.md # 根因分析（不显然时才有）
│ │ └── {slug}-fix-note.md # 修复记录
│ │
│ ├── refactors/ # 重构流程聚合根（beta）
│ │ └── YYYY-MM-DD-{slug}/
│ │ ├── {slug}-scan.md
│ │ ├── {slug}-refactor-design.md
│ │ ├── {slug}-checklist.yaml
│ │ └── {slug}-apply-notes.md
│ │
│ ├── compound/ # 知识沉淀（复利工程）统一目录
│ │ └── YYYY-MM-DD-{doc_type}-{slug}.md
│ │ # doc_type ∈ {learning, trick, decision, explore}
│ │
│ ├── tools/ # 跨工作流共享脚本（onboard 释放）
│ └── reference/ # 共享参考文档（onboard 释放）
│ ├── shared-conventions.md # 跨技能口径 / 路径命名 / 元数据规范
│ ├── system-overview.md # CodeStable 体系总览 + 场景路由
│ └── ...
│
└── AGENTS.md # 在项目根，不在 codestable/ 里
```
**几条要点：**
- 所有产物都聚在 `codestable/` 下，让"上次那个 feature / bug 当时怎么搞的"三秒能找到
- `requirements/` 和 `architecture/` 是**长效档案**（只记现状），`roadmap/` 是**规划层**（接下来怎么走），两者刻意分开
- `features/` `issues/` `refactors/` 用 `YYYY-MM-DD-{slug}/` 一个目录装齐所有相关 spec，不交叉
- `compound/` 是**唯一**的知识沉淀目录，learning / trick / decision / explore 通过 `doc_type` 字段区分而不是分目录——好搜
- `reference/` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `cs-onboard/reference/` 模板，新项目 onboard 自动带上新版
### 硬约束
> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill/reference/xxx.md` 这种引用在运行时**根本读不到**。
>
> 跨 skill 共享的参考文档必须走"工作项目"这一层：由 `cs-onboard` 从技能包复制到项目的 `codestable/reference/`，其他 skill 用项目相对路径读取。
要改共享口径，改 `cs-onboard/reference/` 下的模板，新项目 onboard 时带上新版本。
---
## 设计哲学
CodeStable 与 OMO 做的是**完全相反**的哲学。
- OMO 认为：人只要干预就是失败的信号
- CodeStable 认为：**程序员是软件编码中的在环对象**——可以对黑盒实现不了解，但对整体实现必须有所把控，必要时也可深入
软件架构必须要 **可演进**、**可观测**、**可控制**。
也许这一点在 AI 发展强大以后会变得不再重要，但**当下这样做能让程序员在现状下舒服**——这就是价值所在。
CodeStable 面向真实开发场景，对此进行建模，期望通过一个闭环系统处理开发中常见的问题。**现有大部分框架围绕 AI 建模，而不是围绕人。** 我认为这些框架的作者驱动 AI 的能力很强，但绝对不是严肃软件的开发者——因为缺少对软件开发中需求和设计的基础组织能力，缺乏对代码实现的尊重。
---
## Roadmap
CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。
- [ ] 代码重构流程需要强化（`cs-refactor` 还在 beta）
- [ ] ……
欢迎在 Issue 区贴你的真实开发困境和重构经验。
---
## Star History
[](https://www.star-history.com/?repos=liuzhengdongfortest%2FCodeStable&type=date&legend=top-left)
