工程工作流

本文定义 AsterDrive 从接收任务到交付结果的默认开发流程。目标是减少重复搜索和来回确认，同时保持当前代码证据、任务边界和验证结果可追溯。

开始前先读项目契约，再根据任务路由选择本次真正需要的代码、文档和验证入口。

1. 固定当前任务的证据边界

开始时确认：

git branch --show-current
git rev-parse HEAD
git status --short

任务涉及 issue、PR、review comment、外部协议或第三方 SDK 时，再读取对应权威来源。不要用另一个 branch、旧 review 或历史测试结果代替当前 checkout。

需要形成一个简短的任务边界：

目标：本次需要改变的可观察行为
不做：明确排除的相邻功能或未来 issue
归属：Drive、Forge、前端或协议边界
影响层：route / service / domain / repo / storage / protocol / frontend
验收：必须通过的行为和验证范围

这个摘要用于内部执行，不要求每次都向用户复述。只有边界存在实质歧义时才需要确认。

2. 默认持续执行

任务一旦开始，默认连续完成以下闭环：

侦察 -> 定边界 -> 实现 -> focused validation -> 修复 -> 扩大验证 -> 文档/生成同步 -> 最终检查

• 中间状态更新只说明正在做什么、发现了什么和下一步是什么，不要求用户回复。
• 不在计划完成、代码写完、第一条测试通过或构建开始前停下来等待“继续”。
• 一个验证失败时先自行定位、修复和复测；同一阻塞经过充分调查仍依赖外部输入时才上报。
• 任务期间出现无关工作区改动时保持隔离；只有它与当前任务发生不可调和的冲突时才暂停。
• 用户发来新消息时，以最新意图调整当前执行；未要求暂停时继续完成剩余闭环。

这个规则不适用于纯咨询、方案讨论或用户明确要求“先看看、不改代码”的场景。这类任务在完成证据收集和结论后结束，不擅自进入实现。

3. 按任务路由读取最小上下文

先从任务路由找到最可能的入口，再沿现有调用链阅读：

route / protocol entry
  -> service use case
  -> domain helper
  -> repository / storage / protocol implementation
  -> focused tests

不要默认扫描整个仓库。优先使用 rg 搜索符号、调用点、测试名和已有相邻实现，并排除 target/、docs/node_modules/、构建产物和生成依赖目录。

开始编辑前至少回答：

• 相邻代码采用什么模式？
• 本次行为由哪一层拥有？
• 哪些不变量和调用方会受影响？
• 已有测试在哪里，缺少哪些边界？

如果这些答案仍不清楚，继续调查。不要凭熟悉感猜测当前代码仍与历史记忆一致。

4. 选择最小完整实现

• 保持任务范围，不顺手重构无关模块。
• 优先复用现有 helper、trait、registry、error mapping 和测试支持。
• 新抽象必须建立真实边界或消除有意义的重复。
• 需求边界明确时直接实现最终合理形态，不保留无价值的临时双轨结构。
• 内部重命名、trait 调整或 Forge 接入一次更新声明、调用方、import、测试和文档，不增加纯转发兼容函数。
• 只有公开 API、线上协议、滚动部署或真实产品 adapter 需要时才保留兼容层，并写明测试与删除条件。
• 跨层改动先列出各层职责，再按依赖方向实施。
• 大规模 trait、状态或公共 API 迁移先建立兼容实现并运行编译检查点，再分批迁移调用方。
• 数据库、上传完成、锁、配额和认证状态变更先明确事务与副作用顺序。

仓库可能存在用户未提交改动。只修改任务相关文件；同文件存在交叉改动时先读完整 diff，绝不通过回滚来获得干净工作区。

5. 分批实现和验证

窄改动可以一次完成；跨模块改动按可编译、可测试的批次推进：

1. 类型、契约或兼容边界
2. 核心实现
3. 调用方和适配层
4. 测试与生成产物
5. 文档同步

