# AGENTS 协作说明

本文件用于约束在本仓库内协作开发的 AI Agent 与开发者行为。

## 1. 基本原则

- 所有沟通、注释、说明文档默认使用中文。
- 优先保证系统稳定性，避免影响现有业务流程。
- 修改应遵循“最小改动原则”，不要做无关重构。
- 任何涉及状态流转的改动，必须明确前置状态、目标状态与异常处理。

## 2. 开发规范

- 保持与现有代码风格一致（命名、缩进、异常处理方式）。
- 优先复用已有枚举、服务与仓储方法，避免重复实现。
- 业务常量应放入配置或枚举，不允许硬编码魔法值。
- 涉及批量处理时，优先考虑批量查询/批量更新，避免 N+1 查询。

## 3. 状态与事务

- 涉及“任务创建 + 库存状态 + 货位状态”联动时，必须保证一致性。
- 若任一关键步骤失败，应返回明确错误信息，不能静默失败。
- 对并发场景保持敏感，避免重复创建任务或重复分配库存。

## 4. 接口与集成

- 对接外部系统（如 WCS）前，先确认请求模型与接口约定（单条或批量）。
- 外部通知失败不应阻塞主流程时，必须记录可追踪日志。
- 接口地址优先配置化，避免写死环境地址。

## 5. 验证要求

- 完成改动后至少执行一次可用的编译或测试验证。
- 在提交结果时，说明：
  - 修改了哪些文件
  - 关键逻辑变更点
  - 验证命令与结果

## 6. 禁止事项

- 未经明确要求，不得删除或回滚他人已有改动。
- 不得使用高风险命令（如强制重置）破坏工作区。
- 不得在未验证的情况下宣称“已修复”或“可上线”。

## 7. 建议工作流

1. 先阅读相关上下游代码与枚举定义。
2. 明确输入、处理、输出以及状态变化。
3. 实施最小改动并补充必要注释。
4. 编译/测试验证并输出结果摘要。