repo-memory-workflow

Git 即 AI 记忆。 用 AGENTS.md + .ai/ 目录做编辑器无关、平台无关的项目上下文，告别对话上下文爆满、接手乱麻、进度失忆。

这是一个开源工作流模板，专门解决 AI 辅助开发里的几类痛点：

• 跨 AI 编辑器 — 不绑定 Cursor、TRAE、ChatGPT、VSCode 任一产品。.ai/ 里是纯 Markdown，任意能读文件的 AI 都能用。
• 多人协同 / 同事接手 — 任务、决策、日志都写在 .ai/ 里，随 Git 提交。同事 pull 后生成上下文包就能续写。
• 对话上下文爆满 — 更新 checkpoint、生成 CONTEXT_PACK.md，切到新 chat 或新 codex exec 就能接着干。
• 无人值守接力 — 平台专用 relay 脚本每轮启动新的 codex exec，只执行 .ai/NEXT.md 的下一步。
• 半路进项目 — 代码写了一半但没文档？Task 000 会扫描项目、补齐日志与任务，再拆分剩余工作继续推进。

一套 .ai/ 结构 + 一条 init 命令 + 编辑器规则配置，让 AI 辅助开发可追溯、可交接、可恢复。

核心能力

| 能力 | 说明 | |------|------| | 拆需求 | Planning 模式拆成 3~10 个任务卡，写入 .ai/TASK.md | | 继续开发 | 对话满了 / 切窗口 → 生成 CONTEXT_PACK.md，新 chat 续写 | | 自动接力 | repo-memory-workflow run 调用平台专用 relay 脚本，每轮 fresh codex exec 只执行一个 NEXT action | | 半路接手 | Task 000 扫描代码、补齐日志/决策，拆出剩余任务 | | 版本化测试 | 绑定权威需求快照 → 生成测试用例 / 执行 / 导出 Excel·Word |

• Git-native：.ai/ 跟着 repo 走，版本可控、可协作
• Editor-agnostic：Cursor、TRAE、VSCode Codex、ChatGPT、任意 AI 都能用
• 一条命令：repo-memory-workflow init 在任意项目根目录初始化

一、安装

npm i -g repo-memory-workflow

macOS 若遇 EACCES：sudo npm i -g repo-memory-workflow

从源码安装（开发版）

如果你是下载/clone 了本仓库源码，而不是直接全局安装 npm 包：

cd repo-memory-workflow
npm install
npm link

之后在任意终端确认命令可用：

repo-memory-workflow --help

二、配置（两步搞定）

Step 1：初始化 .ai/

在目标项目根目录执行：

repo-memory-workflow init

会生成：

AGENTS.md          # 长期稳定规则，不放临时状态
run_loop_for_mac.sh # macOS/Linux codex exec 自动接力调度脚本
run_loop_for_win.ps1 # Windows PowerShell 自动接力调度脚本
run_loop.sh        # 兼容入口，转发到 run_loop_for_mac.sh
run_loop.ps1       # 兼容入口，转发到 run_loop_for_win.ps1
.ai/
  START.md          # 工作流总览
  TASK.md           # 任务看板
  STATE.md          # 当前状态核心记忆
  NEXT.md           # 下一轮唯一动作
  CONTEXT.md        # 项目上下文（技术栈、约定等）
  DECISIONS.md      # 重要决策
  LOG.md            # 每轮/每步进度日志
  PROMPT_START.md   # codex exec 固定启动提示词
  TASKING_GUIDE.md  # 任务拆分指南
  RESOURCE_GUIDE.md # 资源/权威输入指南
  QUICK_PROMPTS.md  # 快捷 prompt 模板（无规则/Skill 时用）
  make_context.py   # 上下文包生成器
  resources/        # 权威资源索引与快照
  tasks/            # 任务卡
  tests/            # 测试资产

可选：repo-memory-workflow test init 补齐 .ai/tests/（旧项目升级用）

初始化是增量安全的：已有文件默认不会被覆盖，缺失文件会被补齐。

Step 2：配置编辑器规则

