cs

CodeStable

CodeStable 是一套理解和推进软件演化的方法。它用 Vision、Project Spec、Epic、Issue 和 codestable/ 中的制度记忆连接目标、现实与行动；它不是强制流水线，也不是 Agent 编排器。

调用 cs 不等于跑完整流程。先判断用户此刻要讨论、理解、设计、实现还是收尾，再采用匹配的管理强度。

沟通方式：先结论，再展开

先用用户正在使用的词，简短说明结论和原因。只有需要做取舍、取得授权，或必须展示验证与风险证据时，才展开框架、规则和细节。简短不等于省略关键判断，而是先让用户容易理解，再按需下钻。

节省上下文（Codex）

同一会话中，已经完整读取且没有变化的 SKILL.md、reference、template 或相邻说明，必须复用既有理解，不要重复读取。仅在用户要求重读、文件已变化，或当前理解不足以支撑判断时，读取相关最小范围。

---

1. 先定姿态

从用户原话与上下文中选择一个主姿态。选定后立即读取“必读”，再开始行动；未命中的姿态文件不要预读。

主姿态	用户常这样说	必读	按需读	默认边界
接入	初始化 cs、接入 CodeStable、补齐 codestable/	onboard	—	必须明确授权；不编造业务内容
讨论	聊聊、先理清、想清楚再做、帮我规划一下	talk	docs；具体变化 → quality；UI → ui-spec	用户确认前不落盘，不建 issue、epic 或 vision
愿景	应用将来什么样、整理 vision、产品全景	vision	docs；质量方向 → quality；UI → ui-spec	确认后才写 vision；不强迫创建开发事项
规格	维护 spec、当前真相、epic 活规格	spec	docs；质量约束 → quality；UI → ui-spec	只写仍然成立的结论
理解现状	怎么工作的、这条链路、影响范围	explore	docs；服务具体变化 → quality	先解释现状；复杂且值得复用时才建 Explore Issue
修 bug	坏了、不符合预期、debug、修这个 bug	complain	debug、economy、quality；结构 → code-design	简单问题默认快改并留下 ff；复杂问题可受管理推进
设计	怎么实现、先设计、实现方案	design	code-design、economy、quality；UI → ui-spec	不写代码；高风险先安排穿刺顺序
快交付	快速、快改、小改一下、直接开干、别走流程	fast	economy；必要时 quality；UI → ui-spec	默认轻检索、验证并留下 ff；用户明确不要痕迹时才可省略 ff
受管理实现	做这个 issue、推进 epic、实现（有档）、穿刺/先打通	do	code-design、economy、quality；现状不清 → explore；UI → ui-spec	完成不等于关闭；风险先穿刺，再加厚
收尾	关闭、收尾、做完并沉淀、毕业回写	close	docs、quality；有界简化 → economy	关闭需要用户授权；不自动移入 done/
审代码	review、评审、看看这 diff/PR	code-design（文末 Review）	economy；相关时 → quality	用户点名才做；默认只审不改
记知识	记一下坑、写 note	note	docs	同主题更新原 note，不重复新建
学流程	我带你跑一遍、教 AI 做某流程	maketools	docs	危险操作前再次确认

怎样判断姿态

1. 用户的原话与授权，优先于“看起来应该走重流程”。
2. 事情小、目标清楚、用户要快且没有要求建档 → 快交付。
3. 目标模糊或取舍未定 → 讨论；聊清后再切换到快交付、受管理实现、愿景等姿态。
4. 已有常规 Issue，或用户点名 Issue / Epic → 受管理实现，必要时先设计。
5. 已有行为坏了 → 修 bug；新增能力 → 快交付或受管理实现，不归入 Complain。
6. 用户只问系统怎样工作 → 理解现状，不要默认开始修改。
7. 意图不清，而且选错会实质改变后续，例如是否建 Issue、是否改代码 → 给一句话推荐和理由，请用户选择；不要默认采用重流程。
8. 写或修改 Agent 技能本身，不属于 CodeStable 的职责。

选择管理强度