每批运行能覆盖该批风险的最小检查。Rust 测试优先使用：

cargo nextest run --lib <filter>
cargo nextest run --test <target> <module_or_test_filter>

不要用没有 target 的模糊 filter 触发无关包编译。高风险或公共边界改动完成后，再扩大到 cargo check、相关集成测试、Clippy、数据库矩阵或前端检查。

6. Review comment 工作流

收到 Greptile、CodeRabbit、Gemini 或人工 review comments 时：

1. 对照当前 branch、HEAD、路径和符号逐条验证。
2. 标记真实问题、已解决问题和误报。
3. 只修当前仍成立的真实问题。
4. 按相关性分批修改，每批完成后编译或测试。
5. 最终列出处理结果和验证证据。

review 引用的路径或符号不存在时，先确认评论是否来自其他 revision，不为满足机器人而修改正确代码。

7. 什么时候需要确认

以下情况向 1547 确认：

• 用户可观察行为存在多个合理但不兼容的定义
• 当前任务与项目契约冲突
• Drive 与 Forge 的所有权无法从现有代码和文档判断
• 需要破坏数据、修改公开协议、引入不可逆 migration 或扩大 issue 范围
• 权威规范、SDK 或当前实现彼此矛盾，且不同选择会改变结果

路径、命名、测试入口和相邻实现能够从仓库确定时，直接按现有模式执行，不为低风险细节增加交互。

不属于确认点的事项包括：

• 是否继续执行已经开始的任务
• 是否补齐契约要求的测试
• 是否更新同一内部 API 的全部调用方
• 是否同步当前改动直接影响的文档和生成产物
• 是否修复由本次修改直接造成的编译、lint 或测试失败
• 在已经确定的架构内选择与现有代码一致的命名和文件位置

8. 文档和生成产物同步

• 修改项目长期边界：更新项目契约或架构文档。
• 修改子系统行为：更新对应 design/、api/ 或 testing/ 页面。
• 尚未落地或仅保留历史背景：写入 records/ 并标明状态。
• 修改 OpenAPI schema：导出 OpenAPI，再运行前端 API 生成流程并审查 diff。
• 不手动编辑生成文件，也不把生成产物当作设计事实的唯一来源。

9. 自迭代闭环

每个实质性任务结束前，检查这次工作是否暴露了可重复的工程摩擦：

• 同一个事实是否被反复搜索或确认
• 一步可完成的修改是否被旧 facade、重复入口或手工流程拆成多步
• task routing 是否缺少准确入口或验证命令
• 测试 setup、fixture、生成流程或检查命令是否存在可消除的重复劳动
• 当前文档是否诱导了错误的所有权、实现路径或验收范围

发现问题后按根因更新：

根因	优先改进位置
长期产品或架构边界不清	project-contract.md 或对应架构/design 文档
不知道从哪里开始	task-routing.md
执行步骤低效或重复	本工作流、仓库脚本或 CI
测试搭建重复且容易出错	共享 test support / fixture
旧内部 API 造成多步迁移	删除薄兼容层，直接迁移全部调用方

小而明确、能在当前变更中验证的改进直接完成。较大的独立改进应形成明确 issue 或设计记录，写清触发问题、目标形态和验收条件，不留下模糊的“以后优化”。

只沉淀至少满足以下条件之一的经验：

• 已经重复出现
• 明显会影响多个后续任务
• 涉及数据、协议、安全或长期所有权边界
• 能通过代码、测试或构建结果验证

一次性环境故障、未经证明的猜测和只对当前临时 checkout 有效的细节不进入长期规则。

10. 交付标准

结束前检查：

git diff --check
git status --short

最终结果应说明：

• 改变了什么行为或契约
• 修改集中在哪些边界
• 实际运行了哪些验证
• 哪些验证因环境或范围未运行
• 是否保留了无关的现有工作区改动

只有实际运行完成的命令才算当前证据。正在运行、被中断或来自旧 checkout 的结果不能写成已通过。