# 研发 Agent 执行契约

## 1. 目标

研发 Agent 的目标不是“自动写代码越快越好”，而是稳定地把研发任务从输入推进到可验收输出：

```text
需求输入 -> 任务契约 -> 代码/文档执行 -> 验证 -> 证据包 -> 人审 -> 任务索引
```

## 2. 必须输入

| 字段 | 说明 |
| --- | --- |
| task_id | 云效、Codeup、内部任务号或本项目生成的稳定任务号 |
| target_repo | 目标业务仓库，例如 `store`、`ai_api`、`ai_store`、`ai_app`、`android` |
| target_branch | 目标基线分支 |
| task_branch | 任务分支或 worktree |
| requirement | 需求目标和非目标 |
| acceptance | 验收指标，包括测试、截图、接口、日志、客户确认或人工门禁 |
| forbidden_scope | 不能碰的文件、接口、数据库、支付、权限、生产环境或客户数据 |
| evidence_dir | 本次证据包位置 |

## 3. 必须输出

| 输出 | 位置 | 说明 |
| --- | --- | --- |
| 代码或文档 diff | 业务仓库或控制项目 | 保持范围最小 |
| summary.md | `work*/` 或 `work_<project>/` | 目标、已完成、验证、边界、下一步 |
| source-index.csv | 证据包 | 来源、路径、证据等级、用途 |
| 验证记录 | summary 或独立文件 | 命令、结果、阻塞原因 |
| 人审页 | HTML 或明确说明不需要 | 给研发负责人、产品、交付或管理者看 |
| 任务索引条目 | `control/task-index/items/` | 任务、状态、证据、技能、更新时间 |

## 4. 禁止事项

- 不在没有任务契约时直接改业务代码。
- 不把业务代码复制到 `zhctprompt`。
- 不把生产密钥、数据库口令、客户隐私、完整 SQL dump 写进项目。
- 不把客户承诺、合同状态、验收、收入、毛利、设备兼容、AI 效果写成已确认事实，除非有证据。
- 不把 harness 未通过的输出标记为完成。

## 5. 完成口径

一项研发 Agent 任务只有同时满足以下条件，才能写成完成：

1. 需求和非目标清楚。
2. 修改路径和业务仓库正确。
3. 验证命令已运行，或阻塞原因清楚。
4. 证据包存在并能被 harness 校验。
5. 任务索引已写回。
6. 高风险动作有人工门禁。