Reorganize workspace and archive skill artifacts
This commit is contained in:
@@ -0,0 +1,370 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>CodeStable 深度解析 — github-learn</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
||||
<style>
|
||||
*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
|
||||
html{scroll-behavior:smooth}
|
||||
body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans SC",Roboto,"Helvetica Neue",sans-serif;background:#f8fafc;color:#1e293b;line-height:1.75;font-size:16px}
|
||||
.wrapper{max-width:860px;margin:0 auto;padding:0 24px}
|
||||
.article-header{background:linear-gradient(135deg,#0f172a 0%,#1e3a5f 100%);color:#f1f5f9;padding:64px 0 48px;margin-bottom:48px}
|
||||
.article-header h1{font-size:2rem;font-weight:700;line-height:1.3;margin-bottom:16px;letter-spacing:-0.02em}
|
||||
.article-header .meta{display:flex;gap:16px;flex-wrap:wrap;font-size:.875rem;color:#94a3b8}
|
||||
.article-header .tags{display:flex;gap:8px;flex-wrap:wrap;margin-top:12px}
|
||||
.article-header .tag{background:rgba(255,255,255,0.1);border:1px solid rgba(255,255,255,0.2);padding:2px 10px;border-radius:12px;font-size:.75rem;color:#cbd5e1}
|
||||
.module{margin-bottom:48px}
|
||||
.module-title{font-size:1.35rem;font-weight:700;color:#0f172a;padding-bottom:8px;border-bottom:3px solid #3b82f6;margin-bottom:24px;display:flex;align-items:center;gap:8px}
|
||||
.tldr-box{background:linear-gradient(135deg,#eff6ff,#dbeafe);border-left:4px solid #3b82f6;border-radius:8px;padding:24px;margin-bottom:32px}
|
||||
.tldr-box .core{font-size:1.1rem;font-weight:600;margin-bottom:12px}
|
||||
.tldr-box .hook{background:#fff;border:1px dashed #93c5fd;border-radius:6px;padding:12px 16px;margin-bottom:12px;font-size:.95rem}
|
||||
.tldr-box .anchor{font-style:italic;color:#475569;font-size:.9rem}
|
||||
.mnemonic-card{background:#fffbeb;border:2px dashed #f59e0b;border-radius:8px;padding:20px 24px;margin:24px 0;font-family:"Courier New",monospace;font-size:.95rem;line-height:1.8;white-space:pre-wrap}
|
||||
.mnemonic-card::before{content:"🧠 巧记卡片";display:block;font-family:-apple-system,sans-serif;font-weight:700;color:#b45309;margin-bottom:8px;font-size:.85rem}
|
||||
.story-box{background:#f1f5f9;border-radius:8px;padding:20px 24px;margin:24px 0;border-left:3px solid #64748b}
|
||||
.story-box .story-label{font-size:.8rem;font-weight:700;color:#64748b;text-transform:uppercase;letter-spacing:.05em;margin-bottom:8px}
|
||||
.ascii-box{background:#0f172a;color:#a5f3fc;border-radius:8px;padding:20px 24px;margin:24px 0;font-family:"Courier New",monospace;font-size:.85rem;line-height:1.6;overflow-x:auto;white-space:pre}
|
||||
.mermaid-box{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:24px;margin:24px 0;text-align:center}
|
||||
.table-wrap{overflow-x:auto;margin:24px 0}
|
||||
table{width:100%;border-collapse:collapse;font-size:.9rem}
|
||||
th{background:#f1f5f9;text-align:left;padding:10px 14px;border-bottom:2px solid #cbd5e1;font-weight:600}
|
||||
td{padding:10px 14px;border-bottom:1px solid #e2e8f0}
|
||||
tr:hover td{background:#f8fafc}
|
||||
.fission-section{background:#fef2f2;border-left:4px solid #dc2626;border-radius:8px;padding:24px;margin:32px 0}
|
||||
.fission-section .fission-title{font-size:1.05rem;font-weight:700;color:#991b1b;margin-bottom:16px}
|
||||
.fission-section .fission-label{display:inline-block;background:#dc2626;color:#fff;font-size:.7rem;font-weight:700;padding:2px 8px;border-radius:4px;margin-bottom:12px}
|
||||
.fission-section .search-internal{display:inline-block;background:#f1f5f9;border:1px solid #cbd5e1;font-size:.75rem;padding:2px 8px;border-radius:4px;color:#475569;margin-bottom:12px}
|
||||
.faq-box{margin:24px 0}
|
||||
details{border:1px solid #e2e8f0;border-radius:6px;margin-bottom:8px;overflow:hidden;transition:border-color .2s}
|
||||
details:hover{border-color:#94a3b8}
|
||||
details[open]{border-color:#3b82f6}
|
||||
summary{padding:14px 18px;cursor:pointer;font-weight:500;background:#f8fafc;user-select:none}
|
||||
details[open] summary{border-bottom:1px solid #e2e8f0;background:#eff6ff}
|
||||
details .faq-body{padding:16px 18px;font-size:.95rem;line-height:1.7}
|
||||
.quiz-box{counter-reset:quiz;margin:24px 0}
|
||||
.quiz-item{background:#f8fafc;border:1px solid #e2e8f0;border-radius:6px;padding:14px 18px;margin-bottom:10px;font-size:.95rem;counter-increment:quiz}
|
||||
.quiz-item::before{content:counter(quiz) ". ";font-weight:700;color:#3b82f6}
|
||||
pre{background:#0f172a;color:#e2e8f0;border-radius:8px;padding:18px 20px;overflow-x:auto;font-size:.85rem;line-height:1.6;margin:20px 0}
|
||||
code{font-family:"JetBrains Mono","Fira Code","Consolas",monospace}
|
||||
p code,li code{background:#f1f5f9;padding:2px 6px;border-radius:4px;font-size:.85em;color:#b91c1c}
|
||||
p{margin-bottom:16px}
|
||||
ul,ol{margin-bottom:16px;padding-left:24px}
|
||||
li{margin-bottom:6px}
|
||||
h2{font-size:1.25rem;margin:28px 0 12px;color:#0f172a}
|
||||
h3{font-size:1.1rem;margin:24px 0 10px;color:#1e293b}
|
||||
h4{font-size:1rem;margin:20px 0 8px;color:#334155}
|
||||
blockquote{border-left:3px solid #3b82f6;padding:12px 18px;margin:20px 0;background:#f8fafc;border-radius:0 6px 6px 0;color:#475569}
|
||||
.roi-grid{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin:24px 0}
|
||||
.roi-card{background:#f0fdf4;border:1px solid #bbf7d0;border-radius:8px;padding:16px}
|
||||
.roi-card .roi-label{font-size:.75rem;font-weight:700;color:#16a34a;text-transform:uppercase;margin-bottom:4px}
|
||||
.roi-card .roi-value{font-weight:600;font-size:1rem}
|
||||
.anti-pattern td:first-child{color:#dc2626}
|
||||
.anti-pattern td:last-child{color:#16a34a}
|
||||
.article-footer{text-align:center;padding:32px 0;margin-top:48px;border-top:1px solid #e2e8f0;color:#94a3b8;font-size:.85rem}
|
||||
#search-input{width:100%;padding:12px 16px;border:2px solid #e2e8f0;border-radius:8px;font-size:.95rem;margin-bottom:32px;outline:none;transition:border-color .2s;font-family:inherit}
|
||||
#search-input:focus{border-color:#3b82f6}
|
||||
.hidden{display:none !important}
|
||||
@media(max-width:640px){.article-header h1{font-size:1.5rem}.roi-grid{grid-template-columns:1fr}.wrapper{padding:0 16px}}
|
||||
@media print{.article-header{background:#fff !important;color:#000 !important;padding:24px 0}.article-header h1{color:#000}#search-input{display:none}}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<header class="article-header">
|
||||
<div class="wrapper">
|
||||
<h1>CodeStable 深度解析:编排软件生命周期,而非编排 Agent</h1>
|
||||
<div class="meta"><span>叫我小杨同学的小码酱</span><span>2026-05-19</span></div>
|
||||
<div class="tags">
|
||||
<span class="tag">CodeStable</span><span class="tag">AI Engineering</span><span class="tag">Agent Skills</span><span class="tag">Harness Engineering</span><span class="tag">Human-in-the-Loop</span><span class="tag">工作流</span>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div class="wrapper" id="content-area">
|
||||
|
||||
<input type="text" id="search-input" placeholder="搜索知识点..." autocomplete="off">
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">📌 核心摘要</h2>
|
||||
<div class="tldr-box">
|
||||
<p class="core">CodeStable 是首个将 AI 编码工作流的建模对象从"Agent 怎么协作"翻转为"软件要素怎么组织"的框架——它管的不再是 Agent,而是需求、架构、特性、问题、知识这六个实体的完整生命周期。</p>
|
||||
<div class="hook"><strong>认知挂钩</strong>:想象你在管一个图书馆。SuperPowers 和 OpenSpec 在优化"管理员怎么工作得更高效"。CodeStable 在问一个更根本的问题——书有没有被正确分类、编目、放在对的书架上?管理员再高效,书是乱的,三年后谁也找不到东西。CodeStable 就是那个图书分类法。</div>
|
||||
<div class="anchor"><strong>真理锚点</strong>:"软件工程的混乱本质上不是 Agent 不够强,而是要素没被组织好。" —— liuzhengdong</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">🧊 概念破冰</h2>
|
||||
|
||||
<div class="mnemonic-card">AI 框架两派分:
|
||||
Agent 编排派 → 管的是"谁干什么、怎么配合"
|
||||
软件要素派 → 管的是"需求架构特性问题知识,每样都放对位置"
|
||||
|
||||
CodeStable 选了后者。记住6+3:
|
||||
6 实体(Req, Arch, Roadmap, Feature, Issue, Compound)
|
||||
3 流程(特性引入、问题修复、代码重构)</div>
|
||||
|
||||
<div class="story-box">
|
||||
<div class="story-label">📖 故事引入</div>
|
||||
<p>2026 年初,开发者 liuzhengdong 正在开发一套新的 Harness Agent。一开始他用 VibeCoding——只写设计和需求,代码由 AI 改。这样撑了大部分特性开发。</p>
|
||||
<p>直到有一天,Codex 反复解决不了一个"他认为比较简单"的问题,<strong>反复在同一个地方犯错</strong>。</p>
|
||||
<p>他意识到:项目变大了,AI 开始迷失。不是因为 AI 不够聪明,而是因为之前的那些需求、设计决策、架构约束全忘了——这些信息散落在对话历史里,每次都丢失。</p>
|
||||
<p>他调研了 OpenSpec、SuperPowers、Oh-My-OpenAgent,没一个让他满意。于是从零写了 CodeStable。2026 年 4 月发布,不到两个月,781 stars。</p>
|
||||
</div>
|
||||
|
||||
<div class="ascii-box">Agent 编排派(SuperPowers / OpenSpec / OMO):
|
||||
┌─────┐ ┌─────┐ ┌─────┐
|
||||
│Agent1│←→│Agent2│←→│Agent3│ ← 编排的是 Agent
|
||||
└─────┘ └─────┘ └─────┘
|
||||
↓ ↓ ↓
|
||||
[代码] [代码] [代码] ← 软件要素在对话中丢失
|
||||
|
||||
软件要素派(CodeStable):
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│Requirement│ │Architecture│ │ Feature │ ← 编排的是软件要素
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
↑ ↑ ↑
|
||||
└────────────┼────────────┘
|
||||
│
|
||||
[Agent 们] ← Agent 是执行体,不是建模对象
|
||||
│
|
||||
codestable/ ← 所有产物持久化在文件系统</div>
|
||||
</section>
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">🔬 深度解析</h2>
|
||||
|
||||
<h3>哲学内核:为什么"人在环"不是弱点而是设计选择</h3>
|
||||
<p>CodeStable 最受争议的点,也是它与主流框架最根本的分歧:<strong>它认为程序员必须是"在环对象"</strong>。</p>
|
||||
<p>2026 年 2 月,Hashicorp 联合创始人 Mitchell Hashimoto 提出了 <strong>Harness Engineering(驾驭工程)</strong> 概念——"人类掌舵,Agent 执行"。CodeStable 是这一范式在"编码工作流"领域的具体实现。</p>
|
||||
<p>它不反对自动化。它反对的是<strong>不留下痕迹的自动化</strong>。当 AI 自主完成一个 feature 后,三个月后另一个 developer 面对这段代码时,为什么这么设计?当时有哪些备选方案?这些设计依赖了什么约束?——全部丢失了。</p>
|
||||
<p>CodeStable 的回答:<strong>每做一个决定,就在 codestable/ 目录里写下来。</strong> 给人读的,不是给 AI 自嗨的。</p>
|
||||
|
||||
<h3>6 个实体 + 3 个流程</h3>
|
||||
|
||||
<div class="mermaid-box">
|
||||
<div class="mermaid">
|
||||
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
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>实体</th><th>英文</th><th>核心用途</th></tr>
|
||||
<tr><td><strong>需求</strong></td><td>requirements</td><td>原始用户故事、讨论与权衡。代码烂掉时最终的逃生通道</td></tr>
|
||||
<tr><td><strong>架构</strong></td><td>architecture</td><td>系统编排层文档,精简统一,<strong>给人读的</strong></td></tr>
|
||||
<tr><td><strong>路线图</strong></td><td>roadmap</td><td>大需求拆解——模块拆分 + 接口契约 + 子 feature 清单</td></tr>
|
||||
<tr><td><strong>特性</strong></td><td>feature</td><td>实际工程执行,design → impl → accept 三步闭环</td></tr>
|
||||
<tr><td><strong>问题</strong></td><td>issue</td><td>Bug 单,report → analyze → fix,analyze 和 fix 强制分离</td></tr>
|
||||
<tr><td><strong>知识</strong></td><td>compound</td><td>复利工程:经验 / 模式 / 决策 / 探索,四种知识类型</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>分层架构:不是流水线,是"分层 + 事件驱动"</h3>
|
||||
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>层</th><th>内容</th><th>触发时机</th></tr>
|
||||
<tr><td><strong>阶段 0</strong></td><td>cs-onboard 初始化骨架</td><td>新项目接入(一次)</td></tr>
|
||||
<tr><td><strong>第 1 层</strong></td><td>cs-req / cs-arch 长效档案</td><td>需求/架构变更(反复刷新)</td></tr>
|
||||
<tr><td><strong>第 2 层</strong></td><td>cs-roadmap 规划</td><td>大需求拆解(按需进入)</td></tr>
|
||||
<tr><td><strong>讨论入口</strong></td><td>cs-brainstorm 分诊</td><td>想法模糊时(可选)</td></tr>
|
||||
<tr><td><strong>第 3 层</strong></td><td>cs-feat-* / cs-issue-* / cs-refactor-*</td><td>事件驱动</td></tr>
|
||||
<tr><td><strong>横切层</strong></td><td>cs-learn / cs-trick / cs-decide / cs-explore</td><td>任意时刻觉得"值得记下来"</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>运行时结构:codestable/ 目录设计</h3>
|
||||
<pre><code>你的项目/
|
||||
├── 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</code></pre>
|
||||
|
||||
<h3>硬约束:Skill 隔离与依赖注入</h3>
|
||||
<p>每个 skill 运行时只能看到自己包内的文件。跨 skill 共享的文档由 cs-onboard 从技能包<strong>复制</strong>到项目的 codestable/reference/,其他 skill 通过项目相对路径读取。这本质上是一个<strong>依赖注入</strong>模式——skill 是通用逻辑,codestable/ 是注入的运行时上下文。</p>
|
||||
</section>
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">💥 深度裂变</h2>
|
||||
|
||||
<div class="fission-section">
|
||||
<div class="fission-label">颠覆认知</div>
|
||||
<div class="fission-title">"编排软件要素"是真的范式创新,还是旧酒新瓶?</div>
|
||||
|
||||
<p>对 CodeStable 最尖锐的批判性审视。</p>
|
||||
|
||||
<h4>正方:确实在范式层面做了翻转</h4>
|
||||
<p>所有主流 AI 编码框架都在"Agent 编排"范式下工作。CodeStable 问的是另一个问题:<strong>软件的需求、约束、决策怎么被记下来、被检索、被复用?</strong></p>
|
||||
<p>实践后果:知识沉淀从"副作用"变成"一等公民"。SuperPowers 跑完 TDD → 得到代码和测试。CodeStable 跑完 feature → 得到代码 + design + acceptance + compound。后者在"三个月后还能被理解"上有结构性优势。</p>
|
||||
|
||||
<h4>反方:四个没有解决的问题</h4>
|
||||
<ol>
|
||||
<li><strong>知识检索依赖 AI 上下文窗口</strong>:compound/ 积累 200 个文件后,AI 能一次读完吗?没有索引或向量检索。</li>
|
||||
<li><strong>没有强制执行机制</strong>:SuperPowers 的 TDD 是铁律,CodeStable 的 accept 执行深度取决于人。人把关不严,质量门形同虚设。</li>
|
||||
<li><strong>cs-brainstorm 的分诊能力受限</strong>:让 AI 判断模糊想法"该走哪个流程",这个判断本身就需要很高的理解力。</li>
|
||||
<li><strong>对竞品的批评不完全公平</strong>:OpenSpec 的 Spec 文件设计目标就是人机双读。很多用户的实际体验并非"人类没法读"。</li>
|
||||
</ol>
|
||||
|
||||
<div class="search-internal">🔍 搜索内化:V2EX 和 LINUX DO 社区反馈——"正确性对我来说够了,按照流程生成完手动审查,不复杂的需求基本一次性搞定"——但也指出"上下文一长就会忘"的知识检索问题。作者在 Roadmap 中坦承多个模块仍在 beta。</div>
|
||||
|
||||
<h4>一个被忽略的关键信号:CodeStable 承认自己会"过时"</h4>
|
||||
<blockquote>"CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出,那么这个模块就可以删除。"</blockquote>
|
||||
<p>这让它区别于绝大多数 AI 框架——不是试图建立永恒的体系,而是承认自己是<strong>过渡性工具</strong>。这种"自我消解的诚实"在 AI 工具领域极为罕见。</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">🎯 实战指南</h2>
|
||||
|
||||
<h3>快速开始</h3>
|
||||
<pre><code># 安装
|
||||
npx skills add https://github.com/liuzhengdongfortest/CodeStable
|
||||
|
||||
# 初始化项目
|
||||
/cs-onboard
|
||||
|
||||
# 日常使用——不知道用哪个就喊根入口
|
||||
/cs</code></pre>
|
||||
|
||||
<h3>典型工作流</h3>
|
||||
<pre><code># 场景 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 # 技术决策</code></pre>
|
||||
|
||||
<h3>避坑指南</h3>
|
||||
<div class="table-wrap">
|
||||
<table class="anti-pattern">
|
||||
<tr><th>🔴 反模式</th><th>✅ 正确做法</th></tr>
|
||||
<tr><td>跳过 cs-onboard,手动创建 codestable/</td><td>必须用 cs-onboard 初始化,确保 reference/ 被正确复制</td></tr>
|
||||
<tr><td>cs-feat-impl 中不看 design 自己脑补</td><td>design 是唯一输入,偏离 design 必须回退更新 design</td></tr>
|
||||
<tr><td>所有改动都走 cs-feat(太重)</td><td>小改动用 cs-feat-ff,大功能走完整流程</td></tr>
|
||||
<tr><td>compound 文件乱命名</td><td>严格遵循 YYYY-MM-DD-{type}-{slug}.md 格式</td></tr>
|
||||
<tr><td>不写 acceptance 报告</td><td>acceptance 报告是"三个月后能理解"的关键</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>CodeStable 与你现有 dev-flow 的融合点</h3>
|
||||
<div class="table-wrap">
|
||||
<table>
|
||||
<tr><th>dev-flow 阶段</th><th>CodeStable 替代/增强</th></tr>
|
||||
<tr><td>Phase 0 初始 PRD</td><td>cs-req 沉淀为需求文档(更持久)</td></tr>
|
||||
<tr><td>Phase 1.5 结构化 PRD</td><td>cs-feat-design 作为 design 文档</td></tr>
|
||||
<tr><td>Phase 2 grill-with-docs</td><td>cs-brainstorm 作为讨论入口</td></tr>
|
||||
<tr><td>Phase 2.5 zoom-out</td><td>cs-arch 单独维护架构文档</td></tr>
|
||||
<tr><td>Phase 3 执行</td><td>cs-feat-impl + cs-feat-accept</td></tr>
|
||||
<tr><td>Phase 4 收尾</td><td>cs-learn / cs-decide 沉淀知识</td></tr>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h3>ROI 分析</h3>
|
||||
<div class="roi-grid">
|
||||
<div class="roi-card"><div class="roi-label">初始化</div><div class="roi-value">cs-onboard 2 分钟 → 建好所有目录骨架</div></div>
|
||||
<div class="roi-card"><div class="roi-label">Feature 流程</div><div class="roi-value">比 OpenSpec 多 5-10 分钟 → 留下 design + acceptance + compound</div></div>
|
||||
<div class="roi-card"><div class="roi-label">学习成本</div><div class="roi-value">30-45 分钟熟悉 22 技能 → 覆盖完整软件生命周期</div></div>
|
||||
<div class="roi-card"><div class="roi-label">长期收益</div><div class="roi-value">3 个月后 feature 设计可回溯 → 消除隐知识丢失</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="module">
|
||||
<h2 class="module-title">📝 温故知新</h2>
|
||||
|
||||
<h3>FAQ</h3>
|
||||
<div class="faq-box">
|
||||
<details><summary>CodeStable 和 dev-flow 谁更好?</summary><div class="faq-body">不是替代关系。dev-flow 是流程编排元技能,CodeStable 是软件生命周期建模体系。可组合使用:dev-flow 的 grill-with-docs 补充 CodeStable 缺少的术语对齐;CodeStable 的 compound 补充 dev-flow 缺少的结构化知识沉淀。</div></details>
|
||||
<details><summary>CodeStable 适合一个人用吗?</summary><div class="faq-body">非常适合。设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作。如果是一个人维护的长期项目,CodeStable 是目前最合适的框架。</div></details>
|
||||
<details><summary>CodeStable 和 SuperPowers 能一起用吗?</summary><div class="faq-body">理论上可以,但不推荐。哲学对立——SuperPowers 希望人少介入,CodeStable 要求人在环。建议根据项目类型选一个主线。</div></details>
|
||||
<details><summary>codestable/ 目录会变得很臃肿吗?</summary><div class="faq-body">会,这是有意为之。"臃肿"的文档目录好过"干净"的失忆。日期前缀使按时间浏览很自然,compound 通过 type 字段做聚合。</div></details>
|
||||
<details><summary>轻量通道 cs-feat-ff 什么时候用?</summary><div class="faq-body">非常明确的小改动——"把按钮颜色改蓝"、"加一个表单字段"。不确定该不该走 ff,就走完整流程。</div></details>
|
||||
<details><summary>如果不想用全部 22 个技能怎么办?</summary><div class="faq-body">技能是松耦合的。最精简子集:cs-onboard + cs-req + cs-feat + cs-issue。</div></details>
|
||||
<details><summary>知识检索能力有多强?</summary><div class="faq-body">目前是"文件命名约定 + AI 选择性读取",非向量语义检索。compound/ 积累 50+ 文件后需要引导 AI 只读相关的。</div></details>
|
||||
<details><summary>和 mattpocock/skills 的关系?</summary><div class="faq-body">同样 Skills 封装形式,建模哲学不同。mattpocock 是"小工具"——每个解决特定问题。CodeStable 是"体系"——每个是软件生命周期中的一个步骤。</div></details>
|
||||
</div>
|
||||
|
||||
<h3>自测题</h3>
|
||||
<div class="quiz-box">
|
||||
<div class="quiz-item">CodeStable 的 6 个软件实体是哪 6 个?每个的核心用途是什么?</div>
|
||||
<div class="quiz-item">"编排 Agent"和"编排软件要素"的根本区别是什么?在工程实践上会产生什么不同的后果?</div>
|
||||
<div class="quiz-item">CodeStable 的 3 个核心流程分别是什么?每个流程的技能链是什么?</div>
|
||||
<div class="quiz-item">cs-feat-design 为什么被设计为"后续所有步骤的唯一输入"?这种设计避免了什么问题?</div>
|
||||
<div class="quiz-item">compound/ 目录下的 4 种知识类型分别是什么?它们会在什么时机被 AI 重新检索?</div>
|
||||
<div class="quiz-item">CodeStable 为什么要求每个 skill 运行时只能看到自己包内的文件?这个硬约束解决了什么问题?</div>
|
||||
<div class="quiz-item">CodeStable 作者所说的"复利工程"(Compound Engineering)具体指什么?</div>
|
||||
<div class="quiz-item">如果你要将 CodeStable 集成到你现有的 dev-flow 中,哪些 Phase 可以保留、哪些可以用 CodeStable 替换?</div>
|
||||
</div>
|
||||
|
||||
<h3>参考资源</h3>
|
||||
<ul>
|
||||
<li>GitHub:<a href="https://github.com/liuzhengdongfortest/CodeStable">liuzhengdongfortest/CodeStable</a></li>
|
||||
<li>作者的项目 MA:<a href="https://github.com/liuzhengdongfortest/MA">liuzhengdongfortest/MA</a></li>
|
||||
<li>Harness Engineering (Mitchell Hashimoto, 2026.02)</li>
|
||||
<li>V2EX 讨论:<a href="https://global.v2ex.co/t/1208525">厌倦了 OpenSpec、OMO、SuperPowers?试试 CodeStable</a></li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
</div>
|
||||
|
||||
<footer class="article-footer">
|
||||
<div class="wrapper"><p>© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过</p></div>
|
||||
</footer>
|
||||
|
||||
<script>
|
||||
mermaid.initialize({startOnLoad:true,theme:'base',themeVariables:{primaryColor:'#3b82f6',primaryBorderColor:'#1d4ed8',primaryTextColor:'#1e293b',lineColor:'#64748b',secondaryColor:'#f1f5f9',tertiaryColor:'#eff6ff',fontFamily:'-apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans SC",sans-serif',fontSize:'14px'},flowchart:{useMaxWidth:true,htmlLabels:true,curve:'basis'}});
|
||||
window.onload=function(){
|
||||
const input=document.getElementById('search-input');
|
||||
if(!input)return;
|
||||
input.addEventListener('input',(e)=>{
|
||||
const term=e.target.value.toLowerCase().trim();
|
||||
const contentArea=document.getElementById('content-area');
|
||||
const blocks=contentArea.querySelectorAll('p,li,blockquote,.fission-section,.mnemonic-card,details,.mermaid-box,.ascii-box,.story-box,.tldr-box,.table-wrap,pre,.quiz-item,.roi-card,.faq-box details');
|
||||
if(term.length===0){blocks.forEach(el=>el.classList.remove('hidden'));document.querySelectorAll('h1,h2,h3,h4').forEach(el=>el.classList.remove('hidden'));return}
|
||||
blocks.forEach(el=>el.classList.add('hidden'));document.querySelectorAll('h1,h2,h3,h4').forEach(el=>el.classList.add('hidden'));
|
||||
blocks.forEach(el=>{if(el.innerText.toLowerCase().includes(term))el.classList.remove('hidden')})})};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,378 @@
|
||||
---
|
||||
title: "CodeStable 深度解析:编排软件生命周期,而非编排 Agent"
|
||||
author: "叫我小杨同学的小码酱"
|
||||
tags: [CodeStable, AI Engineering, Agent Skills, Harness Engineering, Human-in-the-Loop, OpenSpec, SuperPowers, 工作流]
|
||||
created: 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 区别于所有其他框架的核心设计:
|
||||
|
||||
```mermaid
|
||||
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 如何开始
|
||||
|
||||
```bash
|
||||
# 安装
|
||||
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)
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: CodeStable 和 dev-flow 谁更好?</strong></summary>
|
||||
不是替代关系。dev-flow 是流程编排元技能("按什么步骤走"),CodeStable 是一套完整的软件生命周期建模体系("软件要素怎么组织")。可以组合使用:dev-flow 的 grill-with-docs 补充 CodeStable 缺少的"术语对齐"阶段;CodeStable 的 compound 补充 dev-flow 缺少的"结构化知识沉淀"。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: CodeStable 适合一个人用吗?</strong></summary>
|
||||
非常适合。CodeStable 的设计前提就是"一个人在环"——没有团队角色、没有多 Agent 协作、没有审批流。它帮助单人开发者维持跨时间的一致性。如果是一个人维护的长期项目,CodeStable 是目前最合适的框架。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: CodeStable 和 SuperPowers 能一起用吗?</strong></summary>
|
||||
理论上可以,但不推荐。两者的哲学是对立的——SuperPowers 希望人少介入,CodeStable 要求人在环。同时用会导致认知冲突:"这一步到底是让 AI 自己决定,还是我来把关?"建议根据项目类型选一个主线。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: codestable/ 目录会变得很臃肿吗?</strong></summary>
|
||||
会。这是有意为之。作者认为"臃肿"的文档目录好过"干净"的失忆。每个 feature 都留下完整的 design + acceptance,长期积累确实会很多文件。但日期前缀命名使按时间浏览很自然,且 compound 通过 type 字段做聚合。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 轻量通道 cs-feat-ff 什么时候用?</strong></summary>
|
||||
当你有一个非常明确的小改动——比如"把这个按钮的颜色改成蓝色"、"加一个表单字段"——不需要写 design 文档和完整的 acceptance 报告。但作者的建议是:"如果不确定该不该走 ff,就走完整流程"。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 如果我不想用全部 22 个技能怎么办?</strong></summary>
|
||||
CodeStable 的技能是松耦合的。你可以只用 cs-req + cs-feat-* 做特性开发,跳过 cs-roadmap 和 cs-refactor。最精简的子集:cs-onboard + cs-req + cs-feat + cs-issue。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: CodeStable 的 knowledge 检索能力有多强?</strong></summary>
|
||||
目前是"文件命名约定 + AI 选择性读取"模式,而非向量语义检索。当 compound/ 积累到 50+ 个文件后,AI 可能无法一次读完所有文件,需要在 prompt 中引导 AI 只读相关的。作者在 Roadmap 中表示关注这个问题。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Q: 和 mattpocock/skills 的关系?</strong></summary>
|
||||
同样是 Agent Skills 的封装形式,但建模哲学完全不同。mattpocock 的技能是"小工具"——每个技能解决一个特定问题(grill、diagnose、tdd)。CodeStable 的技能是"体系"——每个技能是软件生命周期中的一个步骤。前者灵活可组合,后者完整有体系。
|
||||
</details>
|
||||
|
||||
### 自测题
|
||||
|
||||
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 替换?
|
||||
|
||||
### 参考资源
|
||||
|
||||
- GitHub 仓库:https://github.com/liuzhengdongfortest/CodeStable
|
||||
- 作者的项目 MA:https://github.com/liuzhengdongfortest/MA
|
||||
- Harness Engineering 概念起源(Mitchell Hashimoto, 2026.02)
|
||||
- V2EX 讨论帖:https://global.v2ex.co/t/1208525
|
||||
|
||||
---
|
||||
|
||||
*© 2026 叫我小杨同学的小码酱 | 知识吸收器 v3.0 | 真理锚定已通过*
|
||||
Reference in New Issue
Block a user