AGENTS.md

全局 Agent 规则

本文件用于约束自动化代理在本机工作区中的默认工作方式，并将 Superpowers 作为主工作流体系进行选择性激活。

指令优先级

• 指令优先级从高到低：
  1. 当前会话中用户的明确要求
  2. 仓库自身的规则、文档与约定
  3. 本 AGENTS.md 的任务分流与流程规则
  4. 相关 Superpowers / skill 的流程定义
• 默认以 Superpowers 作为主工作流体系。
• 但不默认启用 full Superpowers。
• 对不同任务类型，按需激活对应的 Superpowers skills。
• 本文件保留个人硬门禁、环境约束、交付偏好与沟通方式，不再重复展开各 skill 已定义的全部细节。
• 若本文件某项规则被明确视为“个人硬门禁”，则即使使用 skill，也仍需满足。
• 对于仅涉及审查、分析、解释或方案讨论而不修改仓库文件的任务，可不进入完整实现流程，但仍应保持推理清晰、结论可追溯。
• 如果用户明确要求 continue nonstop，则默认持续推进，直到满足验收标准或出现真实阻塞。

默认工作流原则

最短路径原则

• 默认采用“满足质量要求的最短路径”。
• 能直接完成并验证的，不升级为更重流程。
• 能使用轻量版 planning 完成的小任务，不升级为重文档流程。
• 能使用单一专项 skill 解决的问题，不扩展为 full Superpowers。
• 流程的目标是降低返工与风险，而不是增加形式成本。

Superpowers 主体系原则

• Superpowers 是默认主工作流体系，但不是默认全量流程。
• 对实现类任务，原则上必须先完成需求澄清与计划拆分。
• 对只读任务，不强制进入实现流程。
• 对 review、完成前验证、debug、前端设计等环节，使用对应的 Superpowers skills。

任务分流模型

只读任务

以下任务可直接处理，不强制进入实现流程：

• 分析
• 解释
• 架构说明
• 代码阅读
• 纯信息型问答
• 不修改文件的只读审查

若任务属于真实问题排查，但尚未进入修改，可直接优先使用：

• systematic-debugging

实现类任务

以下任务原则上必须先完成需求澄清与计划拆分：

• brainstorming
• writing-plans

适用：

• 新功能
• bug 修复
• 行为变更
• 重构
• 页面 / 组件 / API / 脚本实现
• 数据处理逻辑改动

默认流程：

1. 用 brainstorming 澄清目标、边界、约束、验收标准
2. 用 writing-plans 形成实现计划
3. 再进入具体实现
4. 根据任务性质按需调用后续技能

轻量版 planning

• 对小任务，允许采用轻量版 brainstorming 与 writing-plans
• 可在当前对话内完成，不强制产出长文档
• 最小集合至少应明确：
  • 目标
  • 边界
  • 风险
  • 验证方式
• 只有当任务规模、风险或不确定性明显上升时，才升级为更重的 planning 流程

Debug 类任务

以下任务优先执行：

• systematic-debugging

适用：

• traceback
• error
• exception
• 数据异常
• 运行时异常
• 协议异常
• UI 显示与数据不一致
• 根因不明的问题

说明：

• 对真实 bug / 异常排查，不直接猜测式修补
• 先做根因分析，再决定修复方案

Review 类任务

以下任务必须执行：

• requesting-code-review

适用：

• review
• code review
• reviewer output
• spec compliance
• 合并前审查
• 阶段性交付审查

若任务是在处理 review 反馈，则使用：

• receiving-code-review

完成前验证

在声称以下状态前，必须执行：

• verification-before-completion

适用：

• 完成
• 已修复
• 可提交
• 可合并
• 测试通过
• 验证通过

前端任务

涉及以下内容时，必须执行：

• ui-ux-pro-max

适用：

• UI
• UX
• 页面布局
• 组件视觉
• 图表呈现
• 交互设计

流程升级规则

若在执行过程中发现以下任一情况，应升级到更重流程：

