最近整理了一套使用 Codex、Claude Code 等 Coding Agent 开发项目时的工作流，并开源到了 GitHub：

https://github.com/Jett-Wu/AgentWorkflow

AgentWorkflow 不是 Multi-Agent Runtime，也不负责模型调度。它主要解决项目管理问题：

当多个 Coding Agent 在同一个项目中交替开发时，如何让它们持续共享项目需求、当前任务、关键决策和验证状态。

整个方案尽量保持轻量，只包含 4 个 Markdown 文件：

AGENTS.md   → Agent 怎么工作
PROJECT.md  → 项目要做什么
TASK.md     → 当前正在做什么
DEVLOG.md   → 哪些重要历史需要保留

其他信息则继续由它们原本的工程工具来负责：

Git         → 实际修改了什么
Tests / CI  → 实现到底对不对

AgentWorkflow 不做大而全的“项目记忆”系统——它只保存一类信息：那些 Git 记不住、代码看不出来、测试测不到，但不同 Agent 之间又必须持续传递的内容。

---

1. 核心设计：一个问题只有一个事实源

AgentWorkflow 的核心原则是：

One Source of Truth per Question

也就是同一个问题只由一个明确的载体负责回答。

信息	事实源
项目必须实现什么	PROJECT.md
Agent 应该怎样工作	AGENTS.md
当前正在做什么	TASK.md
重要决策和失败经验	DEVLOG.md
具体修改了什么	Git
实现是否正确	Tests / CI
依赖版本	package / lock file
API / Schema	Code / Schema

这样可以避免同一份信息同时出现在多个 Markdown 文件中，后期相互冲突。

---

2. AGENTS.md：Agent 的仓库级规则

AGENTS.md 是 Coding Agent 进入项目时首先读取的文件，主要保存项目阅读顺序、安装 / 运行 / 测试命令、仓库级开发约束、Review 策略和任务完成标准。

例如：

修改代码前：
1. 阅读 PROJECT.md。
2. 阅读 TASK.md。
3. 检索 DEVLOG.md 中与当前任务相关的记录。
4. 检查相关代码、测试和 Git diff。

它回答的核心问题是：

Agent 在这个仓库里应该怎样工作？

因此 AGENTS.md 应尽量稳定、简洁，不需要写成项目百科全书。

---

3. PROJECT.md：项目需求和系统级状态

PROJECT.md 负责保存项目级事实，包括需求基线、非目标、成功标准、项目约束、需求变更、能力完成状态、当前系统结构和项目级风险。

例如：

### 必备能力
- R1：支持断点恢复
- R2：数据能够追溯到原始来源
- R3：支持结构化导出

### 非目标
- N1：当前版本不实现实时数据流
- N2：当前版本不开发管理后台

每个需求可以分配一个 ID，例如：

R1
R2
R3
S1
C1

后续任务直接关联这些项目项：

关联项目项：R1、C2

这样可以让任务始终与原始需求保持对应关系，减少 Coding Agent 在多轮开发后逐渐偏离项目目标的问题。需求如果发生变化，也应该明确记录，而不是由某个 Agent 直接修改原有需求。

---

4. TASK.md：当前任务和交接状态

TASK.md 只负责当前正在进行的任务，主要包含任务目标、关联需求、风险等级、任务范围、验收条件、当前状态、下一步、阻塞项和验证结果。

例如：

## 任务信息
任务：T-004 — 增加断点恢复
关联项目项：R1、C2
风险：中
状态：进行中

## 验收条件
- [ ] 中断后能够从 checkpoint 恢复
- [ ] 已完成的数据不会重复写入
- [ ] 原有测试通过
- [ ] 新增恢复测试
- [ ] 未引入无关修改

当 Codex 做到一半，需要换 Claude Code 继续时，只需要在 TASK.md 中更新已完成、进行中、下一步、阻塞项和验证结果，下一位 Agent 就可以比较快地恢复任务状态。

这里还有一个重要原则：

新 Agent 不能只相信上一位 Agent 的完成声明。

它应该结合代码、Git diff、测试和 CI 重新核对真实状态。

