osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a5520db336cfdf7c11cd7edd8455d6d7bc097bc
git-learn/knowledge/entries/knowledge_20260519_CodeStable/knowledge_20260519_CodeStable.md
T

21 KiB
Raw Blame History

title, author, tags, created
title author tags created
CodeStable 深度解析：编排软件生命周期，而非编排 Agent 叫我小杨同学的小码酱
CodeStable
AI Engineering
Agent Skills
Harness Engineering
Human-in-the-Loop
OpenSpec
SuperPowers
工作流
2026-05-19

CodeStable 深度解析：编排软件生命周期，而非编排 Agent

模块 0：核心摘要 (TL;DR)

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

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

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

模块 1：概念破冰 (Concept Ice-breaking)

巧记卡片

AI 框架两派分：
Agent 编排派 → 管的是"谁干什么、怎么配合"
软件要素派 → 管的是"需求架构特性问题知识，每样都放对位置"

CodeStable 选了后者。记住6+3：
6 实体（Req, Arch, Roadmap, Feature, Issue, Compound）
3 流程（特性引入、问题修复、代码重构）

故事引入

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

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

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

他调研了市面上所有的 AI 编码框架——OpenSpec、SuperPowers、Oh-My-OpenAgent——没一个让他满意：

  • OpenSpec "太简单，生成的 Spec 抽象到人类没法读"
  • SuperPowers "没有流程约束，不知道该用哪个"
  • Oh-My-OpenAgent "太重，且哲学上认为'人介入 = 失败'"

于是他决定从零写一套新的。2026 年 4 月，CodeStable 诞生。不到两个月，781 stars。

可视化：两种范式的根本差异

Agent 编排派（SuperPowers / OpenSpec / OMO）:
  ┌─────┐   ┌─────┐   ┌─────┐
  │Agent1│←→│Agent2│←→│Agent3│     ← 编排的是 Agent
  └─────┘   └─────┘   └─────┘
       ↓         ↓         ↓
    [代码]    [代码]    [代码]         ← 软件要素在对话中丢失

软件要素派（CodeStable）:
  ┌──────────┐ ┌──────────┐ ┌──────────┐
  │Requirement│ │Architecture│ │ Feature  │  ← 编排的是软件要素
  └──────────┘ └──────────┘ └──────────┘
       ↑            ↑            ↑
       └────────────┼────────────┘
                    │
               [Agent 们]               ← Agent 是执行体，不是建模对象
                    │
               codestable/              ← 所有产物持久化在文件系统

模块 2：深度解析 (Deep Analysis)

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

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

这个立场需要放在 2026 年的大背景下来理解。2026 年 2 月，Hashicorp 联合创始人 Mitchell Hashimoto 提出了 Harness Engineering（驾驭工程） 概念，核心哲学是"人类掌舵，Agent 执行"（Human Steer, Agent Execute）。很快，OpenAI、Anthropic、LangChain 等主流 AI 工具都采纳了这一范式。

CodeStable 可以理解为 Harness Engineering 在"编码工作流"这个细分领域的具体实现。它不是反对自动化——它反对的是不留下痕迹的自动化。

当你让 AI 自主完成一个 feature，对话结束后，你得到的是代码。但你失去了：

  • 为什么要这么设计？
  • 当时有哪几种备选方案？
  • 这个设计依赖了哪些约束？

三个月后，另一个 developer（或三个月后的你）面对这段代码时，这些信息全部丢失了。

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

2.2 6 个实体：软件要素的建模

这是 CodeStable 区别于所有其他框架的核心设计：

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

实体 1：需求 (Requirement) — 代码烂掉的最终逃生通道。需求文档保留了"为什么要有这个能力"的原始上下文。如果某个 feature 的实现彻底腐化了，你可以拿着需求文档让 AI 重新生成代码。

实体 2：架构 (Architecture) — "系统的编排层长什么样"。刻意强调给人读的，不是给 AI 自嗨的。这回应了作者对 OpenSpec 的批评——"生成的 Spec 抽象到人类没法读"。

