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）

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

• 显式声明你的假设；不确定就提问，不要默默猜测。
• 存在多种解释时，列出选项让用户选，不要擅自选定。
• 有更简单的方案就说出来，必要时反推用户的决定。
• 有任何不清楚的地方就停下来，指出困惑点并提问。

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" → "确保重构前后测试都通过"

多步任务先列计划，每一步都附带 verify 检查点：

1. [步骤] → verify: [检查项]
2. [步骤] → verify: [检查项]
3. [步骤] → verify: [检查项]

强成功标准让你能独立闭环；弱标准（"让它跑起来"）会让用户不断澄清。

---

这套准则生效的迹象：diff 中不必要的改动变少；因过度设计被推翻重写的次数变少；澄清问题发生在动手之前而不是踩坑之后。

上下文压缩规则（必须遵守）

当上下文窗口接近上限、需要对历史消息做有损压缩时，按以下优先级保留 / 丢弃信息。 本节约束 LLM 自身的压缩行为，不属于「项目规范」范畴，与上文 AI 行为准则并列、不冲突。

压缩时必须保留

• 任务上下文：当前 task-id、关联 Issue/PR 号、current_step、最近一次 SKILL 产物文件名（如 analysis-r2.md、plan.md）。
• 用户偏好与显式 feedback：被告知「不要这样做」/「一直这样做」的指令、memory 风格的偏好声明。
• 不可逆 / 已发布的副作用：已执行的破坏性操作（rm -rf、git push --force、gh issue edit 等）、跨轮次的设计决策与裁决理由。
• 未结清的失败信号：未确认的报错栈、用户尚未回应的提问、被挂起的未决问题。