CodeStable 深度解析

📌 核心摘要

CodeStable 是首个将 AI 编码工作流的建模对象从"Agent 怎么协作"翻转为"软件要素怎么组织"的框架——它管的不再是 Agent，而是需求、架构、特性、问题、知识这六个实体的完整生命周期。

认知挂钩：想象你在管一个图书馆。SuperPowers 和 OpenSpec 在优化"管理员怎么工作得更高效"。CodeStable 在问一个更根本的问题——书有没有被正确分类、编目、放在对的书架上？管理员再高效，书是乱的，三年后谁也找不到东西。CodeStable 就是那个图书分类法。

真理锚点："软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好。" —— liuzhengdong

🧊 概念破冰

AI 框架两派分： Agent 编排派 → 管的是"谁干什么、怎么配合" 软件要素派 → 管的是"需求架构特性问题知识，每样都放对位置" CodeStable 选了后者。记住6+3： 6 实体（Req, Arch, Roadmap, Feature, Issue, Compound） 3 流程（特性引入、问题修复、代码重构）

📖 故事引入

2026 年初，开发者 liuzhengdong 正在开发一套新的 Harness Agent。一开始他用 VibeCoding——只写设计和需求，代码由 AI 改。这样撑了大部分特性开发。

直到有一天，Codex 反复解决不了一个"他认为比较简单"的问题，反复在同一个地方犯错。

他意识到：项目变大了，AI 开始迷失。不是因为 AI 不够聪明，而是因为之前的那些需求、设计决策、架构约束全忘了——这些信息散落在对话历史里，每次都丢失。

他调研了 OpenSpec、SuperPowers、Oh-My-OpenAgent，没一个让他满意。于是从零写了 CodeStable。2026 年 4 月发布，不到两个月，781 stars。

Agent 编排派（SuperPowers / OpenSpec / OMO）: ┌─────┐ ┌─────┐ ┌─────┐ │Agent1│←→│Agent2│←→│Agent3│ ← 编排的是 Agent └─────┘ └─────┘ └─────┘ ↓ ↓ ↓ [代码] [代码] [代码] ← 软件要素在对话中丢失软件要素派（CodeStable）: ┌──────────┐ ┌──────────┐ ┌──────────┐ │Requirement│ │Architecture│ │ Feature │ ← 编排的是软件要素 └──────────┘ └──────────┘ └──────────┘ ↑ ↑ ↑ └────────────┼────────────┘ │ [Agent 们] ← Agent 是执行体，不是建模对象 │ codestable/ ← 所有产物持久化在文件系统

🔬 深度解析

哲学内核：为什么"人在环"不是弱点而是设计选择

CodeStable 最受争议的点，也是它与主流框架最根本的分歧：它认为程序员必须是"在环对象"。

2026 年 2 月，Hashicorp 联合创始人 Mitchell Hashimoto 提出了 Harness Engineering（驾驭工程） 概念——"人类掌舵，Agent 执行"。CodeStable 是这一范式在"编码工作流"领域的具体实现。

它不反对自动化。它反对的是不留下痕迹的自动化。当 AI 自主完成一个 feature 后，三个月后另一个 developer 面对这段代码时，为什么这么设计？当时有哪些备选方案？这些设计依赖了什么约束？——全部丢失了。

CodeStable 的回答：每做一个决定，就在 codestable/ 目录里写下来。 给人读的，不是给 AI 自嗨的。

6 个实体 + 3 个流程

flowchart TD CS["cs 根入口"] --> ONBOARD["cs-onboard 初始化"] ONBOARD --> REQ["cs-req: 需求实体"] ONBOARD --> ARCH["cs-arch: 架构实体"] REQ --> ROADMAP["cs-roadmap: 路线图实体"] ARCH --> ROADMAP ROADMAP --> FEAT["cs-feat: 特性流程"] ROADMAP --> ISSUE["cs-issue: 问题流程"] ROADMAP --> REFACTOR["cs-refactor: 重构流程"] FEAT --> FEAT_D["cs-feat-design"] FEAT_D --> FEAT_I["cs-feat-impl"] FEAT_I --> FEAT_A["cs-feat-accept"] ISSUE --> ISSUE_R["cs-issue-report"] ISSUE_R --> ISSUE_A["cs-issue-analyze"] ISSUE_A --> ISSUE_F["cs-issue-fix"] FEAT_A --> COMPOUND["compound: 知识沉淀"] ISSUE_F --> COMPOUND REFACTOR --> COMPOUND COMPOUND --> LEARN["cs-learn: 经验"] COMPOUND --> TRICK["cs-trick: 模式"] COMPOUND --> DECIDE["cs-decide: 决策"] COMPOUND --> EXPLORE["cs-explore: 探索"] LEARN -. "下次被检索" .-> ARCH TRICK -. "下次被检索" .-> FEAT_D DECIDE -. "下次被检索" .-> ISSUE_A EXPLORE -. "下次被检索" .-> ROADMAP

