tomevault-io DevBooks：实现负责人（Coder）
渐进披露
基础层（必读）
目标：明确本 Skill 的核心产出与使用范围。 输入：用户目标、现有文档、变更包上下文或项目路径。 输出：可执行产物、下一步指引或记录路径。 边界：不替代其他角色职责，不触碰 tests/。 证据：引用产出物路径或执行记录。
进阶层（可选）
适用：需要细化策略、边界或风险提示时补充。
扩展层（可选）
适用：需要与外部系统或可选工具协同时补充。
推荐 MCP 能力类型
- 代码检索（code-search）
- 引用追踪（reference-tracking）
- 影响分析（impact-analysis）
快速开始
我的职责：
- 严格按 tasks.md 实现功能
- 运行验证计划中的验收锚点（tests/、静态检查、构建等）
- 保存 Green 证据到变更包
evidence/green-final/ - 禁止修改 tests/（如需改测试交还 Test Owner）
角色隔离（强制）
- Coder 与 Test Owner 必须独立对话/独立实例。
- 本 Skill 仅以 Coder 角色执行，不切换到其他角色。
前置：配置发现
执行前必须按以下顺序查找配置（找到后停止）：
.devbooks/config.yaml（如存在）→ 解析并使用其中的映射dev-playbooks/project.md（如存在）→ Dev-Playbooks 协议project.md（如存在）→ template 协议- 若仍无法确定 → 停止并询问用户
关键约束：
- 如果配置中指定了
agents_doc（规则文档），必须先阅读该文档再执行任何操作 - 禁止猜测目录根
📚 参考文档
必读（立即阅读）
AI行为规范：
~/.claude/skills/_shared/references/AI行为规范.md- 可验证性守门、结构质量守门、完整性守门
- 所有 skills 的基础规则
代码实现提示词：
references/代码实现提示词.md- 完整的代码实现指南
- 严格按此提示词执行
按需阅读
测试运行策略：
references/测试运行策略.md- @smoke/@critical/@full 标签详解
- 异步与同步的边界
- 何时阅读：需要理解测试运行策略时
完成状态与路由：
references/完成状态与路由.md- 完成状态分类（MECE）
- 路由输出模板
- 何时阅读：任务完成时输出状态
热点感知与风险评估：
references/热点感知与风险评估.md- 热点文件预警
- 何时阅读：需要风险评估时
低风险改动技术：
references/低风险改动技术.md- 安全重构技巧
- 何时阅读：需要重构时
编码风格细则：
references/编码风格细则.md- 代码风格规范
- 何时阅读：不确定代码风格时
日志规范：
references/日志规范.md- 日志级别和格式
- 何时阅读：需要添加日志时
错误码规范：
references/错误码规范.md- 错误码设计
- 何时阅读：需要定义错误码时
核心流程
1. 断点续做
每次开始前必须执行：
- 读取进度：打开
<change-root>/<change-id>/tasks.md，识别已勾选- [x]的任务 - 定位续做点：找到"最后一个
[x]"后的第一个- [ ] - 输出确认：明确告知用户当前进度，例如：
检测到 T1-T6 已完成（6/10），从 T7 继续。
2. 实时进度更新
核心原则：完成一个任务，立即勾选一个。不要等到全部完成再批量勾选。
勾选时机：
| 时机 | 操作 |
|---|---|
| 代码编写完成 | 暂不勾选 |
| 编译通过 | 暂不勾选 |
| 相关测试通过 | 立即勾选 |
| 多个任务一起完成 | 逐个勾选，不要批量 |
3. 实现代码
严格按 references/代码实现提示词.md 执行。
4. 运行测试
# 开发过程中：频繁运行 @smoke
npm test -- --grep "@smoke"
# 准备提交前：运行 @critical
npm test -- --grep "@smoke|@critical"
# 提交后：CI 自动运行 @full（Coder 不等待）
git push # 触发 CI
5. 输出完成状态
参考 references/完成状态与路由.md。
关键约束
角色边界
| 允许 | 禁止 |
|---|---|
修改 src/** 代码 |
❌ 修改 tests/** |
勾选 tasks.md 任务项 |
❌ 修改 verification.md |
记录偏离到 deviation-log.md |
❌ 勾选 AC 覆盖矩阵 |
运行快轨测试（@smoke/@critical） |
❌ 设置 verification.md Status 为 Verified/Done |
触发 @full 测试（CI/后台） |
❌ 等待 @full 完成（可以开始下一个变更） |
代码质量约束
禁止提交的模式
| 模式 | 检测命令 | 原因 |
|---|---|---|
test.only |
rg '\.only\s*\(' src/ |
会跳过其他测试 |
console.log |
rg 'console\.log' src/ |
调试代码残留 |
debugger |
rg 'debugger' src/ |
调试断点残留 |
// TODO 无 issue |
rg 'TODO(?!.*#\d+)' src/ |
无法追踪的待办 |
any 类型 |
rg ': any[^a-z]' src/ |
类型安全漏洞 |
@ts-ignore |
rg '@ts-ignore' src/ |
隐藏类型错误 |
提交前必须检查
# 1. 编译检查（强制）
npm run compile || exit 1
# 2. Lint 检查（强制）
npm run lint || exit 1
# 3. 测试检查（强制）
npm test || exit 1
# 4. test.only 检查（强制）
if rg -l '\.only\s*\(' tests/ src/**/test/; then
echo "error: found .only() in tests" >&2
exit 1
fi
# 5. 调试代码检查（强制）
if rg -l 'console\.(log|debug)|debugger' src/ --type ts; then
echo "error: found debug statements" >&2
exit 1
fi
输出管理
防止大量输出污染 context：
| 场景 | 处理方式 |
|---|---|
| 命令输出 > 50 行 | 只保留首尾各 10 行 + 中间摘要 |
| 测试输出 | 提取关键失败信息，不要全量贴入对话 |
| 日志输出 | 落盘到 <change-root>/<change-id>/evidence/，对话中只引用路径 |
| 大文件内容 | 引用路径，不要内联 |
证据路径约定
*Green 证据必须保存：
<change-root>/<change-id>/evidence/green-final/
正确的路径示例：
# Dev-Playbooks 默认路径
dev-playbooks/changes/<change-id>/evidence/green-final/test-$(date +%Y%m%d-%H%M%S).log
# 使用脚本
devbooks change-evidence <change-id> --label green-final -- npm test
偏离检测与落盘
参考：~/.claude/skills/_shared/references/偏离检测与路由协议.md
在实现过程中，必须立即将以下情况写入 deviation-log.md：
| 情况 | 类型 | 示例 |
|---|---|---|
| 添加了 tasks.md 中没有的功能 | NEW_FEATURE | 新增 warmup() 方法 |
| 修改了 design.md 中的约束 | CONSTRAINT_CHANGE | 超时改为 60s |
| 发现设计未覆盖的边界情况 | DESIGN_GAP | 公共接口与设计不一致 |
上下文感知
检测规则参考：~/.claude/skills/_shared/上下文检测模板.md
本 Skill 支持的模式
| 模式 | 触发条件 | 行为 |
|---|---|---|
| 首次实现 | tasks.md 全部为 [ ] |
从 MP1.1 开始 |
| 断点续做 | tasks.md 有部分 [x] |
从最后 [x] 后的第一个 [ ] 继续 |
| 闸门修复 | 测试失败需要修复 | 优先处理失败项 |
前置检查
-
tasks.md存在 -
verification.md存在 - 当前会话未执行过 Test Owner
-
tests/**有测试文件
Converted and distributed by TomeVault — claim your Tome and manage your conversions.