---

5. DEVLOG.md：只保存真正值得保留的历史

DEVLOG.md 不是普通的开发流水账，主要保存 Git 很难直接回答的信息，例如重要技术决策及原因、代价较高的失败方案、难以从最终代码看出的 Root Cause、会影响后续开发的经验和重要项目里程碑。

例如：

### D-007 — checkpoint 重复写入问题

类型：失败方案 / 根因

背景：
异常退出后出现部分数据重复。

结果：
问题并非 SQLite 并发导致，
真正原因是 checkpoint 更新晚于数据写入。

避免重复：
不要继续通过修改 SQLite journal mode 解决该问题。

证据：
tests/test_resume.py
commit xxxxxxx

以后其他 Agent 遇到类似问题时，就可以直接避开已经验证过的错误路线。普通代码修改则不需要记录，因为 Git 已经可以完整保存。

---

6. 标准工作流程

一个任务的正常流程大致如下：

AGENTS.md
    ↓
PROJECT.md
    ↓
TASK.md
    ↓
检索相关 DEVLOG
    ↓
检查代码和测试
    ↓
实现任务
    ↓
Tests / CI
    ↓
Review Git Diff
    ↓
更新 TASK.md

如果开发过程中出现项目级变化，再更新 PROJECT.md；如果出现未来仍然值得保留的重要决策、失败方案或经验，再更新 DEVLOG.md。否则不需要额外维护其他文件。

---

7. 多 Agent 并行开发

默认情况下，项目根目录只维护一个 TASK.md，比较适合：

Codex 开发
→ Claude Code Review
→ Codex 修改

这种串行协作方式。

如果多个 Agent 真正并行开发，可以扩展为：

tasks/
└── active/
    ├── T-001-crawler.md
    └── T-002-frontend.md

同时配合独立 Branch / Worktree、一个任务一个主要负责人、明确任务依赖，并尽量避免多个 Agent 同时修改相同文件。

原则上只有项目真的需要并行任务管理时才扩展，默认工作流仍然保持简单。

---

8. Token 和上下文控制

AgentWorkflow 也考虑到了 Token 消耗的问题，默认读取顺序为：

AGENTS.md
→ PROJECT.md
→ TASK.md
→ 定向检索 DEVLOG.md
→ 当前任务相关代码和测试

主要原则包括：

• 不默认扫描整个仓库；

• 不默认全文读取 DEVLOG.md；

• 不保存完整聊天记录；

• 不重复记录 Git 已经保存的信息；

• 过时状态直接更新，而不是不断追加；

• 能通过测试自动验证的内容优先交给 Tests / CI。

这样可以减少每次开启新会话时重复加载大量上下文的问题。

---

9. 快速使用

仓库中提供了完整的中英文版本：

AGENT_WORKFLOW.md
AGENT_WORKFLOW_CN.md

如果使用中文版，可以把 AGENT_WORKFLOW_CN.md 放到项目中，然后告诉 Coding Agent：

阅读 AGENT_WORKFLOW_CN.md。

检查当前仓库并初始化其中定义的工作流。
创建或更新 AGENTS.md、PROJECT.md、TASK.md 和 DEVLOG.md。
只使用经过验证的仓库事实。
初始化期间不要修改业务代码。

Agent 会根据当前仓库生成或更新：

AGENTS.md
PROJECT.md
TASK.md
DEVLOG.md

之后就可以按照这套工作流持续开发。

---

10. 适用场景

这套工作流比较适合：

• Codex、Claude Code 等多个 Coding Agent 交替开发；

• 一个项目跨多个会话持续进行；

• Agent A 开发、Agent B Review；

• 个人或小团队的中小型软件项目；

• 希望保留基本项目可追踪性，但又不想引入复杂项目管理系统的场景。

AgentWorkflow 本身不会替代 Git、Tests / CI 或现有的 Issue 管理系统，而是作为 Coding Agent 与这些工程工具之间的一层轻量协作约定。

项目地址：

https://github.com/Jett-Wu/AgentWorkflow

欢迎尝试！