实体 3：路线图 (Roadmap) — 大需求的拆解层。作者注意到一个关键问题："我想要一个权限校验系统"直接塞给 AI 是接不住的。必须先拆成模块 → 子 feature → 分配执行顺序。这是人在环中起核心作用的一层。

实体 4：特性 (Feature) — 实际落地的执行过程。design → impl → accept 三步闭环，design 是后续所有步骤的唯一输入。这种设计避免了 AI 在实现过程中"自己脑补"需求。

实体 5：问题 (Issue) — Bug 单，report → analyze → fix 三步走。关键创新是analyze 和 fix 分离——AI 常常急于修复而不理解根因，强制分开让每次修复都有理论依据。

实体 6：知识 (Compound) — CodeStable 最核心的差异优势。四种知识类型覆盖了软件工程中所有"值得记录"的时刻：经验 (learning)、模式 (trick)、决策 (decision)、探索 (explore)。这些知识会在下一次 cs-arch、cs-feat-design、cs-issue-analyze 时被自动检索。

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

CodeStable 的工作流不是一条线性流水线。它被组织成5 层：

层 内容 触发时机
阶段 0 cs-onboard 初始化 codestable/ 骨架 新项目接入时（一次）
第 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 任何时候觉得"值得记下来"

关键设计洞察：第 1 层和第 2 层刻意分开。"系统现在长什么样"和"接下来打算怎么走"是两个不同的问题。大部分 Spec 驱动框架把两者混在一个 Spec 文件里，导致"现状"和"规划"边界模糊。CodeStable 的解决方式是用不同的目录和不同的技能来管理。

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

你的项目/
├── codestable/
│   ├── requirements/                     # 需求（"为什么要有这个能力"）
│   ├── architecture/                     # 架构（"用什么结构实现"）
│   ├── roadmap/                          # 路线图（"接下来怎么走"）
│   ├── features/YYYY-MM-DD-{slug}/       # 特性执行
│   │   ├── {slug}-design.md              #   方案（唯一输入）
│   │   ├── {slug}-checklist.yaml         #   清单（impl 跑、accept 回写）
│   │   └── {slug}-acceptance.md          #   验收报告
│   ├── issues/YYYY-MM-DD-{slug}/         # 问题修复
│   ├── refactors/YYYY-MM-DD-{slug}/      # 重构（beta）
│   ├── compound/                         # 知识沉淀
│   │   └── YYYY-MM-DD-{doc_type}-{slug}.md
│   ├── tools/                            # 共享脚本
│   └── reference/                        # 共享参考文档
└── AGENTS.md

三条设计原则：

  1. 所有产物聚在一个目录下 → "上次那个 feature 怎么搞的，三秒找到"
  2. 日期前缀 → 按时间排序天然就是开发历史
  3. compound 用 type 字段区分而非分目录 → 方便跨类型搜索

2.5 硬约束：Skill 隔离与跨 Skill 共享

CodeStable 有一个重要的工程约束：每个 skill 运行时只能看到自己包内的文件。这意味着 SKILL.md A 不能直接引用 B 的 reference 文件。

解决方案：cs-onboard 在初始化时从技能包复制共享文档到项目的 codestable/reference/，其他 skill 通过项目相对路径读取。

这本质上是一个依赖注入模式——技能是通用逻辑，codestable/ 是注入的运行时上下文。和我们在 mattpocock/skills 中看到的 setup-matt-pocock-skills 设计如出一辙。

模块 3：深度裂变 (Deep Fission)

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

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

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

所有主流 AI 编码框架（截至 2026 年 5 月）都在"Agent 编排"这个范式下工作。它们回答的问题是："Agent 之间怎么分工？怎么协调？怎么传递上下文？"CodeStable 问的是另一个问题："软件的需求、约束、决策怎么被记下来、被检索、被复用？"

