CodeStable：以软件要素为中心的AI编码框架

背景

随着 AI 编码工具的普及，开发者越来越多地依赖大语言模型（如 Claude、Codex）来辅助编写代码。然而，在严肃工程场景中，AI 常常在反复出现相同错误、丢失上下文、遗忘历史决策等问题上暴露出局限性。为此，社区涌现出 OpenSpec、SuperPowers、Oh-My-OpenAgent 等框架，尝试通过编排多个 Agent 来提升协作效率。但这些工具在作者的实际使用中均存在不足：OpenSpec 过于简单且生成的规格抽象到人类无法阅读；SuperPowers 缺乏流程约束；Oh-My-OpenAgent 则过于重量级，且其哲学主张“人介入 = 失败”，不适合需要程序员主导的复杂项目。在此背景下，作者决定开发一套以软件生命周期而非 Agent 为中心的工作流框架，即 CodeStable（原 EasySDD）。

核心内容

CodeStable 的核心定位是解决严肃工程的软件实现和编码问题，而非追求热点或制造新名词。它与主流 AI 编码框架（如 Superpowers、CCW、Oh-My-OpenAgent）的根本区别在于编排的目标：主流框架围绕 Agent 进行编排——让 Agent 组队、协作、头脑风暴、跑流水线、自动接力；而 CodeStable 围绕软件本身的要素——每个需求、架构决定、特性、Bug、历史约束——进行编排，以以软件要素为中心。

六大实体

CodeStable 将软件开发活动建模为 6 个实体，均存储在项目根目录下的 codestable/ 文件树中（人和 AI 均可读写）：

• 需求（requirements）：记录原始用户故事、讨论与权衡，作为代码腐烂时的终极逃生通道。
• 架构（architecture）：记录为实现需求的系统编排层，文档精简、统一，供人阅读。
• 路线图（roadmap）：将模糊大目标拆解为可执行的子任务序列，避免直接塞给 AI 导致失败。
• 特性（feature）：实际落地的工程执行过程，人与 AI 协作，对设计、实现、验收负责。
• 问题（issue）：开发完成后的 Bug 单子，由 AI 和人共同解决。
• 知识（compound）：复利工程的知识库，沉淀踩过的坑、好做法、技术决策。

三大流程

• 特性引入：包含 cs-brainstorm → cs-feat-design → cs-feat-impl → cs-feat-accept 四个子技能，从想清楚到设计、编码、验收。
• 问题修改：包含 cs-issue-report → cs-issue-analyze → cs-issue-fix，先报告问题，再分析根因，最后定点修复。
• 代码重构（beta）：cs-refactor 与 cs-refactor-ff，辅助重构但强调“终归是人在重构”。

技能总览

CodeStable 提供了丰富的技能（skill），每个技能对应一个特定用途的 CLI/对话入口，例如：

• 接入：cs-onboard
• 需求与架构：cs-req、cs-arch
• 路线图：cs-roadmap
• 讨论入口：cs-brainstorm
• 特性流程：cs-feat、cs-feat-design、cs-feat-impl、cs-feat-accept、cs-feat-ff（轻量通道）
• 问题流程：cs-issue、cs-issue-report、cs-issue-analyze、cs-issue-fix
• 重构流程：cs-refactor、cs-refactor-ff
• 知识沉淀：cs-learn、cs-trick、cs-decide
• 探索与文档：cs-explore、cs-guide、cs-libdoc

工作流示意

CodeStable 的技能不是线性流水线，而是分层 + 事件驱动：

• 阶段 0 · 接入：cs-onboard 生成 codestable/ 骨架并释放参考文件。
• 第 1 层 · 长效档案：使用 cs-req、cs-arch 记录系统当前状态。
• 第 2 层 · 规划：使用 cs-roadmap 将大需求拆分为多个可执行特性（小需求可跳过）。
• 讨论入口：cs-brainstorm 对模糊想法进行分诊，路由到设计或特性流。

与 Trellis 的区别

作者专门说明与 Trellis（桃酥大佬的作品）的关系。Trellis 的目录结构偏向 Agent 编排（虽有 spec 但依然以 Agent 协同为核心），而 CodeStable 将 spec 打得更细、更符合开发实践，本质区别仍是编排目标不同。作者强调不拉踩，尊重不同框架的适用场景。

关键要点

• 以软件要素为中心：与主流框架围绕 Agent 编排不同，CodeStable 围绕需求、架构、特性、问题、知识、路线图等软件要素进行组织，目标是让这些要素被长期记录、检索和复用。
• 人机协作定位：CodeStable 主张“人在环”——程序员对整体把控负责，AI 是高效执行体。这与 Oh-My-OpenAgent 的“人介入 = 失败”哲学形成对比。
• 解决上下文丢失与知识遗忘：通过将要素持久化到 codestable/ 文件树，确保今天写下的决策和需求三个月后仍能被准确召回。
• 分层事件驱动的工作流：技能不是线性流水线，而是分层结构（接入 → 长效档案 → 规划 → 讨论入口 → 特性/问题/重构流程），支持按需触发。
• 轻量通道与完整流程并存：提供 cs-feat-ff、cs-refactor-ff 等轻量通道，允许跳过复杂步骤直接执行，兼顾效率与严谨。
• 复利工程：compound 目录用于沉淀踩过的坑、好做法、技术决策，形成可积累的知识库。
• 与 Trellis 的差异：Trellis 偏向 Agent 编排，CodeStable 则更细粒度地管理软件要素，本质区别在于编排目标不同。

意义与影响

CodeStable 的提出反映了 AI 编码工具演进中的一个重要趋势：从多 Agent 协作的自动化产线转向以软件工程本体为核心的治理。在严肃项目中，软件复杂度膨胀、上下文丢失、需求漂移是比 Agent 能力不足更根本的问题。CodeStable 通过将软件要素显式组织为文件树，让 AI 和人能够在同一套结构化信息上协同工作，从而降低重复劳动、提升长期维护性。

该框架的意义在于：

• 为 AI 辅助编程提供了工程化方法论，而不仅仅是提示词技巧或 Agent 调度。
• 强调人的主导地位，避免盲目追求全自动，更适合企业级项目的实际需求。
• 可复用性高：codestable/ 作为项目内文件，与版本控制系统天然兼容，任何开发者或 AI 均可访问。
• 开源且社区驱动：作者遵守开源推广承诺，鼓励社区测试和反馈，有助于形成最佳实践。

CodeStable 并非要替代现有 Agent 编排框架，而是填补了一个被忽视的领域——软件要素的长期组织与治理。对于