• 影响文件、模块或系统边界超出初始判断
• 出现公共 API、schema、持久化、并发或共享逻辑风险
• 用户真实需求仍不清晰
• 当前验证手段不足以覆盖风险
• 任务已从局部修复演变为中大型实现或重构

流程降级规则

若任务满足以下条件，可降级到更轻流程：

• 改动局部且边界清晰
• 不涉及共享核心逻辑
• 验证手段简单直接
• 补长计划或补测试的成本显著高于风险收益
• 问题已收敛为单点修复或局部调整

推进与验证

Step by Step Reasoning Workflow

• 如果需求模糊，应先澄清目标、约束、验收标准与边界条件。
• 为跟踪进度，请维护一个可见的任务列表。
  • 在其中列出先前任务的状态和待办事项，以及项目所需的计划行动（对于简单问答可以跳过）。
  • 对多步骤任务，任一时刻仅保留一个 in_progress 步骤。
  • 开始新步骤前及时标记已完成步骤，并避免重复输出冗长计划。
• 回答时优先给出最相关结论，再补背景、依据与权衡。
• 在任务推进过程中，遇到新信息时应主动修正先前判断中的错误或不一致。
• 多步任务优先使用 update_plan 或同等方式维护高层进度。

Environment

• 环境初始化优先遵循仓库文档与项目级 AGENTS。
• 若无明确要求，则按当前任务所需执行最小准备，不做额外环境工程。

Command Verification Rules

• 不得虚构已运行的命令、退出码或验证结果。
• 如果一个关键验证命令无法执行，必须明确说明原因。
• 在缺少验证证据时，不得声称“通过”“完成”“可提交”“可合并”。
• 如果用户或仓库要求特定验证命令，应优先执行该命令。
• 若关键验证被阻塞，应如实报告当前状态，并根据阻塞程度决定是否继续实现或先与用户确认。

Change Delivery Gate

在声明完成、准备 commit、准备 push、准备发起 PR 之前，应满足以下要求：

1. 已完成与本次改动直接相关的验证，并如实报告结果
2. 已按任务类型完成对应质量门禁：

• 需要 review 的已 review
• 需要 completion verification 的已验证
• 需要测试保护的已按测试策略执行

3. 若仓库要求更重验证，例如构建、集成测试、冒烟测试或特定脚本，应优先遵循仓库规则
4. 若关键验证无法执行，必须明确说明原因，并降低完成度表述

测试策略判定（TDD 不是默认全量强制）

• test-driven-development 不作为所有实现类任务的默认强制技能。
• TDD 是否启用，不按任务大小机械决定，而按“行为影响、共享范围、回归风险、测试价值”显式判定。

A. 直接修改 + 定向验证

适用于：

• 文案、样式、布局微调
• 显然局部、低风险的小修复
• 不涉及公共 API、数据库 schema、共享核心逻辑、复杂状态机或并发语义
• 改动本身明显小于补测试成本

处理方式：

• 可直接修改
• 修改后必须执行与本次改动直接相关的定向验证
• 若已有相关测试，则优先运行相关测试；没有则不强制新增测试

B. 修复后补回归测试

适用于：

• 中小 bug 修复
• 有局部行为变化，但范围有限
• 容易补一个贴近问题表面的回归测试

处理方式：

• 可先修复再补测试
• 不强制严格 TDD
• 但应尽量补最贴近问题表面的回归测试

C. 必须使用 TDD

适用于：

• 新功能开发
• 明确行为变更
• 公共 API / contract 变更
• 跨模块共享逻辑修改
• 数据库 / 持久化 / 并发 / 状态机相关改动
• 高风险或高回归风险任务

处理方式：

• 必须调用 test-driven-development

质量门禁分层

Level 0：定向验证

• 适用于局部、低风险、小改动
• 直接修改后执行定向验证

Level 1：回归测试

• 适用于中小修复或局部行为变化
• 修复后补最贴近问题表面的回归测试

Level 2：TDD

• 适用于新功能、明确行为变更、共享逻辑或高风险改动
• 使用 test-driven-development

Level 3：Code Review

• 适用于阶段收尾、中高风险改动、合并前审查
• 使用 requesting-code-review / receiving-code-review

Level 4：Completion Verification

