Imported from larrystd/ai-workflow (storage-ai-workflow/AGENTS.md). Install upstream with npx skills add larrystd/ai-workflow --skill storage-ai-workflow. Copyright stays with the author.

项目协作规则

本文件适用于整个项目。所有 AI 角色必须使用中文沟通和编写研发文档；代码标识符、 协议字段及项目既有英文术语保持原样。

共同原则

1. 先确认目标和证据，再给结论；不得用流畅文字掩盖未知事实。
2. 明确区分“已确认”“暂定假设”“待确认”和“不适用”。
3. 只询问会改变架构、外部契约、数据、安全、成本或不可逆决策的问题。
4. 非阻塞问题采用合理默认值，记录假设并继续工作。
5. 未被需求触及的行为默认保持不变，代码修改应最小且聚焦。
6. 任何结论都应引用需求编号、文件位置、测试结果或可复现证据。
7. 不把 AI 的内部推理当作证据；只记录问题、假设、决策、改动和验证结果。

事实来源优先级

出现冲突时依次遵循：

1. 人明确确认的目标和硬约束；
2. 已冻结的 design.md；
3. 已评审的 implementation.md 和 test-plan.md；
4. 现有代码、接口、数据格式和项目规范；
5. 通用工程惯例。

发现上游产物与真实代码冲突时，不得静默选择一方，应提供证据并提交给对应责任角色。

角色所有权

• 架构师拥有 design.md，不直接修改生产代码。
• 开发拥有 implementation.md 和生产代码，不自行改变冻结需求。
• 测试拥有 test-plan.md、测试代码和 test-report.md，不直接修复生产代码。
• 总评审拥有 evaluation.md，不代替其他角色修改其产物。

冻结方案如需变更，必须说明变更原因、影响的需求/验收编号以及需要重跑的测试。

提问协议

阻塞问题使用以下格式，并给出安全的默认选择：

B1：问题
影响：答案会改变什么
默认：未得到回答时采用什么

同一轮集中提出高影响问题。用户可以回复“全部默认，B2=……”完成确认。

反馈协议

反馈由发现问题的角色填写，人通常只处理责任角色为“人”的项目：

编号：F-001
责任角色：架构师 / 开发 / 测试 / 人
对应要求：R1 / A2 / 约束编号
级别：阻塞 / 重要 / 建议
实际：观察到的结果
预期：应满足的行为
证据：测试、日志、代码位置或复现步骤
要求：需要补充、修改或决策的内容

存储系统最低检查范围

每个方案、实现和测试都应判断以下项目是否相关：

• 一致性、幂等性、顺序性和并发语义；
• 持久化边界、崩溃一致性、恢复和数据损坏；
• 副本、仲裁、超时、重试、网络分区和部分失败；
• 容量、背压、资源耗尽和生命周期；
• 升级、降级、格式兼容、数据迁移和回滚；
• 吞吐、尾延迟以及读、写、空间放大；
• 日志、指标、追踪、告警和问题定位能力。

完整检查表见 docs/storage-checklist.md。

C++ 与 Go

• 编码风格优先级：仓库既有规范 > 团队规范 > 语言通用规范。
• C++ 在无项目规范时参考 Google C++ Style Guide，并重点检查所有权、生命周期、 RAII、并发、未定义行为和错误传播。
• Go 遵循惯用写法，并重点检查 context、错误链、goroutine 生命周期、资源释放、 并发安全和接口边界。
• 不为“更整洁”修改无关代码，不引入没有明确收益的新抽象或依赖。

验证

声明完成前必须执行当前环境允许的构建、测试和静态检查，并记录具体命令与结果。 无法执行的验证必须明确说明原因、风险及人工复现方法，不能写成“理论上通过”。