情况	默认选择
小、低风险、一次可完成，或用户明确要快	快改；完成后留下 ff，见 fast
用户明确不要痕迹或不要写 Issue	可以不留 ff；若现有真相失效，仍须同步 spec 或标记漂移
涉及范围取舍、多轮推进、交接、显著风险或长期质量承诺	建立常规 Issue：type: feature|bug|chore|refactor
跨模块、多批次，且规格会在边界内持续演化	建立 Epic；边界足够清楚的切片可直接在 Epic 内推进
技术、集成或迁移风险需要先证明可行	先做穿刺，见 do，再加厚实现
用户明确要求管理或明确不要建档	服从用户选择

---

2. 世界模型与工作区

从目标到现实

Vision Spec（目标世界）
        │ 摘取一段有界变化
        ▼
Epic Spec（变化中的活规格） ──推进──> Epic Issues
        │ Epic 关闭后毕业
        ▼
Project Spec（当前现实）

独立 Issue ─────────关闭毕业────────> Project Spec

Vision 保存目标世界；Epic 承载一段有边界的大变化；Issue 是可关闭的行动；Project Spec 只保存当前仍成立的现实。

只靠 Issue 会丢失方向；只靠 Project Spec 无法安放互斥构想；把未来与现实混写会失去时间边界；巨型 Issue 又难以关闭。因此，只把值得跨会话保留的信息写入 codestable/，并放到承担相应职责的位置。

codestable/ 工作区地图

CodeStable 的制度记忆统一存放在项目的 codestable/ 下。

codestable/
├── vision/                         目标世界、旅程与候选方向
│   ├── index.md                    Vision 地图
│   └── ...                         按旅程或能力展开
├── spec/                           当前稳定真相
│   ├── index.md                    Project Spec 地图
│   └── ...                         按场景或能力展开
├── epics/                          有界的大变化；本树独立编号
│   ├── EEE-o|x-{Epic名}/
│   │   ├── spec.md                 该 Epic 唯一权威的活规格
│   │   └── issues/                 只属于该 Epic 的 issues 树
│   └── done/                       用户主动整理后的已关闭 Epic
├── issues/                         不属于单个 Epic 的独立 issues 树
├── notes/                          可复用知识；本树独立编号
│   └── NNN-{主题}.md
├── talks/                          尚未落定的讨论；本树独立编号
│   └── NNN-{议题}.md
└── tools/                          稳定、可重复执行的流程工具
    └── ...                         说明、脚本及其所需资源

根 issues/ 与每个 Epic 内的 issues/ 使用同一种结构，但各自独立编号：

issues/
├── NNN-o|x-{事项}.md               常规 Issue
├── NNN-o|x-ff-{事项}.md            快改记录
├── NNN-o|x-{探索名}/               Explore Issue
│   ├── index.md                    认知地图、边界、结论与毕业位置
│   └── *.md                        按「触发→结果」组织的路径文章
└── done/                           可选整理区；仍参与检索和编号

图中的 o|x 表示取 o（open）或 x（closed），不是路径中的字面字符。路径表达唯一归属：只属于一个 Epic 的事项进入该 Epic 的 issues/，其余留在根 issues/。常规 Issue 与 ff 是单文件；只有需要独立调查工作区的 Explore Issue 使用目录。Epic 的 issues/ 在首个所属事项创建时再建立。

done/ 只是用户主动整理后的存放位置，不是新的生命周期状态。关闭不会自动移动事项；done/ 中的内容仍参与检索和编号。

这张图是定位地图，不是每次工作的必读清单。按当前姿态和关键词命中逐层下钻，只读取足以支撑判断的局部。

各实体回答什么

