cs

# CodeStable CodeStable 是一套理解和推进软件演化的方法。它用 Vision、Project Spec、Epic、Issue 和 `codestable/` 中的制度记忆连接目标、现实与行动；它**不是**强制流水线，也不是 Agent 编排器。 调用 `cs` 不等于跑完整流程。先判断用户此刻要讨论、理解、设计、实现还是收尾，再采用匹配的管理强度。 ### 沟通方式：先结论，再展开 先用用户正在使用的词，简短说明**结论和原因**。只有需要做取舍、取得授权，或必须展示验证与风险证据时，才展开框架、规则和细节。简短不等于省略关键判断，而是先让用户容易理解，再按需下钻。 ### 节省上下文（Codex） 同一会话中，已经完整读取且没有变化的 `SKILL.md`、reference、template 或相邻说明，必须复用既有理解，不要重复读取。仅在用户要求重读、文件已变化，或当前理解不足以支撑判断时，读取相关最小范围。 --- ## 1. 先定姿态 从用户原话与上下文中选择**一个主姿态**。选定后立即读取“必读”，再开始行动；未命中的姿态文件不要预读。 | 主姿态 | 用户常这样说 | 必读 | 按需读 | 默认边界 | |---|---|---|---|---| | **接入** | 初始化 cs、接入 CodeStable、补齐 `codestable/` | [onboard](references/onboard.md) | — | 必须明确授权；不编造业务内容 | | **讨论** | 聊聊、先理清、想清楚再做、帮我规划一下 | [talk](references/talk.md) | [docs](references/docs.md)；具体变化 → [quality](references/quality.md)；UI → [ui-spec](references/ui-spec.md) | 用户确认前不落盘，不建 issue、epic 或 vision | | **愿景** | 应用将来什么样、整理 vision、产品全景 | [vision](references/vision.md) | [docs](references/docs.md)；质量方向 → [quality](references/quality.md)；UI → [ui-spec](references/ui-spec.md) | 确认后才写 vision；不强迫创建开发事项 | | **规格** | 维护 spec、当前真相、epic 活规格 | [spec](references/spec.md) | [docs](references/docs.md)；质量约束 → [quality](references/quality.md)；UI → [ui-spec](references/ui-spec.md) | 只写仍然成立的结论 | | **理解现状** | 怎么工作的、这条链路、影响范围 | [explore](references/explore.md) | [docs](references/docs.md)；服务具体变化 → [quality](references/quality.md) | 先解释现状；复杂且值得复用时才建 Explore Issue | | **修 bug** | 坏了、不符合预期、debug、修这个 bug | [complain](references/complain.md) | [debug](references/debug.md)、[economy](references/economy.md)、[quality](references/quality.md)；结构 → [code-design](references/code-design.md) | 简单问题默认快改并留下 `ff`；复杂问题可受管理推进 | | **设计** | 怎么实现、先设计、实现方案 | [design](references/design.md) | [code-design](references/code-design.md)、[economy](references/economy.md)、[quality](references/quality.md)；UI → [ui-spec](references/ui-spec.md) | 不写代码；高风险先安排穿刺顺序 | | **快交付** | 快速、快改、小改一下、直接开干、别走流程 | [fast](references/fast.md) | [economy](references/economy.md)；必要时 [quality](references/quality.md)；UI → [ui-spec](references/ui-spec.md) | 默认轻检索、验证并留下 `ff`；用户明确不要痕迹时才可省略 `ff` | | **受管理实现** | 做这个 issue、推进 epic、实现（有档）、穿刺/先打通 | [do](references/do.md) | [code-design](references/code-design.md)、[economy](references/economy.md)、[quality](references/quality.md)；现状不清 → [explore](references/explore.md)；UI → [ui-spec](references/ui-spec.md) | 完成不等于关闭；风险先穿刺，再加厚 | | **收尾** | 关闭、收尾、做完并沉淀、毕业回写 | [close](references/close.md) | [docs](references/docs.md)、[quality](references/quality.md)；有界简化 → [economy](references/economy.md) | 关闭需要用户授权；不自动移入 `done/` | | **审代码** | review、评审、看看这 diff/PR | [code-design](references/code-design.md)（文末 Review） | [economy](references/economy.md)；相关时 → [quality](references/quality.md) | 用户点名才做；默认只审不改 | | **记知识** | 记一下坑、写 note | [note](references/note.md) | [docs](references/docs.md) | 同主题更新原 note，不重复新建 | | **学流程** | 我带你跑一遍、教 AI 做某流程 | [maketools](references/maketools.md) | [docs](references/docs.md) | 危险操作前再次确认 | ### 怎样判断姿态 1. 用户的原话与授权，优先于“看起来应该走重流程”。 2. 事情小、目标清楚、用户要快且没有要求建档 → **快交付**。 3. 目标模糊或取舍未定 → **讨论**；聊清后再切换到快交付、受管理实现、愿景等姿态。 4. 已有常规 Issue，或用户点名 Issue / Epic → **受管理实现**，必要时先设计。 5. 已有行为坏了 → **修 bug**；新增能力 → 快交付或受管理实现，不归入 Complain。 6. 用户只问系统怎样工作 → **理解现状**，不要默认开始修改。 7. 意图不清，而且选错会实质改变后续，例如是否建 Issue、是否改代码 → 给一句话推荐和理由，请用户选择；不要默认采用重流程。 8. 写或修改 Agent 技能本身，不属于 CodeStable 的职责。 ### 选择管理强度 | 情况 | 默认选择 | |---|---| | 小、低风险、一次可完成，或用户明确要快 | **快改**；完成后留下 `ff`，见 [fast](references/fast.md) | | 用户明确不要痕迹或不要写 Issue | 可以不留 `ff`；若现有真相失效，仍须同步 spec 或标记漂移 | | 涉及范围取舍、多轮推进、交接、显著风险或长期质量承诺 | 建立**常规 Issue**：`type: feature\|bug\|chore\|refactor` | | 跨模块、多批次，且规格会在边界内持续演化 | 建立 **Epic**；边界足够清楚的切片可直接在 Epic 内推进 | | 技术、集成或迁移风险需要先证明可行 | 先做**穿刺**，见 [do](references/do.md)，再加厚实现 | | 用户明确要求管理或明确不要建档 | 服从用户选择 | --- ## 2. 世界模型与工作区 ### 从目标到现实 ```text 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/` 下。 ```text 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/` 使用同一种结构，但各自独立编号： ```text 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](references/close.md)；不自动移入 `done/` | | push、部署、初始化或覆盖 `codestable/`、关闭 Epic、破坏性操作 | 必须取得明确授权 | 毕业方向： - 独立 Issue → Project Spec。 - Epic 内 Issue → Epic Spec。 - Epic 关闭 → 将稳定结论的**具体内容**合并进 Project Spec，并检查 Vision；只链接 Epic 不算毕业回写。 - `ff` 默认不做大段毕业；若现有真相失效，则同步 spec 或明确标记漂移。 详细规则见 [close](references/close.md)。 ### 质量语言 使用 ISO/IEC 25010:2023 的九个质量特征作为统一语言，但不要把它变成九项必填表。**一旦选中某项，它就是承诺。** 快改不写形式化质量清单，但仍须遵守 spec、用户要求与必要护栏。信息安全性与安全性是不同概念，不要笼统混称为“安全”。详见 [quality](references/quality.md)。 --- ## 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](references/quality.md) | 讨论、设计、实现或关闭具体变化；处理质量相关 bug；在 spec 中记录质量约束 | | [economy](references/economy.md) | 设计、实现或修 bug 时做取舍；关闭时发现可以进行有界简化 | | [code-design](references/code-design.md) | 设计、受管理实现或结构问题；进行 Review 时必须读取全文，包括文末 Review 部分 | | [ui-spec](references/ui-spec.md) | 处理 UI 空间关系、信息层级与多状态 | | [docs](references/docs.md) | 编写或重组 Vision、Spec、Explore、Note、Talk 等文档 | | [debug](references/debug.md) | 修 bug 需要升级到慢路径时 | 实体模板位于 `templates/entities/`，包括 `issue.md`、`ff-issue.md` 以及 Explore、Vision、Spec、Talk、Note 等模板。初始化脚本是 `scripts/init_codestable.py`。产物格式以相应 reference 为准，不要只根据文件名猜测。