配好后，AI 在每次对话中自动加载工作流规则，你只需说短指令即可，不再需要粘贴长 prompt。

根据你使用的编辑器，选择对应方式（任选一个即可）：

Cursor

方式 A：Cursor Rule（推荐，最简单）

打开 Cursor 设置 → Rules, Skills, Subagents → Rules → 点 + New → 粘贴 integrations/cursor/repo-memory-workflow/rule.md 的内容 → 设为 Always 生效。

或用命令行：

mkdir -p .cursor/rules
cp $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow/rule.md .cursor/rules/repo-memory-workflow.md

方式 B：Cursor Skill

# 项目级
mkdir -p .cursor/skills
cp -r $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow .cursor/skills/

# 或个人级（所有项目生效）
mkdir -p ~/.cursor/skills
cp -r $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow ~/.cursor/skills/

TRAE

打开 TRAE 设置 → 规则和技能 → 项目规则 → 点「创建 project_rules.md」→ 粘贴 integrations/trae/repo-memory-workflow/project_rules.md 的内容。

或用命令行：

mkdir -p .trae/rules
cp $(npm root -g)/repo-memory-workflow/integrations/trae/repo-memory-workflow/project_rules.md .trae/rules/project_rules.md

VSCode + Codex

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -r $(npm root -g)/repo-memory-workflow/integrations/codex/repo-memory-workflow "${CODEX_HOME:-$HOME/.codex}/skills/"

重启 Codex 生效。

其他编辑器（Copilot Chat、ChatGPT 等）

打开 .ai/QUICK_PROMPTS.md，复制对应场景的 prompt 粘贴给 AI 即可。

三、日常使用

配好编辑器规则后，你只需说短指令，AI 会自动读取 .ai/ 文件并遵循工作流。

| 你说 | AI 会做什么 | |------|------------| | 「拆一下」 + 需求描述 | 读取 AGENTS + CONTEXT + TASKING_GUIDE，拆成 3~10 个任务卡，更新 TASK/STATE/NEXT。不写代码。 | | 「继续」 | 读取 checkpoint 文件，只执行 .ai/NEXT.md 第一项，并写回 checkpoint。 | | 「生成上下文包」 | 运行 repo-memory-workflow pack，生成 CONTEXT_PACK.md 用于新 chat 续写。 | | 「自动续跑」 | 运行 repo-memory-workflow run，每轮启动新的 codex exec 接力执行。 | | 「补档」 | 扫描项目现状，补齐日志和任务卡，拆出剩余工作。不写代码。 | | 「生成测试用例」 | 绑定 resource 版本，生成可审核的测试用例。 | | 「跑测试」 | 执行配置的 smoke/命令，写入执行记录和报告。 | | 「导出测试报告」 | 导出 Excel/Word 到 .ai/tests/exports/。 |

CLI 命令

repo-memory-workflow init
repo-memory-workflow pack
repo-memory-workflow run --max-rounds 10 --timeout 1800 --max-failures 3
repo-memory-workflow test init

自动接力执行

repo-memory-workflow run 会在 macOS/Linux 调用项目根目录的 run_loop_for_mac.sh，在 Windows PowerShell 调用 run_loop_for_win.ps1。旧的 run_loop.sh / run_loop.ps1 保留为兼容入口。脚本每一轮都会启动新的：

codex exec --cd <project> --skip-git-repo-check --full-auto -

每轮启动后，模型必须先读取：

• AGENTS.md
• .ai/PROMPT_START.md
• .ai/TASK.md
• .ai/STATE.md
• .ai/DECISIONS.md
• .ai/NEXT.md

每轮只执行 .ai/NEXT.md 的第一项。结束前必须更新：

• .ai/STATE.md
• .ai/NEXT.md
• .ai/LOG.md
• .ai/DECISIONS.md（仅关键决策变化时）

这意味着：一个大任务先拆到 .ai/TASK.md，但一个 codex exec 轮次只吃 .ai/NEXT.md 的一个动作。这个动作必须是“可验证的小闭环”，不是键盘级微动作。每轮完成后再把下一棒写回 .ai/NEXT.md。

