English · 中文
面向严肃工程的 AI 编码工作流
厌倦了 OpenSpec 的草台、Oh-My-OpenAgent 的过度设计、Superpowers 的散装——我从 0 写了一套简单轻巧、围绕人在环的 AI Harness。
npx skills add https://github.com/liuzhengdongfortest/CodeStable只需要一键，开始工作：
/cs-onboard之后日常使用时，不知道该用哪个技能就喊根入口：
/cscs 会读你的诉求，告诉你这次该走哪个 cs-xxx。
我在开发一套新的 Harness Agent（MA），一开始当然是 VibeCoding——我只写设计和需求，代码由 AI 来改。这样支撑了大部分特性的开发。直到有一天 Codex 反复解决不了一个我认为比较简单的问题，并且反复在同一个地方犯错。我就知道项目需要一套工作流来维持它继续进行了。
我调研了 OpenSpec、SuperPowers、Oh-My-OpenAgent 这一类工具，没一个用着顺手：
- OpenSpec 太简单，没有复利工程，生成的 Spec 抽象到人类没法读
- SuperPowers 没有流程约束，不知道该用哪个
- Oh-My-OpenAgent 太重，且哲学上认为"人介入 = 失败"
CodeStable 的目标是解决严肃工程的软件实现和编码问题，不是造一个新名词、追求热点。
我看了一圈现在主流的 AI 编码框架——Superpowers、CCW、Oh-My-OpenAgent 等等——它们其实都在做同一件事：
如何把 Agent 编排得更好。 让它们组队、协作、头脑风暴、跑流水线、自动接力。围绕的实体始终是 Agent。
CodeStable 走的是另一个方向：
编排的不是 Agent，而是软件本身的生命周期。 围绕的实体是构成软件的要素——每一个需求、每一个架构决定、每一个特性、每一个 bug、每一条历史里留下来的约束。
| Agent 编排派 | CodeStable | |
|---|---|---|
| 核心实体 | Agent / Role / Team | Requirement / Architecture / Feature / Issue / Decision |
| 主线问题 | Agent 之间怎么分工、传递、协调？ | 软件的需求、约束、决策怎么被记下来、被检索、被复用？ |
| 状态存在哪 | Agent 的 session / 消息总线 / 队列 | 项目里的 codestable/ 文件树（人和 AI 都能读） |
| 解决的痛点 | 单 Agent 能力不够，需要协同放大 | 软件复杂度膨胀撑破上下文、隐知识丢失、需求漂移 |
| 对人的定位 | 人少介入越好，理想是全自动 | 人在环 —— 程序员对整体把控负责，AI 是高效的执行体 |
这两个方向没有谁对谁错。
如果你的任务是"用 AI 跑一个端到端的自动化产线"、"让多个 Agent 互相讨论方案"，Agent 编排派会更顺手。
如果你的任务是"维护一个会跨年迭代的严肃软件"、"让今天写下的需求和决策三个月后还能被准确召回"——那 CodeStable 这套以软件要素为中心的建模会更合适。
我做 CodeStable 是因为我相信：软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好。Agent 再强，也写不了一个把需求、架构、历史决策全丢失的项目。
CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成一组实体和流程。
| 实体 | 英文 | 干什么 |
|---|---|---|
| 需求 | requirements | 原始用户故事 + 领域术语（CONTEXT.md）+ 架构决策（ADR）。最终的逃生通道——代码烂成一坨屎时，可以摒弃所有代码、让 AI 重新生成 |
| 路线图 | roadmap | "我想要一个权限校验系统"——直接塞 feature AI 接不住，先拆成路线图分步推进；cs-roadmap-review 做独立规划审查，cs-roadmap-impl-goal 把大需求一路推到 /goal 指令 |
| 目标 | goals | 限定起点和终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收 |
| 特性 | feature | 实际落地的工程执行过程，人与 AI 共同协作，对 design / 实现 / 验收负责；每个阶段之间有显式的 Gate 卡口（design-review / code-review / qa） |
| 问题 | issue | 开发完成后的 BUG 单子，AI 和人一同解决 |
| 重构 | refactor | 代码腐化时的整理过程（beta） |
| 知识 | compound | 复利工程的知识库，沉淀踩过的坑、好做法、调研结论（cs-keep）；碎片化项目约定写入 attention.md（cs-note） |
| 流程 | 关键技能链 | 说明 |
|---|---|---|
| 特性引入 | cs-feat → cs-feat-design → cs-feat-design-review (Gate) → cs-feat-impl → cs-code-review (Gate) → cs-feat-qa (Gate) → cs-feat-accept |
想清楚 → 方案独立审查 → 逐步编码 → 代码审查 → QA → 验收闭环 |
| 大需求端到端 | cs-roadmap → cs-roadmap-review (Gate) → 用户确认 → cs-roadmap-impl-goal → /goal 指令 |
大需求拆成路线图 → 独立规划审查 → 逐个 feature 自动推进至验收 |
| 目标达成 | cs-goal |
限定起点/终点 → grill 写起点报告 → 自主实现/验证/迭代 → subagent 功能验收 |
| 问题修改 | cs-issue-report → cs-issue-analyze → cs-issue-fix → cs-code-review (Gate) |
跟 AI 说哪里有问题 → 分析根因 → 定点修复 → 合并前独立评审 |
| 代码重构 | cs-refactor (beta) → cs-code-review (Gate) |
软件架构腐化不是一蹴而就的。AI 辅助重构，但终归是人在重构——还在迭代中，欢迎赐教 |
cs-code-review 是各执行流末端、commit 前的横切质量门禁。阶段或里程碑收尾时，用 cs-docs-neat 整理 .codestable/、README/docs、CLAUDE.md / AGENTS.md 和 agent 记忆，避免文档与代码脱节。
强分支保护：
cs-onboard可选释放codestable-ai-branch-guardhook，拦截 AI 在main/master上直接实现，强制走 worktree。详见cs-onboard的「分支保护 hook」。
| 分组 | 技能 | 用途 |
|---|---|---|
| 根入口 | cs | 统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它 |
| 接入 | cs-onboard | 把 CodeStable 接入到一个新仓库 / 已有零散文档的仓库；释放 reference/、tools/ 和可选的分支保护 hook |
| 需求 & 领域 | cs-req | 整理 / 沉淀能力愿景 doc |
cs-domain | 维护 requirements/CONTEXT.md 术语表 + requirements/adrs/ 架构决策（守门 3 判据 + Nygard 四节）+ 单/多 context 拓扑 | |
| 路线图 | cs-roadmap | 承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 / 共享协议）+ 子 feature 拆解清单 |
cs-roadmap-review | roadmap 人审前的独立规划审查 Gate，支持 Paseo 多 agent 辅助审查，产出 {slug}-roadmap-review.md | |
cs-roadmap-impl-goal | 大需求端到端编排：roadmap → review → 用户确认 → 逐 feature design/checklist/design-review → 输出可粘贴的 /goal 指令 | |
| 讨论入口 | cs-brainstorm | 想法模糊时的统一讨论入口，做分诊：直接 design / 进 feature 写 brainstorm.md / 移交 roadmap |
| 目标 | cs-goal | 限定起点/终点，写起点报告后让 AI 自主迭代实现/验证，完成前用 subagent 做功能验收 |
| 特性流程 | cs-feat | 新特性子流程入口，按已有产物自动路由到对应阶段 |
cs-feat-design | 起草 {slug}-design.md + {slug}-checklist.yaml 作为后续唯一输入 | |
cs-feat-design-review ✦Gate | design 人审前的独立方案审查，支持 Paseo 多 agent，产出 {slug}-design-review.md | |
cs-feat-impl | 按 checklist 推进写代码；也处理 review-fix 和 qa-fix 回流 | |
cs-code-review ✦Gate | 任何流程实现后、commit 前的横切只读代码审查，产出 {slug}-review.md；blocking 时回到 impl | |
cs-feat-qa ✦Gate | 代码审查通过后的本地 QA 验证，产出 {slug}-qa.md；失败时回到 impl 的 qa-fix | |
cs-feat-accept | 对照 design 核实现 + review/QA 报告做验收闭环，回写 requirement / roadmap | |
cs-feat-ff | 超轻量通道：不写 design、不分阶段，让 AI 直接做 | |
| 问题流程 | cs-issue | 问题修复子流程入口 |
cs-issue-report | 把脑子里的问题落成可复现、可追溯的 report | |
cs-issue-analyze | 找根因、评估修复风险、给方案 | |
cs-issue-fix | 定点修复 + 验证 + 写 fix-note | |
| 重构流程 | cs-refactor | (beta) 重构主流程：scan → design → apply，每步人工放行 |
cs-refactor-ff | (beta) 轻量重构通道：识别 1-3 条低风险优化，一次确认，原地改 | |
| 审计 | cs-audit | 主动扫描代码：bug 隐患 / 安全漏洞 / 性能问题 / 架构偏离，产出批量发现清单 |
| 知识沉淀 | cs-keep | 坑点 / 技巧 / 决策 / 调研沉淀到 compound/，纯 markdown，grep 检索 |
cs-note | 碎片化项目约定（编译 flag / 路径陷阱 / 命令别名）追加到 attention.md | |
| 文档整理 | cs-docs-neat | 阶段/里程碑收尾时同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md 和 agent 记忆，防止文档与代码脱节 |
| 对外文档 | cs-doc-tutorial | 对外的开发者指南 / 用户指南（任务导向，怎么用 X 做 Y） |
cs-doc-api | 从源码反推的 API 参考（逐条目，给读者查零件） |
完整技能目录见 SKILL_CATALOG.md。日常不知道用哪个时直接调用 /cs，它会按诉求路由到对应技能。
CodeStable 的技能不是一条线性流水，而是分层 + 事件驱动的：根入口路由、onboard、长效档案、roadmap 规划、feature / issue / refactor 执行流，以及横切的知识沉淀。
═══════════════════════════════════════════════════════════════════════
根入口 · 路由 （任何时刻都可以调用）
───────────────────────────────────────────────────────────────────────
cs ──▶ 介绍体系 / 把开放式诉求路由到下面任一具体子技能
（本身不做事，只做分诊和提示）
═══════════════════════════════════════════════════════════════════════
│
┌───────────────┼───────────────┐
▼ ▼ ▼
（未接入） （已接入） （想了解体系）
走阶段 0 直达 1~4 层 / 横切 给速读
│
▼
═══════════════════════════════════════════════════════════════════════
阶段 0 · 接入 （只在新项目跑一次）
───────────────────────────────────────────────────────────────────────
cs-onboard ──▶ 生成 .codestable/ 骨架 + 释放 reference/、tools/
可选：释放 codestable-ai-branch-guard hook（强制走 worktree）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 1 层 · 长效档案（"系统现在长什么样"，只记现状）
───────────────────────────────────────────────────────────────────────
cs-req ──▶ .codestable/requirements/{slug}.md 能力愿景
cs-domain ──▶ .codestable/requirements/CONTEXT.md 领域术语
.codestable/requirements/adrs/NNN-*.md 架构决策（守门 3 判据）
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 2 层 · 规划（"接下来打算怎么做这块大需求"，大需求才需要）
───────────────────────────────────────────────────────────────────────
cs-roadmap ──▶ .codestable/roadmap/{slug}/
① 概设 —— 拆成哪几个模块 / 组件
② 架构层详设 —— 接口契约 / 共享协议
③ 子 feature —— 多条可执行的 feature 清单
cs-roadmap-review ✦Gate ──▶ 独立规划审查 → {slug}-roadmap-review.md
支持 Paseo 多 agent；不通过不能推进实现
cs-roadmap-impl-goal ──▶ 为每个子 feature 完成 design/checklist/design-review
→ 输出可直接粘贴的 /goal 指令
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游）
───────────────────────────────────────────────────────────────────────
┌── case 1 已经够清楚 ──▶ cs-feat-design
cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md）
└── case 3 大需求只有一个词 ─▶ cs-roadmap
═══════════════════════════════════════════════════════════════════════
│
▼
═══════════════════════════════════════════════════════════════════════
第 3 层 · 执行流程（按事件类型选一条进入）
───────────────────────────────────────────────────────────────────────
▸ 事件：新增能力 ┌──────────────┐
│ features/ │
cs-feat-design │ YYYY-MM-DD- │
│ │ {slug}/ │
▼ │ │
cs-feat-design-review ✦Gate ── 不通过回 design │ -design.md │
│ 通过 │ -checklist. │
▼ │ yaml │
cs-feat-impl │ -review.md │
│ │ -qa.md │
▼ │ -acceptance │
cs-code-review ✦Gate ────── blocking 回 impl │ .md │
│ 通过 └──────────────┘
▼
cs-feat-qa ✦Gate ────────── 失败回 impl
│ 通过
▼
cs-feat-accept
cs-feat-ff ──(轻量直通车，跳过 design/gate，直接 impl → review)──▶
▸ 事件：修复缺陷 ┌──────────────┐
cs-issue-report ─▶ cs-issue-analyze ─▶ cs-issue-fix │ issues/ │
─▶ cs-code-review ✦Gate │
└──────────────┘
▸ 事件：代码腐化（beta） ┌──────────────┐
cs-refactor / cs-refactor-ff ─▶ cs-code-review ✦Gate│ refactors/ │
└──────────────┘
▸ 事件：目标驱动 ┌──────────────┐
cs-goal ──▶ grill 起点报告 ─▶ 自主 impl/验证/迭代 │ goals/ │
─▶ subagent 功能验收 └──────────────┘
═══════════════════════════════════════════════════════════════════════
│
┌───────────────────┴───────────────────┐
▼ 任意阶段觉得"这个值得记下来"都能触发 ▼ 阶段/里程碑结束触发
═══════════════════════════════════════════════════════════════════════
横切层 · 知识沉淀 & 文档整理
───────────────────────────────────────────────────────────────────────
cs-keep ──▶ .codestable/compound/YYYY-MM-DD-{slug}.md
纯 markdown，无 frontmatter，grep 检索
下一次 cs-feat-design / cs-issue-analyze 会回头 grep 复用
cs-note ──▶ .codestable/attention.md（碎片约定：flag / 路径 / 别名）
cs-docs-neat ──▶ 同步 .codestable/、README/docs、CLAUDE.md / AGENTS.md
防止文档与代码脱节
═══════════════════════════════════════════════════════════════════════
怎么读这张图：
- 纵向是层次，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入
- ✦Gate 是显式阻断点：design-review / code-review / qa 三道 Gate 各自产出报告，有 blocking 发现时流程不能向前，必须回到对应 impl 修复后重新过 Gate
- 第 3 层是事件入口：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流，目标驱动走 goal 流
- 横切层是飞轮：任何流程跑完发现"这事值得记下来"都可以触发
cs-keep沉淀，沉淀的产物又会被下一次同类工作读到；cs-docs-neat在里程碑收尾时统一整理文档防止漂移
完整示意图见 WORKFLOW.md。
/cs-onboard 跑完后，会在你的项目根下生成 .codestable/，作为 requirements、architecture、roadmap、goals、features、issues、refactors、audits、compound、tools、hooks 和 reference 的聚合根。
你的项目/
├── codestable/
│ ├── requirements/ # 需求 + 领域模型（cs-req / cs-domain 共同维护）
│ │ ├── VISION.md # 能力中心索引
│ │ ├── {slug}.md # 一个能力一份，扁平不分组
│ │ ├── CONTEXT.md # 领域术语表（cs-domain，lazy）
│ │ ├── CONTEXT-MAP.md # 多 context 拓扑入口（仅多 context 项目）
│ │ ├── adrs/ # 架构决策记录（cs-domain，lazy）
│ │ │ └── NNN-{slug}.md # Nygard 四节 + 状态机
│ │ └── {ctx}/ # 子 context 子目录（仅多 context）
│ │ ├── CONTEXT.md
│ │ ├── adrs/
│ │ └── {capability}.md
│ │
│ ├── 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-{slug}.md
│ │ # 纯 markdown，无 frontmatter，grep 检索（cs-keep 产出）
│ │
│ ├── tools/ # 跨工作流共享脚本（onboard 释放）
│ └── reference/ # 共享参考文档（onboard 释放）
│ ├── shared-conventions.md # 跨技能口径 / 路径命名 / 元数据规范
│ ├── system-overview.md # CodeStable 体系总览 + 场景路由
│ └── ...
│
└── AGENTS.md # 在项目根，不在 codestable/ 里
几条要点：
- 所有产物都聚在
codestable/下，让"上次那个 feature / bug 当时怎么搞的"三秒能找到 requirements/是长效档案（能力愿景 + 领域术语 CONTEXT.md + 拍板决策 adrs/），roadmap/是规划层（接下来怎么走），两者刻意分开features/issues/refactors/用YYYY-MM-DD-{slug}/一个目录装齐所有相关 spec，不交叉compound/是唯一的知识沉淀目录，纯 markdown 无 frontmatter，靠grep -r检索——好写好搜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 时带上新版本。
完整目录说明和跨 skill 引用约束见 WORKFLOW.md。
CodeStable 与 OMO 做的是完全相反的哲学。
- OMO 认为：人只要干预就是失败的信号
- CodeStable 认为：程序员是软件编码中的在环对象——可以对黑盒实现不了解，但对整体实现必须有所把控，必要时也可深入
软件架构必须要 可演进、可观测、可控制。
也许这一点在 AI 发展强大以后会变得不再重要，但当下这样做能让程序员在现状下舒服——这就是价值所在。
CodeStable 面向真实开发场景，对此进行建模，期望通过一个闭环系统处理开发中常见的问题。现有大部分框架围绕 AI 建模，而不是围绕人。 我认为这些框架的作者驱动 AI 的能力很强，但绝对不是严肃软件的开发者——因为缺少对软件开发中需求和设计的基础组织能力，缺乏对代码实现的尊重。
CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。
- 代码重构流程需要强化（
cs-refactor还在 beta） - ……
欢迎在 Issue 区贴你的真实开发困境和重构经验。
MIT License · 作者 @liuzhengdong