devbooks-coder

name: devbooks-coder description: devbooks-coder：以 Coder 角色严格按 tasks.md 实现功能并跑闸门，禁止修改 tests/，以测试/静态检查为唯一完成判据。用户说"按计划实现/修复测试失败/让闸门全绿/实现任务项/不改测试"，或在 DevBooks apply 阶段以 coder 执行时使用。 recommended_experts: ["System Architect"] allowed-tools: - Glob - Grep - Read - Write - Edit - Bash

DevBooks：实现负责人（Coder）

渐进披露

基础层（必读）

目标：明确本 Skill 的核心产出与使用范围。输入：用户目标、现有文档、变更包上下文或项目路径。输出：可执行产物、下一步指引或记录路径。边界：不替代其他角色职责，不触碰 tests/。证据：引用产出物路径或执行记录。

进阶层（可选）

适用：需要细化策略、边界或风险提示时补充。

扩展层（可选）

适用：需要与外部系统或可选工具协同时补充。

快速开始

我的职责：

严格按 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/** 有测试文件