合理的 .ai/NEXT.md 粒度：

• 包含一个小目标的实现、最小验证和 checkpoint 更新
• 通常是 10-30 分钟内能完成的一段工作
• 可以被中断后恢复，也能让下一轮看懂结果

不合理的粒度：

• 创建文件
• 写第一行
• 追加第二行
• 改一个 import

这些微动作会导致每一步都重新启动一次 codex exec，固定开销远大于实际工作。应该把它们合并成一个可验证动作。

自动接力脚本支持：

• --max-rounds <n> 最大轮次
• --timeout <seconds> 每轮超时
• --max-failures <n> 连续失败上限
• .ai/STOP 终止机制

Windows 用户直接在 PowerShell 中运行同一条命令即可：

repo-memory-workflow run --max-rounds 10 --timeout 1800 --max-failures 3

你可以让 Codex 在当前会话里启动并监控这条命令；也可以自己在目标项目目录打开终端执行，让它无人值守运行。无人值守前必须先完成“拆需求”，确保 .ai/NEXT.md 里已经有明确的第一步动作。

最小 smoke test

新安装或升级后，建议先跑一个最小 smoke test，不要一上来交给复杂需求。这个 smoke test 应该是一轮完成，而不是拆成三轮：

创建 relay_test.txt，写入两行内容：
helloword
good bye
然后验证文件内容完全一致，并更新 STATE/NEXT/LOG。

预期 1 个 round 后，文件内容为：

helloword
good bye

如果卡在 Round N starting 或没有推进 .ai/NEXT.md，先查看 .ai/run_logs/round_N_output.log。Windows 下还会生成 .ai/run_logs/round_N_run.cmd，可以直接打开它看本轮实际执行的命令。重点检查是否使用了 run_loop_for_win.ps1，以及命令里是否出现 --cd、--skip-git-repo-check、--full-auto。

Windows 下如果要排除 workflow 影响，可以在项目目录直接测试 Codex CLI：

"Create a file named codex_direct_test.txt with the text ok." |
  codex exec --cd "C:\path\to\your\project" --skip-git-repo-check --full-auto -

如果这个命令也卡住，优先排查 Codex CLI 的登录态、网络、权限、state db、skills 加载问题；如果它能跑通，再看 .ai/run_logs/round_N_run.cmd 和 round_N_output.log。

四、完整示例：给博客加评论功能

下面用一个具体案例，演示从配置到完成的完整流程。

需求：给博客加评论功能——用户发评论、看列表、管理员审核。技术栈 Node + React。

1. 配置（只做一次）

# 安装工具
npm i -g repo-memory-workflow

# 在博客项目根目录初始化
cd my-blog
repo-memory-workflow init

# 配置编辑器规则（以 Cursor Rule 为例）
mkdir -p .cursor/rules
cp $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow/rule.md .cursor/rules/repo-memory-workflow.md

2. 填写项目背景

编辑 .ai/CONTEXT.md，写几行关键信息：

## 技术栈
- 后端：Node.js + Express + PostgreSQL
- 前端：React + Vite
- 部署：Docker + Nginx

3. 拆需求（Planning）

在 Cursor / TRAE 对话里说：

拆一下，给博客加评论功能：用户发评论、看评论列表，管理员可审核。

AI 会自动读取 AGENTS.md、.ai/CONTEXT.md 和 .ai/TASKING_GUIDE.md，然后：

• 创建 001_add_comment_api.md、002_comment_ui.md 等任务卡
• 更新 .ai/TASK.md 的 Active 列表
• 更新 .ai/STATE.md 和 .ai/NEXT.md
• 不写代码

注意：.ai/NEXT.md 要写成“可验证的小闭环”，不要写成键盘级步骤。比如 smoke test 应该是“一轮创建文件、写两行并验证”，而不是“建文件 / 写第一行 / 追加第二行”三轮。

4. 开始开发（Implementation）

对 AI 说：

继续

AI 会自动读取 checkpoint 文件，只执行 .ai/NEXT.md 第一项，结束前更新 .ai/STATE.md、.ai/NEXT.md 和 .ai/LOG.md。

