RunBook：为AI编码助手构建项目记忆与标准化协作手册

1. 项目概述为AI编码助手引入“操作手册”如果你和我一样已经深度使用过GitHub Copilot、Cursor、Claude Code这类AI编码助手那你一定经历过这样的场景在一个复杂的项目中你让AI助手帮你修改一个功能它给出了看似完美的代码。但当你第二天打开项目或者换了一个新的对话窗口想让它继续优化或修复一个相关bug时它仿佛得了“失忆症”——完全不记得项目的技术栈、代码结构、之前的决策甚至是你昨天刚和它讨论过的业务逻辑。于是你又得花大量时间重新描述上下文粘贴代码片段解释“我们之前做了什么”。这种上下文断裂、记忆丢失的问题是当前AI编码工具在复杂、长期项目协作中的核心痛点。它们擅长处理单次、孤立的代码片段生成但在需要跨会话、有状态、遵循特定项目规范的持续开发中就显得力不从心。RunBook正是为了解决这个问题而生。它不是另一个AI模型而是一个为你的代码仓库Repository配备的“操作手册”和“项目记忆系统”。简单来说RunBook是一套标准化的文件模板和CLI工具集。它通过在你的项目根目录创建一系列结构化的Markdown文件如AGENTS.md,CODER.md,PLAN.md为AI编码助手提供了一个持久化、可查询的“工作记忆”。这就像是为你的AI助手配备了一位经验丰富的项目架构师它永远记得项目的技术选型、核心架构、待办事项、变更记录甚至是如何从一次意外中断的会话中恢复工作。2. 核心设计理念与架构拆解2.1 为什么需要“项目记忆”传统的AI编码助手其“记忆”完全依赖于当前对话窗口的上下文长度。一旦关闭窗口、重启IDE或者开始一个新对话之前的上下文就消失了。这导致了几个严重问题决策不一致AI可能会在会话A中建议使用Redux进行状态管理在会话B中又推荐Zustand导致项目技术栈混乱。重复劳动开发者需要反复向AI解释项目结构、环境变量设置、启动命令等基础信息。难以协作当项目需要多位开发者或AI助手共同维护时缺乏一个统一的“知识源”来对齐工作方式和规范。会话中断成本高如果AI生成代码的过程中断如网络问题、模型停止响应很难从中断点无缝恢复。RunBook的设计哲学是“Audit first. Implement carefully. Verify honestly.”先审计再谨慎实现最后诚实验证。它强制为AI助手的工作流程引入纪律性将原本存在于开发者脑海或临时对话中的“隐性知识”转化为项目仓库中可版本控制的“显性知识”。2.2 RunBook的核心文件体系RunBook初始化后会在你的项目根目录生成一套核心文件。理解每个文件的作用是有效使用它的关键。RunBook/ |-- AGENTS.md # AI助手主操作指南 |-- SESSION.md # 会话恢复协议 |-- SESSION-EXAMPLE.json # 会话检查点示例 |-- .runbook/ # 运行时目录通常加入.gitignore | -- sessions/ # 存放运行时会话检查点文件 |-- CODER.md # 项目记忆命令、架构、环境 |-- PLAN.md # 当前执行计划 |-- TODO.md # 战略待办事项按价值排序 |-- CHANGELOG.md # 有意义的变更日志 |-- FRONTEND-DNA.md # 前端视觉与交互规则 |-- BACKEND-SECURITY-CHECKLIST.md # 后端安全检查清单 -- AGENT-VARIANTS.md # 不同AI助手的兼容性说明各文件深度解析AGENTS.md这是AI助手的“宪法”。它定义了在本项目中工作的核心原则、代码风格、提交规范、测试要求等。例如你可以在这里规定“所有React组件必须使用TypeScript并导出Props接口”、“API调用必须使用项目封装的useApihook”、“错误处理必须遵循try-catch-log模式”。AI助手在开始任何实质性工作前都应先阅读此文件。CODER.md项目的“长期记忆”。这里记录了所有对AI和人类开发者都至关重要的上下文信息项目启动命令npm run dev、docker-compose up等。核心架构图用文字或Mermaid语法描述的数据流、服务关系。环境变量说明.env.example中每个变量的含义和作用。“坑点”记录例如“User模型的avatar字段可能为null前端需做空值处理”、“/api/v2/search接口在分页超过100页时性能下降建议使用游标分页”。第三方服务配置如Supabase项目ID、Stripe公钥、Sentry DSN等关键信息的获取方式注意永远不要在此存储真实的密钥。SESSION.md.runbook/sessions/实现“会话恢复”的核心。当AI助手处理一个非平凡任务时它可以按照SESSION.md定义的协议将当前的工作状态目标、假设、计划、已修改的文件、下一步行动保存为一个JSON检查点文件存放在.runbook/sessions/目录下。这样即使终端崩溃、电脑重启AI助手也能通过读取最新的检查点文件快速恢复工作上下文继续完成任务。SESSION-EXAMPLE.json提供了一个检查点文件的结构示例。PLAN.md与TODO.md区分“当前计划”与“战略待办”。PLAN.md聚焦于当前正在执行的具体任务分解例如“实现用户登录功能1. 创建登录页面组件 2. 集成认证API 3. 添加表单验证”。而TODO.md则是一个按业务价值和影响排序的长期功能清单更像一个产品路线图。这有助于AI理解任务的优先级和上下文。FRONTEND-DNA.md前端项目的“设计系统速查表”。它定义了颜色主题、间距比例如使用Tailwind的spacing-4还是自定义的8px基准、字体堆栈、组件变体如按钮的primary、secondary、ghost状态等视觉规则。这确保了AI在不同会话中生成的前端代码在视觉上能保持一致。BACKEND-SECURITY-CHECKLIST.md后端开发的“安全护栏”。它列出了在编写API、处理数据库、管理用户认证时必须检查的安全事项例如“所有用户输入必须经过验证和清理”、“敏感操作必须记录审计日志”、“API速率限制是否已启用”。2.3 适配不同AI助手的工作原理RunBook的另一个巧妙之处在于其“适配器”设计。它通过AGENT-VARIANTS.md和特定的提示词工程让同一套项目记忆体系能够适配不同的AI编码助手。对于Claude (Claude Code)RunBook会生成针对Claude模型优化过的提示词指导它如何读取和更新AGENTS.md、CODER.md等文件。Claude强大的长上下文能力使其能很好地理解整个手册。对于CursorRunBook可以利用Cursor的“项目知识库”功能将这些Markdown文件作为背景知识喂给Cursor的Agent使其在代码补全和聊天时能参考项目规范。对于GitHub Copilot虽然Copilot没有直接的“阅读文件”能力但开发者可以在编写代码时通过Copilot Chat主动引用CODER.md中的代码片段或AGENTS.md中的规则来引导Copilot生成符合规范的代码。对于Windsurf/Cline/Aider等RunBook提供了通用的提示词模板开发者可以将其配置到这些工具的设置中使其在分析项目时优先参考RunBook文件。这种设计使得RunBook不绑定于任何特定的AI工具而是成为一个跨平台的“项目上下文层”。3. 从零开始安装、初始化与核心工作流3.1 多种安装方式与选择建议RunBook提供了极其灵活的安装方式核心原则是“无需预先全局安装”。你可以根据使用场景选择最适合的一种。1. 一次性快速试用推荐新手这是最快捷的方式无需在本地或项目中安装任何东西。直接使用npx命令它会临时下载并运行RunBook。npx matsumiko/runbook init这种方式适合快速体验或者在为某个新项目初始化RunBook时使用。缺点是每次命令都需要下载。2. 作为项目开发依赖安装推荐团队项目这是最规范、最可复现的方式。将RunBook作为devDependency添加到你的项目中确保团队每个成员和CI/CD环境都使用相同版本。# 在项目根目录执行 npm install -D matsumiko/runbook # 然后通过 npx 调用 npx runbook init --agent claude,cursor你还可以在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 } }之后就可以用npm run runbook:init来执行。3. 全局安装适合重度个人用户如果你频繁在多个个人项目中使用RunBook并且希望在任何目录都能直接输入runbook命令可以选择全局安装。npm install -g matsumiko/runbook runbook init --agent codex注意全局安装可能导致版本冲突且不利于团队协作时的版本一致性。对于严肃的项目强烈推荐方式2。3.2 初始化项目与选择适配器初始化是使用RunBook的第一步。init命令不仅创建核心文件还可以为你指定的AI助手生成对应的适配提示。基础初始化npx matsumiko/runbook init这会在当前目录创建所有核心的RunBook文件AGENTS.md,CODER.md等。为特定AI助手初始化RunBook的强大之处在于能为不同助手“定制”指南。你可以通过--agent参数指定一个或多个助手。# 仅为Claude Code初始化 npx matsumiko/runbook init --agent claude # 为Cursor和Copilot初始化 npx matsumiko/runbook init --agent cursor,copilot # 初始化所有非Codex适配器Claude, Cursor, Copilot, Gemini, Windsurf, Cline, Aider npx matsumiko/runbook init --agent all # 仅为OpenAI Codex初始化需要特定配置 npx matsumiko/runbook init --agent codex高级选项--dry-run预览将要生成的文件内容而不会实际写入磁盘。在不确定时非常有用。--force强制覆盖已存在的RunBook文件。慎用除非你确定要重置所有配置。指定路径你可以在任何子目录初始化RunBook这对于Monorepo项目特别有用。npx matsumiko/runbook init ./packages/frontend --agent cursor npx matsumiko/runbook init ./apps/admin --agent claude初始化后的第一步操作初始化完成后不要立即让AI开始编码。你首先应该手动编辑CODER.md文件填充项目的关键信息。至少包括如何启动开发服务器npm run dev/yarn start/docker-compose up。项目的技术栈React TypeScript Tailwind CSS / Next.js Prisma / etc.。代码仓库的Git远程地址和主要分支。一两个你最常遇到的“坑”或特殊配置。花10分钟完善CODER.md能为后续的AI协作节省数小时的解释时间。3.3 核心工作流让AI在纪律下工作有了RunBook你与AI协作的流程将发生根本性改变。以下是一个推荐的标准工作流第1步任务启动与上下文注入当你有一个新任务时例如“添加一个用户个人资料页面”首先打开PLAN.md或TODO.md将任务简要描述进去。然后在AI助手的聊天窗口中第一条指令应该是“请先阅读本项目根目录下的AGENTS.md和CODER.md文件了解本项目的开发规范和上下文。然后基于TODO.md中关于‘用户个人资料页面’的描述在PLAN.md中为我制定一个详细的实现计划。”这个指令强制AI先去学习“项目宪法”和“长期记忆”确保它的输出从一开始就符合项目规范。第2步计划评审与迭代AI生成的计划可能会放在PLAN.md中。你需要像评审同事的提案一样评审这个计划技术方案是否合理是否考虑了边界情况是否与现有架构兼容通过聊天与AI讨论并修改计划直到达成一致。这个PLAN.md文件成为了你和AI之间的“任务合同”。第3步分段执行与会话检查点对于复杂任务不要让AI一口气生成所有代码。而是根据PLAN.md分解的子任务分步执行。例如先让AI创建页面组件框架和路由。关键动作来了在AI完成一个子任务后指示它“当前子任务‘创建ProfilePage组件框架’已完成。请按照SESSION.md中的协议将当前会话状态保存为一个检查点并更新PLAN.md中该任务的状态为‘进行中’或‘已完成’。”AI会生成一个SESSION-20240420-1430.json文件保存在.runbook/sessions/下。这样即使你下午关电脑明天早上也可以让AI“恢复上次的会话”它就能立刻知道项目进展到哪里接下来该做什么。第4步代码审查与知识沉淀AI生成代码后进行审查。如果发现一个需要反复提醒AI的规则例如“本项目所有API响应必须用ApiResponseT包装”不要只在聊天里说。立刻将这条规则添加到AGENTS.md的相应章节。如果解决了一个棘手的Bug例如“发现用户头像上传组件在Safari浏览器下有兼容性问题已通过某方式修复”将这个解决方案记录到CODER.md的“坑点”部分。这样RunBook就随着项目一起“成长”变得越来越智能。第5步任务收尾与归档任务完成后指示AI更新CHANGELOG.md记录有意义的变更。同时清理.runbook/sessions/目录下已完成的会话检查点文件可以使用CLI命令npx runbook session clear。4. 深度实战会话恢复与技能库应用4.1 会话恢复机制全解析会话恢复是RunBook最亮眼的功能之一它解决了AI协作中“断点续传”的难题。其核心是SESSION.md协议文件和.runbook/sessions/目录下的运行时检查点。检查点文件里有什么一个典型的会话检查点JSON文件包含以下关键信息goal: 本次会话的最终目标如“实现用户登录API端点”。assumptions: 基于CODER.md和当前代码库做出的假设。plan: 从PLAN.md中提取的当前任务分解步骤。decisions: 本次会话中做出的重要技术决策及原因。touched_files: 本次会话中已查看或修改的文件列表及其最新状态摘要。next_step: 接下来要执行的具体操作。status: 会话状态如ACTIVE、PAUSED、COMPLETED、CANCELLED。如何触发保存与恢复RunBook为AI助手预定义了几个“魔法命令”run:status让AI输出当前任务状态的摘要类似于“我们目前正在做什么进展如何”。run:resume这是恢复命令。当你在一个新对话中发出此命令AI会去寻找最新的ACTIVE或PAUSED状态的检查点文件读取其内容并基于此继续工作。它会先“审计”当前工作区对比检查点中的touched_files和实际文件状态确认无误后再接续next_step。run:recap让AI根据检查点文件生成一份当前任务的中期报告。CLI会话管理工具除了AI内部命令RunBook CLI也提供了管理会话的工具# 列出当前项目中的所有会话检查点 npx runbook session list # 预览哪些已完成/已取消的会话将被清理安全模式 npx runbook session clear --dry-run # 实际清理已完成/已取消的会话 npx runbook session clear # 强制清理所有会话包括活跃的慎用 npx runbook session clear --all --force实操心得定时保存在长时间、多步骤的任务中我养成了每完成2-3个小步骤就手动触发一次run:status或让AI保存检查点的习惯。这就像写代码时频繁按CmdS。检查点即文档decisions字段非常宝贵。它记录了“为什么选择方案A而不是方案B”。这对于后续维护和知识传承至关重要。我经常在代码评审时同时查看相关会话的decisions来理解实现思路。安全第一检查点协议明确要求任何密钥、令牌、Cookie等敏感信息必须被标记为[REDACTED]。务必确保AI遵守此规则。.runbook/sessions/目录也应被添加到.gitignore中避免敏感信息误提交。4.2 强大的Codex技能库从零搭建专业前端界面RunBook内置了一套名为“Codex Skills”的预制技能包这可能是它最“黑科技”的部分。这些技能不是简单的代码片段而是针对特定前端界面类型的、高度结构化的生成协议。它们引导AI特别是像Codex这类代码生成模型按照最佳实践一步步构建出专业、一致、可维护的UI组件和页面。技能库概览与选择逻辑技能库非常庞大覆盖了从基础组件到复杂业务页面的几乎所有常见前端界面类型。其选择逻辑遵循“从基础到具体”的原则确定技术栈frontend-foundation-builder如果你的项目还没有明确的前端UI库首先使用此技能。它会根据项目上下文是纯Web应用还是需要跨端推荐并帮你初始化Chakra UIWeb优先或Tamagui需要React Native支持的配置、主题种子和基础组件。导入设计规范frontend-figma-to-theme如果你有Figma设计稿此技能能引导AI将设计稿中的颜色、字体、间距等变量提取并转换为代码中的主题配置Theme Tokens并更新FRONTEND-DNA.md。构建通用组件frontend-component-builder当技术栈和设计规范就绪后此技能用于构建遵循该规范的通用组件如Button、Card、Input。构建特定交互界面之后根据你要构建的具体UI类型选择对应的技能。例如需要下拉菜单用frontend-dropdown-builder。需要数据表格用frontend-table-builder。需要仪表盘用frontend-dashboard-builder。需要登录流程用frontend-auth-builder。技能使用实战以构建一个数据仪表盘为例假设我们要在一个已有的Next.js Chakra UI项目中新增一个数据分析仪表盘页面。步骤1安装仪表盘构建技能# 在项目根目录RunBook已初始化 npx runbook skill install frontend-dashboard-builder这个命令会将frontend-dashboard-builder技能的详细协议文件复制到.agents/skills/frontend-dashboard-builder/目录下。Codex类AI助手在运行时能自动发现并应用这些技能。步骤2启动AI并应用技能在AI编码助手如Cursor Agent中你可以这样开始“我们需要在/app/dashboard/page.tsx创建一个数据分析仪表盘。请应用RunBook中的frontend-dashboard-builder技能并遵循AGENTS.md和FRONTEND-DNA.md中的规范。仪表盘需要包含1. 顶部KPI卡片用户数、订单量、营收2. 一个近30天营收趋势的折线图3. 一个最新订单列表。请先制定一个实现计划到PLAN.md。”步骤3观察AI如何工作应用了技能后AI的行为会变得非常结构化。它不会天马行空地生成代码而是会遵循技能协议合同定义首先它会明确“仪表盘”的合同Contract——即输入props、输出事件、以及核心状态是什么。层级规划规划页面的整体布局层级确保与项目现有的布局组件如AppLayout兼容。面板系统按照技能指导使用一致的“面板Panel”系统来包装每个区域KPI卡片区、图表区、列表区确保边距、阴影、标题栏样式统一。状态覆盖它会主动考虑并实现各种状态加载中Loading、数据为空Empty、加载错误Error并确保这些状态的UI符合FRONTEND-DNA.md中的定义。组件复用它会检查CODER.md或现有代码看是否有可复用的KpiCard、LineChart组件。如果没有它会按照frontend-kpi-card-builder和frontend-chart-builder的子技能规范来构建它们确保组件库的扩展是一致、可维护的。步骤4最终润色在主体功能完成后你可以再应用frontend-polish-pass技能让AI对页面进行最终的细节打磨检查间距一致性、响应式适配、交互反馈如hover状态、可访问性ARIA标签等。技能库的价值一致性确保不同会话、甚至不同开发者或AI生成的同类UI如所有的下拉菜单都具有相同的行为和外观。高质量技能内置了针对该界面类型的最佳实践和常见陷阱的规避方案。高效率无需从零开始描述复杂的UI规范一个技能名就能传达大量设计约束和实现要求。5. 常见问题、排查技巧与最佳实践5.1 常见问题速查表问题现象可能原因解决方案运行npx matsumiko/runbook init时报错或卡住1. 网络问题导致npx下载包失败。2. Node.js版本过低RunBook要求 18。3. 当前目录没有写权限。1. 检查网络或尝试使用npm cache clean -f后重试。2. 使用node -v检查版本升级到Node 18或更高。3. 尝试在另一个有写权限的目录初始化。AI助手似乎“看不见”或“不理会”RunBook文件1. AI助手的上下文窗口未包含这些文件。2. 没有明确指示AI去阅读这些文件。3. 文件路径不对如在子目录运行AI。1. 在给AI的第一条指令中明确要求它“阅读AGENTS.md和CODER.md”。2. 对于Cursor确保在Agent设置中启用了“Use Project Knowledge”。3. 确保AI的工作目录是包含RunBook文件的根目录。会话恢复 (run:resume) 失败1..runbook/sessions/目录下没有ACTIVE状态的检查点文件。2. 检查点文件损坏或格式错误。3. 工作区文件与检查点中记录的状态严重不符。1. 运行npx runbook session list查看可用会话。2. 检查最新的.json文件看是否是有效的JSON。3. 手动对比touched_files如果差异太大可能需要放弃恢复从PLAN.md中当前步骤手动重启。技能安装后AI没有应用它1. 技能未安装到正确的.agents/skills/目录。2. AI模型不支持或未启用技能发现功能。3. 没有在提示词中明确要求应用该技能。1. 确认技能文件存在于.agents/skills/skill-name/下。2. 目前技能主要针对OpenAI Codex或深度集成的Agent如某些Cursor模式。对于普通聊天式AI需要你手动将技能协议的核心要点作为提示词给出。3. 在指令中明确说“请应用frontend-table-builder技能”。CODER.md变得冗长杂乱随着项目发展信息不断堆砌缺乏结构。定期重构CODER.md。建议按章节组织## 项目启动、## 架构说明、## 环境变量、## 已知问题与解决方案、## 第三方服务集成。使用清晰的标题和列表。团队其他成员不习惯使用RunBook增加了学习成本和新的工作流程。1.从小处开始先在个人分支试用展示其价值如快速让新AI理解项目。2.文档化在团队的README中简要说明RunBook的作用和基本命令。3.纳入流程在代码审查时不仅看代码也检查AGENTS.md的更新和CHANGELOG.md的记录是否准确。5.2 高级技巧与避坑指南将RunBook与Git工作流结合分支策略为每个功能分支维护独立的RunBook文件可能不现实。更好的做法是将AGENTS.md、CODER.md、FRONTEND-DNA.md等“核心宪法”文件放在主分支如main上作为项目的权威来源。功能分支的AI协作可以基于此进行。提交信息鼓励在提交信息中引用相关的PLAN.md任务或TODO.md条目例如git commit -m feat: add user profile page (ref: PLAN.md#task-2)。合并冲突AGENTS.md和CODER.md可能会在团队协作时产生合并冲突。处理它们应像处理代码冲突一样认真因为它们是项目的重要知识。优化AI提示词与RunBook协同 你可以创建更高效的提示词模板将RunBook的核心思想融入其中。例如给你的AI助手设置一个自定义指令如在Cursor的Agent设置中“你是一个遵循RunBook规范的资深开发者。在开始任何任务前你必须1. 自动读取项目根目录下的AGENTS.md和CODER.md文件以理解项目上下文和规范。2. 对于复杂任务主动建议在PLAN.md中创建执行计划。3. 在实现过程中如果发现缺失的规范或解决的难题主动提议更新AGENTS.md或CODER.md。4. 在长时间任务中定期询问是否需要保存会话检查点。”不要过度依赖保持批判性思维 RunBook和AI是强大的辅助工具但不能替代开发者的思考和决策。AI生成的计划、代码尤其是对CODER.md中“坑点”的解决方案必须经过你的仔细审查。RunBook的BACKEND-SECURITY-CHECKLIST.md就是一个很好的提醒——安全等重要事项必须由人类最终把关。管理技能库的膨胀 不是每个项目都需要安装所有技能。只安装你当前项目真正需要的技能。对于不常用的技能记住你可以随时通过npx runbook skill list查看并按需安装。保持.agents/skills/目录的整洁有助于AI更准确地发现相关技能。处理AI的“幻觉”或偏离 即使有RunBookAI有时仍会“忘记”规则或产生不符合规范的代码。此时不要只在聊天中纠正它。正确的做法是指出错误然后立即带领AI一起去修改AGENTS.md中相关的规则使其更明确、更不容误解。例如如果AI忘记了使用ApiResponse包装器就在AGENTS.md的“API规范”章节加上一条“强制规则所有控制器返回必须使用ApiResponse.success(data)或ApiResponse.error(message)包装。直接返回裸数据将被视为严重错误。” 这样下次AI再犯同样错误的概率就会大大降低。RunBook本质上是一个将项目知识“外部化”、“结构化”和“可操作化”的系统。它初期可能需要一些投入来建立和维护但随着项目复杂度和团队包括AI成员规模的扩大它所提供的上下文一致性、协作流畅性和知识沉淀能力会带来巨大的长期回报。它让AI编码从一种随机的、基于单次对话的“魔法”变成一种可预测、可管理、可传承的工程实践。