跳转至

Agent 任务书： <标题>

每个 Agent 开工前一份。任务书越清楚，返工越少。

1. 角色

你是 <后端功能工程师 / 前端功能工程师 / 测试工程师 / 集成工程师>， 负责 的 <范围>。

2. 目标

<一句话说明交付什么。>

示例：

实现 POST /api/v1/tasks，满足 AC-1 ~ AC-4，单元/集成测试全绿， 生成实现报告，并更新 CSV 状态到 integ_done。

3. 必读

开工前按顺序阅读：

  1. CLAUDE.md
  2. docs/00-discovery/user-story-details.md#<story>
  3. docs/01-design/api/openapi.yaml#<operationId>
  4. docs/01-design/db/schema.sql#<table>
  5. docs/01-design/feature-implementation.md#<story>
  6. docs/01-design/file-ownership.md
  7. docs/01-design/test-strategy.md

如果这些文件之间有不一致，先停下来报告，不要自行选择一个。

4. 文件所有权

4.1 可以修改

  • <path 1>
  • <path 2>
  • 对应的 _test.go / *.spec.ts

4.2 禁止修改

  • backend/internal/adapter/http/router.go
  • backend/cmd/api/main.go
  • backend/migrations/**
  • backend/api/openapi.yaml
  • 其他 Agent 的模块：<list>
  • 前端共享组件：<list>

4.3 需要修改共享文件时

写变更请求：

docs/01-design/change-requests/CR-<id>.md

内容包括：需要改什么、为什么、影响哪些模块、兼容性、建议方案。 等架构 Agent 处理后继续。

5. 契约

5.1 API

  • Operation：<operationId>
  • Method/Path：<METHOD> <path>
  • 请求：<schema>
  • 成功：<status + schema>
  • 失败：<error codes>

5.2 数据

  • 读表：<tables>
  • 写表：<tables>
  • 关键约束：<unique/foreign key/check>
  • 事务边界：<...>

5.3 错误码

场景 HTTP 错误码
<...> <...> <...>

5.4 幂等/并发

  • 幂等：
  • 并发：<乐观锁 version / 行锁 / 无>
  • 重试：<...>

6. 验收标准

从 user-story-details.md 复制，确保完整：

AC-1 <名称> Given <...> When <...> Then <...>

AC-2 <异常> Given <...> When <...> Then <...>

AC-3 <权限> Given <...> When <...> Then <...>

7. 测试要求

7.1 单元测试

必须覆盖：

  • 正常路径
  • 参数校验（空、超长、非法枚举）
  • 权限（未登录、非成员、角色不足）
  • 业务规则（状态转换、默认值）
  • 错误码

命令：

<command>

7.2 集成测试

必须覆盖：

  • 数据库约束
  • 事务回滚
  • 幂等
  • 审计写入
  • 并发（如适用）

命令：

<command>

7.3 测试质量要求

  • 先写会失败的测试，再实现。
  • 不允许删除/跳过测试让 CI 变绿。
  • 不允许只调用不断言。
  • 关键 bug 修复必须加回归测试。

8. 完成定义

  • 代码编译/类型检查通过
  • 单元测试全绿
  • 集成测试全绿
  • lint/vet 通过
  • 没有修改未授权文件
  • 生成 docs/03-dev/reports/<STORY_ID>-<标题>.md
  • 用脚本更新 CSV：
python3 scripts/update_story_status.py \
  --file docs/00-discovery/user-story.csv \
  --story <STORY_ID> \
  --status integ_done \
  --owner <agent> \
  --branch <branch> \
  --report docs/03-dev/reports/<STORY_ID>-<标题>.md \
  --unit-test-status pass \
  --integ-test-status pass
  • 提交 Git：
git add <files>
git commit -m "feat(<scope>): <summary>"

9. 输出要求

完成后输出：

  1. 改动文件清单
  2. 实现要点（≤ 10 条）
  3. 测试命令和结果
  4. 验收标准覆盖表
  5. 已知限制
  6. 报告路径
  7. CSV 更新结果
  8. 下一步建议

不要粘贴大段代码/日志。

10. 停止条件

遇到以下任一情况，停止并报告，不要硬撑：

  • 契约与实现冲突
  • 需要修改共享文件但没有授权
  • 测试无法通过且原因不明
  • 需求缺失/矛盾
  • 发现安全问题
  • 发现数据会被破坏
  • 上下文过长/开始重复犯错

报告格式：

停止原因：
已尝试：
证据（日志/文件/行号）：
需要谁做什么：

11. 工作方式

  1. 先列出实现计划（≤ 10 步），等确认。
  2. 小步提交，每步可编译。
  3. 每完成一步报告测试结果。
  4. 不猜契约；读文件。
  5. 不扩大范围；发现额外问题写 TODO/issue，不顺手改。