缘起

我在开发一套新的 Harness Agent ，一开始当然是 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 、每一条历史里留下来的约束。

这两个方向没有谁对谁错。

如果你的任务是"用 AI 跑一个端到端的自动化产线"、"让多个 Agent 互相讨论方案"，Agent 编排派会更顺手。

如果你的任务是"维护一个会跨年迭代的严肃软件"、"让今天写下的需求和决策三个月后还能被准确召回"——那 CodeStable 这套以软件要素为中心的建模会更合适。

我做 CodeStable 是因为我相信：软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好。Agent 再强，也写不了一个把需求、架构、历史决策全丢失的项目。

设计：6 个实体 + 3 个流程

CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 6 个实体 和 3 个流程。

6 个实体

3 个流程

技能总览

工作流示意

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/                            # 跨工作流共享脚本（ onboarding 释放）
│   └── reference/                        # 共享参考文档（ onboarding 释放）
│       ├── 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/ 模板，新项目 onboarding 自动带上新版

硬约束

Skill 是独立安装单元，运行时每个 skill 只能看到自己包内的文件。A 技能的 SKILL.md 里写 B-skill/reference/xxx.md 这种引用在运行时根本读不到。

跨 skill 共享的参考文档必须走"工作项目"这一层：由 cs-onboard 从技能包复制到项目的 codestable/reference/，其他 skill 用项目相对路径读取。

要改共享口径，改 cs-onboard/reference/ 下的模板，新项目 onboarding 时带上新版本。

设计哲学

CodeStable 与 OMO 做的是完全相反的哲学。

• OMO 认为：人只要干预就是失败的信号
• CodeStable 认为：程序员是软件编码中的在环对象——可以对黑盒实现不了解，但对整体实现必须有所把控，必要时也可深入

软件架构必须要 可演进、可观测、可控制。

也许这一点在 AI 发展强大以后会变得不再重要，但当下这样做能让程序员在现状下舒服——这就是价值所在。

CodeStable 面向真实开发场景，对此进行建模，期望通过一个闭环系统处理开发中常见的问题。现有大部分框架围绕 AI 建模，而不是围绕人。 我认为这些框架的作者驱动 AI 的能力很强，但绝对不是严肃软件的开发者——因为缺少对软件开发中需求和设计的基础组织能力，缺乏对代码实现的尊重。

Roadmap

CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。

• 代码重构流程需要强化（cs-refactor 还在 beta ）
• ……

项目地址： https://github.com/liuzhengdongfortest/CodeStable

MIT License · 作者 @liuzhengdong