这个翻转在实践层面有一个直接后果：知识沉淀从"副作用"变成了"一等公民"。在 SuperPowers 中，你跑完一个 TDD 循环，你得到的是代码和测试。在 CodeStable 中，你跑完一个 feature，你得到的是代码 + design 文档 + acceptance 报告 + （可选的）compound 知识条目。后者在"三个月后还能被理解"这个维度上有结构性优势。

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

  1. 知识检索依赖 AI 的上下文窗口。compound/ 目录里的文件再多，最终还是要靠 AI "读" 来检索。如果 compound 积累了 200 个文件，AI 能一次读完吗？CodeStable 目前依赖 AI 在启动时选择性读取相关文件，没有真正的索引或向量检索。

  2. 没有强制执行机制。SuperPowers 的 TDD 是铁律——你跳过 RED 阶段，它直接中断你。CodeStable 的 cs-feat-accept 是验收，但验收的执行深度取决于你。如果人把关不严，整个质量门形同虚设。

  3. cs-brainstorm 的"分诊"能力受限于模型理解能力。让 AI 判断一个模糊想法"该走 design 还是进 roadmap 还是直接 feature"——这个判断本身就需要很高的理解力。模型理解错了，整个流程从一开始就偏了。

  4. 对比并非完全公平。OpenSpec 的 Spec 文件设计目标就是机器和人双读，作者批评它"抽象到人类没法读"，但很多 OpenSpec 用户的实际体验并非如此。这可能更多是使用方式和配置问题，而非框架本身的设计缺陷。

🔍 搜索内化：根据 V2EX 和 LINUX DO 社区讨论，CodeStable 的实际用户反馈总体积极——"正确性对我来说够了，按照流程生成完，手动审查，不复杂的需求基本一次性搞定"——但用户也指出了"上下文一长就会忘"的知识检索问题。CodeStable 作者在 README Roadmap 中也坦承项目处于早期阶段，多个模块（如 cs-refactor）仍在 beta。

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

在 README 的 Roadmap 部分，有这样一句话：

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

这让 CodeStable 区别于绝大多数 AI 框架——它不是试图建立一个永恒的体系，而是承认自己是一个过渡性工具。当未来的 AI 模型强到不需要手工组织软件要素时，CodeStable 的使命就完成了。

这种"自我消解的诚实"在 AI 工具领域极为罕见。大多数框架在讲"未来五年"的故事。CodeStable 在讲"在 AI 还不够好的当下，这样工作最舒服"。

模块 4：实战指南 (Actionable Guide)

4.1 如何开始

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

# 初始化项目
/cs-onboard

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

4.2 典型工作流

场景 A：新增功能

/cs-feat            # 进入特性流程
/cs-feat-design     # 写 design 文档（后续的唯一输入）
/cs-feat-impl       # 按 design 推进写代码
/cs-feat-accept     # 对照 design 验收

场景 B：修 Bug

/cs-issue           # 进入问题流程
/cs-issue-report    # 落成可复现的 report
/cs-issue-analyze   # 找根因、评估风险
/cs-issue-fix       # 定点修复 + 验证

场景 C：快速小改动

/cs-feat-ff         # 超轻量通道，跳过 design/accept

场景 D：沉淀知识

/cs-learn           # 踩坑经验
/cs-trick           # 可复用模式
/cs-decide          # 技术决策

4.3 避坑指南

🔴 反模式 ✅ 正确做法
跳过 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 报告 cs-feat-accept 的验收报告是"三个月后能理解"的关键

4.4 CodeStable 与你现有工作流的融合点

如果你已经有 /dev-flow（openspec + grill-with-docs + zoom-out + apply + diagnose），CodeStable 可以和它互补使用：

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 沉淀知识（比 CONTEXT.md 更结构化）

关键差异：dev-flow 的产出散落在 docs/ 和 CONTEXT.md 中。CodeStable 的产出全部集中在 codestable/ 下，用统一的命名约定管理。如果你的项目预计跨年维护，这种集中管理会越来越有价值。

4.5 ROI 分析

