galaxybruce

通用AGENTS.md

角色与输出规范

• 所有回答必须使用中文表述
• 所有回复、思考过程及任务清单，均须使用中文
• 固定指令：Implementation Plan, Task List and Thought in Chinese
• 提供代码时，为关键逻辑和可能造成理解困难的部分添加简明的中文注释
• 生成的代码超过 20 行时，优先考虑是否可以进行适当的抽象或聚合

---

一、核心设计原则

1.1 SOLID 原则

• 所有生成/修改的 OOP 代码（类、接口、抽象类、方法、模块）必须严格遵循 SOLID 五大原则
• 每次输出代码前，自省检查是否违反 SOLID，并在思考过程中写明对应原则
• 自检清单：
  • S：这个类是否只有一个职责？能否用一个句子描述其职责？
  • O：新增功能是否需要修改已有代码？还是可以通过扩展实现？
  • L：子类能否完全替换父类而不改变程序正确性？
  • I：接口中的方法是否都被实现者需要？是否存在胖接口？
  • D：高层模块是否依赖抽象接口，而非具体实现？

1.2 设计原则

• 高内聚、低耦合：模块内部职责高度集中，模块之间依赖最小化
• DRY（Don’t Repeat Yourself）：避免重复代码，提取公共逻辑为可复用函数或工具类
• KISS（Keep It Simple, Stupid）：保持简单，避免过度设计
• 禁止 God Class、超长方法、重复逻辑：类应职责单一，方法应短小精悍

1.3 思维方法

• 第一性原理（First Principles Thinking）：立足于基本原理剖析问题，而非依赖类比或既有经验
• 事实为本：以事实为最高准则，若有任何谬误，恳请坦率斧正

---

二、开发工作流

阶段一：需求分析与方案设计

• 渐进式开发：通过多轮对话迭代，明确并实现需求
• 前置调研：在着手任何设计或编码工作前，必须完成前期调研并厘清所有疑点
• 结构化流程：严格遵循以下顺序——
  1. 构思方案：输出方案文档（含设计思路、技术选型、影响范围、潜在风险）
  2. 提请审核：输出审核确认记录（通过/修改意见）
  3. 分解为具体任务：输出可执行任务清单（含优先级、依赖关系、预估工时）

阶段二：编码与重构

• 小步重构：每次只做一个小改动，然后进行测试验证
• 频繁提交：保持代码在任何时候都是可工作状态
• 每次重构的目标明确，一次只解决一个问题

阶段三：测试与审查

• 测试保障：
  • 重构前确保有足够的测试覆盖，如测试不足应先补充测试
  • 每次修改后运行测试，确保重构不改变原有行为
  • 测试通过后方可进行下一次重构迭代
• 代码审查：
  • 重构完成后进行代码审查，确保质量
  • 审查重点关注：逻辑正确性、性能影响、代码可读性
  • 重大问题应在审查中暴露并修复，避免合入主分支

---

三、代码可读性规范

3.1 命名约定

• 使用有意义的、描述性的名称，名称应能准确表达变量/函数/类的用途
• 遵循项目或语言的命名规范（如 camelCase、PascalCase、snake_case）
• 避免缩写和单字母变量名，除非是约定俗成的场景（如循环计数器 i、j，坐标 x、y）

3.2 代码组织

• 相关代码放在一起：按功能模块组织文件和目录结构
• 函数只做一件事：函数长度建议控制在 20 行以内，最多不超过 30 行
• 保持适当的抽象层次：高层函数调用低层函数，避免在同一函数中混用不同抽象层次

3.3 注释与文档

• 为公共 API（public 类/方法）编写注释，为关键/复杂逻辑添加解释性注释，简单 getter/setter 可省略
• 注释格式遵循行业内标准格式（如 Javadoc、Doxygen 等）
• 注释应该解释”为什么”，而不是”做什么”（代码本身应能说明”做什么”）
• 为公共 API 说明：函数用途、参数含义、返回值、可能抛出的异常
• 更新注释以反映代码变化：代码修改后同步更新相关注释，避免注释与代码脱节

---

四、性能优化规范

4.1 内存优化

• 避免不必要的对象复制或克隆：优先使用引用传递，仅在必要时（如防御性复制）才进行显式克隆
• 避免不必要的对象创建：重用对象，使用对象池或缓存机制
• 及时释放不再需要的资源：显式关闭文件句柄、数据库连接、网络连接等
• 注意内存泄漏问题：关注事件监听器未解绑、定时器未清理、集合无限增长等常见泄漏场景
• 避免多层嵌套，提前返回：使用卫语句（Guard Clauses）减少嵌套层级，保持代码扁平化

4.2 计算优化

• 避免重复计算：将重复使用的计算结果缓存为变量
• 使用适当的数据结构和算法：根据访问模式选择最优容器（如查找频繁用哈希表，有序遍历用平衡树）
• 延迟计算直到必要时：使用懒加载（Lazy Initialization）避免提前执行高开销操作

4.3 并行优化

• 识别可并行化的任务：对无依赖关系的任务使用并行处理
• 使用适当的并发控制机制：根据场景选择合适的并发策略（如线程池、协程、异步 I/O）
• 避免不必要的同步：减少锁的粒度，使用无锁数据结构或原子操作
• 注意线程安全问题：确保共享状态在并发环境下的正确性

---

五、绝对禁止

• 禁止输出未经静态检查或明显无法运行的代码
• 禁止在未厘清需求前进行设计或编码
• 禁止在代码中硬编码敏感信息（密钥、密码、Token、数据库连接串）
• 禁止删除或修改现有功能而不保留向后兼容性
• 禁止创建 God Class 或超过 30 行的超长方法