AI - Jul1en

Claude Fable 5 提示指南

Sat, 04 Jul 2026 15:27:07 +0800

Claude Fable 5 提示指南

Anthropic 最近重新发布了 Fable 5 和 Mythos 5，随之配套更新了官方的提示指南。这篇笔记是对为 Claude Fable 5 编写提示这篇文档的阅读整理，主要关注从 Opus 4.8 迁移过来要注意哪些行为变化，以及在 agentic 场景下如何配置 prompt 和 scaffold

背景与能力定位

Fable 5 的定位不太一样。文档一开始就说，取得最佳成果的团队会把它用在「最棘手的未解决问题」上，而不是在简单工作负载上测试它——因为那样往往会低估它的能力范围。

和 Opus 4.8 相比，几个方向有明显改进：

长周期自主性：能连续跑多日的目标导向任务，在长期运行中保持指令记忆能力
首次正确率：以往需要数天迭代的系统，有团队报告说现在可以一次性实现
视觉能力：解读密集技术图像、截图的准确度显著提高，还经过训练可以用 bash 和裁剪工具处理翻转、模糊或含噪声的图像
代码审查：跨代码库和仓库历史的缺陷发现召回率高于 Opus 4.8
应对模糊性：收到复杂多线程请求时能自行界定范围、提出澄清问题并执行
并行子 agent 调度：比之前的模型更可靠，能稳定管理与子 agent 之间的持续通信

不过有个限制需要注意：Fable 5 不适用于攻击性网络安全或生物/生命科学工作，它对此类敏感任务有严格的防护墙，这类请求会返回 stop_reason: "refusal"，配置回退到 Opus 4.8。挺搞笑的，在 X 上见到有人查 Claude Code 后台日志，发现了一个系统标签：TOO_DUMB_TO_NEED_FABLE，被工程师嘲讽：说实话，我压根没想到你们真的会去翻日志😹

行为变化与迁移要点

文档里最核心的一部分，是讲从 Opus 4.8 迁移过来会遇到的几个行为差异。

回合时长变长了。 在较高 effort 设置下，单个请求可能运行数分钟，自主运行可能持续数小时。文档说这是团队适应 Fable 5 时遇到的最大转变之一。迁移前需要调整客户端超时、流式传输和进度指示器，并考虑把测试框架改成异步方式检查运行状态（比如定时任务），而不是阻塞等待。

effort 控制是主要杠杆。 Fable 5 引入了 high / xhigh / medium / low 几个 effort 级别。文档建议大多数任务用 high 作为默认值，能力最密集的工作负载用 xhigh，日常工作用 medium 或 low。有个有意思的描述：Fable 5 上较低的 effort 设置通常超过先前模型 xhigh 的性能——也就是说，没必要无脑拉满。

再往下看，会发现在较高 effort 下它会做一些「超出任务所需」的事情：对没有问的选项进行比较、冗长地解释根本原因、写很重的 PR 描述，或给下一行代码写注释。文档说只需要一条简短的简洁性指令就能管住这些行为，不需要逐一列举。

长时间运行场景的几个要点

这部分对 agentic workflow 的设计影响较大

核实进度声明。 文档特别提到，在长时间自主运行中，要指示 Fable 5 根据实际工具结果审核进度。Anthropic 自己测试的结论是：这样做能几乎完全消除虚假状态报告，哪怕是专门设计用于诱发这类问题的任务也能规避。

明确边界。 Fable 5 偶尔会做未经请求的操作——比如在没被要求时起草 email、创建防御性的 git 分支备份。需要在 prompt 里明确定义它应该做什么和不应该做什么。

并行子 agent 调度。 文档建议频繁使用子 agent，提供清晰的委派指导，并优先采用编排器与子 agent 之间的异步通信（而不是阻塞等待每个返回）。长期存活的子 agent 能在各子任务之间保留上下文，可以通过缓存读取节省时间，同时避免因最慢的子 agent 而出现瓶颈。

记忆系统。 文档说「当 Fable 5 能够记录先前运行的经验教训并加以参考时，其表现尤为出色」。建议提供一个记录笔记的位置，简单到一个 Markdown 文件就够了。还可以让它回顾过去的会话来引导记忆系统。

两个比较少见但需要知道的情况

