开源项目CodeStable：以软件要素为核心重构AI编码工作流

背景

在 AI 辅助编程日益普及的当下，开发者面临着从“Vibe Coding”（仅通过自然语言描述需求，由 AI 生成代码）向严肃软件工程过渡的痛点。作者最初在开发一套新的 Harness Agent 时，依赖 Codex 等模型进行代码生成，但在遇到复杂逻辑和重复性错误时，发现单纯依赖 AI 无法维持项目的长期演进。

为了解决这一问题，作者调研了当时主流的 AI 编码框架，如 OpenSpec、SuperPowers 和 Oh-My-OpenAgent，但认为它们存在明显缺陷：

• OpenSpec：过于简单，缺乏复利工程支持，生成的规范（Spec）抽象程度过高，人类难以阅读。
• SuperPowers：缺乏流程约束，开发者不清楚何时使用何种功能。
• Oh-My-OpenAgent：架构过重，且其哲学理念认为“人类介入即失败”，这在严肃工程中并不适用。

在此背景下，作者将之前的项目 EasySDD 正式更名为 CodeStable。该项目的核心目标并非追求新名词或热点，而是解决严肃软件工程中代码实现与编码管理的实际问题。

核心内容

CodeStable 的核心理念在于重新定义 AI 编码框架的编排对象。它不与现有的 Agent 编排框架（如 SuperPowers、CCW、Oh-My-OpenAgent 等）竞争，而是提供了另一种视角。

编排目标的差异：Agent vs. 软件要素

现有主流框架主要关注如何编排 Agent（智能体），围绕的实体是 Agent、角色或团队，旨在让它们协作、头脑风暴、跑流水线。其核心问题是 Agent 之间如何分工与协调，状态通常存储在 Session、消息总线或队列中，且倾向于减少人类介入。

CodeStable 则不同，它编排的是软件本身的生命周期。围绕的实体是构成软件的要素：每一个需求、每一个架构决定、每一个特性、每一个 Bug 以及历史遗留的约束。其核心问题是软件的需求、约束和决策如何被记录、检索和复用。状态存储在项目根目录下的 codestable/ 文件树中，这是一种人和 AI 都能直接读取的结构化数据。

这种设计解决的痛点是：软件复杂度的膨胀导致上下文溢出、隐知识丢失和需求漂移。CodeStable 认为，软件工程的混乱本质不是 Agent 不够强，而是要素没有被组织好。即使 Agent 能力再强，如果需求、架构和历史决策全部丢失，逻辑上也无法完成一个可持续迭代的项目。

与 Trellis 的区别

针对社区询问，作者特别对比了由站内开发者桃酥制作的 Trellis 框架。虽然两者都涉及规范化管理，但根本区别依然在于“编排的目标”：

• Trellis：目录结构包含 .trellis/spec/、tasks/、workspace/ 等，依然偏向于 Agent 编排和任务流转。
• CodeStable：目录结构以 codestable/ 为核心，细分为 requirements/（需求）、architecture/（架构）、roadmap/（路线图）、features/（特性）、issues/（问题）、refactors/（重构）、compound/（知识沉淀）等。

作者认为，CodeStable 将所谓的 Spec 打得更细，更符合实际开发实践，强调以软件要素为中心，而非以 Agent 为中心。

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

CodeStable 顺着软件编码的真实流程，将开发活动建模为 6 个实体和 3 个流程。

6 个核心实体

1. 需求 (Requirements)：记录原始用户故事、当时的讨论与权衡。它是最终的“逃生通道”，当代码质量恶化时，可基于原始需求让 AI 重新生成。
2. 架构 (Architecture)：为实现需求而设计的系统编排层。文档要求精简、统一，主要供人类阅读，而非供 AI 自我娱乐。
3. 路线图 (Roadmap)：将模糊的大目标（如“我想要一个权限校验系统”）拆解为可分步推进的子任务序列，避免直接让 AI 处理过于复杂的特性。
4. 特性 (Feature)：实际落地的工程执行过程，人与 AI 共同协作，对设计、实现和验收负责。
5. 问题 (Issue)：开发完成后的 Bug 单子，由 AI 和人类共同解决。
6. 知识 (Compound)：复利工程的知识库，用于沉淀踩过的坑、好做法和技术决策。

3 个核心流程

1. 特性引入 (Feature Introduction)：
   • 流程：cs-brainstorm → cs-feat-design → cs-feat-impl → cs-feat-accept
   • 说明：从想法模糊时的统一讨论入口（分诊），到综合架构设计，再到逐步编码，最后进行验收测试。
2. 问题修改 (Issue Modification)：
   • 流程：cs-issue-report → cs-issue-analyze → cs-issue-fix
   • 说明：将问题转化为可复现的报告，让 AI 分析根因并评估风险，最后进行定点修复并验证。
3. 代码重构 (Code Refactoring)：
   • 流程：cs-refactor (Beta)
   • 说明：软件架构腐化是渐进的。AI 辅助重构，但最终决策和执行仍由人类主导。

技能与工作流示意

CodeStable 的技能并非线性流水线，而是分层且事件驱动的。

• 阶段 0 · 接入：通过 cs-onboard 命令，在新项目或已有仓库中生成 codestable/ 骨架，并释放共享参考文档和工具。
• 第 1 层 · 长效档案：通过 cs-req 和 cs-arch 记录系统现状，生成需求文档和架构文档。
• 第 2 层 · 规划：通过 cs-roadmap 将大需求拆解为可执行的 Feature。小需求可跳过此层。
• 讨论入口：通过 cs-brainstorm 进行想法分诊，根据清晰度和复杂度路由到 cs-feat-design 或直接进入 Feature 流。

此外，还提供了一系列细分技能，如 cs-learn（沉淀学习）、cs-trick（整理编程模式）、cs-decide（记录技术选型）、cs-explore（定向代码探索）等，以支持全生命周期的知识管理。

关键要点

• 核心理念转变：CodeStable 从“编排 Agent”转向“编排软件要素”，强调需求、架构、决策等静态要素的结构化管理，以应对软件复杂度膨胀和上下文丢失。
• 人在环 (Human-in-the-loop)：与认为“人介入即失败”的框架不同，CodeStable 坚持人在环理念，程序员负责整体把控，AI 作为高效执行体，两者协作而非替代。
• 结构化存储：所有状态和知识存储在项目根目录的 codestable/ 文件树中，确保人和 AI 均可直接读取和检索，避免了黑盒化的 Agent 状态管理。
• 复利工程：通过 compound 目录和 cs-learn、cs-trick 等技能，强制沉淀踩坑经验和技术决策，形成可复用的知识资产，避免重复犯错。
• 分层工作流：工作流分为接入、长效档案、规划、讨论入口等层级，支持从模糊想法到具体实现的平滑过渡，并提供轻量级通道（如 cs-feat-ff）以适应不同复杂度的任务。
• 开源与透明：项目完全开源，遵循 LINUX DO 社区推广规范，强调内容的真实性和可监督性。

意义与影响

CodeStable 的提出为 AI 辅助编程领域提供了一个重要的补充视角。当前大多数 AI 编码工具倾向于自动化和 Agent 协作，往往忽视了软件工程中“知识管理”和“