agent-infra: Instructions file for Codex

agent-infra - AI 开发指南

本仓库包含 agent-infra 模板和技能仓库，用于多 AI 协作基础设施。

AI 行为准则（必须遵守）

源自 Andrej Karpathy 总结的 4 条 LLM 编程铁律，本项目所有 AI 工具均需遵守。 与下方项目规范冲突时，以项目规范为准；其余场景以本节为准。 这些准则偏向「稳」而非「快」，琐碎任务可酌情判断。

SKILL 执行场景的特例：在执行任一 SKILL 时，优先遵循 .agents/rules/no-mid-flow-questions.md（默认禁言 + 该规则文件列出的例外）。每次执行 SKILL 前应先 Read 该规则文件，以加载完整例外清单和具体约束。这与下文第 1 条「不确定就提问」不矛盾——SKILL 执行有明确的输入、输出和产物，不确定项应按最稳健方案推进并写入产物的「假设」/「未决问题」段落，由用户在审查检查点统一处理，而不是中途打断对话。

1. 先思考，再动手（Think Before Coding）

不要硬猜，不要藏起困惑，把权衡点摆到台面上。

• 在 SKILL 执行期间，先按 .agents/rules/no-mid-flow-questions.md 的诊断与恢复顺序处理工具和执行问题；把仍未解决的假设或问题写入产物。
• 对 SKILL 入口的自然语言需求，若存在会实质影响范围的歧义且不能从已有事实安全推导，再按对应入口规则澄清。
• 对可逆、低影响的执行细节，优先采用符合现有代码和规则的方案并说明假设，不为一般执行选择中断工作流。
• 当平台、客户端、协议、工作流、业务规则或算法存在多种行为时，识别各实现共用的流程，并用接口定义可替换的行为；主流程依赖接口，具体策略在注册或装配处选择。新增变体优先实现策略并接入现有装配逻辑，避免给每条链路分别增加分支。方案和实现阶段遵循 .agents/rules/strategy-pattern.md。
• 有更简单的方案就说出来，必要时反推用户的决定。
• 需要用户独有的事实或授权、无法验证安全边界或无法安全恢复时，按适用规则升级；其余情况继续独立工作并记录阻塞条件。

2. 简洁优先（Simplicity First）

选择能正确承载需求与真实变化的最简设计，不以最少行数或最少抽象为目标。

• 不添加未被要求的功能、配置项或缺乏行为差异依据的抽象。为已明确的不同实现定义接口属于正确设计，不是投机扩展。
• 不为稳定、单一且没有明确变化迹象的逻辑引入抽象层；当需求包含真实的行为变体时，应使用接口和策略模式隔离差异，即使当前只有一个实现。
• 不为不可能发生的场景写错误处理。
• 写了 200 行但 50 行就够时，重写它。
• 自检："资深工程师会觉得这过度设计吗？"——会，就简化。

兼容性默认关闭（Compatibility by Exception）

没有明确兼容承诺时，只实现当前契约，不主动保留旧行为。

• 不因“可能有旧调用方”而新增 adapter、wrapper、shim、双写、旧 schema 读取或迁移分支。
• 兼容性必须有证据：明确的旧消费者或存量数据、不可直接切换的原因、支持期限和删除条件；缺少任一项时按当前版本直接切换。
• 优先一次性边界迁移或可操作的失败提示，不在主路径长期维护新旧两套状态机。
• 临时兼容集中在唯一边界，并在该边界用 TODO(compat): Remove ... once ... 标记删除对象和可验证删除条件；任务或 Issue 仅用于可选排期，不是兼容事实源或完成门禁。
• 当前流程的崩溃恢复、幂等重试和安全校验不等于历史兼容；只保留证明当前操作正确所需的最小事实。
• 发现任务范围外的既有兼容逻辑时只记录，不顺手删除；新增或延长兼容逻辑则必须遵循 .agents/rules/compatibility-policy.md。

3. 外科手术式修改（Surgical Changes）

只动该动的地方；只清理你自己制造的垃圾。

• 不顺手"优化"邻近代码、注释、格式。
• 不重构没坏的东西。
• 保持现有风格，即使你个人偏好不同。
• 发现无关的死代码——提醒用户，不要擅自删除。
• 因你的改动而产生的孤儿 import/变量/函数，必须由你清理。
• 自检：每一行改动都能直接追溯到用户的请求吗？

4. 目标驱动执行（Goal-Driven Execution）

先定义可验证的成功标准，再循环执行直到达成。

把任务转成可验证的目标：

• "加校验" → "先写非法输入的失败用例，再让它通过"
• "修 Bug" → "先写复现该 Bug 的用例，再修到通过"
• "重构 X" → "确保重构前后测试都通过"