[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-870":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":8,"pushedAt":8,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},870,"CodeStable","liuzhengdongfortest\u002FCodeStable","liuzhengdongfortest",null,"Python",909,65,4,10,0,9,35,200,27,9.46,false,"main",[],"2026-06-12 02:00:19","\u003Cdiv align=\"center\">\n\n# CodeStable\n\n![](.\u002Fasset\u002FPromotionalImage.png)\n\n[English](.\u002FREADME.en.md) · **中文**\n\n**面向严肃工程的 AI 编码工作流**\n\n厌倦了 OpenSpec 的草台、Oh-My-OpenAgent 的过度设计、Superpowers 的散装——我从 0 写了一套简单轻巧、围绕**人在环**的 AI Harness。\n\n\u003Cp>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-beta-F59E0B?style=flat-square\" alt=\"Status\"\u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fskills-22-6366F1?style=flat-square\" alt=\"Skills\"\u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-10B981?style=flat-square\" alt=\"License\"\u002F>\n\u003C\u002Fp>\n\n\u003C\u002Fdiv>\n\n---\n\n## 安装\n\n```bash\nnpx skills add https:\u002F\u002Fgithub.com\u002Fliuzhengdongfortest\u002FCodeStable\n```\n\n只需要一键，开始工作：\n\n```bash\n\u002Fcs-onboard\n```\n\n之后日常使用时，不知道该用哪个技能就喊根入口：\n\n```bash\n\u002Fcs\n```\n\n`cs` 会读你的诉求，告诉你这次该走哪个 `cs-xxx`。\n\n---\n\n## 缘起\n\n我在开发一套新的 Harness Agent（[MA](https:\u002F\u002Fgithub.com\u002Fliuzhengdongfortest\u002FMA)），一开始当然是 VibeCoding——我只写设计和需求，代码由 AI 来改。这样支撑了大部分特性的开发。直到有一天 Codex 反复解决不了一个我认为比较简单的问题，并且反复在同一个地方犯错。我就知道项目需要一套工作流来维持它继续进行了。\n\n我调研了 OpenSpec、SuperPowers、Oh-My-OpenAgent 这一类工具，没一个用着顺手：\n\n- **OpenSpec** 太简单，没有复利工程，生成的 Spec 抽象到人类没法读\n- **SuperPowers** 没有流程约束，不知道该用哪个\n- **Oh-My-OpenAgent** 太重，且哲学上认为\"人介入 = 失败\"\n\nCodeStable 的目标是**解决严肃工程的软件实现和编码问题**，不是造一个新名词、追求热点。\n\n---\n\n## 与其他框架的核心区别：编排的目标是谁\n\n我看了一圈现在主流的 AI 编码框架——Superpowers、CCW、Oh-My-OpenAgent 等等——它们其实都在做**同一件事**：\n\n> **如何把 Agent 编排得更好。** 让它们组队、协作、头脑风暴、跑流水线、自动接力。围绕的实体始终是 **Agent**。\n\nCodeStable 走的是**另一个方向**：\n\n> **编排的不是 Agent，而是软件本身的生命周期。** 围绕的实体是**构成软件的要素**——每一个需求、每一个架构决定、每一个特性、每一个 bug、每一条历史里留下来的约束。\n\n\u003Ctable>\n\u003Ctr>\u003Cth>\u003C\u002Fth>\u003Cth>Agent 编排派\u003C\u002Fth>\u003Cth>CodeStable\u003C\u002Fth>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>核心实体\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>Agent \u002F Role \u002F Team\u003C\u002Ftd>\u003Ctd>Requirement \u002F Architecture \u002F Feature \u002F Issue \u002F Decision\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>主线问题\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>Agent 之间怎么分工、传递、协调？\u003C\u002Ftd>\u003Ctd>软件的需求、约束、决策怎么被记下来、被检索、被复用？\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>状态存在哪\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>Agent 的 session \u002F 消息总线 \u002F 队列\u003C\u002Ftd>\u003Ctd>项目里的 \u003Ccode>codestable\u002F\u003C\u002Fcode> 文件树（人和 AI 都能读）\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>解决的痛点\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>单 Agent 能力不够，需要协同放大\u003C\u002Ftd>\u003Ctd>软件复杂度膨胀撑破上下文、隐知识丢失、需求漂移\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>对人的定位\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>人少介入越好，理想是全自动\u003C\u002Ftd>\u003Ctd>人在环 —— 程序员对整体把控负责，AI 是高效的执行体\u003C\u002Ftd>\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n![](.\u002Fasset\u002FCodeStableVSAgent.png)\n\n\n**这两个方向没有谁对谁错。**\n\n如果你的任务是\"用 AI 跑一个端到端的自动化产线\"、\"让多个 Agent 互相讨论方案\"，Agent 编排派会更顺手。\n\n如果你的任务是\"维护一个会跨年迭代的严肃软件\"、\"让今天写下的需求和决策三个月后还能被准确召回\"——那 CodeStable 这套以软件要素为中心的建模会更合适。\n\n我做 CodeStable 是因为我相信：**软件工程的混乱本质上不是 Agent 不够强，而是要素没被组织好**。Agent 再强，也写不了一个把需求、架构、历史决策全丢失的项目。\n\n---\n\n## 设计：6 个实体 + 3 个流程\n\nCodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 **6 个实体** 和 **3 个流程**。\n\n### 6 个实体\n\n| 实体 | 英文 | 干什么 |\n|------|------|--------|\n| **需求** | requirements | 原始用户故事、当时的讨论与权衡。最终的逃生通道——代码烂成一坨屎时，可以摒弃所有代码、让 AI 重新生成 |\n| **架构** | architecture | 为实现需求，系统的编排层长什么样。文档要尽可能精简、统一，**给人读的**，不是给 AI 自嗨的 |\n| **路线图** | roadmap | \"我想要一个权限校验系统\"——直接塞 feature AI 接不住，先拆成路线图分步推进 |\n| **特性** | feature | 实际落地的工程执行过程，人与 AI 共同协作，对 design \u002F 实现 \u002F 验收负责 |\n| **问题** | issue | 开发完成后的 BUG 单子，AI 和人一同解决 |\n| **知识** | compound | 复利工程的知识库，沉淀踩过的坑、好做法、技术决策 |\n\n### 3 个流程\n\n| 流程 | 关键技能链 | 说明 |\n|------|------------|------|\n| **特性引入** | `cs-feat` → `cs-feat-design` → `cs-feat-impl` → `cs-feat-accept` | 想清楚 → 综合架构设计 → 逐步编码 → 验收测试。各位程序员怎么顺手怎么来 |\n| **问题修改** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | 跟 AI 说哪里有问题 → 让 AI 分析根因 → 让 AI 定点修复 |\n| **代码重构** | `cs-refactor` (beta) | 软件架构腐化不是一蹴而就的。AI 辅助重构，但**终归是人在重构**——还在迭代中，欢迎赐教 |\n\n\n---\n\n## 技能总览\n\n\u003Ctable>\n\u003Ctr>\u003Cth>分组\u003C\u002Fth>\u003Cth>技能\u003C\u002Fth>\u003Cth>用途\u003C\u002Fth>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>根入口\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>统一入口——介绍体系全貌 + 把开放式诉求路由到正确的 cs-* 子技能。不知道用哪个时就喊它\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"1\">\u003Cb>接入\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-onboard\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>把 CodeStable 接入到一个新仓库 \u002F 已有零散文档的仓库\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"2\">\u003Cb>需求 & 架构\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-req\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>整理 \u002F 沉淀原始需求文档\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-arch\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>起草或更新 \u003Ccode>codestable\u002Farchitecture\u002F\u003C\u002Fcode> 下的架构文档\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>路线图\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-roadmap\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>承载一块大需求的事前规划：概设（模块拆分）+ 架构层详设（接口契约 \u002F 共享协议）+ 子 feature 拆解清单\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cb>讨论入口\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-brainstorm\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>想法模糊时的统一讨论入口，做分诊：直接 design \u002F 进 feature 写 brainstorm.md \u002F 移交 roadmap\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"5\">\u003Cb>特性流程\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-feat\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>新特性子流程入口\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-feat-design\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>起草 \u003Ccode>{slug}-design.md\u003C\u002Fcode> 作为后续唯一输入\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-feat-impl\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>按 design 的推进顺序写代码\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-feat-accept\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>逐层对照 design 核对实现，做完整验收闭环\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-feat-ff\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>超轻量通道：不写 design、不分阶段，让 AI 直接做\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"4\">\u003Cb>问题流程\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-issue\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>问题修复子流程入口\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-issue-report\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>把脑子里的问题落成可复现、可追溯的 report\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-issue-analyze\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>找根因、评估修复风险、给方案\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-issue-fix\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>定点修复 + 验证 + 写 fix-note\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"2\">\u003Cb>重构流程\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-refactor\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>(beta) 重构主流程\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-refactor-ff\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>(beta) 轻量重构通道\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"3\">\u003Cb>知识沉淀\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-learn\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>把踩过的坑 \u002F 好做法沉淀成 learning 文档\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-trick\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>把可复用的编程模式 \u002F 库用法整理成处方性参考\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-decide\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>把已拍板的技术选型、架构决定、长期约束记成永久文档\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd rowspan=\"2\">\u003Cb>探索 & 文档\u003C\u002Fb>\u003C\u002Ftd>\u003Ctd>\u003Ccode>cs-explore\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>定向代码探索，把\"提问 → 读代码 → 得结论\"沉淀成证据\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Ccode>cs-guide\u003C\u002Fcode> \u002F \u003Ccode>cs-libdoc\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>对外的开发者指南 \u002F 库参考文档\u003C\u002Ftd>\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n## 工作流示意\n\nCodeStable 的技能不是一条线性流水，而是**分层 + 事件驱动**的：\n\n```\n═══════════════════════════════════════════════════════════════════════\n 根入口 · 路由                              （任何时刻都可以调用）\n───────────────────────────────────────────────────────────────────────\n   cs ──▶ 介绍体系 \u002F 把开放式诉求路由到下面任一具体子技能\n          （本身不做事，只做分诊和提示）\n═══════════════════════════════════════════════════════════════════════\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n        （未接入）        （已接入）      （想了解体系）\n         走阶段 0       直达 1~4 层 \u002F 横切    给速读\n              │\n              ▼\n═══════════════════════════════════════════════════════════════════════\n 阶段 0 · 接入                                  （只在新项目跑一次）\n───────────────────────────────────────────────────────────────────────\n   cs-onboard ──▶ 生成 codestable\u002F 骨架 + 释放 reference\u002F、tools\u002F\n═══════════════════════════════════════════════════════════════════════\n                              │\n                              ▼\n═══════════════════════════════════════════════════════════════════════\n 第 1 层 · 长效档案（\"系统现在长什么样\"，只记现状）\n───────────────────────────────────────────────────────────────────────\n   cs-req   ──▶ codestable\u002Frequirements\u002F{slug}.md\n   cs-arch  ──▶ codestable\u002Farchitecture\u002FARCHITECTURE.md\n                                       └─ {type}-{slug}.md（子系统）\n═══════════════════════════════════════════════════════════════════════\n                              │\n                              ▼\n═══════════════════════════════════════════════════════════════════════\n 第 2 层 · 规划（\"接下来打算怎么做这块大需求\"，大需求才需要）\n───────────────────────────────────────────────────────────────────────\n   cs-roadmap ──▶ codestable\u002Froadmap\u002F{slug}\u002F\n                  把一个\"我想要 X 系统\"做成完整的事前规划：\n                    ① 概设          —— 拆成哪几个模块 \u002F 组件\n                    ② 架构层详设    —— 模块间接口契约 \u002F 共享协议\n                    ③ 子 feature    —— 把方案分解成多条可执行的 feature\n                  ② 是 feature-design 的硬约束输入\n                  （小需求可跳过本层，直接进第 3 层）\n═══════════════════════════════════════════════════════════════════════\n                              │\n                              ▼\n═══════════════════════════════════════════════════════════════════════\n 讨论入口（可选 · 想法模糊时进入，做分诊后路由到下游）\n───────────────────────────────────────────────────────────────────────\n                          ┌── case 1 已经够清楚 ──▶ cs-feat-design\n   cs-brainstorm ────────▶┼── case 2 小需求方向定 ─▶ feature 流（落 brainstorm.md）\n                          └── case 3 大需求只有一个词 ─▶ cs-roadmap\n═══════════════════════════════════════════════════════════════════════\n                              │\n                              ▼\n═══════════════════════════════════════════════════════════════════════\n 第 3 层 · 执行流程（按事件类型选一条进入）\n───────────────────────────────────────────────────────────────────────\n\n  ▸ 事件：新增能力                                          ┌──────────┐\n       cs-feat-design ──▶ cs-feat-impl ──▶ cs-feat-accept  │ features │\n       cs-feat-ff     ──(轻量直通车，跳过 design\u002Faccept)─▶  │ \u002FYYYY-…\u002F │\n                                                            └──────────┘\n\n  ▸ 事件：修复缺陷                                          ┌──────────┐\n       cs-issue-report ──▶ cs-issue-analyze ──▶ cs-issue-fix│  issues  │\n                                                            │ \u002FYYYY-…\u002F │\n                                                            └──────────┘\n\n  ▸ 事件：代码腐化（beta）                                   ┌──────────┐\n       cs-refactor \u002F cs-refactor-ff                         │refactors │\n                                                            │ \u002FYYYY-…\u002F │\n                                                            └──────────┘\n═══════════════════════════════════════════════════════════════════════\n                              │\n                ▼ 任意阶段觉得\"这个值得记下来\"都能触发 ▼\n═══════════════════════════════════════════════════════════════════════\n 横切层 · 知识沉淀（复利工程）\n───────────────────────────────────────────────────────────────────────\n   cs-learn   ──▶ ┐\n   cs-trick   ──▶ ├─▶ codestable\u002Fcompound\u002FYYYY-MM-DD-{doc_type}-{slug}.md\n   cs-decide  ──▶ │     doc_type ∈ { learning, trick, decision, explore }\n   cs-explore ──▶ ┘\n                   ↑\n          下一次 cs-arch \u002F cs-feat-design \u002F cs-issue-analyze\n          会回头读 compound\u002F，让经验在新工作里被复用\n═══════════════════════════════════════════════════════════════════════\n```\n\n**怎么读这张图：**\n\n- **纵向是层次**，不是严格的时间顺序——长效档案层会反复被刷新，规划层只在大需求时进入\n- **第 3 层是事件入口**：来了新需求走 feature 流，发现 bug 走 issue 流，发现腐化走 refactor 流\n- **横切层是飞轮**：任何流程跑完发现\"这事值得记下来\"都可以触发沉淀，沉淀的产物又会被下一次同类工作读到——这是 CodeStable \"复利\"的物理实现\n\n---\n\n## 运行时结构\n\n`\u002Fcs-onboard` 跑完后，会在你的项目根下生成一个 `codestable\u002F` 目录——这是 CodeStable 所有产物的聚合根，也是各个子技能在运行时**唯一**会读写的工作区。\n\n```\n你的项目\u002F\n├── codestable\u002F\n│   ├── requirements\u002F                     # 需求实体（\"为什么要有这个能力\"）\n│   │   └── {slug}.md                     # 一个能力一份，扁平不分组\n│   │\n│   ├── architecture\u002F                     # 架构实体（\"用什么结构实现\"）\n│   │   ├── ARCHITECTURE.md               # 架构总入口 \u002F 索引\n│   │   └── {type}-{slug}.md              # 子系统架构 doc（同类 ≥6 份自动收进子目录）\n│   │\n│   ├── roadmap\u002F                          # 路线图（\"接下来打算怎么走\"）\n│   │   └── {slug}\u002F\n│   │       ├── {slug}-roadmap.md         # 主文档：背景 \u002F 拆解 \u002F 排期\n│   │       ├── {slug}-items.yaml         # 机器可读子 feature 清单，acceptance 回写状态\n│   │       └── drafts\u002F                   # 可选：草稿 \u002F 调研\n│   │\n│   ├── features\u002F                         # 特性流程聚合根\n│   │   └── YYYY-MM-DD-{slug}\u002F            # 一个 feature 一个目录\n│   │       ├── {slug}-brainstorm.md      # 可选（cs-brainstorm 产出）\n│   │       ├── {slug}-design.md          # 方案（cs-feat-design）\n│   │       ├── {slug}-checklist.yaml     # 推进清单（impl 跑、accept 回写）\n│   │       └── {slug}-acceptance.md      # 验收报告（cs-feat-accept）\n│   │\n│   ├── issues\u002F                           # 问题流程聚合根\n│   │   └── YYYY-MM-DD-{slug}\u002F\n│   │       ├── {slug}-report.md          # 问题报告\n│   │       ├── {slug}-analysis.md        # 根因分析（不显然时才有）\n│   │       └── {slug}-fix-note.md        # 修复记录\n│   │\n│   ├── refactors\u002F                        # 重构流程聚合根（beta）\n│   │   └── YYYY-MM-DD-{slug}\u002F\n│   │       ├── {slug}-scan.md\n│   │       ├── {slug}-refactor-design.md\n│   │       ├── {slug}-checklist.yaml\n│   │       └── {slug}-apply-notes.md\n│   │\n│   ├── compound\u002F                         # 知识沉淀（复利工程）统一目录\n│   │   └── YYYY-MM-DD-{doc_type}-{slug}.md\n│   │       # doc_type ∈ {learning, trick, decision, explore}\n│   │\n│   ├── tools\u002F                            # 跨工作流共享脚本（onboard 释放）\n│   └── reference\u002F                        # 共享参考文档（onboard 释放）\n│       ├── shared-conventions.md         # 跨技能口径 \u002F 路径命名 \u002F 元数据规范\n│       ├── system-overview.md            # CodeStable 体系总览 + 场景路由\n│       └── ...\n│\n└── AGENTS.md                             # 在项目根，不在 codestable\u002F 里\n```\n\n**几条要点：**\n\n- 所有产物都聚在 `codestable\u002F` 下，让\"上次那个 feature \u002F bug 当时怎么搞的\"三秒能找到\n- `requirements\u002F` 和 `architecture\u002F` 是**长效档案**（只记现状），`roadmap\u002F` 是**规划层**（接下来怎么走），两者刻意分开\n- `features\u002F` `issues\u002F` `refactors\u002F` 用 `YYYY-MM-DD-{slug}\u002F` 一个目录装齐所有相关 spec，不交叉\n- `compound\u002F` 是**唯一**的知识沉淀目录，learning \u002F trick \u002F decision \u002F explore 通过 `doc_type` 字段区分而不是分目录——好搜\n- `reference\u002F` 是 `cs-onboard` 从技能包复制过来的；要改共享口径，改 `cs-onboard\u002Freference\u002F` 模板，新项目 onboard 自动带上新版\n\n### 硬约束\n\n> Skill 是独立安装单元，运行时**每个 skill 只能看到自己包内的文件**。A 技能的 SKILL.md 里写 `B-skill\u002Freference\u002Fxxx.md` 这种引用在运行时**根本读不到**。\n>\n> 跨 skill 共享的参考文档必须走\"工作项目\"这一层：由 `cs-onboard` 从技能包复制到项目的 `codestable\u002Freference\u002F`，其他 skill 用项目相对路径读取。\n\n要改共享口径，改 `cs-onboard\u002Freference\u002F` 下的模板，新项目 onboard 时带上新版本。\n\n---\n\n## 设计哲学\n\nCodeStable 与 OMO 做的是**完全相反**的哲学。\n\n- OMO 认为：人只要干预就是失败的信号\n- CodeStable 认为：**程序员是软件编码中的在环对象**——可以对黑盒实现不了解，但对整体实现必须有所把控，必要时也可深入\n\n软件架构必须要 **可演进**、**可观测**、**可控制**。\n\n也许这一点在 AI 发展强大以后会变得不再重要，但**当下这样做能让程序员在现状下舒服**——这就是价值所在。\n\nCodeStable 面向真实开发场景，对此进行建模，期望通过一个闭环系统处理开发中常见的问题。**现有大部分框架围绕 AI 建模，而不是围绕人。** 我认为这些框架的作者驱动 AI 的能力很强，但绝对不是严肃软件的开发者——因为缺少对软件开发中需求和设计的基础组织能力，缺乏对代码实现的尊重。\n\n---\n\n## Roadmap\n\nCodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。\n\n- [ ] 代码重构流程需要强化（`cs-refactor` 还在 beta）\n- [ ] ……\n\n欢迎在 Issue 区贴你的真实开发困境和重构经验。\n\n---\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=liuzhengdongfortest\u002FCodeStable&type=date&legend=top-left)](https:\u002F\u002Fwww.star-history.com\u002F?repos=liuzhengdongfortest%2FCodeStable&type=date&legend=top-left)\n\n\u003Cdiv align=\"center\">\n\nMIT License · 作者 [@liuzhengdong](https:\u002F\u002Fgithub.com\u002Fliuzhengdongfortest)\n\n\u003C\u002Fdiv>\n","CodeStable 是一个面向严肃工程的 AI 编码工作流工具，旨在通过围绕人在环的方式简化和优化软件开发流程。其核心功能包括需求管理、架构设计、特性实现与问题追踪等，通过将这些软件要素组织起来，确保项目长期迭代过程中知识和决策的有效保存与复用。技术上，CodeStable 采用 Python 开发，强调轻量级和易用性，避免了其他同类工具可能存在的过度设计或复杂度高的问题。特别适合需要跨年度持续维护和发展、对历史决策和当前需求有严格记录要求的软件工程项目使用。",2,"2026-06-11 02:39:54","CREATED_QUERY"]