实体	回答的问题
Vision	应用最终要成为什么样；有哪些旅程、能力以及候选或互斥方向
Project Spec	项目现在有哪些仍然成立的稳定事实；按场景和能力组织，不按代码目录组织
Epic	这段有界大变化已经确定什么、仍在变化什么、接下来可以推进什么
Issue	要完成并关闭哪一个具体行动；物理位置表达唯一归属
Fast Fix (ff)	这个小改做了什么、改了哪里、怎样验证、是否影响制度记忆
Explore Issue	一个复杂、可停止、可复用的现状调查得出了什么；简单理解只做现状说明，不建事项
Talk	一个尚未落定的议题如何被提出、纠正和收束，以及建议从哪里继续
Note	哪些知识、证据、步骤与坑点在未来仍值得复用
Tool	哪段已跑通的流程已经稳定到可以重复执行，同时仍需守住哪些危险边界

路径、命名与编号

每棵编号树分别编号：根 issues/、每个 Epic 的 issues/、epics/、notes/、talks/ 都从本树（包含 done/）已有最大开头数字加 1。编号至少三位；超过 999 后继续使用 1000、1001，不设上限。

Issue 编号不是全局身份。引用 Epic Issue 时，必须给完整路径，或写成 Epic NNN / Issue NNN。

形态	路径
独立 Issue	codestable/issues/{NNN}-o|x-{名}.md
Epic Issue	codestable/epics/{EEE}-o|x-{epic}/issues/{NNN}-o|x-{名}.md
快改	所属 issues 树下 {NNN}-o|x-ff-{名}.md；type: ff；模板 ff-issue.md
Explore Issue	所属 issues 树下 {NNN}-o|x-{名}/index.md
Epic	codestable/epics/{NNN}-o|x-{名}/spec.md；每个 Epic 只有一份权威 spec
已整理事项	对应 issues 树的 done/ 下保留同名文件或目录
已整理 Epic	codestable/epics/done/ 下保留同名目录
Talk / Note	{NNN}-{名}.md，不使用 o、x 或 ff

归属由路径决定：

• 只属于一个 Epic 的 Issue，必须进入该 Epic 的 issues/。
• 不属于任何 Epic 的 Issue，留在根 issues/。
• 跨多个 Epic 的事项，不得随意挂到其中一个；应保留为独立 Issue，或升级为 Epic。
• ff、bug、feature、chore、refactor 与 Explore Issue 都遵守同一归属规则。
• 新建 Issue 不再用 epic frontmatter 表达归属。归属改变时移动原事项并更新明确引用，不复制第二份。

旧版中位于根 issues/、依靠 epic frontmatter 关联的已关闭 Issue 仍然有效，不自动迁移。仍在推进的旧 Issue，在下次实质更新时移入所属 Epic：优先保留原编号；若编号冲突，则使用该 Epic issues 树的下一编号，并更新明确引用。

关闭 Issue 时，将目标路径中的 -o- 改为 -x-，序号与名称不变，并把 status 改为 closed。关闭 Epic 时只改 Epic 目录名，内部 Issue 随目录保留。

常规 Issue 使用 templates/entities/issue.md，type 只能是 feature|bug|chore|refactor。ff 只回答四件事：做了什么、改了哪些、怎样验证、对 codestable/ 有什么影响；不要写成迷你 Design，也不要保留空槽位。

Talk 写入 codestable/talks/；Note 写入 codestable/notes/，同主题更新原文件；Tool 写入 codestable/tools/。启动时必须自动注入的短规则，只写入 AGENTS.md 或 CLAUDE.md，不要在两处重复，也不要创建 facts.md。

什么内容可以写到哪一层

写入位置	时机
Vision 目标内容	用户确认愿景后；实现结论若要改变目标，必须再次确认
Vision 实现程度与链接	Epic 关闭时，按已经发生的事实更新
Project Spec	独立 Issue / Explore Issue 关闭毕业；Epic 关闭合并；快改使现有真相失效；或处于规格维护姿态
Epic Spec	处于规格维护姿态；或 Epic 下的 Issue 关闭回写
Issue / Explore Issue / ff	受管理推进时按归属写入对应 issues 树；快改完成后写入并关闭 ff

出现冲突时，按 用户最新确认 > 证据与代码 > 疑似过期的 spec 判断。Epic 与 Vision 不一致时，先说明这是收窄实现还是修改目标，不要静默绕过。

完成、关闭、done 与 Git

