# 开发工作流

## 一次任务怎样完成

### 1. 讨论

用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍，让用户确认。

### 2. 建单

方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码。

新产品或较大版本先建立 Epic，再建立 MVP：

```text
[Epic] 产品或长期目标
└── [MVP] 第一个可交付版本
    ├── #101 单元任务
    ├── #102 单元任务
    └── #103 单元任务
```

每个单元任务都应目标单一，能够独立测试、提交和回退。

### 3. 实施

Agent 检查工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果它不影响当前验收，另建工单，不扩大当前任务。

重要进度应及时写回工单：

- 已确认的根因；
- 方案或范围变化；
- 测试结果；
- 阻塞和未验证内容；
- Git 提交哈希。

### 4. 待验收

实现和测试完成后，Agent 提交代码并将工单更新为待验收。用户验收前工单保持开启。

### 5. 归档和关闭

使用以下命令创建归档草稿：

```powershell
python scripts/new_task_archive.py 123 "修复登录超时"
```

填写实际结果后单独提交归档，再把路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。

## 什么时候重新确认方案

以下变化必须先更新工单，再由用户确认：

- 交付结果或用户操作发生变化；
- 增加或删除接口、数据库字段或迁移；
- 安全边界、权限或不可逆操作发生变化；
- 原方案不可行，需要更换主要技术路线；
- 任务范围明显扩大。

普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。

## 工单与文档分别写什么

| 信息 | Gitea 工单 | `docs/task` |
|---|---:|---:|
| 讨论过程和临时方案 | 是 | 否 |
| 实施进度和阻塞 | 是 | 否 |
| 最终实现方案 | 是 | 是 |
| 测试结果与未验证内容 | 是 | 是 |
| 提交哈希 | 是 | 是 |
| 长期有效的最终结论 | 可链接 | 是 |