实体	英文	核心用途
需求	requirements	原始用户故事、讨论与权衡。代码烂掉时最终的逃生通道
架构	architecture	系统编排层文档，精简统一，给人读的
路线图	roadmap	大需求拆解——模块拆分 + 接口契约 + 子 feature 清单
特性	feature	实际工程执行，design → impl → accept 三步闭环
问题	issue	Bug 单，report → analyze → fix，analyze 和 fix 强制分离
知识	compound	复利工程：经验 / 模式 / 决策 / 探索，四种知识类型

分层架构：不是流水线，是"分层 + 事件驱动"

层	内容	触发时机
阶段 0	cs-onboard 初始化骨架	新项目接入（一次）
第 1 层	cs-req / cs-arch 长效档案	需求/架构变更（反复刷新）
第 2 层	cs-roadmap 规划	大需求拆解（按需进入）
讨论入口	cs-brainstorm 分诊	想法模糊时（可选）
第 3 层	cs-feat-* / cs-issue-* / cs-refactor-*	事件驱动
横切层	cs-learn / cs-trick / cs-decide / cs-explore	任意时刻觉得"值得记下来"

运行时结构：codestable/ 目录设计

你的项目/
├── codestable/
│   ├── requirements/              # 需求（"为什么要有这个能力"）
│   ├── architecture/              # 架构（"用什么结构实现"）
│   ├── roadmap/                   # 路线图（"接下来怎么走"）
│   ├── features/YYYY-MM-DD-{slug}/ # 特性执行
│   ├── issues/YYYY-MM-DD-{slug}/  # 问题修复
│   ├── refactors/YYYY-MM-DD-{slug}/ # 重构（beta）
│   ├── compound/                  # 知识沉淀（复利工程）
│   │   └── YYYY-MM-DD-{type}-{slug}.md
│   ├── tools/                     # 共享脚本
│   └── reference/                 # 共享参考文档
└── AGENTS.md

硬约束：Skill 隔离与依赖注入

每个 skill 运行时只能看到自己包内的文件。跨 skill 共享的文档由 cs-onboard 从技能包复制到项目的 codestable/reference/，其他 skill 通过项目相对路径读取。这本质上是一个依赖注入模式——skill 是通用逻辑，codestable/ 是注入的运行时上下文。

💥 深度裂变

颠覆认知

"编排软件要素"是真的范式创新，还是旧酒新瓶？

对 CodeStable 最尖锐的批判性审视。

正方：确实在范式层面做了翻转

所有主流 AI 编码框架都在"Agent 编排"范式下工作。CodeStable 问的是另一个问题：软件的需求、约束、决策怎么被记下来、被检索、被复用？

实践后果：知识沉淀从"副作用"变成"一等公民"。SuperPowers 跑完 TDD → 得到代码和测试。CodeStable 跑完 feature → 得到代码 + design + acceptance + compound。后者在"三个月后还能被理解"上有结构性优势。

反方：四个没有解决的问题

知识检索依赖 AI 上下文窗口：compound/ 积累 200 个文件后，AI 能一次读完吗？没有索引或向量检索。
没有强制执行机制：SuperPowers 的 TDD 是铁律，CodeStable 的 accept 执行深度取决于人。人把关不严，质量门形同虚设。
cs-brainstorm 的分诊能力受限：让 AI 判断模糊想法"该走哪个流程"，这个判断本身就需要很高的理解力。
对竞品的批评不完全公平：OpenSpec 的 Spec 文件设计目标就是人机双读。很多用户的实际体验并非"人类没法读"。

🔍 搜索内化：V2EX 和 LINUX DO 社区反馈——"正确性对我来说够了，按照流程生成完手动审查，不复杂的需求基本一次性搞定"——但也指出"上下文一长就会忘"的知识检索问题。作者在 Roadmap 中坦承多个模块仍在 beta。

一个被忽略的关键信号：CodeStable 承认自己会"过时"

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

这让它区别于绝大多数 AI 框架——不是试图建立永恒的体系，而是承认自己是过渡性工具。这种"自我消解的诚实"在 AI 工具领域极为罕见。

🎯 实战指南

快速开始

# 安装
npx skills add https://github.com/liuzhengdongfortest/CodeStable

# 初始化项目
/cs-onboard

# 日常使用——不知道用哪个就喊根入口
/cs

典型工作流

# 场景 A：新增功能
/cs-feat → /cs-feat-design → /cs-feat-impl → /cs-feat-accept

