3.5 KiB
3.5 KiB
开发工作流
目标
用最少但完整的步骤完成需求，同时确保实现、测试和文档一致。流程服务于开发，不增加与风险无关的门禁。
标准流程
1. 理解需求
明确以下内容：
- 目标结果和使用场景；
- 输入、输出和验收方式；
- 修改范围与明确不做的内容；
- 是否会改变现有协议、数据库或运行行为。
范围清楚、实现方式唯一且容易回退的小改动，可以检查现状后直接实施。存在关键事实缺失、多个重要方案或兼容性取舍时，先和用户确认。
2. 检查现状
先读与需求直接相关的代码、配置、测试和文档，不根据文件名或旧说明猜测实现。检查工作区状态，保留无关改动。
建议入口：
- 项目规则：
AGENTS.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（若为长期规则） |
需求变化
需求或已确认方案发生变化时，先重新确认受影响范围，再继续实现。已经完成且仍有效的工作保留，不为追求形式完整而重做。
发现范围外问题
记录并在交付时提示，但不自动混入本次修改。只有它会阻止当前需求、破坏数据或使验证失真时，才需要立即处理或请求用户决策。