5. 任务完成 → 下一个

一个任务做完后，AI 会把它移到 Done，下一个任务进 Active，并把下一轮唯一动作写入 .ai/NEXT.md。你继续说「继续」，或运行 repo-memory-workflow run 自动接力。

如果要让 Codex 帮你监控自动接力，就在对话里说：

自动续跑，并观察失败日志

AI 会在项目目录启动 repo-memory-workflow run，必要时查看 .ai/run_logs/ 和 .ai/NEXT.md。如果你想脱离 Codex，就在项目目录的终端里直接执行 repo-memory-workflow run --max-rounds 100 --timeout 3600，之后通过 .ai/STOP 或中断终端停止。

6. 对话满了 → 切窗口

对 AI 说：

生成上下文包

在新 chat 里说「继续」，AI 读取 CONTEXT_PACK.md 后从 .ai/NEXT.md 自动接上进度。

五、更多场景

场景一：全新需求，从零开始

适用：接到一个新需求，打算用 AI 一起做。

步骤：

1. repo-memory-workflow init
2. 编辑 .ai/CONTEXT.md 填项目背景
3. 对 AI 说「拆一下」+ 需求描述 → AI 拆任务卡（不写代码）
4. 对 AI 说「继续」→ AI 执行 .ai/NEXT.md 的第一项
5. 每轮完成后 AI 重写 .ai/NEXT.md，你继续说「继续」或运行 repo-memory-workflow run

未配编辑器规则时，Step 3 需要手动粘贴 prompt（见 .ai/QUICK_PROMPTS.md）；配好规则后直接说短指令即可。

场景二：需求做了一半，才开始用这套流程（补档）

适用：代码已写了一部分，但没有 .ai/ 流程，想补档后继续。

步骤：

1. repo-memory-workflow init
2. 运行 repo-memory-workflow pack 生成上下文包
3. 对 AI 说「补档」→ AI 扫描项目、补齐日志、拆出剩余任务（不写代码）
4. 补档完成后，对 AI 说「继续」开始开发

场景三：对话/窗口满了，换编辑器或开新窗口

适用：对话太长 / 换编辑器 / 开新 chat。

步骤：

1. 在原 chat 里对 AI 说「生成上下文包」
2. AI 更新 .ai/STATE.md、.ai/NEXT.md 和日志，运行 repo-memory-workflow pack 生成 CONTEXT_PACK.md
3. 在新 chat 里说「继续」→ AI 自动读取上下文包，从 .ai/NEXT.md 接上进度

场景四：大功能 / 三方对接

适用：对接三方支付、登录、短信等大功能，外部文档很长、易变。

核心做法：把权威文档落盘到 .ai/resources/，任务卡只引用路径。

1. 把外部资料按版本存到 .ai/resources/vendor_docs/<key>/versions/<version>/
2. 在 .ai/resources/_index.md 登记条目
3. 对 AI 说「拆一下」+ 需求 → AI 自动引用 resource 路径创建任务

场景五：需求变更 / 规则升级

适用：需求反复改，担心 AI 用了旧规则实现。

核心做法：每次变更生成新版本资源快照 + change_summary.md。

1. 新建版本目录 + 变更摘要
2. 更新 _index.md（新版本 active，旧版本 frozen）
3. 对 AI 说：基于变更摘要更新任务（先更新任务，不写代码）

场景六：版本化测试

适用：按版本迭代，需要可审核的测试用例和报告。

# 生成测试用例
repo-memory-workflow test cases --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

# 执行测试
repo-memory-workflow test run --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

# 导出 Excel/Word
repo-memory-workflow test export --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

设计原则

• 不猜：缺上下文就写到 Open questions，不凭空编
• 必记：每步完成后更新任务卡 + 追加 LOG.md，必要时更新 DECISIONS.md
• 小步迭代：改动尽量小、可追溯

License

MIT

English

Git as AI memory. Use AGENTS.md plus a .ai/ folder as your editor-agnostic, platform-agnostic project context. No more chat overflow, handoff chaos, or lost progress.