罕见的提前停止。 在长会话的深入阶段，Fable 5 偶尔会用纯文本的意图声明（「我现在将运行 X」）结束回合而不发出工具调用，或者在已有足够信息继续时暂停请求许可。这时候回复「继续」或「直接端到端完成」就可以了。对于自主 pipeline，文档建议加一条系统提醒处理这种情况。

罕见的上下文预算担忧。 在非常长的会话里，Fable 5 偶尔会建议开启新会话、提议总结并交接，或削减自己的工作。这种情况最常在测试框架向模型显示剩余 token 倒计时时触发。文档建议尽可能避免显示明确的上下文预算计数。

可读性与沟通

在扩展对话或 agent 式对话中，Fable 5 可能会生成难以理解的文本：密集的箭头链式简写、深入的实现细节、引用用户从未看到的思考内容，或过于技术化的措辞。添加沟通风格补充说明可以缓解这个问题～

迁移时的几个注意点

文档最后整理了几条建议，值得关注的：

从难度范围的顶端开始测试。 选一个比分配给先前模型更难的任务，让 Fable 5 界定范围、提出澄清问题并执行。

重构现有的 prompt 和 skill。 为之前模型开发的 skill 对 Fable 5 而言往往过于规定性，可能会降低输出质量。如果默认性能更好，应该审查并考虑移除旧指令。Fable 5 也擅长根据从当前任务学到的内容即时更新 skill。

个人觉得现在的模型能力越来越强，那些要求边界明显的 skill 会消灭模型探索的能力，这要求我们编写 skill 要适当规范化和更加的通用化，不应因为过多的边界而限制了模型的发挥。

不要指示 Claude 在响应中复现其推理。 告诉模型将内部推理回显、转录或解释的 prompt 指令，可能会在 Fable 5 上触发 reasoning_extraction 拒绝类别，导致更频繁回退到 Opus 4.8。迁移时需要审核现有 skill 和系统提示中的「展示思考过程」类指令。如果应用程序需要推理可见性，应该改为读取 adaptive thinking 中的结构化 thinking 块。

总结

从这份文档来看，Fable 5 的核心转变是从「单次对话中的强大模型」变成了「能跑几天的自主 agent」。相应地，使用方式也需要从「逐条指令」转向「给目标、给边界、异步检查」。之前为 Opus 4.8 写的很多 prompt 技巧可能不再必要，甚至适得其反——这倒是给了一个机会重新审视并精简现有的框架。

Codex 工作流更新-v3

Wed, 24 Jun 2026 21:49:31 +0800

相关博客：Codex 工作流更新-v2

Codex 工作流更新-v3

最近 OpenAI 的一篇博客： Codex-maxxing for long-running work 分享了关于长周期复杂任务的指南，并针对我已有的工作流作出一些更新。

长周期的复杂任务通常不是一次 prompt 改完代码就结束。它可能要经历调查、实现、预览、反馈、等 CI、继续修改、准备 PR、后续检查。该博客更像是总结了 Claude Code goal 和 loop 命令的思想 💭

v2 现状

v2 从项目初始化开始： setup-light / setup-full 生成 AGENTS.md、CLAUDE.md 和 docs/ 记忆文件，让 Agent 进入一个项目后，知道行为规范。它不太关注于任务线本身，比如预览页面谁来看，用户反馈放在哪里，PR review 几个小时后才来又怎么接着改，这些长期任务流程问题是 v2 未涉及的。

长时间复杂任务

OpenAI 这篇博客把 Codex 看成一个 persistent workspace：一件复杂任务有自己的线程、记忆、工具和审阅对象，重要的有以下几点。

Durable thread： 给长期任务一个固定会话，维护会话的上下文、旧决策、待办和用户反馈容易丢失。

Memory： 不只依赖聊天记录，而是把项目状态、决策、开放事项写进可以查看、可以 diff、可以复用的文件。对应到当前工作流里， docs/ 就承担了 memory 的作用，跨项目 or 会话的个性要求则可以放进个人记忆或知识库。

Steering： Codex 工作时，用户可以继续补充 prompt。比如“先不要接短信登录”“这个错误提示太别扭”“等预览部署完再继续”。任务就不再是一次性指令，而是可以边做边调整的任务队列。

Thread automation： 定时任务，比如等待部署、看 review 是否更新、检查支持工单有没有新回复。

Side panel： 产物本身要进入审阅循环。Markdown、CSV、PDF、slides、本地页面预览都可以直接作为审阅对象，用户的评论继续变成下一轮任务上下文。

