Agent 开发工作总规则
核心总纲
功能正确优先。能治理AI生成代码的只有AI；禁止无节制堆砌代码，持续治理历史技术债务。
上下文过大会显著提升模型幻觉，因此严格限定工作范围，只处理当前职责模块，不跨模块修改无关代码。
1｜编码铁律
- 在完成业务功能前提下：以精简并删除历史冗余代码为荣，以堆砌重复实现为耻。
- 禁止复制粘贴重复逻辑，相同逻辑必须抽成公共函数/工具类。
- 废弃、无效、被替代的旧代码，不要注释保留，直接删除；历史版本交由Git版本回溯。
- 所有代码注释统一使用中文。注释描述业务意图，不要复述代码本身逻辑。
- 不写过度炫技晦涩代码，优先保证可读性，便于人类研发阅读理解维护。
- 修改代码最小化变更范围，不随意格式化无关文件、不改动职责外模块。
2｜重构与删减工作模式
- 迭代新功能的同时，主动识别当前模块内冗余、重复、坏味道代码，同步清理，不要堆积债务。
- 重构不能改变原有业务行为，重构前后业务表现保持一致。
- 发现重复实现逻辑，优先合并收敛，而不是新增一套实现。
- 代码冲突上涨属于异常；理想状态：持续删减冗余，新增代码可控。
3｜需求基准：PRD 为唯一可信源
- 所有开发、测试、验收，严格以项目PRD文档作为受控基准。
- PRD描述模糊的地方，不自行脑补业务逻辑；标记疑问，等待明确需求后再编码。
- 不得脑补不存在的业务场景，脑补会直接带来AI幻觉Bug。
4｜专职Agent 职责边界规则（多Agent协作）
- 当前Agent仅允许操作分配给自己的业务模块，不触碰其他模块代码。
- 仅加载本模块相关上下文、架构契约文档、PRD对应章节；禁止加载整个百万行完整仓库上下文。
- 模块之间只依赖对外定义输入输出契约，禁止跨模块深入内部实现。
- 如果发现业务需要跨模块改动，输出变更建议，交由对应模块Agent处理，不越权修改。
- 职责粒度越细，模型输出质量越高；测试覆盖不足，代表模块拆分还需要进一步细化。
5｜Bug修复约束（重点，防止修Bug引入更多Bug）
- 修复Bug时，禁止大范围重写周边代码，限定修复范围。
- 修复完成必须考虑回归：覆盖原有故障场景，同时不能破坏原有正常流程。
- 不能只凭自己理解写测试；优先复用：PRD用例、人工归档真实故障样本、Jira历史缺陷。
- AI自身测试存在幻觉，不相信AI自测即100%正确；必须参考人类真实问题样本做校验。
- 出现旧Bug反复复现，说明缺少对应的自动化回归用例，需要补充。
6｜测试相关约束
- 优先文档化阻塞性核心测试用例；AI无法自动化执行的硬件/人工操作明确标注出来，避免自动化任务卡死。
- 自动化测试输入来源：PRD文档、核心阻塞用例、人类真实故障样本、历史缺陷清单。
- 自动化Agent自行拆解实体、属性、操作，组合业务流程生成测试场景。
- 多专职Agent各自运行独立测试实例，测试场景结果求并集提升整体覆盖率。
- 非功能性测试（安全、性能、稳定性）不能省略，需要单独设计场景。
7｜日志与故障元数据约定
- 关键流程埋入日志，输出完整元数据：版本号、设备SN、入参出参。
- 便于对接IM机器人、缺陷工单系统，沉淀真实人类问题，用来收敛AI幻觉。
8｜输出格式约定
- 改动代码块完整输出，不要片段省略。
- 重要变更附带简短中文说明：改了什么、为什么改、风险点。
- 如果发现PRD矛盾、逻辑风险、潜在幻觉点，明确列出风险提示。