Imported from cpc-lib/demo (
springboot-payment/payment-demo-go-dm/AGENTS.md). Install upstream withnpx skills add cpc-lib/demo --skill payment-demo-go-dm. Copyright stays with the author.
Payment Demo Agent Rules
本文件是仓库级协作规则。任何代码、测试、文档、spec 变更都要先按这里分类，再决定是否直接实现。
1. Issue 分类
| 分类 | 判定标准 | 处理规则 |
|---|---|---|
| 局部 bug | 期望行为已被现有 spec、测试或兼容承诺定义清楚；影响面局限在单个职责块 | 复现问题，做最小修复，补回归测试，同步受影响文档和 spec |
| 设计变更 | 新功能、架构调整、状态机变化、跨模块职责迁移、运行规则变化 | 先写或更新 spec/planned/，经确认后再实现 |
| 公共接口或兼容影响 | HTTP 路径、响应结构、状态值、DB schema、配置字段、MQ 名称、前端调用契约、第三方回调响应变化 | 先更新 spec 的契约和兼容影响；必须补特征测试和迁移/兼容说明 |
| 多 issue 同根因 | 多个问题共享同一状态机、幂等、配置、接口或数据模型根因 | 暂停逐个补丁，先抽象统一 spec 和处理范围 |
分类不确定时，按“设计变更”处理，先对齐 spec，再动代码。
2. 分支命名
bug-fix/<short-topic>：局部 bug 修复。feature/<short-topic>：新能力或设计变更。refactor/<short-topic>：行为不变的结构调整。update/<short-topic>：文档、spec、配置、测试治理。
分支名、提交信息、PR 标题不要包含 agent 名称、厂商名、生成标记或个人签名。
3. 测试要求
- 行为变更必须先有能失败的测试，再做最小实现。
- 安全重构必须保持现有特征测试全绿。
- 涉及 DB、Redis、RabbitMQ、配置文件、环境变量或全局状态的测试，必须使用临时隔离并在测试后 reset。
- 渠道回调、错误/拒绝路径、事件消息、日志/审计字段属于契约面，相关改动必须测试。
- 当前 Go 后端的基础验证命令是：
cd payment-demo-go
go test ./...4. Spec 对账规则
spec/是项目状态账本，不是一次性文档。- 动手前先查
spec/README.md，确认相关 spec 是planned、implemented、governance还是缺失。 - 新功能、公共接口变化、兼容变化、状态机变化，必须先进入
spec/planned/。 - 已实现且测试锁住的行为，放入
spec/implemented/。 - 废弃、延后、被替代的设计，移动到
spec/archived/并说明原因。 - 只部分落地的 spec 不得标为
implemented；必须保留剩余验收标准。 - 实现、测试、文档、示例、兼容说明和 spec 不一致时，不得宣称完成。
5. 完成定义
一个工作项只有同时满足以下条件才算完成：
- 实现符合对应 spec，或者明确说明 spec 不适用。
- 测试覆盖新增或被保护的行为，并且相关测试全绿。
- 文档、示例、前端调用、配置说明与代码一致。
- 兼容影响已写清楚，包括 HTTP、DB、状态值、配置、MQ、第三方回调。
spec/README.md中的状态索引已同步。
6. PR 合并前 Spec 对账清单
- 本 PR 关联了已有 spec，或说明为什么不需要 spec。
- 如有设计/公共接口/兼容影响，相关 spec 已在
planned/或implemented/中更新。 - spec 的状态、契约、验收标准、实现锚点、兼容影响与代码一致。
- 特征测试或回归测试覆盖了本 PR 触碰的行为面。
-
go test ./...已在payment-demo-go/下通过，或明确列出阻塞原因。 - 前端 API 封装、README、配置样例没有与后端契约冲突。