brainwave/docs/agent-playbook.md

编码代理工作手册

状态：Harness 基线 读者：在本仓库中执行分析、实现、评审和修复的编码代理

1. 开始任务

1. 阅读 文档地图，再按任务类型读取专题文档。
2. 构建、初始化或设备任务先阅读本地开发环境，不要假设 Android Studio、模拟器或全局 Gradle 存在。
3. 检查工作树、已有实现和测试；不要假设方案文档已经被编码。
4. 找到关联需求编号、架构边界和完成标准。
5. 把目标拆成可独立验证的小改动，明确不在范围的内容。
6. 只有必要产品选择无法从仓库确定且错误假设风险较高时，才请求用户决定。

根 AGENTS.md 创建后应保持为短入口，只包含仓库导航、常用命令和不可违反的不变量，并指向本手册；不要复制全部专题文档。

2. 事实源与检索顺序

1. 当前用户任务和已接受 ADR。
2. 对应产品需求、领域规则、AI 安全和架构文档。
3. 自动化测试与 schema。
4. 代码实现。
5. 外部官方文档。

测试、代码和文档互相矛盾时，不要随意选择最方便的一方。先判断哪一个表达了当前已接受行为；修复时同步其余事实源，并在交付说明中指出冲突。

代码发现优先使用仓库配置的知识图谱工具：search_graph → trace_path → get_code_snippet → query_graph → get_architecture。图工具不足，或搜索字符串、配置和非代码文件时，再使用 rg。

3. 永久不变量

任何任务都不得违反：

• AI、网络、时间、问题文本和随机数不参与起卦。
• 六爻领域顺序为 bottom-up；6/9 动，7/8 静。
• 第六轮确认后，AI 和解释层不能修改 CastResult。
• 核心起卦和本地内容离线可用。
• 开发者密钥不进入 APK、源码、日志和测试夹具。
• 问题原文和 AI 全文不进入遥测或崩溃日志。
• 未授权或来源不明的现代译文、字体和图像不能进入发布包。
• AI 不预测和替用户作高影响决定。
• 东方文化表达不得牺牲触控、对比度、读屏和字体缩放。

若任务显式要求违反其中一项，停止实现并请求产品确认；确认后先更新决策和规范，再改代码。

4. 实现工作流

4.1 Inspect

• 确认当前分支/工作树和用户已有改动。
• 阅读最小充分上下文，不进行无目的全仓库扫描。
• 查找已有相似模式、测试 fake、主题令牌和错误类型。
• 确认依赖版本与官方 API，而不是凭记忆猜测会变化的接口。

4.2 Plan

• 用需求编号描述结果，而不是只列文件。
• 标记数据迁移、隐私、安全、内容授权和 UI 无障碍风险。
• 优先扩展现有抽象；新抽象必须有两个以上清楚的使用点或隔离重要边界。

4.3 Implement

• 做满足验收的最小完整改动。
• 领域逻辑用封闭类型和纯函数，边界数据先解析再进入领域。
• UI 使用不可变状态和显式 action；不在 Composable 中访问数据源。
• 新颜色、字号、间距和文案进入设计/资源令牌。
• 不顺手重构与任务无关的用户代码，不覆盖脏工作树。

4.4 Verify

• 先运行最接近改动的测试，再运行 verifyLocal 或等价全量门禁。
• UI 变更至少检查正常、加载、错误、空、离线和恢复状态。
• 领域变更运行穷举/属性测试。
• AI 变更使用 fake server，不依赖实时模型作为唯一证据。
• 明确记录执行过、未执行和失败的命令；不把预期当结果。

4.5 Document

以下变化必须同步文档：

• 用户可见行为 → 产品规格/UX
• 算法或模型 → 领域规则
• 包、依赖或数据流 → 系统架构
• schema、来源、隐私 → 数据与内容
• 提示词/模型行为 → AI 安全
• 命令/门禁 → 质量门禁
• JDK、SDK、Gradle、IDE、设备或代理能力 → 本地开发环境
• 架构取舍 → 决策记录
• 可复现失败 → 失败记忆

5. 依赖政策

引入依赖前回答：

1. 现有 AndroidX/Kotlin/项目代码能否清晰完成？
2. 依赖是否维护、兼容当前工具链并有明确许可证？
3. 它增加多少 APK/构建/运行复杂度？
4. 它会不会模糊领域边界或把密钥带入客户端？
5. 测试如何替换或 fake 它？

新增大型依赖、具体 AI SDK、分析 SDK、字体包或多模块结构必须记录 ADR。

6. 测试纪律

• 修复缺陷先建立可失败的回归测试，再修复。
• 不删除、跳过或放宽断言来让门禁变绿，除非需求正式改变。
• 不在测试中使用 Thread.sleep 等不稳定等待；使用测试调度器和可控 fake。
• 不把实时日期、网络和模型输出放入确定性测试。
• screenshot golden 的更新必须人工确认差异来源。
• 数据库迁移必须从上一发布 schema 测到当前 schema。

7. 失败处理

命令失败时：

1. 保存准确命令、错误摘要和环境。
2. 判断是实现缺陷、环境缺失、测试脆弱还是规范冲突。
3. 修复根因并重新运行最小失败用例。
4. 再运行相关全量门禁。
5. 若相同类别可能复发，更新失败记忆并增加机械护栏。

不得无限重复同一失败命令，也不得用捕获异常、硬编码测试值或关闭检查掩盖失败。

8. 交付格式

最终交付至少说明：

## 结果
- 完成了什么，对应哪些需求

## 关键实现
- 重要边界或决策

## 验证
- 实际运行的命令和结果
- 人工验证

## 剩余事项
- 未运行、TBD、外部阻塞或剩余风险

如果任务只完成文档或调查，直接说明没有构建/测试，不伪造运行证据。

9. 定期维护

每个里程碑执行一次轻量“熵清理”：

• 删除无引用文档、死代码和过期 TODO；
• 合并重复 helper 和重复主题令牌；
• 检查实现是否绕过层边界；
• 检查文档链接、状态和验证命令；
• 检查依赖、许可证、内容版本和数据库迁移；
• 将重复评审意见提升为自动化规则。

目标不是追求文件数量，而是让下一次代理运行能更快找到真实约束，并从环境得到准确反馈。