Goals： 目标要能有具体的量化标准：如要写清楚页面、接口、测试、异常情况分别达到什么结果。

这些点合在一起，就能把任务进化成一个工作循环：

目标 -> 线程 -> 项目记忆 -> 调用工具 -> 产出 -> review -> 下一轮任务

这张图可以作为本次更新的总览。

三层模型

通过上述总结可以把工作流分成三层：

Thread： 保存一条长期任务的上下文
Project memory： 保存 repo 内的事实，也就是 AGENTS.md 和 docs/*
Execution surfaces： 接触真实工作界面，比如 browser、Chrome、computer use、connectors、skills

而 v2 正好属于 Project memory 这一层，所以不需要做改进。另外，长期任务容易越做越多，所以边界要提前写清楚，例如可以配置相关 Hooks

哪些任务适合长期线程？

不是所有任务都要开长期线程。一次性命令、小改动、马上能验完的问题，按 v2 的普通流程就够。

更适合长期线程的场景：

会跨多轮修改
需要用户看预览或多次反馈
需要等待 CI、部署、review、第三方回复
需要跨工具处理，比如 GitHub + 本地代码 + 浏览器
后续可能沉淀成 skill
中断后还要接着做

Prompt 模板

下次遇到复杂任务需要长时间工作流的场景，可以直接这样编写 prompt：可以手动引用 loop goal 命令进一步约束 Agent，确保执行正确

这是一个长期任务线程：<任务名>。

先读 AGENTS.md 和 docs/agent_workflow.md。
必要时再读 docs/project_status.md、docs/project_spec.md、docs/architecture.md。

目标：
- <目标 1>
- <目标 2>

验收标准：
1. <可以检查的结果>
2. <需要运行的检查>
3. <需要用户审阅的产物>

执行规则：
- 先调查，不要急着改代码
- 改前说明方案和影响范围
- 改后运行相关检查
- 涉及 UI 时，启动本地预览并给出地址
- 不要 push、发布、删除数据、发送消息，除非用户明确批准
- 任务中断前，更新 docs/project_status.md

这里的关键是验收标准要能检查。不要只写“完成登录功能”，而是写清楚哪些页面、哪些接口、哪些测试、哪些异常情况必须通过。

Tools

此外还要说清楚，任务需要碰到哪些工具。可手动引用或在规范文档、prompt 中提示

常见选择：

本地网页预览：用 browser
需要用户登录态：用 Chrome
必须点桌面软件：用 computer use
GitHub、Gmail、Slack、Calendar：用对应的 MCP
反复使用的流程：整理成 skill
需要隔一段时间回来查：用 thread automation

checkpoint 的判断

v2 里 checkpoint 更像 commit 前的项目状态检查；这里 checkpoint 更像一次任务阶段记录。

需要 checkpoint 的情况包括：

当前阶段已经完成
任务要暂停
要交给另一个 Agent
后续需要接着做
出现新的风险或阻塞
行为、架构、依赖或项目状态发生变化

与之前的 checkpoint 思想不同，不是为了每次 commit 都按需更新记忆文档，而是为了让任务之后能接上。如果只是普通小改动，就不需要每次都更新一堆 docs。

复盘

v2 规定了 Agent 对项目的维护方式，v3 则是面对复杂长期任务时总结的思想

博客来源：

Codex-maxxing for long-running work

Codex 工作流更新-v2

Sat, 30 May 2026 00:00:00 +0800

相关博客：Claude 迁移 Codex 工作流更新

背景

这次主要是在整理 Codex / Claude Code / 其他 Agent 之间的项目初始化工作流。之前有两个入口，一个是偏 Claude 的 setup，主要维护 CLAUDE.md；另一个是偏 Codex 的 codex-agents-init，主要维护 AGENTS.md。刚开始看起来只是名字不同，但实际用的时候会发现，这两个入口很容易记混，而且 Agent 自己也不一定能稳定判断当前到底运行在 Claude Code、Codex，还是其他兼容环境里。

所以这次调整的重点在于统一入口：以后都走 setup 系列，只是根据项目复杂度分成 setup-light 和 setup-full。

优化

最后没有继续保留默认 setup，也不再使用 codex-agents-init 这个名字，而是拆成两个更明确的入口：setup-light 和 setup-full。 setup-light 保留做小项目、脚本、demo、短期实验，只保留最基本的项目状态和 Agent 工作流记录：

.
├── AGENTS.md
├── CLAUDE.md
└── docs/
    ├── project_status.md
    └── agent_workflow.md

setup-full 适合长期项目、产品型项目、多 Agent 接力，需要完整一点的项目记忆：

.
├── AGENTS.md
├── CLAUDE.md
└── docs/
    ├── brainstorm.md
    ├── project_spec.md
    ├── architecture.md
    ├── project_status.md
    ├── changelog.md
    ├── decisions.md
    ├── agent_workflow.md
    └── bugs/

这里比较重要的是 AGENTS.md 和 CLAUDE.md 的关系。Codex 原生读取 AGENTS.md，Claude Code 则通过 CLAUDE.md 里的 @AGENTS.md 间接读取同一份规则。也就是说真正维护的只有 AGENTS.md，CLAUDE.md 只是桥接文件，避免两边各写一套规则，后面越改越不一致。

setup 现在负责什么

新的 setup 系列不再只服务 Claude，而是作为通用的项目初始化入口。它会创建或更新 AGENTS.md，写入 CLAUDE.md 的桥接内容，按 light / full 创建对应的 docs/ 文件，同时迁移旧的 codex-long-term-docs block，移除旧的 claude-long-term-docs block。

这里需要注意的是，它只替换 managed block，不会整文件覆盖。已经存在的用户规则、已有的 docs 文件，都应该保留下来。setup-light 实际调用的是 --profile light，setup-full 调用的是 --profile full。

codex-agents-init 目录已经删掉了，主要是避免以后又出现两个入口。后续如果继续改初始化逻辑，优先改 setup-light / setup-full 的 skill，尽量不要重新造一个新名字。

AGENTS.md 的定位

这次我不想让 AGENTS.md 变成一份很长的操作手册。它应该告诉 Agent 必须遵守什么，以及更详细的 workflow 去哪里读。checkpoint、commit、bug、handoff 的细节步骤，放到 docs/agent_workflow.md 会更合适。

所以 AGENTS.md 里保留的是文件职责：docs/brainstorm.md 是想法池，不能当最终需求；docs/project_spec.md 是产品行为的事实来源；docs/architecture.md 是系统设计和模块边界；docs/project_status.md 记录当前里程碑、进度、阻塞和下一步；docs/changelog.md 记录有意义的用户可见或开发可见变化；docs/decisions.md 记录重要技术决策；复杂 bug 则先进入 docs/bugs/ 做研究报告。

这次新增了一条比较关键的规则：

Before any git commit, check whether the change requires a checkpoint.

意思是提交前不能只想着 git commit，要先判断这次改动会不会影响项目长期记忆。如果影响产品行为、架构、依赖、项目进度、阻塞、下一步，或者涉及长时间任务交接，就要先更新相关 docs。

具体的 checkpoint / commit / bug / handoff 流程则放到 docs/agent_workflow.md。这样 AGENTS.md 不会越来越长，Agent 真要执行的时候也有地方继续读。

checkpoint 的作用

之前的 /update-docs-and-commit 是有用的，因为它能让 AI 长时间自主工作时留下一个项目状态记录。但是这个命令是会在每次提交都会更新文档，对小项目来说没问题，但是对于一些长期的项目，还需要进一步的优化。

所以后面改成 /checkpoint。

/checkpoint 的逻辑是：先读当前项目记忆，优先看 docs/agent_workflow.md，再看 git status 和 diff，判断这次状态是否值得长期保存。如果值得保存，就更新 docs/project_status.md，按需更新 docs/changelog.md、docs/decisions.md，复杂问题则补 docs/bugs/ 报告，最后再 commit 一次作为恢复点。

它的作用更偏向状态判断：让 AI 在一个任务阶段结束时判断，现在这个状态以后还需不需要恢复。如果只是普通小改动，可以正常提交；但如果这次改动影响行为、架构、依赖、进度、阻塞、交接上下文或未解决风险，就应该先 checkpoint。我觉得 AI 能力越强，对它的 Hermes 应该适当放宽一些，让 AI 自主决定提交～

当前规则是：

The agent may propose a checkpoint, but must create one when changes affect behavior, architecture, dependencies, project status, blockers, next actions, long-running task progress, handoff context, or unresolved risk.
Commit only the checkpoint-relevant files and current work.
Do not push unless the user explicitly asks or the current task grants push/publish authorization.

这里默认不 push。这样可以让 AI 自主维护状态，但不会未经授权把内容发布出去。

setup skill 排版重构

后来又对 setup-light 和 setup-full 的 SKILL.md 做了一次排版重构。

之前的问题是模板内容太靠前，Agent 一进来先看到一大段生成内容，反而不容易立刻知道自己应该怎么执行。后面改成先说明 profile 和事实来源，再写执行流程和安全规则，最后才放模板。

新的主结构是：

Profile
Sources Of Truth
Workflow
Safety Rules
Minimal Templates
Managed Block

这样做的好处是，Profile 先告诉 Agent light / full 分别适合什么项目；Sources Of Truth 明确 AGENTS.md、CLAUDE.md、SKILL.md 的职责；Workflow 放在前面，Agent 不需要先读完大段模板；Safety Rules 提前强调不能覆盖用户已有内容、不能自动 commit、不能做无关修改。

Minimal Templates 和 Managed Block 继续保留在 SKILL.md 中，脚本仍然从 skill 中抽取模板和 managed block。这样以后只需要改 skill，就能更新生成结果，不需要在脚本里再重复维护一份模板。

复盘

这次更新的核心是把工作流拆清楚。初始化规则交给 setup-light 和 setup-full，长期项目记忆放进 AGENTS.md 和 docs/，Claude Code 通过 @AGENTS.md 复用同一套规则，细流程放进 docs/agent_workflow.md，长时间自主工作再靠 /checkpoint 建立恢复点。

我觉得这里比较重要的一点是：AGENTS.md 只负责放最核心的规则和文件职责，尽量精简，如果需要更详细的说明可给出对应文件的索引，让 AI 按需寻找。比如一开始我规定 AGENTS.md 里放着具体的 workflow 流程，具体到每一步都写上去了，那我们就可以将这些具体步骤放到 docs/agent_workflow.md，在 AGENTS.md 中只需给出对应的文档索引，模型就会去主动找，这样后面维护起来更清楚。

这次还有一个经验：工作流本身也可以让 AI 参与 review，减少一次性拍定方案的风险。最开始只是想合并 Claude 和 Codex 的初始化入口，后来让 AI 从批判角度检查，发现 AGENTS.md 承载了太多流程说明；再继续拆流程，又发现小项目不需要完整 docs，所以才拆成 light 和 full；最后又发现脚本不应该重复维护大量模板内容，于是改成从 SKILL.md 里抽取模板。

Claude 迁移 Codex 工作流更新

Sun, 03 May 2026 14:25:17 +0000

Claude 迁移 Codex 工作流更新

工作流框架

这篇博客旨在为从 Claude 转到 Codex 的工作者提供一些注意事项与 Tips。

Claude code 的工作方式与 Codex 还是有些许不一样，Claude code 更适合长对话的上下文，将模糊的想法转为可实现的东西，而 Codex 更专注于任务的执行，所以需要稍微改变一下我们的使用习惯。

先介绍下我的 Claude 工作流，大致为：先沉淀想法brainstorm.md → 生成规格文档project_spec.md → 拆架构与里程碑 → issue 化 bug → 研究报告驱动修复 → commit 同步 changelog/status，维护项目的变更日志与进度。

首先最明显的改变即是 CLAUDE.md 改为 AGENTS.md，但他们维护重心都是要求要短、准确、实用，不要写成又长又泛的“愿景文档”。

我的长期维护文件也有变化，新增了decisions.md

.
├── AGENTS.md                  # Codex 的长期项目指令，替代 CLAUDE.md
├── docs/
│   ├── brainstorm.md          # 想法池，偏发散
│   ├── project_spec.md        # 产品规格，偏稳定
│   ├── architecture.md        # 架构设计
│   ├── project_status.md      # 当前进度与里程碑
│   ├── changelog.md           # 用户可读/开发可读变更记录
│   ├── decisions.md           # 重要技术决策记录
│   └── bugs/
│       └── issue-xxx-research.md  # 定位、写研究报告，再修 bug

我之前的工作流有一个问题，即每次commit会把变化放在 project_status 和 changelog，时间长了这部分记录会非常长，这类决策后面会反复影响实现。decisions.md 专门记录技术取舍，比放进 changelog 更清除

在自己整理完想法文档后，建议不要让 Codex 直接让它根据对话结果自由生成项目规格，更加稳健的是执行以下指令

阅读 docs/brainstorm.md。

请不要修改代码。只做需求整理，生成 docs/project_spec.md。

要求：

区分「已确定需求」「待确认问题」「暂不实现」

每个核心功能必须包含：用户场景、输入、输出、边界条件、失败情况

不要脑补未在 brainstorm 中出现的功能

如果发现冲突，写入「待确认问题」，不要自行决定

如果有不确定的则向用户提问，直至你有信心能完成最初的 MVP

Bug 工作流

我在 Claude 中处理 Bug 的工作流为：复杂 bug → 写研究报告research report → 提issue → 基于研究报告修复，这套工作流同样可适用于 Codex

Step 1：创建研究报告

阅读 GitHub issue #23 和相关代码。

第一阶段：只调查，不修改代码。
请生成 docs/bugs/issue-23-research.md，内容包括：

现象复述

最小复现路径

相关文件和调用链

根因假设，按可能性排序

推荐修复方案

需要新增/修改的测试

风险点

完成后停止，不要修复。

Step 2：基于研究报告修复 bug

基于 docs/bugs/issue-23-research.md 修复 bug。

要求：

先实现最小修复，不做无关重构

添加或更新测试

运行相关测试

更新 docs/changelog.md 和 docs/project_status.md

最后给出变更摘要、测试结果、风险说明

当然，可以将这些可复用的prompt封装成skill或者专属于你的命令行，这都是可行的。

维护记忆文档

上述提到的维护长期文件，我们可以将这套规则写入 Codex 的记忆文档中，我们每次初始化记忆文档时，Codex 就会自动帮我们维护这些长期文件，这对长时间的工作是非常重要。

同样我们也可以创建相关的skill

以在 Windows PowerShell 为例，创建这个目录：

mkdir "$HOME\.agents\skills\codex-agents-init"
mkdir "$HOME\.agents\skills\codex-agents-init\scripts"

~/.codex 主要是 Codex 配置和全局 AGENTS.md；用户级 Skill 的推荐位置是 $HOME/.agents/skills。

然后创建SKILL.md：

notepad "$HOME\.agents\skills\codex-agents-init\SKILL.md"

把下面内容完整粘进去👇：

name: codex-agents-init
description: Initialize or update a repository AGENTS.md for Codex with long-term documentation maintenance rules. Use this when the user asks to initialize AGENTS.md, set up Codex project instructions, add docs/project_spec.md architecture/status/changelog rules, or create a document-driven Codex workflow.

Codex AGENTS.md Initialization Skill

Use this skill when the user asks to initialize or update Codex project instructions, especially with phrases like:

初始化 AGENTS.md

初始化 agents

创建 Codex 项目规范

加上长期文件维护规则

初始化 docs 工作流

添加 project_spec / architecture / project_status / changelog 维护规范

set up AGENTS.md for this repo

initialize Codex instructions

Goal

Create or update the current repository so that Codex has durable project instructions and long-term documentation maintenance rules.

The expected repository structure is:
.
├── AGENTS.md
└── docs/
    ├── brainstorm.md
    ├── project_spec.md
    ├── architecture.md
    ├── project_status.md
    ├── changelog.md
    ├── decisions.md
    └── bugs/
Required behavior

When invoked:

Locate the repository root.

Prefer git rev-parse --show-toplevel.

If that fails, use the current working directory.

Create AGENTS.md if it does not exist.

If AGENTS.md exists, preserve existing content.

Do not delete existing project-specific rules.

Do not overwrite the whole file.

Append or replace only the managed block marked by:


Ensure these files/directories exist:

docs/brainstorm.md

docs/project_spec.md

docs/architecture.md

docs/project_status.md

docs/changelog.md

docs/decisions.md

docs/bugs/

Do not overwrite existing documentation files.

If a file already exists, leave its content unchanged.

If a file is missing, create it with a minimal useful template.

Add long-term maintenance rules to AGENTS.md.

The rules must state:

docs/brainstorm.md is an idea pool and must not be treated as final requirements.

docs/project_spec.md is the source of truth for product behavior.

docs/architecture.md is the source of truth for system design and module boundaries.

docs/project_status.md tracks current milestone, progress, blockers, and next actions.

docs/changelog.md records user-visible or developer-visible behavior changes.

docs/decisions.md records important technical decisions and rationale.

docs/bugs/ stores complex bug investigation reports.

For complex bugs, first create a research report under docs/bugs/, then implement the fix in a separate step unless the user explicitly asks otherwise.

Before finishing implementation tasks, update docs/changelog.md and docs/project_status.md when relevant.

Do not perform broad rewrites or unrelated refactors during initialization.

Prefer using the bundled script:
powershell -ExecutionPolicy Bypass -File .agents/skills/codex-agents-init/scripts/init-codex-agents.ps1
If the skill is installed in the user-level skill directory, run the script from that location instead:
powershell -ExecutionPolicy Bypass -File "$HOME\.agents\skills\codex-agents-init\scripts\init-codex-agents.ps1"
After running, summarize:

Created files

Skipped existing files

Updated AGENTS.md

Any errors or manual follow-up needed

Safety rules

Never delete existing documentation.

Never overwrite an existing AGENTS.md.

Never make unrelated code changes.

Never commit automatically unless the user explicitly asks.

If shell execution is unavailable, perform the same changes manually.

然后创建脚本：

notepad "$HOME\.agents\skills\codex-agents-init\scripts\init-codex-agents.ps1"

在脚本里粘贴下面这份：

$ErrorActionPreference = "Stop"

function Get-RepoRoot {
  try {
    $root = git rev-parse --show-toplevel 2>$null
    if ($LASTEXITCODE -eq 0 -and $root) {
      return $root.Trim()
    }
  } catch {
    # Fallback below.
  }

  return (Get-Location).Path
}

$RepoRoot = Get-RepoRoot
Set-Location $RepoRoot

$Created = New-Object System.Collections.Generic.List[string]
$Skipped = New-Object System.Collections.Generic.List[string]
$Updated = New-Object System.Collections.Generic.List[string]

function Ensure-Directory {
  param([string]$Path)

  if (!(Test-Path $Path)) {
    New-Item -ItemType Directory -Path $Path -Force | Out-Null
    $Created.Add($Path + "/")
  } else {
    $Skipped.Add($Path + "/")
  }
}

function Ensure-File {
  param(
    [string]$Path,
    [string]$Content
  )

  $Dir = Split-Path $Path

  if ($Dir -and !(Test-Path $Dir)) {
    New-Item -ItemType Directory -Path $Dir -Force | Out-Null
    $Created.Add($Dir + "/")
  }

  if (Test-Path $Path) {
    $Skipped.Add($Path)
    return
  }

  Set-Content -Path $Path -Value $Content -Encoding UTF8
  $Created.Add($Path)
}

$AgentsBlock = @"
<!-- BEGIN: codex-long-term-docs -->

## Long-term documentation workflow

This repository uses durable documentation files under `docs/` as project memory. Before modifying code, read the relevant documentation files and preserve their roles.

### Documentation sources of truth

- `docs/brainstorm.md`: rough ideas, pain points, and early product thinking. Do not treat this file as final requirements.
- `docs/project_spec.md`: source of truth for product behavior, user scenarios, accepted requirements, non-goals, edge cases, and failure behavior.
- `docs/architecture.md`: source of truth for system design, module boundaries, data flow, key abstractions, dependencies, and trade-offs.
- `docs/project_status.md`: source of truth for current milestone, progress, blockers, open questions, and next actions.
- `docs/changelog.md`: chronological record of user-visible or developer-visible behavior changes.
- `docs/decisions.md`: important technical decisions and their rationale.
- `docs/bugs/`: complex bug investigation reports.

### Before implementation

- Read `docs/project_spec.md`, `docs/architecture.md`, and `docs/project_status.md` when relevant.
- If `docs/brainstorm.md` conflicts with `docs/project_spec.md`, follow `docs/project_spec.md`.
- If requirements are ambiguous, record assumptions or questions in `docs/project_status.md` instead of silently guessing.
- Prefer small, coherent, reversible changes.

### Complex bug workflow

For complex bugs:

1. First create a research report under `docs/bugs/`.
2. The report should include:
   - Symptom summary
   - Minimal reproduction path
   - Related files and call chain
   - Root-cause hypotheses ranked by likelihood
   - Recommended fix
   - Required tests
   - Risks and rollback notes
3. Do not implement the fix in the same step unless explicitly asked.

### Before finishing a task

- Run relevant tests, or explain why they could not be run.
- Update `docs/changelog.md` when behavior changes, a feature is added, a user-visible bug is fixed, configuration changes, or a breaking change is introduced.
- Update `docs/project_status.md` when milestone progress, blockers, or next actions change.
- Do not update `docs/changelog.md` for pure formatting, comment-only changes, test-only refactors, or internal renames with no behavior change.
- Summarize changed files, tests run, and remaining risks.

<!-- END: codex-long-term-docs -->
"@

function Ensure-AgentsMd {
  $Path = "AGENTS.md"

  if (!(Test-Path $Path)) {
    Set-Content -Path $Path -Value "# AGENTS.md`n`n$AgentsBlock`n" -Encoding UTF8
    $Created.Add($Path)
    return
  }

  $Existing = Get-Content -Path $Path -Raw

  $Pattern = "(?s)<!-- BEGIN: codex-long-term-docs -->.*?<!-- END: codex-long-term-docs -->"

  if ($Existing -match $Pattern) {
    $NewContent = [regex]::Replace($Existing, $Pattern, $AgentsBlock.Trim())
    Set-Content -Path $Path -Value $NewContent -Encoding UTF8
    $Updated.Add($Path + " managed block")
    return
  }

  $Separator = if ($Existing.Trim().Length -eq 0) { "" } else { "`n`n" }
  Add-Content -Path $Path -Value ($Separator + $AgentsBlock)
  $Updated.Add($Path + " appended managed block")
}

Ensure-AgentsMd

Ensure-File "docs/brainstorm.md" @"
# Brainstorm

This file stores rough ideas, pain points, feature intuition, and early product thinking.

Do not treat this file as final requirements.

## Raw ideas

-

## Pain points

-

## Core feature candidates

-

## Open questions

-
"@

Ensure-File "docs/project_spec.md" @"
# Project Specification

This file is the source of truth for product behavior.

## Product goal

-

## Users and scenarios

-

## Core requirements

-

## Non-goals

-

## Inputs and outputs

-

## Edge cases

-

## Failure behavior

-

## Acceptance criteria

-
"@

Ensure-File "docs/architecture.md" @"
# Architecture

This file is the source of truth for system design and module boundaries.

## Overview

-

## Module boundaries

-

## Data flow

-

## Key abstractions

-

## External dependencies

-

## Risks and trade-offs

-
"@

Ensure-File "docs/project_status.md" @"
# Project Status

## Current milestone

Milestone:

Status:

## Done

-

## In progress

-

## Blocked / Questions

-

## Next actions

1.
2.
3.
"@

Ensure-File "docs/changelog.md" @"
# Changelog

All notable changes to this project should be documented here.

## Unreleased

### Added

-

### Changed

-

### Fixed

-

### Removed

-
"@

Ensure-File "docs/decisions.md" @"
# Technical Decisions

This file records important technical decisions and their rationale.

## Template

### YYYY-MM-DD - Decision title

Status: Proposed / Accepted / Rejected / Superseded

Context:

Decision:

Alternatives considered:

Consequences:
"@

Ensure-Directory "docs/bugs"

Write-Host ""
Write-Host "Codex AGENTS.md documentation workflow initialized."
Write-Host "Repository root: $RepoRoot"
Write-Host ""

Write-Host "Created:"
if ($Created.Count -eq 0) {
  Write-Host "  - None"
} else {
  $Created | ForEach-Object { Write-Host "  - $_" }
}

Write-Host ""
Write-Host "Updated:"
if ($Updated.Count -eq 0) {
  Write-Host "  - None"
} else {
  $Updated | ForEach-Object { Write-Host "  - $_" }
}

Write-Host ""
Write-Host "Skipped existing:"
if ($Skipped.Count -eq 0) {
  Write-Host "  - None"
} else {
  $Skipped | ForEach-Object { Write-Host "  - $_" }
}

这样你的 Skill 结构就是：

$HOME\.agents\skills\codex-agents-init\
├── SKILL.md
└── scripts\
    └── init-codex-agents.ps1

保存后，重启 Codex 桌面端,之后你在 Codex 里可以这样说：

/codex-agents-init 初始化当前项目的 AGENTS.md，并加上长期文件维护规范。

或者直接说：

初始化 AGENTS.md，并创建 docs/project_spec.md、architecture.md、project_status.md、changelog.md 等长期维护文件。

结语

以上就是我目前的工作流的整体迁移，整体来说都是比较无缝衔接的，希望这篇帖子对你有所帮助~