An open-source workflow template for AI-assisted development:

• Cross-AI editor — Not locked to Cursor, TRAE, ChatGPT, or VSCode. .ai/ is plain Markdown; any AI that can read files can use it.
• Team handoff — Tasks, decisions, and logs live in .ai/, committed with Git. Teammates pull, generate a context pack, and continue.
• Chat overflow — Update checkpoints, generate CONTEXT_PACK.md, paste into new chat or start a fresh codex exec, keep going.
• Automated relay — platform-specific relay scripts start a fresh codex exec each round and execute only .ai/NEXT.md.
• Join mid-project — Task 000 scans the repo, backfills logs/tasks, splits remaining work.

One .ai/ structure + one init command + editor rules config — traceable, handoff-ready, recoverable.

Capabilities

| Capability | Description | |-----------|------------| | Split requirement | Planning mode: 3~10 task cards → .ai/TASK.md | | Continue work | Chat full → CONTEXT_PACK.md → paste in new chat or start a fresh relay round | | Automated relay | repo-memory-workflow run → platform-specific relay script → fresh codex exec rounds | | Join mid-project | Task 000: scan repo, backfill, split remaining tasks | | Versioned testing | Bind resource snapshot → generate cases / run / export Excel·Word |

• Git-native — .ai/ lives in repo, versioned, shareable
• Editor-agnostic — Cursor, TRAE, VSCode Codex, ChatGPT, any AI
• One command — repo-memory-workflow init

1. Install

npm i -g repo-memory-workflow

macOS permission issues: sudo npm i -g repo-memory-workflow

2. Configure (two steps)

Step 1: Initialize .ai/

In your project root:

repo-memory-workflow init

Creates AGENTS.md, run_loop_for_mac.sh, run_loop_for_win.ps1, compatibility launchers, and .ai/ with START.md, TASK.md, STATE.md, NEXT.md, CONTEXT.md, DECISIONS.md, LOG.md, PROMPT_START.md, TASKING_GUIDE.md, RESOURCE_GUIDE.md, make_context.py, resources/, tasks/, tests/.

Optional: repo-memory-workflow test init to add .ai/tests/ for older projects.

Step 2: Configure editor rules

After configuration, AI automatically loads the workflow rules in every conversation. You only need short commands — no more pasting long prompts.

Pick your editor:

Cursor

Option A: Cursor Rule (recommended, simplest) — Open Cursor Settings → Rules, Skills, Subagents → Rules → click + New → paste the content of integrations/cursor/repo-memory-workflow/rule.md → set to Always.

Or via CLI:

mkdir -p .cursor/rules
cp $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow/rule.md .cursor/rules/repo-memory-workflow.md

Option B: Cursor Skill —

mkdir -p .cursor/skills  # or ~/.cursor/skills for global
cp -r $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow .cursor/skills/

TRAE

Open TRAE Settings → Rules & Skills → Project Rules → create project_rules.md → paste the content of integrations/trae/repo-memory-workflow/project_rules.md.

Or via CLI:

mkdir -p .trae/rules
cp $(npm root -g)/repo-memory-workflow/integrations/trae/repo-memory-workflow/project_rules.md .trae/rules/project_rules.md

VSCode + Codex

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -r $(npm root -g)/repo-memory-workflow/integrations/codex/repo-memory-workflow "${CODEX_HOME:-$HOME/.codex}/skills/"

Restart Codex to activate.

Other editors (Copilot Chat, ChatGPT, etc.)

Open .ai/QUICK_PROMPTS.md and copy the prompt for your scenario.

3. Daily usage

After configuring editor rules, just say short commands. AI automatically reads .ai/ files and follows the workflow.

