# 开发工作流

## 目标

用最少但完整的步骤完成需求，同时确保实现、测试和文档一致。流程服务于开发，不增加与风险无关的门禁。

## 标准流程

### 1. 理解需求

明确以下内容：

- 目标结果和使用场景；
- 输入、输出和验收方式；
- 修改范围与明确不做的内容；
- 是否会改变现有协议、数据库或运行行为。

范围清楚、实现方式唯一且容易回退的小改动，可以检查现状后直接实施。存在关键事实缺失、多个重要方案或兼容性取舍时，先和用户确认。

### 2. 检查现状

先读与需求直接相关的代码、配置、测试和文档，不根据文件名或旧说明猜测实现。检查工作区状态，保留无关改动。

建议入口：

- 项目规则：`AGENTS.md`
- 代码定位：[架构与代码地图](02-architecture-and-code-map.md)
- 协议与动作：`docs/agent/`
- 构建版本：`android/*.gradle.kts` 和 Gradle Wrapper 配置

### 3. 分析方案

根据改动范围说明必要的设计事实：

- 模块边界和数据流；
- 协议、接口或持久化变化；
- 异常和超时行为；
- 兼容性影响；
- 自动测试与真机验证范围。

简单改动不要求编写单独方案文档；在任务沟通中说明即可。

### 4. 实施改动

- 按已确认方案做最小且完整的实现；
- 优先扩展已有抽象，不复制相同逻辑；
- 不混入与当前需求无关的重构；
- 变更协议、数据库或长期规则时，同步更新相关文档和测试；
- 当前没有 Android 实现需求时，只改文档，不以占位代码宣称能力可用。

### 5. 执行验证

验证应覆盖受影响范围：

- 文档改动：检查链接、路径、命令和实现状态；
- 模型、协议、同步或执行器：运行相关单元测试，交付前运行完整 `test`；
- Manifest、资源、依赖或 Android 应用代码：运行 `assembleDebug`；
- SQLite 结构：补充读写或升级测试；
- 无障碍行为：除自动测试和构建外，列出需要真机验证的页面与动作。

测试必须真实执行。未运行、无法运行或需要外部环境的项目要明确说明。

### 6. 交付

向用户简要说明：

- 实现结果和主要改动文件；
- 实际执行的验证及结果；
- 未完成、未验证或仍待确认的事项。

只有用户要求时才创建 Git 提交。提交前检查差异，确保不包含无关文件；不自动推送、发布 APK 或创建标签。

## 改动与文档的对应关系

| 改动 | 同步检查 |
|---|---|
| 项目标识、版本或依赖 | `README.md`、`AGENTS.md`、项目概况、构建文件 |
| 任务 JSON 或校验规则 | `docs/agent/protocol.md`、解析测试 |
| 选择器 | `docs/agent/selector.md`、解析和执行测试 |
| 动作 | 模型、解析器、执行器、动作页、动作索引和测试 |
| 任务同步规则 | 业务规则、调度代码、同步测试 |
| SQLite 表结构 | 业务规则、持久化代码、升级或读写测试 |
| 构建或运行方式 | README、本地开发文档、AGENTS（若为长期规则） |

## 需求变化

需求或已确认方案发生变化时，先重新确认受影响范围，再继续实现。已经完成且仍有效的工作保留，不为追求形式完整而重做。

## 发现范围外问题

记录并在交付时提示，但不自动混入本次修改。只有它会阻止当前需求、破坏数据或使验证失真时，才需要立即处理或请求用户决策。