# 场景 B：修 Bug
/cs-issue → /cs-issue-report → /cs-issue-analyze → /cs-issue-fix

# 场景 C：快速小改动
/cs-feat-ff    # 超轻量通道

# 场景 D：沉淀知识
/cs-learn      # 踩坑经验
/cs-trick      # 可复用模式
/cs-decide     # 技术决策

避坑指南

🔴 反模式	✅ 正确做法
跳过 cs-onboard，手动创建 codestable/	必须用 cs-onboard 初始化，确保 reference/ 被正确复制
cs-feat-impl 中不看 design 自己脑补	design 是唯一输入，偏离 design 必须回退更新 design
所有改动都走 cs-feat（太重）	小改动用 cs-feat-ff，大功能走完整流程
compound 文件乱命名	严格遵循 YYYY-MM-DD-{type}-{slug}.md 格式
不写 acceptance 报告	acceptance 报告是"三个月后能理解"的关键

CodeStable 与你现有 dev-flow 的融合点

dev-flow 阶段	CodeStable 替代/增强
Phase 0 初始 PRD	cs-req 沉淀为需求文档（更持久）
Phase 1.5 结构化 PRD	cs-feat-design 作为 design 文档
Phase 2 grill-with-docs	cs-brainstorm 作为讨论入口
Phase 2.5 zoom-out	cs-arch 单独维护架构文档
Phase 3 执行	cs-feat-impl + cs-feat-accept
Phase 4 收尾	cs-learn / cs-decide 沉淀知识

ROI 分析

初始化

cs-onboard 2 分钟 → 建好所有目录骨架

Feature 流程

比 OpenSpec 多 5-10 分钟 → 留下 design + acceptance + compound

学习成本

30-45 分钟熟悉 22 技能 → 覆盖完整软件生命周期

长期收益

3 个月后 feature 设计可回溯 → 消除隐知识丢失

📝 温故知新

FAQ

CodeStable 和 dev-flow 谁更好？

不是替代关系。dev-flow 是流程编排元技能，CodeStable 是软件生命周期建模体系。可组合使用：dev-flow 的 grill-with-docs 补充 CodeStable 缺少的术语对齐；CodeStable 的 compound 补充 dev-flow 缺少的结构化知识沉淀。

CodeStable 适合一个人用吗？

非常适合。设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作。如果是一个人维护的长期项目，CodeStable 是目前最合适的框架。

CodeStable 和 SuperPowers 能一起用吗？

理论上可以，但不推荐。哲学对立——SuperPowers 希望人少介入，CodeStable 要求人在环。建议根据项目类型选一个主线。

codestable/ 目录会变得很臃肿吗？

会，这是有意为之。"臃肿"的文档目录好过"干净"的失忆。日期前缀使按时间浏览很自然，compound 通过 type 字段做聚合。

轻量通道 cs-feat-ff 什么时候用？

非常明确的小改动——"把按钮颜色改蓝"、"加一个表单字段"。不确定该不该走 ff，就走完整流程。

如果不想用全部 22 个技能怎么办？

技能是松耦合的。最精简子集：cs-onboard + cs-req + cs-feat + cs-issue。

知识检索能力有多强？

目前是"文件命名约定 + AI 选择性读取"，非向量语义检索。compound/ 积累 50+ 文件后需要引导 AI 只读相关的。

和 mattpocock/skills 的关系？

同样 Skills 封装形式，建模哲学不同。mattpocock 是"小工具"——每个解决特定问题。CodeStable 是"体系"——每个是软件生命周期中的一个步骤。

自测题

CodeStable 的 6 个软件实体是哪 6 个？每个的核心用途是什么？

"编排 Agent"和"编排软件要素"的根本区别是什么？在工程实践上会产生什么不同的后果？

CodeStable 的 3 个核心流程分别是什么？每个流程的技能链是什么？

cs-feat-design 为什么被设计为"后续所有步骤的唯一输入"？这种设计避免了什么问题？

compound/ 目录下的 4 种知识类型分别是什么？它们会在什么时机被 AI 重新检索？

CodeStable 为什么要求每个 skill 运行时只能看到自己包内的文件？这个硬约束解决了什么问题？

CodeStable 作者所说的"复利工程"（Compound Engineering）具体指什么？

如果你要将 CodeStable 集成到你现有的 dev-flow 中，哪些 Phase 可以保留、哪些可以用 CodeStable 替换？

参考资源

GitHub：liuzhengdongfortest/CodeStable
作者的项目 MA：liuzhengdongfortest/MA
Harness Engineering (Mitchell Hashimoto, 2026.02)
V2EX 讨论：厌倦了 OpenSpec、OMO、SuperPowers？试试 CodeStable