92 lines
3.5 KiB
Markdown
92 lines
3.5 KiB
Markdown
# 开发工作流
|
||
|
||
## 目标
|
||
|
||
用最少但完整的步骤完成需求，同时确保实现、测试和文档一致。流程服务于开发，不增加与风险无关的门禁。
|
||
|
||
## 标准流程
|
||
|
||
### 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（若为长期规则） |
|
||
|
||
## 需求变化
|
||
|
||
需求或已确认方案发生变化时，先重新确认受影响范围，再继续实现。已经完成且仍有效的工作保留，不为追求形式完整而重做。
|
||
|
||
## 发现范围外问题
|
||
|
||
记录并在交付时提示，但不自动混入本次修改。只有它会阻止当前需求、破坏数据或使验证失真时，才需要立即处理或请求用户决策。
|