• 适用于所有准备声称完成、已修复、可提交、可合并的任务
• 使用 verification-before-completion

工程实践

快速上手

1. 阅读仓库上下文

• 查看相关文件、文档、最近提交
• 优先理解当前任务涉及的模块边界

2. 如用户提供 plan2go=<path>：

• 将该文件视为当前执行来源
• 执行过程中保持计划状态与进度同步

3. 若需要理解代码架构、调用链、数据流、入口与依赖关系：

• 优先使用 ace-tool 的 mcp__ace-tool__search_context
• rg / grep 只用于已知字符串的精确定位
• 若用户明确要求“找出所有出现位置”，可以先用 ace-tool 缩小范围，再用 rg 做枚举；但架构结论必须以 ace-tool 结果为准

文档维护

• 每当计划、目标、约束 / 假设、关键决策、经验教训、步骤或进度状态发生变化时，应同步更新相关计划文档。
• 复杂任务在开始实现前，应先评估工作量并拆分为范围受限、因果有序的子任务。
• 对项目中在开发、review、debug、验证过程中反复证明有价值的经验，应及时沉淀到项目级 AGENTS.md 或等效项目规则文档中，而不是只停留在当前对话。
• 经验沉淀的对象包括但不限于：
  • 常见根因与排查顺序
  • 特定模块的实现 / review 注意点
  • 特定验证入口、命令、超时或环境约束
  • 易误判、易回归、易重复犯错的问题
• 原则是让项目规则随着真实问题不断演进：一次有效经验，尽量避免团队或后续 agent 再次付出同样试错成本。
• 若项目已有经验模板，应尽量按统一模板沉淀，避免写成只在当前语境下才能理解的零散描述。
• 一个推荐的最小经验模板包括：
  • 标题：一句话概括问题 / 经验
  • 触发信号：什么现象说明又遇到了同类问题
  • 根因 / 约束：为什么会发生
  • 正确做法：以后应优先怎么处理
  • 验证方式：如何确认这次处理是对的
  • 适用范围：影响哪些模块、页面、链路或命令

执行原则

1. 先澄清，再实现；先缩小边界，再扩展范围。
2. 优先局部修改与最小充分实现，避免无关扩张。
3. 若任务复杂度上升，应及时升级流程，而不是硬撑轻流程。
4. 若任务收敛为局部改动，应及时降级流程，避免形式成本。

How to Report Bugs

• 清晰描述 bug 的现象、触发条件、预期行为与实际行为。
• 给出尽量稳定可复现的步骤。
• 说明真实影响范围与严重程度。
• 清晰解释真实世界中的后果，并关联影响严重程度和修复优先级。
• 收集有助于诊断 bug 的上下文信息，例如使用模式、错误信息、堆栈跟踪、日志、环境配置与版本。

Bug Fixing

• 真实 bug 默认优先使用 systematic-debugging
• 不直接猜测式修补，先确认根因，再决定修复策略
• 修复后按测试策略与验证门禁完成收口

Testing Standards

• 测试优先覆盖关键路径、边界情况和错误路径。
• 测试应具体、可读、稳定，避免脆弱测试。
• 对 assertEqual 类断言，优先遵循“expected 在前，actual 在后”。
• 是否需要 TDD，按全局测试策略判定，不在本节重复规定。

How to Write Code 如何编写代码

• 遵循 SOLID、DRY、关注点分离与 YAGNI。
• 命名应清晰、抽象应务实。
• 仅在关键或不直观逻辑处添加简短注释，避免注释噪音。
• 修改行为时，优先移除死代码和明显过时的兼容路径，除非用户明确要求保留。
• 明确处理边界条件，不要隐藏失败。
• 关注时间复杂度和空间复杂度，尤其在高 IO 或高内存路径上。
• 新增文档字符串时，保持简洁，说明目的、关键假设与实现理由。
• 除非没有更合理方案，不主动添加大范围 linter 抑制注释。

代码指标（硬性上限）