投入 产出
cs-onboard 初始化：2 分钟 建好所有目录骨架和共享 reference
跑完一个 feature 流程：比原来 OpenSpec 多 5-10 分钟 留下 design + acceptance + 可选的 compound，三个月后可回溯
学习 22 个技能：30-45 分钟 覆盖需求→架构→特性→问题→重构→知识的完整链路

模块 5：温故知新 (Consolidation)

常见陷阱 (FAQ)

Q: CodeStable 和 dev-flow 谁更好？ 不是替代关系。dev-flow 是流程编排元技能（"按什么步骤走"），CodeStable 是一套完整的软件生命周期建模体系（"软件要素怎么组织"）。可以组合使用：dev-flow 的 grill-with-docs 补充 CodeStable 缺少的"术语对齐"阶段；CodeStable 的 compound 补充 dev-flow 缺少的"结构化知识沉淀"。
Q: CodeStable 适合一个人用吗？ 非常适合。CodeStable 的设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作、没有审批流。它帮助单人开发者维持跨时间的一致性。如果是一个人维护的长期项目，CodeStable 是目前最合适的框架。
Q: CodeStable 和 SuperPowers 能一起用吗？ 理论上可以，但不推荐。两者的哲学是对立的——SuperPowers 希望人少介入，CodeStable 要求人在环。同时用会导致认知冲突："这一步到底是让 AI 自己决定，还是我来把关？"建议根据项目类型选一个主线。
Q: codestable/ 目录会变得很臃肿吗？ 会。这是有意为之。作者认为"臃肿"的文档目录好过"干净"的失忆。每个 feature 都留下完整的 design + acceptance，长期积累确实会很多文件。但日期前缀命名使按时间浏览很自然，且 compound 通过 type 字段做聚合。
Q: 轻量通道 cs-feat-ff 什么时候用？ 当你有一个非常明确的小改动——比如"把这个按钮的颜色改成蓝色"、"加一个表单字段"——不需要写 design 文档和完整的 acceptance 报告。但作者的建议是："如果不确定该不该走 ff，就走完整流程"。
Q: 如果我不想用全部 22 个技能怎么办？ CodeStable 的技能是松耦合的。你可以只用 cs-req + cs-feat-* 做特性开发，跳过 cs-roadmap 和 cs-refactor。最精简的子集：cs-onboard + cs-req + cs-feat + cs-issue。
Q: CodeStable 的 knowledge 检索能力有多强？ 目前是"文件命名约定 + AI 选择性读取"模式，而非向量语义检索。当 compound/ 积累到 50+ 个文件后，AI 可能无法一次读完所有文件，需要在 prompt 中引导 AI 只读相关的。作者在 Roadmap 中表示关注这个问题。
Q: 和 mattpocock/skills 的关系？ 同样是 Agent Skills 的封装形式，但建模哲学完全不同。mattpocock 的技能是"小工具"——每个技能解决一个特定问题（grill、diagnose、tdd）。CodeStable 的技能是"体系"——每个技能是软件生命周期中的一个步骤。前者灵活可组合，后者完整有体系。

自测题

  1. CodeStable 的 6 个软件实体是哪 6 个？每个的核心用途是什么？
  2. "编排 Agent"和"编排软件要素"的根本区别是什么？这种区别在工程实践上会产生什么不同的后果？
  3. CodeStable 的 3 个核心流程分别是什么？每个流程的技能链是什么？
  4. cs-feat-design 为什么被设计为"后续所有步骤的唯一输入"？这种设计避免了什么问题？
  5. compound/ 目录下的 4 种知识类型分别是什么？它们会在什么时机被 AI 重新检索？
  6. CodeStable 为什么要求每个 skill 运行时只能看到自己包内的文件？这个硬约束解决了什么问题？
  7. CodeStable 作者所说的"复利工程"（Compound Engineering）具体指什么？
  8. 如果你要将 CodeStable 集成到你现有的 dev-flow 中，哪些 Phase 可以保留、哪些可以用 CodeStable 替换？

参考资源

© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过

Reference in New Issue View Git Blame Copy Permalink