AGENTS.md

Codex 代理基础约束（AGENTS）

1. 适用范围与覆盖规则

本文件定义 Codex 的全局默认规则。

本文件中：第 2 章为硬规则；第 3 章为默认策略。冲突处理见 1.1。

1.1 规则优先级（冲突处理）

当多份规范同时存在且出现冲突时，按以下优先级（从高到低）执行：

1. 用户当次明确指令（针对当前任务的具体要求）
2. 项目级规范（同一层级：项目内 AGENTS.md、CONTRIBUTING.md、README.md、.github 内规范、团队/仓库政策等）
3. 全局默认规范（如全局 AGENTS.md）
4. 其它默认习惯或通用最佳实践

同一优先级内的冲突处理：

• 更具体（更贴近当前任务/目录/工具链/语言）的规则优先于更泛化的规则。
• 若仍无法判定，以更保守（更少副作用、风险更低、约束更严格）的一条为准，并在回复中说明取舍理由；必要时先向用户确认。

2. 硬规则

2.1 沟通与称呼

• 日常对话使用中文。
• 当前会话用户为 DCjanus（邮箱：DCjanus@dcjanus.com）。
• 默认简洁回答，优先直接回答用户问题；除非用户明确要求，否则不要展开背景、替代方案或额外建议。

2.2 破坏性更新（Breaking Change）

• 如果改动会导致既有用法失效或行为变化，必须在回复中显著标识为 breaking change，并清晰说明影响范围（哪些用法/接口/行为变了）与迁移建议（用户该怎么改）。

2.3 依赖管理

• 优先使用官方命令获取最新版依赖。
• 禁止手动修改项目描述文件或锁文件。
• 一次性临时 Python 统一使用 uv run (--with <外部依赖包>)* python ...（* 表示 0~N 次），不要直接调用系统 python/python3。

3. 默认策略

3.1 长期质量

• 优先选择能提升长期可维护、可理解、可扩展的方案；避免为了快速完成任务引入临时权衡/一次性 hack 或长期复杂度。
• 除非用户当次明确要求，否则不为历史接口/行为做兼容层；如确需引入额外复杂度，先说明成本与替代方案，再执行。
• 修复 BUG 时，是否补测试应遵循项目既有测试风格与维护成本做法。

3.2 文档与 Markdown 风格

• Markdown 链接优先使用 [描述](URL) 形式，避免裸露 <URL>；在 Markdown 中引用相对路径文件时，优先使用链接形式（链接文本仅保留文件名、路径放在链接目标里）。除非有歧义或明确要求，否则不要用 inline code 引用路径。
• 输出文件路径只写纯路径/文件名，不附加 :行号 或 #L行号；仅当用户明确要求或任务必须精确定位（如代码评审/报错排查/同名文件消歧）时附加行号；新生成且需直接打开的文件一律不加行号。

3.3 依赖版本策略

• 使用最新可用版本；非必要不手动固定版本号。

3.4 Codex 安装偏好

• Codex CLI 安装命令：npm i -g @openai/codex@alpha。

3.5 补测试的执行顺序

• 核心原则：先写失败测试，再修复问题。不要先改实现，再回头补测试。
• 推荐顺序：
  1. 先补一个能稳定复现当前问题、且在修复前会明确失败的测试。
  2. 先运行该测试，确认它确实失败，且失败点就是当前要修复的问题。
  3. 再修改实现，使该测试通过。
  4. 修复完成后保留该测试，作为后续回归保护。
• 示例：
  • 当前 BUG：空字符串输入时错误返回 200
  • 正确做法：先补一个“输入空字符串，预期返回 400”的测试
  • 验证顺序：先看到该测试失败，再修改实现，最后确认该测试通过
• 例外：若问题无法通过自动化测试稳定复现，或补测试成本显著高于收益，应在回复中明确说明原因，不能直接跳过而不交代。

4. 操作流程

4.1 开始修改前

• 只要要修改文件内容，开始动手前先读取与当前改动相关的仓库规范；若仓库另有要求，以仓库要求为准。
• 优先检查：相关目录下的 CONTRIBUTING.md、README.md，以及与当前改动直接相关的其它说明。
• 读完后再开始修改；若仓库对改动流程、测试方式、文档更新、提交粒度或分支策略有明确要求，先按要求规划，再执行修改。

4.2 Git 提交相关操作

• 涉及 git commit、git push、分支命名、提交信息或提交前整理时，优先使用非交互命令，并遵循仓库内对应约定。
• 在正式提交前，复核本地状态是否与仓库要求一致，包括改动方式、当前分支、暂存内容、提交标题/正文、测试、文档与变更说明。

4.3 GitHub / GitLab 交互

• 涉及 GitHub、GitLab 等代码托管平台资源或交互（如 repo/project、issue、PR/MR、comment、release、workflow、wiki 等）的查看、更新或创建时，优先使用对应平台的官方 CLI 或 API，并尽量保持非交互。

4.4 添加/更新依赖

• 使用对应生态官方命令：
  • Rust：cargo add <crate>
  • Python：uv add <package>
  • 前端（npm）：npm install <package>
  • 前端（pnpm）：pnpm add <package>
  • 前端（yarn）：yarn add <package>
  • Go：go get <module>
• 依赖变更可复现（通过 lockfile/工具链保证）；不手工编辑描述文件或锁文件。