实现自检清单
开发者在编写代码前后自检使用。确保代码忠实实现设计、可测试且符合项目规范。
分为"实现前"（PRE）和"实现后"（POST）两部分。全部通过后方可提交代码评审。
使用说明
- PRE 项在开始写代码前检查；
- POST 项在完成编码和所有验证命令后检查；
- 对"不通过"项必须在代码评审前修复；
- 无法满足的项标记
[N/A: <原因>]；
- 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 版本变更返回类型或参数） |
☐ |
☐ |
☐ |
|
