1. 项目概述为AI编码助手引入“操作手册”如果你和我一样在过去一年里深度使用过 Claude Code、Cursor、GitHub Copilot 或 Codex 这类 AI 编码助手你肯定经历过这样的场景你让 AI 帮你重构一个复杂的组件它写了一半然后对话因为各种原因网络中断、模型上下文限制、你临时离开中断了。当你重新打开项目试图让 AI “接着刚才的继续”时它要么一脸茫然要么开始基于错误的理解重新生成代码你不得不花大量时间重新解释上下文、架构决策和已经完成的部分。这种“上下文丢失”和“记忆断层”是当前 AI 辅助开发中最令人沮丧的痛点之一。Matsumiko/runbook正是为了解决这个问题而生的。它不是一个新模型也不是一个替代现有 AI 助手的工具而是一个“操作手册”或“项目记忆层”。它的核心思想是将项目的关键上下文、开发规范、会话状态和任务计划以结构化的 Markdown 和 JSON 文件形式持久化在代码仓库中。这样无论是同一个 AI 助手在不同会话间还是不同的 AI 助手比如从 Claude 切换到 Cursor都能基于这份共享的“记忆”无缝地继续工作大幅减少重复沟通和上下文重建的成本。简单来说RunBook 为你的代码仓库装上了一块“固态硬盘”让 AI 编码助手拥有了跨会话、跨工具的持久化工作记忆。它特别适合需要长期迭代、团队协作或由 AI 主导进行大量代码生成和重构的项目。2. 核心设计理念与架构拆解RunBook 的设计哲学可以概括为“审计优先谨慎实施诚实验证”。这不仅仅是口号而是贯穿其所有功能的指导原则。它试图将人类工程师的严谨工作流——规划、记录、检查、迭代——编码成一套 AI 也能理解和遵循的协议。2.1 核心文件系统构建项目记忆体RunBook 的核心是一系列放置在项目根目录下的 Markdown 文件。这些文件共同构成了项目的“记忆体”和“操作手册”。我们来逐一拆解每个文件的设计意图AGENTS.md这是 AI 助手的“主操作手册”。它定义了在这个项目中工作的核心原则、代码风格、提交规范、测试要求等。你可以把它想象成给新加入项目的 AI 工程师的入职文档。例如里面会明确规定“本项目使用 TypeScript 严格模式”、“组件采用函数式写法并导出 Props 接口”、“所有 API 调用必须包含错误边界处理”。当 AI 开始工作时首先被引导阅读这个文件确保其输出符合项目规范。SESSION.md与.runbook/sessions/这是实现“会话恢复”功能的关键。SESSION.md定义了一个协议指导 AI 如何将当前的工作状态包括目标、计划、已修改的文件、下一步行动等序列化成一个 JSON 文件保存在.runbook/sessions/目录下。这个 JSON 文件就像一个游戏的“存档点”。如果会话中断新的 AI 实例可以通过读取最新的存档文件快速恢复到中断前的精确状态包括光标位置和思维链。SESSION-EXAMPLE.json则提供了一个标准格式的示例。CODER.md这是项目的“长期记忆”。它记录了那些不会频繁变动但对理解项目至关重要的信息如何启动开发服务器、关键的环境变量、数据库连接字符串的格式、常用的 npm scripts、项目特有的“坑”Gotchas以及整体的架构图。这部分信息通常不会写在README.md里但对 AI 高效工作至关重要。PLAN.md与TODO.md这两个文件管理任务流。PLAN.md是“当前执行计划”是一个动态的、细粒度的任务列表描述正在进行的任务的具体步骤。TODO.md则是“战略待办清单”按价值和影响优先级排序是PLAN.md的任务来源。这模仿了敏捷开发中的 Sprint Backlog 和 Product Backlog。CHANGELOG.md一个诚实的、有意义的变更日志。RunBook 鼓励 AI 在完成一个有意义的功能块后主动更新此文件记录“做了什么”以及“为什么这么做”而不是简单地罗列提交信息。这为项目提供了可追溯的决策历史。FRONTEND-DNA.md与BACKEND-SECURITY-CHECKLIST.md这是领域特定的“护栏”文件。FRONTEND-DNA.md定义了前端的设计系统核心色彩体系、间距比例、字体层级、交互状态等。BACKEND-SECURITY-CHECKLIST.md则是一个安全检查清单确保 AI 在编写后端代码时不会遗漏输入验证、SQL 注入防护、权限检查等关键安全项。AGENT-VARIANTS.md这是一个兼容性矩阵记录了不同 AI 助手Claude, Cursor, Copilot, Codex 等在本项目中的特定配置、已知的提示词差异或最佳实践。这确保了多 AI 环境下的行为一致性。2.2 会话恢复机制从“失忆”到“断点续传”会话恢复是 RunBook 最亮眼的功能。传统上AI 对话是“无状态”的。RunBook 通过一个简单的协议使其“有状态化”。创建检查点当 AI 开始一个非平凡任务比如“重构用户资料页面”时它会根据SESSION.md的指引创建一个会话文件例如.runbook/sessions/SESSION-20240420-1430.json。这个文件包含了project项目元数据名称、根目录、Git 远程地址、分支。goal本次会话的最终目标。assumptions基于项目上下文所做的假设。plan为达成目标制定的步骤计划。decisions已做出的关键技术决策及原因。touched_files已查看或修改的文件列表及其最新状态摘要。next_step下一步要执行的具体操作。system_state系统状态如开发服务器是否在运行。恢复会话当需要恢复工作时例如打开新的终端窗口AI 或开发者可以运行runbook session list查看可恢复的会话。然后AI 会读取最新的ACTIVE状态会话文件。它会先“审计”工作区比对touched_files中的记录与当前文件状态确认没有外部冲突。之后它便可以从next_step处无缝继续仿佛从未中断。安全与清理会话文件默认被.gitignore排除在版本控制之外因为它们是临时的运行时产物。runbook session clear命令可以安全地清理已COMPLETED或CANCELLED的会话。对于因崩溃而残留的ACTIVE会话RunBook 采取保守策略除非使用--all --force否则不会删除以便手动恢复。实操心得会话命名的智慧默认的基于时间戳的会话文件名如SESSION-20240420-1430.json虽然唯一但缺乏语义。在实际使用中我习惯在初始化会话时让 AI 在goal字段填写清晰的任务描述并手动将文件名改为类似SESSION-refactor-user-profile-component.json。这样在session list时一目了然便于管理多个并行任务。2.3 多智能体适配器统一工作界面RunBook 的另一个强大之处在于它对主流 AI 编码助手提供了“原生适配”。它并不是为每个工具重新发明轮子而是提供了一套统一的“语言”即那些 Markdown 文件并给出了如何让不同 AI 助手理解这套语言的指引。对于 Claude Code/Cursor这些工具通常能直接读取项目根目录下的 Markdown 文件。你只需在对话开始时提示“请先阅读AGENTS.md和CODER.md以了解项目上下文。”对于 GitHub Copilot Chat你可以在 IDE 的 Copilot Chat 中通过workspace指令让它索引这些文件或者直接粘贴相关章节作为上下文。对于 Windsurf/Cline/Aider这些工具通常支持通过配置文件或初始提示词加载上下文。RunBook 的AGENT-VARIANTS.md可能会包含针对这些工具的特定配置片段。这种设计使得项目上下文和开发规范成为一种与工具无关的资产极大地提升了团队协作和工具切换的灵活性。3. 从零开始RunBook 的完整实操流程3.1 环境准备与安装决策RunBook 是一个 Node.js CLI 工具要求 Node.js 版本 18。安装方式非常灵活你可以根据使用场景选择场景一快速体验推荐初次使用者无需安装直接使用npx运行。这是最干净、无侵入的方式适合快速评估或一次性初始化。npx matsumiko/runbook init场景二项目级依赖推荐团队项目将 RunBook 作为开发依赖安装到项目中确保所有协作者环境一致。npm install -D matsumiko/runbook # 之后在项目内使用 npx runbook init --agent all你还可以在package.json的scripts中封装常用命令提升团队体验{ scripts: { runbook:init: runbook init --agent all, runbook:session:list: runbook session list, runbook:skill:install: runbook skill install frontend-foundation-builder } }场景三全局安装适合重度个人用户如果你频繁在多个个人项目中使用 RunBook可以全局安装以获得最短的命令。npm install -g matsumiko/runbook # 之后在任何地方直接使用 runbook skill list注意事项权限与网络全局安装可能需要sudo在 Linux/macOS 上或以管理员身份运行在 Windows 上。使用npx或本地安装通常能避免权限问题。同时npx会从网络下载包请确保你的网络环境畅通。3.2 初始化项目注入“操作手册”初始化是使用 RunBook 的第一步。它会创建上一节提到的所有核心文件。基础初始化# 在当前目录初始化 npx matsumiko/runbook init这会在当前目录生成全套 RunBook 文件。如果文件已存在默认会跳过避免覆盖你的已有配置。指定 AI 助手适配器 RunBook 允许你在初始化时为特定的 AI 助手生成更针对性的引导内容。例如如果你主要用 Claude Codenpx matsumiko/runbook init --agent claude如果你使用多种工具npx matsumiko/runbook init --agent claude,cursor,copilot或者一次性为所有支持的助手生成适配说明npx matsumiko/runbook init --agent all高级初始化选项--dry-run预览将要生成的文件列表和内容而不实际写入磁盘。这在首次使用或不确定时非常有用。--force强制覆盖已存在的 RunBook 文件。请谨慎使用最好先备份。指定路径你可以在任何子目录初始化 RunBook这对于 Monorepo 项目特别有用。npx matsumiko/runbook init ./packages/web-app --agent codex初始化完成后你应该花时间仔细填写CODER.md和AGENTS.md。这是“训练”AI 理解你项目的最关键步骤。CODER.md里要写下那些“只有老队员才知道”的事情比如“启动后端需要先运行docker-compose up db”、“API_BASE_URL在.env.local里配置”、“组件库的主题覆盖文件在src/theme/overrides.ts”。3.3 核心技能包加速前端开发RunBook 内置了一套名为“Codex Skills”的前端开发技能包。这可能是它最实用的功能之一。这些技能包不是魔法而是一套高度结构化、针对特定 UI 场景的提示词模板和实现指南封装在.agents/skills/目录下。技能包是什么每个技能包如frontend-table-builder都包含场景定义明确说明这个技能用于构建什么例如数据表格、仪表盘、表单。设计合约明确 UI 组件需要遵守的规则包括无障碍访问、响应式行为、状态管理加载、空数据、错误。实现指南推荐的技术栈选择Chakra UI vs Tamagui、组件结构、Props API 设计。验收清单完成开发后需要检查的项目。如何安装和使用技能包列出可用技能npx matsumiko/runbook skill list这个命令会输出一个长长的表格展示所有技能包及其适用场景。安装所需技能 假设你要构建一个仪表盘页面你需要先安装仪表盘构建技能。# 安装到当前项目 npx matsumiko/runbook skill install frontend-dashboard-builder # 安装到指定子项目 npx matsumiko/runbook skill install frontend-dashboard-builder ./apps/admin引导 AI 使用技能 安装后技能包文件位于.agents/skills/frontend-dashboard-builder/。当你需要构建仪表盘时你可以直接告诉 AI“请参考.agents/skills/frontend-dashboard-builder/下的指南来构建管理员仪表盘页面。” AI 会读取其中的“设计合约”和“实现指南”输出更符合预期、更高质量的代码。技能包选择逻辑与推荐顺序RunBook 的技能包设计有很强的逻辑性和顺序性模仿了专业前端开发的工作流确定基础如果项目还没有明确的前端技术栈UI 库首先使用frontend-foundation-builder。这个技能会引导你或 AI根据项目特点选择 Chakra UI纯 Web或 Tamagui跨端并搭建好主题、Provider 等基础设置。定义设计语言如果有 Figma 设计稿使用frontend-figma-to-theme将设计令牌颜色、字体、间距转化为代码中的主题配置并更新FRONTEND-DNA.md。构建通用组件使用frontend-component-builder来创建遵循设计系统的基础组件如 Button、Card、Input。按需选用高级组件根据页面需要选择对应的技能包。例如需要表格就用frontend-table-builder需要图表就用frontend-chart-builder需要复杂表单就用frontend-form-builder。最终打磨在所有主要功能完成后使用frontend-polish-pass进行整体的细节打磨统一间距、优化响应式、完善各种状态。这种“技能即插件”的架构非常灵活。社区未来可以贡献更多的技能包覆盖更垂直的领域如backend-api-crud-builder,>npx matsumiko/runbook init --agent claude然后我们手动完善几个关键文件CODER.md添加项目启动命令 (npm run dev)后端 API 基地址 (http://localhost:3001/api)以及关键文件路径说明。AGENTS.md规定代码风格使用 ESLint Prettier 配置、组件必须使用命名导出、API 调用必须使用项目封装的request工具函数。FRONTEND-DNA.md定义主色为蓝色系次色为灰色系间距基数为 4px并注明我们使用的是 Chakra UI 组件库。5.2 阶段二规划与技能准备我们在TODO.md中添加新条目“高优先级为团队管理员开发一个仪表盘页面包含统计卡片、活跃度图表和任务列表。” 然后我们与 Claude Code 协作将这个大任务拆解到PLAN.md[ ] 安装并配置图表库选择 Recharts。[ ] 使用frontend-dashboard-builder技能包规划仪表盘布局网格系统。[ ] 使用frontend-kpi-card-builder技能包构建任务统计卡片总数、进行中、已完成。[ ] 使用frontend-chart-builder技能包构建成员任务完成趋势图折线图。[ ] 使用frontend-table-builder技能包构建可过滤的团队任务列表。[ ] 集成所有组件到新页面路由/dashboard。[ ] 添加响应式适配。[ ] 编写组件 Storybook 故事可选。接着我们安装所需的技能包npx runbook skill install frontend-dashboard-builder npx runbook skill install frontend-kpi-card-builder npx runbook skill install frontend-chart-builder npx runbook skill install frontend-table-builder5.3 阶段三会话式开发与恢复我们开始执行第一个子任务“安装并配置图表库”。 我们启动一个 RunBook 会话。在 Claude Code 中我们输入“让我们开始一个 RunBook 会话来完成‘安装并配置 Recharts 图表库’这个任务。请先阅读相关上下文然后创建会话。”Claude Code 会读取AGENTS.md和PLAN.md然后创建一个会话文件。它可能会输出我已阅读项目上下文。正在创建会话存档... 会话目标安装 Recharts 库并在项目中完成基础配置以便后续构建图表组件。 计划步骤 1. 检查当前依赖确定安装命令。 2. 运行 npm install recharts。 3. 在 src/utils/chart-theme.ts 中创建基础的图表主题配置以匹配我们的 FRONTEND-DNA。 4. 更新 CODER.md记录图表库的使用说明。 开始执行步骤 1...此时.runbook/sessions/下会生成一个会话 JSON 文件。假设我们在它执行到步骤 3 时电脑突然没电了。重启后我们运行npx runbook session list看到有一个状态为ACTIVE的会话。我们打开新的 Claude Code 对话输入“请恢复最新的 RunBook 会话并继续。”Claude Code 会读取会话文件检查src/utils/chart-theme.ts是否已被创建或修改。如果文件已存在且内容匹配预期它会直接跳到步骤 4“更新CODER.md”。如果因为断电导致文件未保存它可能会检测到不一致并提示“检测到工作区状态与会话记录不符。文件chart-theme.ts不存在。是否重新执行步骤 3” 我们可以选择“是”。这样我们无需重新解释整个任务开发得以快速恢复。5.4 阶段四应用技能包构建复杂 UI在配置好图表库后我们开始构建“成员活跃度图表”。我们引导 Claude Code“请应用frontend-chart-builder技能包基于 Recharts 构建一个折线图展示过去 7 天团队成员的任务完成趋势。数据可以从我们模拟的mockApi.getMemberActivity()获取。”Claude Code 会去阅读.agents/skills/frontend-chart-builder/CONTRACT.md和GUIDE.md。基于这些约束它生成的代码会自动处理“无数据”状态显示友好的占位图。确保图表具有清晰的标题、轴标签和图例。遵循FRONTEND-DNA.md中的颜色定义。实现基本的响应式容器宽度自适应。甚至可能根据GUIDE.md的建议添加一个“切换为柱状图”的按钮原型。由于技能包提供了清晰的“设计合约”AI 输出的代码第一次就更可能接近生产要求减少了来回修改的次数。5.5 阶段五收尾与知识沉淀当所有子任务完成仪表盘页面功能完整后我们让 Claude Code 更新状态将PLAN.md中该任务的所有子项标记为完成。在CHANGELOG.md中添加条目“新增团队仪表盘页面包含统计卡片、Recharts 趋势图及可过滤任务列表。统一了可视化组件的主题配色。”将当前会话标记为COMPLETED。最后我们可以运行npx runbook session clear来清理已完成的会话文件保持项目整洁。6. 常见问题、排查技巧与进阶思考6.1 常见问题速查表问题现象可能原因解决方案运行npx matsumiko/runbook init报错 “Command not found”Node.js 版本过低或未安装确保已安装 Node.js 18。运行node -v检查。AI 助手似乎忽略了AGENTS.md中的规则AI 的初始提示词未引导其阅读该文件在对话开始时明确指令“请先阅读项目根目录下的AGENTS.md和CODER.md文件以了解项目规范和上下文。”会话恢复后AI 对代码的理解出现偏差会话 JSON 文件与当前工作区文件状态不一致可能被手动修改过。让 AI 先执行“工作区审计”比对会话记录的文件哈希或内容摘要。根据差异决定是继续、回退还是重新开始。技能包安装后AI 不知道如何使用技能包路径未被 AI 的上下文加载。明确告诉 AI 技能包的具体路径“请参考.agents/skills/frontend-form-builder/GUIDE.md中的指南来实现这个表单。”SESSION.md文件被意外提交到了 Git.runbook/sessions/目录已被.gitignore但SESSION.md本身没有。SESSION.md是协议文件应该被版本管理。检查是否误将其加入.gitignore。运行时产生的.json文件才不应提交。多个 AI 助手如 Cursor 和 Copilot行为不一致不同助手对提示词和上下文的处理方式不同。利用AGENT-VARIANTS.md文件为每个助手记录特定的、最优的交互指令或提示词片段。6.2 性能与规模化的考量上下文长度RunBook 文件可能会变得很长尤其是CODER.md。这可能会占满 AI 模型的上下文窗口。建议定期整理CODER.md只保留最关键、最通用的信息。将具体的、过时的信息归档到项目 Wiki 或专门的ARCHIVED.md中。会话文件管理对于长期活跃的项目.runbook/sessions/目录可能会积累大量文件。建议定期使用runbook session clear进行清理或编写简单的脚本按时间删除旧文件。Monorepo 支持在 Monorepo 中你可以在根目录和每个子包package中分别初始化 RunBook。子包的CODER.md可以继承根目录的通用配置同时记录子包特有的信息。这需要更精细的上下文管理策略。6.3 安全与隐私提醒RunBook 的SESSION.md协议中明确要求会话文件在记录系统状态时必须将密钥、令牌、Cookie 等敏感信息标记为[REDACTED]。这是一个非常重要的安全约定。在实际操作中你必须确保绝对不要在CODER.md或任何其他 Markdown 文件中明文填写真实的密码、API 密钥、私钥。对于必要的配置应使用环境变量占位符如process.env.API_KEY并在.env.example中说明。定期检查会话 JSON 文件确认没有意外记录敏感信息。6.4 超越代码生成RunBook 作为工程实践框架RunBook 的价值远不止于“让 AI 记住上下文”。它实质上是在推广一种可审计、可恢复、文档驱动的软件开发实践。即使在没有 AI 参与的传统团队中这套文件系统清晰的AGENTS.md、详实的CODER.md、动态的PLAN.md和TODO.md本身就能极大提升新成员 onboarding 的效率和项目知识的传承。它迫使开发者无论是人还是 AI在动手前先思考PLAN.md在过程中记录决策会话日志在完成后总结CHANGELOG.md。这是一种对抗软件熵和“巴士因子”风险的有效方法。在我个人的使用中最大的体会是它带来了一种“确定性”。以前让 AI 修改代码像是一场赌博你永远不知道它这次会理解成什么样。现在通过 RunBook 建立的共享上下文和明确合约AI 的输出变得可预测、可引导。它从一个“才华横溢但健忘的实习生”变成了一个“遵循操作规程的助理工程师”。这种转变对于将 AI 真正融入严肃的软件工程流程是至关重要的一步。 RunBook：为AI编码助手构建持久化项目记忆与协作框架
1. 项目概述为AI编码助手引入“操作手册”如果你和我一样在过去一年里深度使用过 Claude Code、Cursor、GitHub Copilot 或 Codex 这类 AI 编码助手你肯定经历过这样的场景你让 AI 帮你重构一个复杂的组件它写了一半然后对话因为各种原因网络中断、模型上下文限制、你临时离开中断了。当你重新打开项目试图让 AI “接着刚才的继续”时它要么一脸茫然要么开始基于错误的理解重新生成代码你不得不花大量时间重新解释上下文、架构决策和已经完成的部分。这种“上下文丢失”和“记忆断层”是当前 AI 辅助开发中最令人沮丧的痛点之一。Matsumiko/runbook正是为了解决这个问题而生的。它不是一个新模型也不是一个替代现有 AI 助手的工具而是一个“操作手册”或“项目记忆层”。它的核心思想是将项目的关键上下文、开发规范、会话状态和任务计划以结构化的 Markdown 和 JSON 文件形式持久化在代码仓库中。这样无论是同一个 AI 助手在不同会话间还是不同的 AI 助手比如从 Claude 切换到 Cursor都能基于这份共享的“记忆”无缝地继续工作大幅减少重复沟通和上下文重建的成本。简单来说RunBook 为你的代码仓库装上了一块“固态硬盘”让 AI 编码助手拥有了跨会话、跨工具的持久化工作记忆。它特别适合需要长期迭代、团队协作或由 AI 主导进行大量代码生成和重构的项目。2. 核心设计理念与架构拆解RunBook 的设计哲学可以概括为“审计优先谨慎实施诚实验证”。这不仅仅是口号而是贯穿其所有功能的指导原则。它试图将人类工程师的严谨工作流——规划、记录、检查、迭代——编码成一套 AI 也能理解和遵循的协议。2.1 核心文件系统构建项目记忆体RunBook 的核心是一系列放置在项目根目录下的 Markdown 文件。这些文件共同构成了项目的“记忆体”和“操作手册”。我们来逐一拆解每个文件的设计意图AGENTS.md这是 AI 助手的“主操作手册”。它定义了在这个项目中工作的核心原则、代码风格、提交规范、测试要求等。你可以把它想象成给新加入项目的 AI 工程师的入职文档。例如里面会明确规定“本项目使用 TypeScript 严格模式”、“组件采用函数式写法并导出 Props 接口”、“所有 API 调用必须包含错误边界处理”。当 AI 开始工作时首先被引导阅读这个文件确保其输出符合项目规范。SESSION.md与.runbook/sessions/这是实现“会话恢复”功能的关键。SESSION.md定义了一个协议指导 AI 如何将当前的工作状态包括目标、计划、已修改的文件、下一步行动等序列化成一个 JSON 文件保存在.runbook/sessions/目录下。这个 JSON 文件就像一个游戏的“存档点”。如果会话中断新的 AI 实例可以通过读取最新的存档文件快速恢复到中断前的精确状态包括光标位置和思维链。SESSION-EXAMPLE.json则提供了一个标准格式的示例。CODER.md这是项目的“长期记忆”。它记录了那些不会频繁变动但对理解项目至关重要的信息如何启动开发服务器、关键的环境变量、数据库连接字符串的格式、常用的 npm scripts、项目特有的“坑”Gotchas以及整体的架构图。这部分信息通常不会写在README.md里但对 AI 高效工作至关重要。PLAN.md与TODO.md这两个文件管理任务流。PLAN.md是“当前执行计划”是一个动态的、细粒度的任务列表描述正在进行的任务的具体步骤。TODO.md则是“战略待办清单”按价值和影响优先级排序是PLAN.md的任务来源。这模仿了敏捷开发中的 Sprint Backlog 和 Product Backlog。CHANGELOG.md一个诚实的、有意义的变更日志。RunBook 鼓励 AI 在完成一个有意义的功能块后主动更新此文件记录“做了什么”以及“为什么这么做”而不是简单地罗列提交信息。这为项目提供了可追溯的决策历史。FRONTEND-DNA.md与BACKEND-SECURITY-CHECKLIST.md这是领域特定的“护栏”文件。FRONTEND-DNA.md定义了前端的设计系统核心色彩体系、间距比例、字体层级、交互状态等。BACKEND-SECURITY-CHECKLIST.md则是一个安全检查清单确保 AI 在编写后端代码时不会遗漏输入验证、SQL 注入防护、权限检查等关键安全项。AGENT-VARIANTS.md这是一个兼容性矩阵记录了不同 AI 助手Claude, Cursor, Copilot, Codex 等在本项目中的特定配置、已知的提示词差异或最佳实践。这确保了多 AI 环境下的行为一致性。2.2 会话恢复机制从“失忆”到“断点续传”会话恢复是 RunBook 最亮眼的功能。传统上AI 对话是“无状态”的。RunBook 通过一个简单的协议使其“有状态化”。创建检查点当 AI 开始一个非平凡任务比如“重构用户资料页面”时它会根据SESSION.md的指引创建一个会话文件例如.runbook/sessions/SESSION-20240420-1430.json。这个文件包含了project项目元数据名称、根目录、Git 远程地址、分支。goal本次会话的最终目标。assumptions基于项目上下文所做的假设。plan为达成目标制定的步骤计划。decisions已做出的关键技术决策及原因。touched_files已查看或修改的文件列表及其最新状态摘要。next_step下一步要执行的具体操作。system_state系统状态如开发服务器是否在运行。恢复会话当需要恢复工作时例如打开新的终端窗口AI 或开发者可以运行runbook session list查看可恢复的会话。然后AI 会读取最新的ACTIVE状态会话文件。它会先“审计”工作区比对touched_files中的记录与当前文件状态确认没有外部冲突。之后它便可以从next_step处无缝继续仿佛从未中断。安全与清理会话文件默认被.gitignore排除在版本控制之外因为它们是临时的运行时产物。runbook session clear命令可以安全地清理已COMPLETED或CANCELLED的会话。对于因崩溃而残留的ACTIVE会话RunBook 采取保守策略除非使用--all --force否则不会删除以便手动恢复。实操心得会话命名的智慧默认的基于时间戳的会话文件名如SESSION-20240420-1430.json虽然唯一但缺乏语义。在实际使用中我习惯在初始化会话时让 AI 在goal字段填写清晰的任务描述并手动将文件名改为类似SESSION-refactor-user-profile-component.json。这样在session list时一目了然便于管理多个并行任务。2.3 多智能体适配器统一工作界面RunBook 的另一个强大之处在于它对主流 AI 编码助手提供了“原生适配”。它并不是为每个工具重新发明轮子而是提供了一套统一的“语言”即那些 Markdown 文件并给出了如何让不同 AI 助手理解这套语言的指引。对于 Claude Code/Cursor这些工具通常能直接读取项目根目录下的 Markdown 文件。你只需在对话开始时提示“请先阅读AGENTS.md和CODER.md以了解项目上下文。”对于 GitHub Copilot Chat你可以在 IDE 的 Copilot Chat 中通过workspace指令让它索引这些文件或者直接粘贴相关章节作为上下文。对于 Windsurf/Cline/Aider这些工具通常支持通过配置文件或初始提示词加载上下文。RunBook 的AGENT-VARIANTS.md可能会包含针对这些工具的特定配置片段。这种设计使得项目上下文和开发规范成为一种与工具无关的资产极大地提升了团队协作和工具切换的灵活性。3. 从零开始RunBook 的完整实操流程3.1 环境准备与安装决策RunBook 是一个 Node.js CLI 工具要求 Node.js 版本 18。安装方式非常灵活你可以根据使用场景选择场景一快速体验推荐初次使用者无需安装直接使用npx运行。这是最干净、无侵入的方式适合快速评估或一次性初始化。npx matsumiko/runbook init场景二项目级依赖推荐团队项目将 RunBook 作为开发依赖安装到项目中确保所有协作者环境一致。npm install -D matsumiko/runbook # 之后在项目内使用 npx runbook init --agent all你还可以在package.json的scripts中封装常用命令提升团队体验{ scripts: { runbook:init: runbook init --agent all, runbook:session:list: runbook session list, runbook:skill:install: runbook skill install frontend-foundation-builder } }场景三全局安装适合重度个人用户如果你频繁在多个个人项目中使用 RunBook可以全局安装以获得最短的命令。npm install -g matsumiko/runbook # 之后在任何地方直接使用 runbook skill list注意事项权限与网络全局安装可能需要sudo在 Linux/macOS 上或以管理员身份运行在 Windows 上。使用npx或本地安装通常能避免权限问题。同时npx会从网络下载包请确保你的网络环境畅通。3.2 初始化项目注入“操作手册”初始化是使用 RunBook 的第一步。它会创建上一节提到的所有核心文件。基础初始化# 在当前目录初始化 npx matsumiko/runbook init这会在当前目录生成全套 RunBook 文件。如果文件已存在默认会跳过避免覆盖你的已有配置。指定 AI 助手适配器 RunBook 允许你在初始化时为特定的 AI 助手生成更针对性的引导内容。例如如果你主要用 Claude Codenpx matsumiko/runbook init --agent claude如果你使用多种工具npx matsumiko/runbook init --agent claude,cursor,copilot或者一次性为所有支持的助手生成适配说明npx matsumiko/runbook init --agent all高级初始化选项--dry-run预览将要生成的文件列表和内容而不实际写入磁盘。这在首次使用或不确定时非常有用。--force强制覆盖已存在的 RunBook 文件。请谨慎使用最好先备份。指定路径你可以在任何子目录初始化 RunBook这对于 Monorepo 项目特别有用。npx matsumiko/runbook init ./packages/web-app --agent codex初始化完成后你应该花时间仔细填写CODER.md和AGENTS.md。这是“训练”AI 理解你项目的最关键步骤。CODER.md里要写下那些“只有老队员才知道”的事情比如“启动后端需要先运行docker-compose up db”、“API_BASE_URL在.env.local里配置”、“组件库的主题覆盖文件在src/theme/overrides.ts”。3.3 核心技能包加速前端开发RunBook 内置了一套名为“Codex Skills”的前端开发技能包。这可能是它最实用的功能之一。这些技能包不是魔法而是一套高度结构化、针对特定 UI 场景的提示词模板和实现指南封装在.agents/skills/目录下。技能包是什么每个技能包如frontend-table-builder都包含场景定义明确说明这个技能用于构建什么例如数据表格、仪表盘、表单。设计合约明确 UI 组件需要遵守的规则包括无障碍访问、响应式行为、状态管理加载、空数据、错误。实现指南推荐的技术栈选择Chakra UI vs Tamagui、组件结构、Props API 设计。验收清单完成开发后需要检查的项目。如何安装和使用技能包列出可用技能npx matsumiko/runbook skill list这个命令会输出一个长长的表格展示所有技能包及其适用场景。安装所需技能 假设你要构建一个仪表盘页面你需要先安装仪表盘构建技能。# 安装到当前项目 npx matsumiko/runbook skill install frontend-dashboard-builder # 安装到指定子项目 npx matsumiko/runbook skill install frontend-dashboard-builder ./apps/admin引导 AI 使用技能 安装后技能包文件位于.agents/skills/frontend-dashboard-builder/。当你需要构建仪表盘时你可以直接告诉 AI“请参考.agents/skills/frontend-dashboard-builder/下的指南来构建管理员仪表盘页面。” AI 会读取其中的“设计合约”和“实现指南”输出更符合预期、更高质量的代码。技能包选择逻辑与推荐顺序RunBook 的技能包设计有很强的逻辑性和顺序性模仿了专业前端开发的工作流确定基础如果项目还没有明确的前端技术栈UI 库首先使用frontend-foundation-builder。这个技能会引导你或 AI根据项目特点选择 Chakra UI纯 Web或 Tamagui跨端并搭建好主题、Provider 等基础设置。定义设计语言如果有 Figma 设计稿使用frontend-figma-to-theme将设计令牌颜色、字体、间距转化为代码中的主题配置并更新FRONTEND-DNA.md。构建通用组件使用frontend-component-builder来创建遵循设计系统的基础组件如 Button、Card、Input。按需选用高级组件根据页面需要选择对应的技能包。例如需要表格就用frontend-table-builder需要图表就用frontend-chart-builder需要复杂表单就用frontend-form-builder。最终打磨在所有主要功能完成后使用frontend-polish-pass进行整体的细节打磨统一间距、优化响应式、完善各种状态。这种“技能即插件”的架构非常灵活。社区未来可以贡献更多的技能包覆盖更垂直的领域如backend-api-crud-builder,>npx matsumiko/runbook init --agent claude然后我们手动完善几个关键文件CODER.md添加项目启动命令 (npm run dev)后端 API 基地址 (http://localhost:3001/api)以及关键文件路径说明。AGENTS.md规定代码风格使用 ESLint Prettier 配置、组件必须使用命名导出、API 调用必须使用项目封装的request工具函数。FRONTEND-DNA.md定义主色为蓝色系次色为灰色系间距基数为 4px并注明我们使用的是 Chakra UI 组件库。5.2 阶段二规划与技能准备我们在TODO.md中添加新条目“高优先级为团队管理员开发一个仪表盘页面包含统计卡片、活跃度图表和任务列表。” 然后我们与 Claude Code 协作将这个大任务拆解到PLAN.md[ ] 安装并配置图表库选择 Recharts。[ ] 使用frontend-dashboard-builder技能包规划仪表盘布局网格系统。[ ] 使用frontend-kpi-card-builder技能包构建任务统计卡片总数、进行中、已完成。[ ] 使用frontend-chart-builder技能包构建成员任务完成趋势图折线图。[ ] 使用frontend-table-builder技能包构建可过滤的团队任务列表。[ ] 集成所有组件到新页面路由/dashboard。[ ] 添加响应式适配。[ ] 编写组件 Storybook 故事可选。接着我们安装所需的技能包npx runbook skill install frontend-dashboard-builder npx runbook skill install frontend-kpi-card-builder npx runbook skill install frontend-chart-builder npx runbook skill install frontend-table-builder5.3 阶段三会话式开发与恢复我们开始执行第一个子任务“安装并配置图表库”。 我们启动一个 RunBook 会话。在 Claude Code 中我们输入“让我们开始一个 RunBook 会话来完成‘安装并配置 Recharts 图表库’这个任务。请先阅读相关上下文然后创建会话。”Claude Code 会读取AGENTS.md和PLAN.md然后创建一个会话文件。它可能会输出我已阅读项目上下文。正在创建会话存档... 会话目标安装 Recharts 库并在项目中完成基础配置以便后续构建图表组件。 计划步骤 1. 检查当前依赖确定安装命令。 2. 运行 npm install recharts。 3. 在 src/utils/chart-theme.ts 中创建基础的图表主题配置以匹配我们的 FRONTEND-DNA。 4. 更新 CODER.md记录图表库的使用说明。 开始执行步骤 1...此时.runbook/sessions/下会生成一个会话 JSON 文件。假设我们在它执行到步骤 3 时电脑突然没电了。重启后我们运行npx runbook session list看到有一个状态为ACTIVE的会话。我们打开新的 Claude Code 对话输入“请恢复最新的 RunBook 会话并继续。”Claude Code 会读取会话文件检查src/utils/chart-theme.ts是否已被创建或修改。如果文件已存在且内容匹配预期它会直接跳到步骤 4“更新CODER.md”。如果因为断电导致文件未保存它可能会检测到不一致并提示“检测到工作区状态与会话记录不符。文件chart-theme.ts不存在。是否重新执行步骤 3” 我们可以选择“是”。这样我们无需重新解释整个任务开发得以快速恢复。5.4 阶段四应用技能包构建复杂 UI在配置好图表库后我们开始构建“成员活跃度图表”。我们引导 Claude Code“请应用frontend-chart-builder技能包基于 Recharts 构建一个折线图展示过去 7 天团队成员的任务完成趋势。数据可以从我们模拟的mockApi.getMemberActivity()获取。”Claude Code 会去阅读.agents/skills/frontend-chart-builder/CONTRACT.md和GUIDE.md。基于这些约束它生成的代码会自动处理“无数据”状态显示友好的占位图。确保图表具有清晰的标题、轴标签和图例。遵循FRONTEND-DNA.md中的颜色定义。实现基本的响应式容器宽度自适应。甚至可能根据GUIDE.md的建议添加一个“切换为柱状图”的按钮原型。由于技能包提供了清晰的“设计合约”AI 输出的代码第一次就更可能接近生产要求减少了来回修改的次数。5.5 阶段五收尾与知识沉淀当所有子任务完成仪表盘页面功能完整后我们让 Claude Code 更新状态将PLAN.md中该任务的所有子项标记为完成。在CHANGELOG.md中添加条目“新增团队仪表盘页面包含统计卡片、Recharts 趋势图及可过滤任务列表。统一了可视化组件的主题配色。”将当前会话标记为COMPLETED。最后我们可以运行npx runbook session clear来清理已完成的会话文件保持项目整洁。6. 常见问题、排查技巧与进阶思考6.1 常见问题速查表问题现象可能原因解决方案运行npx matsumiko/runbook init报错 “Command not found”Node.js 版本过低或未安装确保已安装 Node.js 18。运行node -v检查。AI 助手似乎忽略了AGENTS.md中的规则AI 的初始提示词未引导其阅读该文件在对话开始时明确指令“请先阅读项目根目录下的AGENTS.md和CODER.md文件以了解项目规范和上下文。”会话恢复后AI 对代码的理解出现偏差会话 JSON 文件与当前工作区文件状态不一致可能被手动修改过。让 AI 先执行“工作区审计”比对会话记录的文件哈希或内容摘要。根据差异决定是继续、回退还是重新开始。技能包安装后AI 不知道如何使用技能包路径未被 AI 的上下文加载。明确告诉 AI 技能包的具体路径“请参考.agents/skills/frontend-form-builder/GUIDE.md中的指南来实现这个表单。”SESSION.md文件被意外提交到了 Git.runbook/sessions/目录已被.gitignore但SESSION.md本身没有。SESSION.md是协议文件应该被版本管理。检查是否误将其加入.gitignore。运行时产生的.json文件才不应提交。多个 AI 助手如 Cursor 和 Copilot行为不一致不同助手对提示词和上下文的处理方式不同。利用AGENT-VARIANTS.md文件为每个助手记录特定的、最优的交互指令或提示词片段。6.2 性能与规模化的考量上下文长度RunBook 文件可能会变得很长尤其是CODER.md。这可能会占满 AI 模型的上下文窗口。建议定期整理CODER.md只保留最关键、最通用的信息。将具体的、过时的信息归档到项目 Wiki 或专门的ARCHIVED.md中。会话文件管理对于长期活跃的项目.runbook/sessions/目录可能会积累大量文件。建议定期使用runbook session clear进行清理或编写简单的脚本按时间删除旧文件。Monorepo 支持在 Monorepo 中你可以在根目录和每个子包package中分别初始化 RunBook。子包的CODER.md可以继承根目录的通用配置同时记录子包特有的信息。这需要更精细的上下文管理策略。6.3 安全与隐私提醒RunBook 的SESSION.md协议中明确要求会话文件在记录系统状态时必须将密钥、令牌、Cookie 等敏感信息标记为[REDACTED]。这是一个非常重要的安全约定。在实际操作中你必须确保绝对不要在CODER.md或任何其他 Markdown 文件中明文填写真实的密码、API 密钥、私钥。对于必要的配置应使用环境变量占位符如process.env.API_KEY并在.env.example中说明。定期检查会话 JSON 文件确认没有意外记录敏感信息。6.4 超越代码生成RunBook 作为工程实践框架RunBook 的价值远不止于“让 AI 记住上下文”。它实质上是在推广一种可审计、可恢复、文档驱动的软件开发实践。即使在没有 AI 参与的传统团队中这套文件系统清晰的AGENTS.md、详实的CODER.md、动态的PLAN.md和TODO.md本身就能极大提升新成员 onboarding 的效率和项目知识的传承。它迫使开发者无论是人还是 AI在动手前先思考PLAN.md在过程中记录决策会话日志在完成后总结CHANGELOG.md。这是一种对抗软件熵和“巴士因子”风险的有效方法。在我个人的使用中最大的体会是它带来了一种“确定性”。以前让 AI 修改代码像是一场赌博你永远不知道它这次会理解成什么样。现在通过 RunBook 建立的共享上下文和明确合约AI 的输出变得可预测、可引导。它从一个“才华横溢但健忘的实习生”变成了一个“遵循操作规程的助理工程师”。这种转变对于将 AI 真正融入严肃的软件工程流程是至关重要的一步。