Cs Onboard

# onboard 参考模板

本文件提供 `cs-onboard` 使用的骨架模板。

## 1. `.codestable/architecture/ARCHITECTURE.md` 占位模板

```markdown
# {项目名} 架构总入口

> 状态：骨架（待填充）
> 创建日期：YYYY-MM-DD

## 1. 项目简介

## 2. 核心概念 / 术语表

## 3. 子系统 / 模块索引

## 4. 关键架构决定

## 5. 已知约束 / 硬边界
```

## 2. `.codestable/attention.md` 最小模板

attention.md 是 CodeStable 技能启动必读的项目注意事项入口。onboard 创建最小骨架，不替项目 owner 填实质内容；后续短规则由 `cs-note` 追加。

```markdown
# Attention

本文件是 CodeStable 技能启动必读的项目注意事项入口。所有 CodeStable 子技能开始工作前必须读取它。

## 项目碎片知识

<!-- cs-note managed: 用 cs-note 维护，新条目按下面分节追加 -->

### 编译与构建

### 运行与本地起服务

### 测试

### 命令与脚本陷阱

### 路径与目录约定

### 环境变量与凭证

### 其他
```


# 代码维度速查

写代码前先确认每个维度的档位。没明说的走默认，偏离默认的地方要标出来让用户确认。

这份文档是 CodeStable 子技能共享的口径，被 design / fastforward / issue-fix 等阶段引用。项目内的权威副本在 `.codestable/reference/code-dimensions.md`，由 `cs-onboard` 从技能包释放。

---

## 核心四维（每次都要定）

### 健壮性 Robustness —— 错误处理的严苛程度

- **L1 快跑**：happy path 跑通就行，异常直接崩、让它炸。适合一次性脚本、探索代码。
- **L2 够用**：捕获预期错误（文件不存在、网络超时），非预期错误往上抛。适合内部工具。
- **L3 严防**：所有外部输入验证、所有失败路径都有明确处理、关键操作幂等可重试。适合对外接口、生产系统。

### 结构 Structure —— 代码组织的颗粒度

- **inline**：全写在一起，十几行搞定的那种。
- **functions**：按职责拆函数，同一个文件内。
- **modules**：拆多个文件/模块，有明确的导入关系。
- **layers**：分层架构（如 handler / service / repository），有依赖方向约束。

### 性能 Performance —— 对开销的关注度

- **careless**：怎么方便怎么写，O(n²) 也无所谓。
- **reasonable**：避开明显的坑（循环里查 DB、重复计算），但不刻意优化。
- **budgeted**：有明确的性能预算（延迟、内存、QPS），按预算设计数据结构和算法。
- **extreme**：榨性能，要 profiling、要基准测试、可以牺牲可读性。

### 可读性 Readability —— 写给谁看

- **self**：自己当下看得懂就行，命名可以随意。
- **team**：队友半年后还能快速上手，命名规范、关键处有注释。
- **public**：外部开发者能无背景读懂，公共 API 要有文档、示例。
- **teaching**：代码本身就是教材，每一步意图清晰、刻意展示模式。

---

## 场景维度（相关时才定）

### 可演进性 Evolvability —— 预期会怎么变

- **frozen**：接口锁死，不许改（如已发布的库 API）。
- **stable**：偶尔变，变动要走流程、要兼容。
- **active**：当前在迭代，接口随业务调整。
- **experimental**：随时推倒重来，不考虑向后兼容。

### 可观测性 Observability —— 运行时能看到多少

- **opaque**：黑盒，出了问题靠猜。
- **logged**：关键路径有日志，能事后翻查。
- **traced**：有链路追踪，跨服务能串起来。
- **instrumented**：指标齐全（metrics / traces / logs 三件套），可接告警。

### 可测试性 Testability —— 测试覆盖的深度

- **untested**：没测试。
- **testable**：结构支持测试（依赖可注入、副作用可隔离），但还没写。
- **tested**：有单元/集成测试覆盖主要路径。
- **verified**：核心逻辑有测试 + 关键不变量有断言/属性测试/形式化验证。

### 安全性 Security —— 信任边界

- **trusted**：全在可信环境内，不设防。
- **validated**：外部输入做校验和清洗。
- **sandboxed**：权限最小化、危险操作隔离（容器、subprocess 限权）。
- **hardened**：按对抗性环境设计，防注入/防越权/防侧信道，有威胁模型。

---

## 特殊维度（只在涉及时提）

- **Concurrency 并发**：single-threaded / thread-safe / lock-free / distributed
- **Determinism 确定性**：nondeterministic / reproducible / deterministic
- **Compatibility 兼容性**：current-only / backward-compatible / cross-version
- **Idempotency 幂等性**：non-idempotent / idempotent / exactly-once

---

## 常用默认组合

| 场景 | 组合 |
|---|---|
| 聊天里问的随手代码 | L1 + inline + careless + self + experimental |
| 项目内部工具 | L2 + functions + reasonable + team + active + logged + testable |
| 对外发布的库/服务 | L3 + modules + budgeted + public + stable + traced + tested + validated |

没明说就按场景走默认。动手前列出关键档位，偏离默认的地方明确标出来让用户确认。

---

## 怎么用这份文档

- **design / fastforward 起草时**：AI 先按场景猜默认组合，把判断出的"可能偏离默认"的维度列出来问用户；用户没明确说的维度按默认走。只记偏离项，默认档位不抄。
- **implement / fix 写代码时**：翻一眼当前 feature 或 issue 记录的维度档位，按档位写。比如记了 `健壮性=L3` 就不要偷工省掉输入校验；记了 `可读性=public` 就得补示例和文档。
- **acceptance / review 时**：把维度档位当成验收标准的一部分——档位说 L3 但代码里外部输入没校验，就是不达标。


# CodeStable 维护者说明

本文件由 `cs-onboard` 复制到项目的 `.codestable/reference/maintainer-notes.md`。维护 CodeStable 技能家族时需要反复查阅、但不适合放在各子技能正文里的说明。

---

## 1. 断点恢复

AI 对话随时可能中断（token 超限、网络断开、用户换设备）。各阶段发现自己不是从零开始时，必须优先检查已有产物的完成度，从上次停下的地方继续：

- **brainstorm**：如 `{slug}-brainstorm.md` 已有部分内容，读取后问用户"上次聊到 X，要接着聊还是推翻重来？"
- **design**：如 `{slug}-design.md` 已有部分节，逐节检查完成度，补齐缺失节，不重写已完成节
- **implement**：`{slug}-checklist.yaml` 中已 `done` 的步骤不重做，从第一个 `pending` 步骤开始
- **acceptance**：如 `{slug}-acceptance.md` 已有部分节，检查哪些节已填写（有实质 checklist 勾选），从下一个未完成节继续
- **issue-analyze**：如 `{slug}-analysis.md` 已存在，检查 5 节是否都有内容，缺失的补做，已有的不重写
- **issue-fix**：如代码已改但 `{slug}-fix-note.md` 不存在，直接进入验证 + 写 fix-note 环节

恢复时先向用户简短汇报："检测到上次工作到 X 阶段，我从 Y 继续"。

---

## 2. 扩展点

### 新增子工作流

新工作流定型后，在 `cs-onboard/reference/system-overview.md` 的"技