Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)
This commit is contained in:
octopus
@@ -0,0 +1,153 @@
|
||||
# 实现自检清单
|
||||
|
||||
> 开发者在编写代码前后自检使用。确保代码忠实实现设计、可测试且符合项目规范。
|
||||
> 分为"实现前"（PRE）和"实现后"（POST）两部分。全部通过后方可提交代码评审。
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **PRE** 项在开始写代码前检查；
|
||||
2. **POST** 项在完成编码和所有验证命令后检查；
|
||||
3. 对"不通过"项必须在代码评审前修复；
|
||||
4. 无法满足的项标记 `[N/A: <原因>]`；
|
||||
5. **DAG 路由产物解析（[org-internal #3072] phase 3 后唯一管线模式）**：DAG 运行不存在
|
||||
legacy `{slug}/04-plan-*` / `{slug}/03-design-*` 页面，PRE-1～PRE-7、
|
||||
PRE-11、PRE-12、PRE-19、POST-15.1 引用的产物按 `implement`/`verify`
|
||||
SKILL 的 DAG-route read map 解析：工作项定义 → 冻结 DAG 副本
|
||||
`{epic-slug}/dag` 节点规格 + 节点工单正文；验收条件与声明的 `test_id`
|
||||
→ 节点 `acceptance_criteria`（含 `{epic-slug}/dag-nodes/{node-id}`
|
||||
下沉子页）；组件/接口/数据设计、REQ→组件追溯 → 节点规格 + 跨 session
|
||||
边契约（`{epic-slug}/shared/{file}`）；「在 plan 中标注」（PRE-19）与
|
||||
迭代计划页标注（POST-15.1）→ 节点 `acceptance_criteria` 或节点工单
|
||||
正文显式标注。standalone 模式（bugfix/refactor/port）以请求本身为规格，
|
||||
上述项标记 `[N/A: standalone 无 legacy 产物]`。
|
||||
|
||||
---
|
||||
|
||||
## 实现前（PRE — Pre-Implementation）
|
||||
|
||||
### 1. 上下文完备性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ----- | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-1 | 已读取工作项定义（wiki page `{slug}/04-plan-04-iteration-assignment`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-2 | 已读取本迭代验收条件（wiki page `{slug}/04-plan-05-acceptance-criteria`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-2.1 | 已从 plan/05 验收条件表提取本工作项每条声明的 test_id（测试用例 ID 列），作为 Phase 3 Red→Green 测试优先顺序的依据；MANUAL/BENCH 类型已识别 | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-3 | 已读取可追溯矩阵中的 REQ→组件映射（wiki page `{slug}/03-design-08-traceability`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
| PRE-4 | 已读取涉及组件的设计文档（wiki page `{slug}/03-design-03-component-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-5 | 若涉及 API，已读取接口设计（wiki page `{slug}/03-design-04-interface-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-6 | 若涉及数据模型，已读取数据设计（wiki page `{slug}/03-design-05-data-design`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-7 | 若涉及非功能需求，已读取对应设计章节（wiki page `{slug}/03-design-06-non-functional-design`） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 2. 代码图调研（Code Graph）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| PRE-CG1 | 会话已确认代码图就绪（`codegraph_status` 非空，否则 `codegraph init -i`） | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG2 | 已用 `codegraph_explore`/`codegraph_search` 定位待改符号的定义与依赖，而非 grep+read 全文拼凑 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG3 | 已用 `codegraph_callers` 查清待改符号的所有调用方，确认改动不遗漏调用点 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG4 | 已用 `codegraph_explore`/`codegraph_callers` 评估改动的传递影响范围，回归风险已知 | ☐ | ☐ | ☐ | |
|
||||
| PRE-CG5 | 精读实现时使用 `read(filePath, symbol: ...)` 只取目标符号，未整文件读取大文件 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 3. 工作项边界
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ---------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-8 | 工作项范围清晰，不超过 3 个文件变更（单次 Worker 会话上下文窗口限制） | ☐ | ☐ | ☐ | |
|
||||
| PRE-9 | 所有需要创建/修改的文件在设计文档中有对应组件或接口 | ☐ | ☐ | ☐ | |
|
||||
| PRE-10 | 没有设计文档未提及的新组件、新表或新外部依赖需要引入 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 4. 设计与计划门控（Design & Plan Gate）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-11 | 设计文档（wiki pages `{slug}/03-design-**`）已存在且包含本工作项涉及的全部组件设计 | ☐ | ☐ | ☐ | |
|
||||
| PRE-12 | 迭代计划（plan/）已存在且本工作项有明确的工作项 ID 和验收条件 | ☐ | ☐ | ☐ | |
|
||||
| PRE-13 | 评审门已收敛：DAG 路由下为 review-dag 单门收敛（`octopus review status --stage review-dag` 的 state 为 `success`，与 `pipeline-gate.md` DAG 路由变体一致）；standalone 模式（bugfix/refactor/port）无上游评审门，标记 `[N/A: standalone 无上游评审]`（legacy design-space / iteration-plan 双门已随 [org-internal #3072] phase 3 归档） | ☐ | ☐ | ☐ | |
|
||||
| PRE-14 | 合并前基准刷新：当前分支已 rebase 到目标分支（`git fetch origin && git rebase origin/main`），无合并冲突。若 rebase 引入新变更，重新运行 `bun typecheck && bun run test:parallel` 后再提交 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 5. UI 组件设计完整性（仅前端/UI 工作项）
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | -------------------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| PRE-15 | 设计文档覆盖了组件的全部四种状态（Loading / Empty / Error / Success），每种状态有明确的渲染内容和触发条件（参见 `.octopus/archive/templates/design.md` §11.1，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-16 | 设计文档覆盖了组件所需的全部交互行为：列表导航、焦点管理、键盘快捷键、展开/折叠、实时过滤（参见 `.octopus/archive/templates/design.md` §11.2，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-17 | 设计文档覆盖了组件的全部可访问性要求：ARIA role/label、键盘可达、焦点环、对比度、色彩独立性（参见 `.octopus/archive/templates/design.md` §11.3，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-18 | 设计文档已逐组件声明测试策略类型（render / source-verification / E2E / manual）。已知测试基础设施限制（Kobalte portal + happydom、路由上下文缺失等）已有对应替代方案标记（参见 `.octopus/archive/templates/design.md` §11.4，legacy 设计模板 [org-internal #3072] phase 3） | ☐ | ☐ | ☐ | |
|
||||
| PRE-19 | 超过 3 个 MANUAL 类型的 AC 已标记为设计风险，并在 plan 中标注更高级测试基础设施依赖 | ☐ | ☐ | ☐ | |
|
||||
|
||||
---
|
||||
|
||||
## 实现后（POST — Post-Implementation）
|
||||
|
||||
### 4. 设计一致性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------ | ------------------------------------------------------ | ---- | ------ | --- | ---- |
|
||||
| POST-1 | 组件接口签名（方法名、参数、返回值）与设计文档一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-2 | 数据模型字段名、类型、约束与数据设计一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-3 | API 端点、方法、请求/响应格式、状态码与接口设计一致 | ☐ | ☐ | ☐ | |
|
||||
| POST-4 | 组件依赖关系与设计的依赖图一致，无反向依赖或新增依赖 | ☐ | ☐ | ☐ | |
|
||||
| POST-5 | 未引入设计文档未提及的新依赖（npm 包、外部服务） | ☐ | ☐ | ☐ | |
|
||||
| POST-6 | 若不得已偏离设计，有明确的注释标注原因和设计修正建议（含 ADR/amend 引用 — 不可仅写"偏离设计"） | ☐ | ☐ | ☐ | |
|
||||
| POST-6.1 | 已用设计文档中的决策树/状态机/真值表，代入至少 2 组具体输入手工 trace 每条分支，确认代码输出与设计预期一致（尤其条件取反、`===` vs `!==`、状态翻转等易错点） | ☐ | ☐ | ☐ | |
|
||||
| POST-6.2 | 因 API 不兼容、上游限制或测试基础设施不足而延迟的项，已在代码中用 `[OPEN: <short-id>]` 标注（含延迟原因、影响范围、建议解决时机）。verify Phase 5.5 会为每个 `[OPEN]` 项在源票 `## TD 登记` 评论登记一行（registry-first，`ticket-lifecycle.md`；排期后才升格独立票）。禁止仅标注 `[OPEN]` 而不登记 | ☐ | ☐ | ☐ | |
|
||||
| POST-6.3 | 邻近配额（[org-internal #3002] G3）：本迭代触碰的区域（包/模块）若在源票 `## TD 登记` 中有适用行，已带走 ≥1 项一并处置（修复或带理由显式再延迟）；无适用行时在报告记录 `0 applicable` | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 5. 代码质量
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ----------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-7 | `bun typecheck` 通过，无类型错误 | ☐ | ☐ | ☐ | |
|
||||
| POST-8 | `bun lint` 通过，无 lint 错误或警告 | ☐ | ☐ | ☐ | |
|
||||
| POST-8.1 | 删除代码后（清理死代码、测试文件、重构移除），重新运行 `bun lint` 并确认无 unused-import / unused-variable 警告（常见遗留：删除测试代码后遗漏的 import） | ☐ | ☐ | ☐ | |
|
||||
| POST-8.2 | 删除 `.ts`/`.tsx` 文件后，验证 `bun typecheck` 无"找不到模块"或孤立类型引用错误 | ☐ | ☐ | ☐ | |
|
||||
| POST-9 | 函数/方法长度合理（≤ 50 行），单一职责 | ☐ | ☐ | ☐ | |
|
||||
| POST-10 | 错误处理路径完备（I/O、网络、解析、数据库操作） | ☐ | ☐ | ☐ | |
|
||||
| POST-10.1 | I/O 操作有超时守卫（如 `Effect.timeout`），避免无限挂起 | ☐ | ☐ | ☐ | |
|
||||
| POST-10.2 | 子进程调用有显式退出码检查（`exitCode !== 0` 显式 fail） | ☐ | ☐ | ☐ | |
|
||||
| POST-10.3 | `Effect.orDie`/`orDieWith` 仅用于 unrecoverable 场景；recoverable 错误用 `catchAll`/`recoverWith` | ☐ | ☐ | ☐ | |
|
||||
| POST-10.4 | 多写操作（INSERT + UPDATE）用 `Database.transaction` 包裹保证原子性 | ☐ | ☐ | ☐ | |
|
||||
| POST-11 | 无硬编码凭据、密钥、内网地址或环境特定值 | ☐ | ☐ | ☐ | |
|
||||
| POST-11.1 | 提交前无法跟踪链接检查（单一事实来源：`code-review.md` SEC 3.7.1——`git diff --cached --diff-filter=T` 为空；判据以该条为准）| ☐ | ☐ | ☐ | |
|
||||
| POST-11.2 | 提交前已确认无进程/流程副产品混入暂存区（如 `.claim` 空文件、claim carrier、临时 pid/日志）——`git status` 逐条核对，`git add -A` 前先看 untracked 清单（[org-internal #3169] 教训：`.claim` 空文件随 iter-0 混入，round-1 九维评审要求 `git rm`） | ☐ | ☐ | ☐ | |
|
||||
| POST-12 | 无注释掉的代码块或 `console.log` 调试语句 | ☐ | ☐ | ☐ | |
|
||||
| POST-13 | 无 `as any` 类型断言绕过类型检查（生产代码必须保有完整类型安全） | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 6. 测试
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ---------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-14 | `bun run test:parallel` 全部通过，无失败用例 | ☐ | ☐ | ☐ | |
|
||||
| POST-15 | 新增代码有测试覆盖，覆盖主要路径和关键分支 | ☐ | ☐ | ☐ | |
|
||||
| POST-15.1 | 测试与实现位于同一迭代；若分拆到下一迭代，必须在迭代计划（wiki page `{slug}/04-plan-04-iteration-assignment`）中显式标注并给出理由。实现提交时不得处于"零测试覆盖"状态 | ☐ | ☐ | ☐ | |
|
||||
| POST-15.2 | 新增组件源文件（`.tsx`/组件 `.ts`）提交时，同一 commit 必须附带至少一个冒烟测试（render 测试，或 Kobalte portal 类组件的源码验证测试——见 AGENTS.md「Testing Kobalte components with happydom」）。禁止整批源文件无任何测试落地、将全部测试统一延后到未来 chunk | ☐ | ☐ | ☐ | |
|
||||
| POST-15.3 | plan/05 中声明的每个 test_id 已落地为真实测试（文件路径::测试名与声明一致） | ☐ | ☐ | ☐ | |
|
||||
| POST-16 | 测试验证了验收条件中的具体行为 | ☐ | ☐ | ☐ | |
|
||||
| POST-17 | 测试覆盖了边界条件（空值、异常输入、权限边界） | ☐ | ☐ | ☐ | |
|
||||
| POST-18 | 测试相互独立，可任意顺序运行 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 7. 文档与日志
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | ---------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-19 | 复杂逻辑有简洁解释（若真正非直觉） | ☐ | ☐ | ☐ | |
|
||||
| POST-20 | 对外 API 的错误消息用户可读且可操作 | ☐ | ☐ | ☐ | |
|
||||
| POST-21 | 关键操作有结构化日志（含上下文如 userId、requestId） | ☐ | ☐ | ☐ | |
|
||||
| POST-22 | JSDoc 与实际函数签名一致，参数（含新增参数）已完整文档化 | ☐ | ☐ | ☐ | |
|
||||
| POST-23 | 带副作用的新代码路径（日志、事件发布）已守卫所有控制流（恢复、空值、错误路径），防止幽灵触发 | ☐ | ☐ | ☐ | |
|
||||
|
||||
### 8. 过程与规范一致性
|
||||
|
||||
| # | 检查项 | 通过 | 不通过 | N/A | 备注 |
|
||||
| ------- | -------------------------------------------------------------- | ---- | ------ | --- | ---- |
|
||||
| POST-24 | AI artifact header 使用 `@ai-artifact:` 多行格式（示例见 AGENTS.md）。不得使用其他格式如 `// AI-GENERATED ARTIFACT` | ☐ | ☐ | ☐ | |
|
||||
| POST-25 | 评审修订后，若修改了被测试覆盖的代码，已同步更新对应的测试断言（source-verification 或 render 测试） | ☐ | ☐ | ☐ | |
|
||||
| POST-26 | 测试断言中不得包含 `@opencode-ai` 字符串字面量（namespace gate 扫描字符串字面量，会将其误判为命名空间残留）；安全写法见 `.octopus/rules/testing.md` § "Namespace gate and test assertions" | ☐ | ☐ | ☐ | |
|
||||
| POST-31 | commit 消息使用了正确的 conventional 类型：性能优化用 `perf`（非 `feat`），内部重构用 `refactor`，新功能用 `feat`，bug 修复用 `fix`。类型选择直接影响 auto-changelog 和 release notes 准确性 | ☐ | ☐ | ☐ | |
|
||||
| POST-32 | 若工作项依赖关键 upstream 库（如 `marked`、`effect`、`@kobalte/core`），已在本地运行基础 smoke test 确认 API 签名未变（upstream 可能在 minor 版本变更返回类型或参数） | ☐ | ☐ | ☐ | |
|
||||
Reference in New Issue
Block a user