企业官网建设流程全解析

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 通过一个简单的协议使其“有状态化”。

1. 创建检查点：当 AI 开始一个非平凡任务（比如“重构用户资料页面”）时，它会根据SESSION.md的指引，创建一个会话文件，例如.runbook/sessions/SESSION-20240420-1430.json。这个文件包含了：

   • project：项目元数据（名称、根目录、Git 远程地址、分支）。
   • goal：本次会话的最终目标。
   • assumptions：基于项目上下文所做的假设。
   • plan：为达成目标制定的步骤计划。
   • decisions：已做出的关键技术决策及原因。
   • touched_files：已查看或修改的文件列表及其最新状态摘要。
   • next_step：下一步要执行的具体操作。
   • system_state：系统状态（如：开发服务器是否在运行）。

2. 恢复会话：当需要恢复工作时（例如打开新的终端窗口），AI 或开发者可以运行runbook session list查看可恢复的会话。然后，AI 会读取最新的ACTIVE状态会话文件。它会先“审计”工作区，比对touched_files中的记录与当前文件状态，确认没有外部冲突。之后，它便可以从next_step处无缝继续，仿佛从未中断。

3. 安全与清理：会话文件默认被.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 Code：

npx @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）都包含：

1. 场景定义：明确说明这个技能用于构建什么（例如：数据表格、仪表盘、表单）。
2. 设计合约：明确 UI 组件需要遵守的规则，包括无障碍访问、响应式行为、状态管理（加载、空数据、错误）。
3. 实现指南：推荐的技术栈选择（Chakra UI vs Tamagui）、组件结构、Props API 设计。
4. 验收清单：完成开发后需要检查的项目。

如何安装和使用技能包？

1. 列出可用技能：

   npx @matsumiko/runbook skill list

   这个命令会输出一个长长的表格，展示所有技能包及其适用场景。

2. 安装所需技能： 假设你要构建一个仪表盘页面，你需要先安装仪表盘构建技能。

   # 安装到当前项目 npx @matsumiko/runbook skill install frontend-dashboard-builder # 安装到指定子项目 npx @matsumiko/runbook skill install frontend-dashboard-builder ./apps/admin

3. 引导 AI 使用技能： 安装后，技能包文件位于.agents/skills/frontend-dashboard-builder/。当你需要构建仪表盘时，你可以直接告诉 AI：“请参考.agents/skills/frontend-dashboard-builder/下的指南来构建管理员仪表盘页面。” AI 会读取其中的“设计合约”和“实现指南”，输出更符合预期、更高质量的代码。

技能包选择逻辑与推荐顺序RunBook 的技能包设计有很强的逻辑性和顺序性，模仿了专业前端开发的工作流：

1. 确定基础：如果项目还没有明确的前端技术栈（UI 库），首先使用frontend-foundation-builder。这个技能会引导你（或 AI）根据项目特点选择 Chakra UI（纯 Web）或 Tamagui（跨端），并搭建好主题、Provider 等基础设置。
2. 定义设计语言：如果有 Figma 设计稿，使用frontend-figma-to-theme将设计令牌（颜色、字体、间距）转化为代码中的主题配置，并更新FRONTEND-DNA.md。
3. 构建通用组件：使用frontend-component-builder来创建遵循设计系统的基础组件（如 Button、Card、Input）。
4. 按需选用高级组件：根据页面需要，选择对应的技能包。例如，需要表格就用frontend-table-builder，需要图表就用frontend-chart-builder，需要复杂表单就用frontend-form-builder。
5. 最终打磨：在所有主要功能完成后，使用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：

1. [ ] 安装并配置图表库（选择 Recharts）。
2. [ ] 使用frontend-dashboard-builder技能包，规划仪表盘布局（网格系统）。
3. [ ] 使用frontend-kpi-card-builder技能包，构建任务统计卡片（总数、进行中、已完成）。
4. [ ] 使用frontend-chart-builder技能包，构建成员任务完成趋势图（折线图）。
5. [ ] 使用frontend-table-builder技能包，构建可过滤的团队任务列表。
6. [ ] 集成所有组件到新页面路由/dashboard。
7. [ ] 添加响应式适配。
8. [ ] 编写组件 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-builder

5.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 更新状态：

1. 将PLAN.md中该任务的所有子项标记为完成。
2. 在CHANGELOG.md中添加条目：“新增团队仪表盘页面，包含统计卡片、Recharts 趋势图及可过滤任务列表。统一了可视化组件的主题配色。”
3. 将当前会话标记为COMPLETED。

最后，我们可以运行npx runbook session clear来清理已完成的会话文件，保持项目整洁。

6. 常见问题、排查技巧与进阶思考

6.1 常见问题速查表

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 真正融入严肃的软件工程流程，是至关重要的一步。