| You say | AI does | |---------|---------| | "拆一下" + requirement | Read AGENTS + CONTEXT + TASKING_GUIDE, split into 3~10 task cards, update TASK/STATE/NEXT. No code. | | "继续" / "continue" | Read checkpoint files, execute only .ai/NEXT.md first action, then update checkpoints. | | "生成上下文包" / "context pack" | Run repo-memory-workflow pack, generate CONTEXT_PACK.md for new chat. | | "自动续跑" / "auto relay" | Run repo-memory-workflow run, starting fresh codex exec rounds. | | "补档" / "retrofit" | Scan project, backfill logs and tasks, split remaining work. No code. | | "生成测试用例" / "test cases" | Bind resource version, generate reviewable test cases. | | "跑测试" / "run tests" | Run configured smoke/commands, write run records and report. | | "导出测试报告" / "export report" | Export Excel/Word to .ai/tests/exports/. |

4. Full example: add comment feature to a blog

Requirement: Add comments to a blog — users post comments, view list, admin moderates. Tech: Node + React.

Setup (once)

npm i -g repo-memory-workflow
cd my-blog
repo-memory-workflow init

# Configure editor rules (Cursor Rule example)
mkdir -p .cursor/rules
cp $(npm root -g)/repo-memory-workflow/integrations/cursor/repo-memory-workflow/rule.md .cursor/rules/repo-memory-workflow.md

Edit .ai/CONTEXT.md with your tech stack:

## Tech stack
- Backend: Node.js + Express + PostgreSQL
- Frontend: React + Vite
- Deploy: Docker + Nginx

Split requirement (Planning)

In Cursor / TRAE chat, say:

拆一下, add comment feature: users post comments, view list, admin can moderate.

AI automatically reads AGENTS.md + .ai/CONTEXT.md + .ai/TASKING_GUIDE.md, creates task cards like 001_add_comment_api.md, 002_comment_ui.md, and updates .ai/TASK.md, .ai/STATE.md, and .ai/NEXT.md. No code yet.

Develop (Implementation)

Say:

继续 (or "continue")

AI reads checkpoint files, executes only the first action in .ai/NEXT.md, then updates .ai/STATE.md, .ai/NEXT.md, and .ai/LOG.md.

Task done → next

When a task is complete, AI moves it to Done, activates the next one, and writes the next single action to .ai/NEXT.md. Keep saying "继续" or run repo-memory-workflow run.

Chat full → switch window

Say:

生成上下文包 (or "context pack")

In the new chat, say "继续" — AI reads CONTEXT_PACK.md and resumes from .ai/NEXT.md.

5. More scenarios

Scenario 1: New requirement from scratch

1. repo-memory-workflow init
2. Edit .ai/CONTEXT.md with project background
3. Say "拆一下" + requirement → AI creates task cards (no code)
4. Say "继续" → AI executes the first .ai/NEXT.md action
5. Repeat "继续", or run repo-memory-workflow run for automated relay

Without editor rules, Step 3 requires pasting a long prompt from .ai/QUICK_PROMPTS.md. With rules configured, just say short commands.

Scenario 2: Join mid-project (retrofit)

1. repo-memory-workflow init
2. Run repo-memory-workflow pack
3. Say "补档" → AI scans project, backfills logs, splits remaining tasks (no code)
4. Say "继续" to start development

Scenario 3: Chat full, switch window/editor

1. Say "生成上下文包" in current chat
2. AI updates .ai/STATE.md, .ai/NEXT.md, and logs, then generates CONTEXT_PACK.md
3. In new chat, say "继续" → AI resumes from .ai/NEXT.md

Scenario 4: Large integrations / 3rd-party docs

Store authoritative docs under .ai/resources/ with versioned snapshots. Task cards reference resource paths instead of pasting large text. Say "拆一下" + requirement — AI auto-references active resources.

Scenario 5: Requirement changes

Create a new version snapshot + change_summary.md. Update _index.md (new = active, old = frozen). Ask AI to update tasks based on changes first, then code.

Scenario 6: Versioned testing

# Generate test cases
repo-memory-workflow test cases --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

# Run tests
repo-memory-workflow test run --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

# Export Excel/Word
repo-memory-workflow test export --resource ".ai/resources/prd/foo/versions/v1/01_overview.md"

Design principles

• Do not guess — If context is missing, write to Open questions, don't invent
• Always log — After each step, update task card + append LOG.md, and DECISIONS.md when needed
• Small increments — Keep changes minimal and traceable