天眼投资 Logo

SKYEYE RESEARCH

天眼投资北京有限公司

博客列表返回首页
TECH2026-04-074 min

Research Note

推荐一份好用的 AGENTS.md

分享一份适合搭配 Codex 使用的 AGENTS.md。核心不是堆规则，而是用渐进式 Spec 把不同复杂度的任务切到合适流程里。

“AI 不是不聪明，是不知道该在哪停。这套东西解决的就是这个问题。”

这份 AGENTS.md 我自己用下来很顺手，尤其适合刚开始和 Codex 配合的新手伙伴。它把什么时候直接做、什么时候先写 Spec、什么时候要走完整评审讲得很清楚，用起来不容易失控。

CodexAGENTS.mdSpec工作流

Module 01

为什么推荐

这份 AGENTS.md 最好的地方，不是规则堆得多，而是很多话都写得很直接，拿来就能用。

它把语言、注意事项、代码规范和任务管理放在同一个约束体系里，尤其适合刚开始和 Codex 配合的新手伙伴。

  • 默认中文交流
  • 默认不自动生成说明文档
  • 函数和关键逻辑都要求中文注释

Module 02

渐进式 Spec

它最核心的一段就是渐进式 Spec：不同复杂度的需求，走不同深度的流程，偶然复杂度应该尽可能压缩。

  • 简单（改字段、修 bug）：直接执行，无需 Spec
  • 中等（3+ 步骤，有架构决策）：写轻量 Spec，HARD-GATE 后再编码
  • 复杂（跨模块、多系统）：完整 Propose → Apply → Review

Module 03

Spec 三铁律

这套约束最有力量的地方，是把 Spec 放在代码之前，也把执行中的偏差重新拉回到文档真相上。

  • No Spec, No Code
  • Spec is Truth，代码和 Spec 冲突，错的是代码
  • Reverse Sync，执行中发现偏差，先改 Spec 再改代码

Module 04

不只是 Spec

这份规则真正完整的地方，在于它不只讲 Spec，还把调研、规划、执行、验证和复盘都串起来了。

  • Plan Node Default：中等及以上复杂度任务默认进入 plan mode
  • Subagent Strategy：Research、探索和并行分析尽量交给 subagent
  • 执行自由度曲线：调研、设计、规划、执行、验收各阶段自由度不同
  • Verification 铁律：未经验证，不得标记为完成
  • Task Management：先写计划、追踪进度、记录 review
  • Core Principles：Simplicity First、Minimal Impact、意图分离
AGENTS.md

一键复制后可直接粘贴到本地规则文件。

# 语言
 
- 和我对话的语言默认中文
 
# 注意
 
默认情况下，不要创建任何新的说明文档或文档文件。
不要自动生成 README.md、设计文档、使用说明、架构说明等。
只有在我明确要求"编写文档 / 生成 README / 写说明文档"时，才允许创建或修改文档。
 
# 代码规范
 
- 代码要写清楚中文注释，所有函数和关键逻辑都必须有注释
 
---
 
# Workflow Orchestration
 
## 1. 渐进式 Spec：按需复杂度
 
不同复杂度的需求，走不同深度的流程——偶然复杂度应该尽可能压缩：
 
| 需求规模 | 流程 |
|---------|------|
| 简单（改字段、修 bug） | 直接执行，无需 Spec |
| 中等（3+ 步骤，有架构决策） | 写轻量 Spec，HARD-GATE 后再编码 |
| 复杂（跨模块、多系统） | 完整 Propose → Apply → Review |
 
**Spec 三铁律**（仅中等及以上复杂度触发）：
1. **No Spec, No Code** — 没有 Spec，不准写代码
2. **Spec is Truth** — Spec 和代码冲突时，错的一定是代码
3. **Reverse Sync** — 执行中发现偏差，先修 Spec，再修代码
 
**HARD-GATE**：Spec 完整生成后，必须等用户显式确认才能开始编码。确认前禁止任何代码修改动作。
 
**Research 必须有出处**：描述代码现状时，每个结论必须标注文件路径 + 函数名，不接受"通常来说"或无依据的推断。
 
**Spec 分段确认**：不一口气生成完整 Spec。按段输出（现状分析 → 功能点 → 风险与决策），每段等用户确认后再继续。越早发现方向偏差，修正成本越低。
 
## 2. Plan Node Default
 
- 对任何中等及以上复杂度的任务，进入 plan mode
- 出问题立刻停下重新规划，不要强行推进
- Plan mode 同样适用于验证步骤，不只是构建阶段
 
## 3. Subagent Strategy
 
- 大量使用 subagent 保持主 context 窗口干净
- Research、探索、并行分析交给 subagent
- 复杂问题通过 subagent 投入更多计算
- 每个 subagent 只做一件事，专注执行
 
## 4. 执行自由度曲线
 
| 阶段 | 自由度 | 原则 |
|------|--------|------|
| 调研 | 中 | 自由探索，但结论必须有代码出处 |
| 方案设计 | 高 | 充分想象，提选项 + 给推荐 |
| 规划 | 低 | 精确到文件路径和函数签名 |
| 执行 | 零 | 严格按计划，有偏差立即停下问 |
| 验收 | 中 | 自由检查，结论要有依据 |
 
## 5. Self-Improvement Loop
 
- 用户每次纠正后：将模式写入 `tasks/lessons.md`
- 写规则防止同类错误重现
- 每次会话开始时 review lessons 里的相关规则
- 有价值的踩坑和领域发现，主动建议沉淀到项目知识库
 
## 6. Verification 铁律
 
- 任务未经验证，不得标记为完成
- 必须展示可验证的证据（编译输出 / 测试结果 / 运行日志）
- 禁止"应该没问题"等无证据声明
- 必要时对比修改前后的行为差异
 
## 7. Demand Elegance（适度）
 
- 非简单修改时，停下来问一句："有没有更优雅的方式？"
- 如果方案感觉 hacky："知道了这些之后，实现优雅方案"
- 简单显而易见的修复直接做，不要过度设计
 
## 8. Autonomous Bug Fixing
 
- 给 bug 报告就去修，不要等手把手指导
- 指向日志、报错、失败测试，然后解决它
- 不需要用户切换上下文
- CI 测试失败，主动去修
 
---
 
# Task Management
 
1. **先写计划**：将计划写入 `tasks/todo.md`，使用可勾选的任务项
2. **确认后执行**：中等及以上复杂度任务，HARD-GATE 后才开始实现
3. **追踪进度**：完成一项立刻标记
4. **解释变更**：每步给出高层次说明
5. **记录结果**：在 `tasks/todo.md` 末尾添加 review 小节
6. **沉淀教训**：用户纠正后更新 `tasks/lessons.md`
 
---
 
# Core Principles
 
- **Simplicity First**：每次改动尽量简单。最小化影响范围。
- **No Laziness**：找根因，不打补丁，用 senior developer 标准。
- **Minimal Impact**：只改必要的代码，避免引入新问题。
- **意图分离**：一次只处理一种意图——探索、决策、执行、审查不要混着来。