codex-agents-template AGENTS.md

AGENTS.md

Scope and instruction priority

• 本文件用于指导 Codex 在当前目录及其子目录中的工作方式。
• 若更深层目录存在额外的 AGENTS.md，优先遵循更靠近被修改文件的说明。
• 若本文件与用户当前明确指令冲突，优先遵循用户当前指令。
• 若项目 README、贡献指南、测试配置或已有代码风格与本文件不同，优先遵循项目内更具体的约定。

Default language

• 默认使用中文与我沟通。
• 代码、注释、文档、提交信息优先遵循项目既有约定；若项目没有明确约定，则保持一致性并避免混用风格。

Working method

• 先理解需求和上下文，再进行修改。
• 对中等及以上复杂度的任务，先给出简短计划，再开始实施。
• 优先做最小必要改动，避免无关重构。
• 如果存在多个实现路径，优先选择与现有架构最一致、最容易验证、最容易 review 的方案。
• 不要在没有阅读相关文件、配置、测试或报错信息之前直接大改代码。
• 不要静默猜测需求、接口、文件位置或环境配置。
• 若信息不完整：
  • 对低风险、可回退的小改动：先说明当前假设，并在该假设下继续推进。
  • 对会影响架构、数据、依赖、环境、CI/CD 或大量文件的改动：先提出问题，等待确认。
• 如果存在多个合理解释，先列出选项和取舍，不要悄悄选择其中一个。
• 如果有更简单、更局部的方案，优先说明并采用；必要时可以提醒我需求可能过度复杂。
• 对多步骤任务，计划中尽量写清每一步的验证方式。

Platform and language preference

• 我主要在 Windows 环境下开发 Python。
• 其他语言和技术栈通常不是重点，除非项目本身明确要求。
• 给出命令、路径、环境说明时，优先使用适配 Windows 的写法，不要默认使用 Unix/macOS shell 习惯。
• 如果必须给出 Unix/macOS 命令，应明确标注其适用环境，并尽量同时给出 Windows PowerShell 等价写法。

Python environment rules

• 处理 Python 项目时，先识别项目当前使用的解释器、依赖管理方式和虚拟环境。
• 若仓库、文档、配置或目录结构已经明确虚拟环境约定，则按现有约定执行。
• 若环境约定不明确，在运行安装、测试、脚本、调试命令之前，先向用户确认应使用哪个虚拟环境。
• 不要默认使用系统全局 Python。
• 优先使用与当前解释器绑定的命令形式，例如：
  • python -m pip
  • python -m pytest
• 运行依赖安装、测试、脚本时，优先确保 python、pip、pytest 来自同一虚拟环境。
• 如果测试或脚本执行失败，需要区分：
  • 代码逻辑问题
  • 缺少依赖
  • Python 版本不匹配
  • 虚拟环境选择错误
  • 路径或系统环境变量问题

Code modification rules

• 保持与现有代码风格、命名方式、目录组织一致。
• 优先复用已有模块、工具函数和模式，不随意新增平行实现。
• 不要无理由引入新依赖；若必须引入，先说明原因、替代方案和影响范围。
• 不要顺手修改与当前任务无关的文件。
• 非必要不要进行大规模重命名、批量格式化、跨模块搬迁或无关清理。
• 修复问题时优先解决根因，不只处理表面现象。
• 每一处改动都应该能追溯到本次任务目标；如果某行改动无法解释其必要性，就不要改。
• 能补测试时优先补与本次改动直接相关的测试。
• 只有当类型、边界处理、错误信息或文档与本次改动直接相关时，才补齐；不要借机扩大改动范围。
• 如果发现无关的坏味道、死代码或潜在问题，可以在结果中指出，但默认不要直接修改。

Debugging rules

• 修 bug 时先确认复现路径、触发条件和可能根因，再进行修改。
• 尽量通过日志、测试、调用链、类型信息、配置文件和错误信息来验证判断，而不是仅凭猜测修改代码。
• 若问题本质上是环境、依赖或配置问题，要明确指出，不要误报为纯代码缺陷。
• 若无法稳定复现，要明确写出当前判断依据和未确认点。
• 不要为了“看起来修好了”而吞掉异常、扩大 try/except，或加入掩盖根因的兜底逻辑。

Validation rules

• 开始实现前，先把任务转化为可验证目标：
  • 修 bug：优先写出或运行能复现问题的最小测试/脚本，再修到通过。
  • 加功能：明确正常路径、关键边界和至少一个失败路径的验证方式。
  • 重构：改动前后都应保持现有测试通过，除非任务明确要求改变行为。
• 改动完成后，尽量运行与任务最相关的验证命令，例如测试、lint、type check、build 或最小复现脚本。
• 若因为环境、权限、依赖或时间成本无法执行某项验证，要明确说明原因。
• 输出中必须区分：
  • 已执行并通过
  • 已执行但失败
  • 未执行
• 不要把“理论上应该可以”表述成“已经验证通过”。
• 不要把“代码已修改”当成完成；完成标准是相关验证通过，或明确说明为什么无法验证。