• 函数长度：≤ 50 行（不含空行）
• 文件大小：≤ 300 行
• 嵌套深度：≤ 3 层
• 参数数量：位置参数 ≤ 3
• 圈复杂度：每函数 ≤ 10
• 禁止魔法数字：提取为具名常量

Refactoring Standards

• 默认优先保持行为不变，再提升结构质量。
• 重构应在测试或验证保护下进行，必要时先补测试再重构。
• 如果检测到循环导入，请将共享逻辑提取到新工具模块或现有模块中，以保持依赖图无环。
• 对较大的重构，优先先拆分计划，再按步骤推进。
• 重构完成后，仍需回到 review 与 completion verification。

Safety Rules 安全规则

• 不要运行破坏性命令，例如 git reset，除非用户明确要求。
• 不要使用非 Git 工具操作 .git 目录。
• 避免危险删除命令，除非其作用范围被明确限制在临时产物。
• 不要将密钥、凭证、API Key 硬编码进源码文件。
• 数据库访问应使用参数化查询。
• 不要通过拼接不可信输入来构造 shell 命令或 SQL。
• 在系统边界校验并清理外部输入。
• 除非用户明确要求，否则不要终止非当前任务启动的进程。

沟通与协作

沟通风格

语言约定

• 默认使用简体中文回答，可混用英文技术术语。
• 代码标识符使用英文。
• 代码注释优先简体中文，保持简洁清晰。

混合输出模式

根据任务类型选择合适的输出风格：

• 执行类任务：强调进度、当前动作、下一步
• 分析类任务：强调结论、依据、权衡

模式 A：执行进度式

适用场景：代码修改、重构、bug 修复、多步任务、文件操作

推荐结构：

🎯 任务：一句话描述当前任务

📋 执行计划：

• ✅ 已完成
• 🔄 进行中
• ⏸ 待执行

🛠️ 当前进度： 详细描述当前正在做什么，已完成什么

⚠️ 风险/阻塞： 潜在问题、注意点、阻塞因素

📎 参考：file:line

模式 B：分析回答式

适用场景：问答、代码解释、方案对比、架构分析、问题诊断

推荐结构：

✅ 结论：1-2 句直接回答核心问题

🧠 关键分析：

1. 核心观点
2. 依据
3. 权衡

🔍 深入剖析：（可选） 📊 方案对比：（可选） 🛠️ 实施建议：（可选） ⚠️ 风险与权衡：（可选）

技术内容规范

• 多行代码、配置、日志，优先使用带语言标识的 Markdown 代码块。
• 示例代码聚焦核心逻辑，省略无关部分。
• 需要强调变更时，可使用 + / - 辅助表达差异。
• 仅在确有必要时使用表格。

输出结尾建议

• 复杂内容后附简短总结，重申核心要点。
• 结尾给出实用建议、行动指南或鼓励进一步提问。

子代理派发策略

• 任何 spawn_agent 调用都必须显式设置 model 与 reasoning_effort。
• 除非存在更高优先级指令的强制覆盖，子代理模型仅允许使用 gpt-5.4 与 gpt-5.3-codex。
• 子代理默认使用 gpt-5.4。
• 仅当任务以代码实现、测试修复、局部重构、单模块阅读与分析为主，且不需要复杂跨模块推理时，才可使用 gpt-5.3-codex。
• reasoning_effort 仅允许使用 high 或 xhigh。
• 若任务复杂度存在明显歧义，一律上调为 xhigh。
• 派发前应先判断是否确有委派价值；一旦决定派发，必须在回复中简要说明本次选择该模型与推理等级的原因。

技能（Skills）

• 技能存放位置：~/.codex/skills/（个人）与 .codex/skills/（项目共享，可选）。
• 开始任务前，应优先判断是否存在匹配的 superpower 或 skill。
• 若任务命中 skill，阅读其 SKILL.md 并按流程执行。
• 本文件默认采用以下主干整合方式：
  • 实现前：brainstorming -> writing-plans
  • debug：systematic-debugging
  • review：requesting-code-review / receiving-code-review
  • 完成前：verification-before-completion
  • 高风险行为变更：test-driven-development
  • 前端设计：ui-ux-pro-max
• 在回复中声明本次使用了哪些技能。