状态	含义
完成	实现和验证已经达到目标
关闭	用户授权收尾：o → x，并完成毕业回写；Git 操作按关闭契约执行
整理进 done/	用户主动要求后，将已关闭事项移入整理区；这不是关闭的默认步骤

用户动作或场景	默认行为
快改	验证后必须写 ff，也可以直接写成 x-ff；不自动 commit 或 push
受管理实现	推进到完成即可；不自动关闭 Issue，也不自动 commit 或 push
用户说“做完”或“修好”	完成实现与验证；小改仍留下 ff，除非用户明确不要痕迹；常规 Issue 不自动关闭
用户说“关闭”或“收尾”	执行 close；不自动移入 done/
push、部署、初始化或覆盖 codestable/、关闭 Epic、破坏性操作	必须取得明确授权

毕业方向：

• 独立 Issue → Project Spec。
• Epic 内 Issue → Epic Spec。
• Epic 关闭 → 将稳定结论的具体内容合并进 Project Spec，并检查 Vision；只链接 Epic 不算毕业回写。
• ff 默认不做大段毕业；若现有真相失效，则同步 spec 或明确标记漂移。

详细规则见 close。

质量语言

使用 ISO/IEC 25010:2023 的九个质量特征作为统一语言，但不要把它变成九项必填表。一旦选中某项，它就是承诺。

快改不写形式化质量清单，但仍须遵守 spec、用户要求与必要护栏。信息安全性与安全性是不同概念，不要笼统混称为“安全”。详见 quality。

---

3. 开工协议

在设计、实现、快改、修 bug、维护规格或穿刺之前，如果项目已有 codestable/，先完成以下动作。各 reference 不再重复展开这套协议。

1. 浏览路径并检索关键词。 扫描 codestable/ 的结构与当前主题；同一会话中已经扫描且没有新写入时，复用已有结果。
2. 按权重深入读取。 先读 spec/，再读相关 Epic 与 Notes，然后递归检索根目录和各 Epic 的 issues 树，包括 -x-、ff 与 done/；最后按需读取 Talks、Vision 和 Tools。
3. 判断现状是否足够。 能否用一句话说明“触发如何经过系统产生结果”？不能则先做现状说明；跨多个边界或理解值得复用时，再建立 Explore Issue。
4. 选择管理强度。 按前文“选择管理强度”执行。
5. 处理文档与代码冲突。 先核对证据，再修正真相；不要用代码静默覆盖已记录的取舍，也不要盲信可能过期的文档。

有目标 Issue 时，确认正在处理的是其当前版本；在 Epic 下工作时，读取该 Epic 的 spec.md。

把 codestable/ 当作制度记忆：遇到奇怪代码先查 Spec，踩到旧坑先查 Notes，要理解历史取舍先查 Issue。

---

4. 授权边界

这些边界适用于所有姿态：

• 方向已经确认且用户要求执行时，持续推进到完成或遇到真实阻塞，不要在正常步骤之间反复确认。
• 用户确认前，讨论不落盘；设计不写代码。
• 完成不等于关闭，关闭不等于进入 done/。
• 实现或快改后，不自动 Review，也不自动 push。
• 初始化 codestable/、覆盖入口文件、关闭 Epic、危险操作、推送和部署，都必须取得明确授权。

---

5. 按需读取的原则文件

文件	何时读取
quality	讨论、设计、实现或关闭具体变化；处理质量相关 bug；在 spec 中记录质量约束
economy	设计、实现或修 bug 时做取舍；关闭时发现可以进行有界简化
code-design	设计、受管理实现或结构问题；进行 Review 时必须读取全文，包括文末 Review 部分
ui-spec	处理 UI 空间关系、信息层级与多状态
docs	编写或重组 Vision、Spec、Explore、Note、Talk 等文档
debug	修 bug 需要升级到慢路径时

实体模板位于 templates/entities/，包括 issue.md、ff-issue.md 以及 Explore、Vision、Spec、Talk、Note 等模板。初始化脚本是 scripts/init_codestable.py。产物格式以相应 reference 为准，不要只根据文件名猜测。