在使用claude code 进行项目优化时，它提出了如下的卡片形式：
<标题>
- 批次：<数字；不确定时填「待确认」>
- 状态：TODO
- 依赖：<其他卡片 ID 列表 或「无」；如果你从需求中识别出语义依赖，列出来并标注「待我确认 ID」>
- 自检：<可执行命令 / 「手动：……」一句话 / 「无」；优先从验收标准中归纳出最小验证步骤>
问题定位
<为什么要做、当前痛点；尽量引用具体 文件:行号>
实施方案
<分步骤，每步可独立验证；不要重新设计，不要提替代方案>
涉及位置
<具体 文件:行号；区分「会改」与「只读引用」；明确不会改动的范围>
风险
<可能的副作用、要规避的情况、被打断的边界场景；列出对策>
验收标准
<可逐条勾选的 checkbox 列表；覆盖正常路径 + 异常路径 + 持久化 + 边界场景>
基于此，我将该卡片发送给AI，AI完成了该卡片，但我还有别的卡片需要完成 
，我转念一想，我要是将这写卡片都用/goal 命令完成岂不是省力，然后我粘贴了多占卡片，不出所料超出了长度限制…
于是我转向让/goal 命令通过阅读文档的形式来获取任务。于是产出了如下数个文档：
agent-rules（agent运行总则）
Agent 执行规则
本文件定义 Codex / Agent 执行任务时必须遵守的固定规则。
配套文件：
docs/agent-plan.md：任务卡片（卡片状态以本文件为权威源）docs/agent-progress.md：运行时进度（不再镜像状态表，只记录会话与「不要重复做」）
基本原则
- 只执行
docs/agent-progress.md中「当前批次」对应的任务。- 按
docs/agent-plan.md中的卡片顺序执行。- 不要重新设计方案，不要提出替代方案。
- 不要重构无关代码。
- 不要改变接口、数据结构和现有业务逻辑。
- 不要删除现有功能。
- 不要引入第三方依赖，除非卡片明确要求。
- 如果代码结构与卡片描述不一致，做最小侵入式适配；适配范围超出卡片描述时标记 BLOCKED。
- 卡片状态以
docs/agent-plan.md为权威源，docs/agent-progress.md中不重复维护状态表。
启动协议
每次会话开始前必须按顺序完成：
- 完整读取
docs/agent-rules.md、docs/agent-plan.md、docs/agent-progress.md。- 读取
docs/agent-progress.md中「不要重复做」清单，避免在本轮重复已知失败或无效的尝试。- 以
docs/agent-progress.md中「当前批次」为本轮范围，输出本轮将执行的卡片列表，再开始执行。- 在
docs/agent-progress.md的「会话历史」末尾追加一个新的### 会话 YYYY-MM-DD HH:mm块，本轮所有运行时记录写入该块；不修改历史会话块。
批次推进协议
- 当「当前批次」的所有卡片状态都为 DONE（或 BLOCKED 已被用户确认）时：
- 将
docs/agent-progress.md中「当前批次」的值 +1；- 在当前会话块中输出推进确认信息；
- 停止执行，等待用户决定是否继续下一批次；
- 不要自动开始下一批次的卡片。
卡片状态
每张卡片只能使用以下状态之一：
- TODO：未开始
- IN_PROGRESS：正在执行
- DONE：已完成
- BLOCKED：无法安全继续
卡片字段规范
每张卡片必须包含以下字段，缺字段视为卡片不合格，标记 BLOCKED 并提示用户补全。
头部（机读元数据）：
- 批次：数字
- 状态：TODO / IN_PROGRESS / DONE / BLOCKED
- 依赖：其他卡片 ID 或「无」
- 自检：可执行命令、「手动：…」描述，或「无」
正文（5 字段强制结构）：
- 问题定位：为什么要做、当前痛点
- 实施方案：具体步骤
- 涉及位置：会改动的文件/组件/接口
- 风险：可能的副作用、需要规避的情况
- 验收标准：可逐条勾选的 checkbox 列表
运行时：
- 执行记录：Agent 完成后填写（时间、实际改动文件、自检结果、风险回应）
每张卡片的执行流程
- 阅读卡片所有字段，特别注意「风险」与「依赖」。
- 在
docs/agent-plan.md中将卡片状态改为 IN_PROGRESS。- 在「涉及位置」范围内做最小改动；超出该范围立即停止并标记 BLOCKED。
- 执行卡片「自检」命令；填写为「无」时跳过自动校验，按验收标准做人工核对。
- 通过验收后将卡片状态改为 DONE；未通过且无法在最小范围修复时改为 BLOCKED。
- 在卡片「执行记录」中填写：时间、实际改动文件、自检结果、风险回应（已规避 / 已发生 / 不适用）。
- 在当前会话块中追加该卡片的完成摘要。
自检定义
- 「自检」字段是该卡片唯一的自动化校验入口。
- 自检命令失败时，不要通过修改无关代码绕过；先尝试在「涉及位置」范围内修复，仍失败则标记 BLOCKED。
- 「自检」为「无」或「手动：…」时，必须在执行记录中描述人工验证步骤与结果。
停止条件
遇到以下任一情况立即停止并输出说明：
- 「当前批次」所有卡片完成（触发批次推进协议）；
- 卡片自检失败且无法在最小范围内修复；
- 需要修改接口、数据结构或核心业务逻辑，但卡片未明确要求；
- 卡片字段不合格、依赖卡片未完成、或「涉及位置」不存在。
输出要求
每次会话结束时必须输出：
- 本次完成 / BLOCKED 的卡片 ID；
- 实际修改的文件列表；
- 自检命令及结果（含手动验证摘要）；
- 阻塞原因（若有）；
- 下一步建议：继续下一张 TODO 卡片 / 触发批次推进 / 等待用户决策。
agent-progress（用于规范操作流程）
Agent 执行进度
本文件记录 Agent 运行时状态，用于多轮任务续接。
- 卡片状态以
docs/agent-plan.md为权威源，本文件不再镜像状态表。- 本文件维护三件事：当前批次指针、不要重复做清单、会话历史。
当前批次
1
当前批次的所有卡片 DONE 后，由 Agent 按「批次推进协议」将此值 +1，并停止等待用户确认。
不要重复做
Agent 启动时必读。记录已知失败、无效或被用户否决的尝试，避免在新会话中重复。
每条用一行简述，必要时附会话日期。
- 空。
会话历史
每次会话开始时，Agent 在本节末尾追加一个新的
### 会话 YYYY-MM-DD HH:mm块。
历史会话块只读，不修改。会话模板（复制使用，不要修改本块）
### 会话 YYYY-MM-DD HH:mm - 本轮范围：批次 N，卡片 X1 / X2 - 完成： - X1：DONE - X2：BLOCKED（原因：...） - 修改文件： - path/to/a - path/to/b - 自检： - X1：命令或手动步骤 → 结果 - X2：... - 风险回应： - X1：已规避 / 已发生 / 不适用 - 阻塞与待决： - （若有） - 下一步： - 继续 X3 / 触发批次推进 / 等待用户决策
agent-plan(用于存放卡片)
Agent 任务计划
本文件是任务卡片清单，卡片状态以本文件为权威源。
执行规则见：
docs/agent-rules.md运行时进度见：
docs/agent-progress.md卡片字段规范见
docs/agent-rules.md中「卡片字段规范」一节。
至此，我们完成了一个较完整的工作流，但是还缺乏卡片生成器及启动提示词，经过折腾，产出如下：
agent-card-template(用于生成卡片)
卡片生成指令
用途：让 AI 帮你写一张新的任务卡片时，复制下方
===== 模板 =====之间的内容贴在需求前面，AI 会按规范输出可直接粘贴进docs/agent-plan.md的卡片。字段规范的权威定义见
docs/agent-rules.md中「卡片字段规范」一节。本模板与之保持一致。
使用步骤
- 复制下方
===== 模板 =====之间的全部内容。- 贴在你描述需求的消息开头，紧接着写出你的需求。
- AI 输出卡片后，你只需确认两项：
- 批次：数字由你定（AI 不知道你的批次排期）。
- 依赖：如果 AI 标注了「待我确认 ID」，对照
docs/agent-plan.md把 ID 补准或改为「无」。- 把卡片粘贴到
docs/agent-plan.md末尾，用---与上一张卡片分隔。- 当前阶段请先完成：
- 扫描项目结构；
- 找到主要入口文件、核心页面、状态管理、请求封装、渲染函数；
===== 模板 =====
请按以下格式输出任务卡片，所有字段必填，不要省略，不要解释，直接输出 Markdown：
## <ID> <标题> - 批次：<数字；不确定时填「待确认」> - 状态：TODO - 依赖：<其他卡片 ID 列表 或「无」；如果你从需求中识别出语义依赖，列出来并标注「待我确认 ID」> - 自检：<可执行命令 / 「手动：……」一句话 / 「无」；优先从验收标准中归纳出最小验证步骤> ### 问题定位 <为什么要做、当前痛点；尽量引用具体 文件:行号> ### 实施方案 <分步骤，每步可独立验证；不要重新设计，不要提替代方案> ### 涉及位置 <具体 文件:行号；区分「会改」与「只读引用」；明确不会改动的范围> ### 风险 <可能的副作用、要规避的情况、被打断的边界场景；列出对策> ### 验收标准 <可逐条勾选的 checkbox 列表；覆盖正常路径 + 异常路径 + 持久化 + 边界场景> ### 执行记录 （Agent 填写：完成时间 / 实际改动文件 / 自检结果 / 风险回应）约束：
- 不要新增字段，不要删除字段。
- 不要在字段里写「TODO 待补」「视情况而定」之类的占位话术；信息不足时写「无」或直接问我。
- 「实施方案」和「涉及位置」必须引用具体文件路径，不接受「项目主文件」「相关组件」这类泛指。
- 「验收标准」每条必须是可观察的行为，不接受「代码质量好」「性能提升」这类不可验证的描述。
===== 模板结束 =====
卡片示例（最小完整版）
## A1 首屏加载反馈演示 - 批次：1 - 状态：TODO - 依赖：无 - 自检：手动：浏览器打开 `index.html`，刷新页面观察加载反馈 ### 问题定位 演示页面在数据加载期间无任何视觉反馈，用户会误以为页面卡死。 ### 实施方案 1. 在 `index.html` 中定位数据加载相关代码段。 2. 请求开始时显示 loading 提示，结束（成功或失败）后隐藏。 3. 优先复用页面中已有的提示元素。 ### 涉及位置 - `index.html`（前端单文件，定位数据加载相关脚本块）。 - 不修改 `server.js` 与数据库相关代码。 ### 风险 - 不要把 loading 状态做成全局变量。 - 不要改变现有 fetch 接口和返回数据结构。 - 不要引入第三方 loading 库。 ### 验收标准 - [ ] 触发数据加载时可见反馈； - [ ] 加载完成后反馈消失； - [ ] 加载失败时反馈也能正确退出； - [ ] 未改动接口签名和返回数据结构。 ### 执行记录 （Agent 填写：完成时间 / 实际改动文件 / 自检结果 / 风险回应）
以及最后的启动提示词：
请按以下流程执行任务：
先完整读取：
- docs/agent-rules.md
- docs/agent-plan.md
- docs/agent-progress.md
严格遵守 agent-rules.md 中的所有规则。
以 agent-progress.md 中的「当前批次」为本轮范围，
按 agent-plan.md 的卡片顺序，只执行该批次中状态为 TODO 的卡片。每完成一张卡片，按 rules.md 要求更新 plan.md 和 progress.md。
先输出本轮将执行的卡片列表，再开始执行。
至此，完成了所有文档准备，我们只需要将卡片完成，就可以用goal命令愉快的摸鱼了！！！
以下是简化版的操作流程：
- 先让 AI 根据需求生成卡片
- 你确认批次和依赖
- 把卡片粘到 agent-plan.md
- 让 Agent 按 rules/progress/plan 执行
- 每轮只做当前批次
- 批次完成后停下
- 你检查结果，再决定是否进入下一批
欢迎各位愿意尝试的佬欢迎提出优化建议和问题。
1 个帖子 - 1 位参与者