skills/codestable__codestable
1
0
Fork 0
mirror of https://github.com/codestable/CodeStable.git synced 2026-09-19 09:03:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): rewrite around the v2 methodology (zh+en)

Browse Source 
Rebuilt the three v2 content sections as the main narrative instead of
v1-era framing with patches:

- 'Design: thin harness, thick context' — write responsibilities not
  steps; the hard-gate table per flow (incl. 3-round review cap, design
  persistence, test-first); on-demand references for engineering
  judgment; the six homes of knowledge with graduate-before-delete
- Skill catalog refreshed (cs-review three modes, epic inline-first
  sub-designs, the single cs-code-review alias called out)
- 'Workflow and project memory' — one execution mainline, per-request
  risk judgment, zero artifacts for ordinary work, retrieval-with-source
  discipline, zero-migration v1 boundary
- Tagline gains the one-line methodology; roadmap logs the dogfood loop

Personal narrative sections (origin, orchestration comparison,
philosophy, build->evaluate loop) preserved as-is. Doc contract tests
stay green (96 passed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
dafang
2026-07-31 12:39:57 +08:00
parent b134b9d278
commit 286a180806
2 changed files with 76 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.en.md
+38 -38
View File
@@ -10,6 +10,8 @@
Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpowers' fragmentation — I built a lightweight, **human-in-the-loop** AI harness from scratch.
The v2 methodology in one line: **thin harness, thick context** — write responsibilities for strong models, not step-by-step scripts; retrieve context on demand, never preload it.
<p>
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
<img src="https://img.shields.io/badge/cs--skills-8-6366F1?style=flat-square" alt="CodeStable Skills"/>
@@ -148,31 +150,35 @@ I built CodeStable because I believe **the chaos of software engineering isn't r
---
## Design: entities + flows
## Design: thin harness, thick context
CodeStable models real coding work as a set of **entities** and **flows**.
The core judgment of v2: **the stronger the model, the more you should write responsibilities instead of steps.** v1 guarded weak models with 20k+ lines of state machines, gates, and stage artifacts; v2 deletes all of that and ships 8 **thin responsibility contracts** of 30–60 lines each — every skill states exactly three things: what must be achieved, what must not be crossed, and how completion is proven. The route belongs to the model.
### Project memory
Thin rules do not mean no boundaries. What remains are **hard gates**, each decidable in one sentence:
| Entity | What it does |
| Flow | Entry | Hard gate |
|------|------|--------|
| **Feature delivery** | `cs-feat` | High-risk designs are persisted to a work doc, pass independent agent review, then user confirmation — never auto-approved; test-first when a setup exists; completion requires verifiable evidence |
| **Issue fixing** | `cs-issue` | No root-cause guessing without a check that clearly turns red; the red check must turn green before claiming the fix |
| **Refactoring** | `cs-refactor` | Equivalence evidence exists before code changes; stop and report the moment behavior would change |
| **Epic delivery** | `cs-epic` | Decomposition passes independent review and user confirmation; one epic doc keeps the full picture; final acceptance is never done on the user's behalf |
| **Independent review** | `cs-review` | Read-only, independent subagent perspective; blocking findings must be resolved, fix-and-rereview capped at 3 rounds before human arbitration |
Engineering judgment does not occupy the always-loaded context: module depth, implementation economy, and debug escalation live in **on-demand references**, read only when the scene calls for them — the thin harness owns reliability, the thick context owns quality.
### The six homes of knowledge
The capture principle: **everything in its place, no archive hall**:
| Home | What it carries |
|------|--------|
| **attention** | A small set of project facts needed every session, kept to at most 25 entries |
| **lessons** | One file per pitfall, technique, or research result, retrieved by keyword when relevant |
| **work** | Active cross-session or multi-agent work, filenames carry a type prefix feat-/issue-/refactor-/epic-; ordinary tasks create none, completed work is removed |
| **Project docs / ADRs** | The canonical owner for requirements, domain models, public contracts, and long-lived decisions |
| `attention.md` | Project facts read every session, ≤25 entries |
| `lessons/` | One file per pitfall, technique, or research result; traceable evidence required, dedupe-and-merge first |
| Project docs / ADRs | The canonical owner of current facts and structural decisions — CodeStable builds no parallel truth |
| `work/` | Active cross-session tasks, filenames type-prefixed feat-/issue-/refactor-/epic-; ordinary tasks create none |
| git / PR | Execution history |
### Flows
| Flow | Recommended main entry | Notes |
|------|------------|------|
| **Feature delivery** | `cs-feat` | Understand, implement, and verify directly; confirm high-risk contracts or real tradeoffs first |
| **Epic delivery** | `cs-epic` | Maintain one work document and drive confirmed feature / issue / refactor items |
| **Issue fixing** | `cs-issue` | Establish a failing check first, then fix the issue and prove it turns green |
| **Refactoring** | `cs-refactor` | Establish equivalence evidence, change structure incrementally, and keep verification green |
| **Review / audit** | `cs-review` | Independently review the current diff or audit a requested scope, read-only |
| **Knowledge capture** | `cs-keep` | Store evidence-backed frequent facts or reusable lessons in project memory |
High-risk changes, or an explicit owner request, invoke `cs-review` for independent review. The development task that owns a change also updates its docs and ADRs; separate stage skills are no longer needed.
Completed work docs **graduate before deletion**: the final report must list the graduation destinations — which conclusion went into which project doc, which lesson was distilled, or an explicit "nothing to graduate" — no list, no deletion. When a destination does not exist, the agent proposes one and keeps the doc until the owner decides.
---
@@ -183,31 +189,23 @@ High-risk changes, or an explicit owner request, invoke `cs-review` for independ
| Group | Skill | Purpose |
|---|---|---|
| Navigation | `cs` | Clear action requests dispatch to the target skill in the same turn; advice gets a recommendation only; the overview writes no files |
| Onboard | `cs-onboard` | Install CodeStable into a repository |
| Epic | `cs-epic` | Decompose, confirm, and drive multiple deliverable items over time |
| Feature | `cs-feat` | Implement new capability and scale design confirmation or review with risk |
| Onboard | `cs-onboard` | Create the minimal project-memory skeleton; v1 legacy preserved untouched |
| Feature | `cs-feat` | Implement new capability with process strength proportional to risk |
| Issue | `cs-issue` | Fix bugs or broken behavior with red-to-green evidence |
| Refactor | `cs-refactor` | Change structure or performance under behavioral-equivalence evidence |
| Review | `cs-review` | Perform independent read-only diff review or an on-demand audit |
| Memory | `cs-keep` | Capture evidence-backed frequent facts and reusable lessons |
| Epic | `cs-epic` | Decompose, confirm, and drive multiple items; sub-designs inline-first, standalone only when risk escalates |
| Review | `cs-review` | Independent review in three modes: diff / design / repo audit |
| Memory | `cs-keep` | Capture evidence-backed lessons and project facts with automatic tier selection |
The other 24 names from v1.0.4 are retired and not shipped with v2; no compatibility shims are installed. See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for mappings and upgrade boundaries. Call `/cs` when you are unsure which entry fits.
`cs-code-review` ships as the single compatibility alias of `cs-review` (the carried-over v1 name, forwarding only). The other 24 names from v1.0.4 are retired and not shipped with v2; no compatibility shims are installed for them. See [SKILL_CATALOG.en.md](./SKILL_CATALOG.en.md) for mappings and upgrade boundaries. Call `/cs` when you are unsure which entry fits.
---
## Workflow and project memory
CodeStable v2 keeps responsibility, hard gates, and completion evidence in a thin harness, then loads project facts only when relevant:
Every entry shares one execution mainline: **understand the relevant facts → act → run proportionate verification → deliver**. Risk is re-judged per request — no persistent lanes, no stage state machines; ordinary tasks produce zero CodeStable artifacts — the diff, test output, and delivery summary are the evidence.
```text
cs # navigation only
cs-onboard # project setup / v1 upgrade
cs-epic # large initiative -> feature / issue / refactor items
cs-feat ---\
cs-issue ----> cs-review when risk or the owner requires it
cs-refactor ---/
cs-keep # project memory
```
Captured knowledge only has value when it gets read: before acting, every skill greps `lessons/`, v1 legacy knowledge, and project docs by task keywords, and reports the sources of any hits.
After `/cs-onboard`, a new project has only this CodeStable-owned memory:
@@ -218,7 +216,7 @@ After `/cs-onboard`, a new project has only this CodeStable-owned memory:
└── work/
```
Skill-specific context and helpers belong to the owning skill. Requirements, domain models, and ADRs stay in the project's own documentation structure. Historical v1 directories, tools, gates, and hooks remain available for knowledge retrieval, but v2 neither executes nor refreshes that runtime. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full boundary.
Skill-specific context and helpers belong to the owning skill. Requirements, domain models, and ADRs stay in the project's own documentation structure. v1 projects migrate nothing: historical directories, tools, gates, and hooks remain untouched and retrievable, but v2 neither executes nor refreshes that runtime. See [WORKFLOW.en.md](./WORKFLOW.en.md) for the full boundary.
---
@@ -241,7 +239,9 @@ CodeStable is modeled for real-world development scenarios, aiming to handle com
CodeStable adapts to model capability. If a future model nails a module reliably, that module gets removed.
- [ ] Refactor flow needs hardening (`cs-refactor` is still beta)
- [x] Simplified the cs skills family: v2 converges on 8 independent thin-harness skills, retiring 24 v1 entries
- [x] v2 dogfood loop in motion: same-turn dispatch, graduation lists, type-prefixed work docs, and the 3-round review cap all landed from real usage feedback
- [ ] Refactor flow needs hardening
- [ ] …
Issues welcome — share your real-world dev pain and refactoring experience.
README.md
+38 -29
View File
@@ -12,6 +12,8 @@
严肃工程不止于"用 AI 写代码"，更在于**用工程方法约束 AI 本身**：skill 不靠感觉写、靠可复现实验证明与迭代——见 [技能怎么迭代：工程化的 build → evaluate 闭环](#技能怎么迭代工程化的-build--evaluate-闭环)。
v2 的方法论一句话：**thin harness, thick context**——给强模型写责任，不写步骤；上下文按需检索，不预载。
<p>
<img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
<img src="https://img.shields.io/badge/cs--skills-8-6366F1?style=flat-square" alt="CodeStable Skills"/>
@@ -151,31 +153,35 @@ CodeStable 走的是**另一个方向**：
---
## 设计：实体 + 流程
## 设计：thin harness, thick context
CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成一组**实体**和**流程**。
v2 的核心判断：**模型越强，越该给它写责任，而不是写步骤。** v1 用两万多行状态机、gate 和阶段产物防着弱模型；v2 把这些整体删掉，换成 8 个 30–60 行的**薄责任契约**——每个 skill 只说三件事：要达成什么、不可越过什么、如何证明完成。路线交给模型自己找。
### 项目记忆
规则减薄不等于没有边界。留下来的都是一句话可判定的**硬门槛**：
| 实体 | 干什么 |
| 流程 | 入口 | 硬门槛 |
|------|------|--------|
| **特性引入** | `cs-feat` | 高风险设计先落盘 work 文档、过独立 agent review 再交人确认，不 auto-approve；测试设施可用时测试先行；完成必须附可核验证据 |
| **问题修复** | `cs-issue` | 没有能明确变红的验证不许猜根因；修复完成时变红的验证必须变绿 |
| **代码重构** | `cs-refactor` | 先有能自证行为等价的验证再动代码；发现要改行为立即停下转向 |
| **大需求** | `cs-epic` | 拆解方案经独立 review 与用户确认后执行；一个 epic 文档维护全景；不代替用户做整体验收 |
| **独立审查** | `cs-review` | 只读、独立 subagent 视角；blocking 未解决不得通过，修复-复审最多 3 轮后交人裁决 |
工程判断力不占常驻上下文：模块深度、实现经济性、debug 升级路径这些"怎么做好"的判据放在**按需加载的 references** 里，进入对应场景才读——thin harness 管可靠，thick context 管质量。
### 知识的六个归宿
沉淀的原则是**各归其位、没有档案馆**：
| 归宿 | 承载什么 |
|------|--------|
| **attention** | 每次会话都要知道的少量项目事实，保持在 25 条以内 |
| **lessons** | 一条一文件的踩坑、技巧和调研结论，靠关键词检索后按需加载 |
| **work** | 跨会话或多人交接的活动任务，文件名带类型前缀 feat-/issue-/refactor-/epic-；普通任务不创建，完成后清理 |
| **项目文档 / ADR** | 需求、领域模型、公开契约与长期技术决策的 canonical owner |
| `attention.md` | 每次会话必读的项目事实，≤25 条 |
| `lessons/` | 一条一文件的坑、技巧、调研结论；写入必须有可追溯证据，先查重合并 |
| 项目文档 / ADR | 当前事实与结构性决策的 canonical owner——CodeStable 不建平行真相 |
| `work/` | 进行中的跨会话任务，文件名带类型前缀 feat-/issue-/refactor-/epic-；普通任务不创建 |
| git / PR | 执行历史 |
### 流程
| 流程 | 推荐主入口 | 说明 |
|------|------------|------|
| **特性引入** | `cs-feat` | 默认直接理解、实现、验证；遇到高风险契约或真实取舍时先让用户确认 |
| **大需求端到端** | `cs-epic` | 维护一个 work 文档，确认拆解后逐个推进 feature / issue / refactor 子项 |
| **问题修改** | `cs-issue` | 先建立会变红的验证，再修复并证明它变绿 |
| **代码重构** | `cs-refactor` | 先建立等价性证据，分步调整结构并持续验证 |
| **代码审查 / 审计** | `cs-review` | 独立只读审查当前 diff，或按指定范围做 audit |
| **知识沉淀** | `cs-keep` | 把有证据的高频事实或可复用经验写入项目记忆 |
高风险改动或用户要求时，执行流调用 `cs-review` 做独立审查。文档与 ADR 由拥有该变化的开发任务同步，不再需要独立的阶段 skill。
work 文档完成后**先毕业再删除**：最终报告必须列出毕业清单——哪条结论进了哪个项目文档、沉了哪条 lesson，无可毕业则明说——不列清单不得删；毕业目标位置不存在时给出建议落点等用户拍板，拍板前文档保留。
---
@@ -186,22 +192,24 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成
| 分组 | 技能 | 用途 |
|---|---|---|
| 导航 | `cs` | 明确行动诉求同轮直转对应入口；咨询只推荐；导览不写文件 |
| 接入 | `cs-onboard` | 把 CodeStable 接入新仓库或已有零散文档仓库 |
| 大需求 | `cs-epic` | 拆解、确认并长程推进多个子项 |
| 功能 | `cs-feat` | 实现新功能或功能改造，按风险升级设计确认与 review |
| 接入 | `cs-onboard` | 创建最小项目记忆骨架；v1 存量无损保留 |
| 功能 | `cs-feat` | 实现新功能或功能改造，流程强度与风险相称 |
| 问题 | `cs-issue` | 用红到绿证据修复 bug 或既有行为异常 |
| 重构 | `cs-refactor` | 在行为等价证据下调整结构或性能 |
| 审查 | `cs-review` | 独立只读 diff review 或按需 audit |
| 记忆 | `cs-keep` | 沉淀有证据的高频事实与可复用经验 |
| 大需求 | `cs-epic` | 拆解、确认并长程推进多个子项；子设计就近内联、高风险才独立落盘 |
| 审查 | `cs-review` | 独立审查三模式：diff / design / repo 审计 |
| 记忆 | `cs-keep` | 沉淀有证据的经验与项目事实，自动判层 |
v1.0.4 的另外 24 个名称已退役且不随 v2 交付，不再安装兼容 shim。映射与升级边界见
`cs-code-review` 作为 `cs-review` 的唯一兼容别名随包交付（v1 沿用名，只转发）。v1.0.4 的另外 24 个名称已退役且不随 v2 交付，不再安装兼容 shim。映射与升级边界见
[SKILL_CATALOG.md](./SKILL_CATALOG.md)；不知道用哪个时调用 `/cs` 获取推荐。
---
## 工作流与项目记忆
CodeStable v2 用 thin harness 保留责任、硬门槛和完成证据，把项目事实按需加载。`cs` 只做导航；功能、问题与重构入口直接完成工作，高风险或用户要求时再调用独立审查；`cs-epic` 用一个 work 文档维护跨会话全景。
所有入口共用一条执行主线：**理解相关事实 → 行动 → 相称的验证 → 交付结果**。风险每次按当前事实重判，没有持久 lane、没有阶段状态机；普通任务零 CodeStable 产物——diff、测试输出和交付说明就是证据。
沉淀的价值在被读到：每个 skill 动手前按任务关键词 grep `lessons/`、v1 存量沉淀与项目文档，命中必须报告来源路径。
`cs-onboard` 在项目根生成最小 `.codestable/`：
@@ -212,9 +220,9 @@ CodeStable v2 用 thin harness 保留责任、硬门槛和完成证据，把项
└── work/
```
skill 专属 context/helper 归 owning skill；项目需求、领域模型与 ADR 继续使用项目自己的文档结构。v1 历史目录、tool、gate 与 hook 原样保留并可作为知识检索，但 v2 不执行旧 runtime，也不复制或刷新它们。
skill 专属 context/helper 归 owning skill；项目需求、领域模型与 ADR 继续使用项目自己的文档结构。v1 存量项目零迁移：历史目录、tool、gate 与 hook 原样保留并继续被检索覆盖，但 v2 不执行旧 runtime，也不复制或刷新它们。
完整工作流、目录树和跨 skill 引用约束见 [WORKFLOW.md](./WORKFLOW.md)。
完整工作流与持久化约定见 [WORKFLOW.md](./WORKFLOW.md)。
---
@@ -265,6 +273,7 @@ CodeStable 的 skill 不靠"感觉写得更清楚了"来演进，而是**用可
CodeStable 会根据模型能力的发展进行调整。如果未来某个模型做到某个模块的稳定产出，那么这个模块就可以删除。
- [x] 简化 cs skills 体系：v2 收敛为 8 个独立 thin-harness skill，退役 24 个旧入口
- [x] v2 dogfood 闭环运转：同轮直转、毕业清单、work 类型前缀、3 轮复审上限等规则均由真实使用反馈驱动落地
- [x] 端到端测评 · 基础路由评测：decision fixtures + 跨模型机械判分，[measured] 证明重构增益
- [x] 端到端测评 · 效果评测：种子仓库 + 隐藏验收测试 + 真 agent 对照裸 agent，`cs-issue`/`cs-feat` 已跑，诚实测出能力边界与过程契约价值
- [ ] 效果评测扩容：cs-epic 多子 feature 端到端；design 对弱模型增益补统计功效