古法编程

Claude Code 的演示系统采用三层架构进行管理与维护：第一层是三个独立的幻灯片文件（Vibe Coding、Claude Code、Claude Gemini），每个幻灯片都有其特定的受众和结构差异；第二层是委托规则，强制规定任何修改必须通过匹配的专用 Agent 完成，禁止直接编辑 HTML；第三层是 Presentation Skills（如 presentation-structure 和 presentation-styling），它们为 Agent 提供了幻灯片格式、层级系统和 CSS 组件类等可复用的知识，确保演示内容的一致性和质量。

Claude Code 演示系统架构：三个幻灯片、专用 Agent 和 Presentation Skills

在管理复杂的演示文稿时，随着内容增长和版本分支，手动维护多个幻灯片文件容易导致结构混乱和样式不一致。Claude Code 最佳实践仓库为此提供了一套系统化的解决方案，其核心思想是将演示内容、修改职责和样式规范分层解耦。这套架构不仅适用于管理本项目的演示文件，也为任何使用 Claude Code 进行结构化文档创作的团队提供了参考模式。

核心架构：三个幻灯片与专用 Agent

整个演示系统建立在一个明确的委托规则之上。如 .claude/rules/presentation.md 所定义，任何对演示幻灯片的更新、修改或修复请求，必须由匹配的专用 Agent 处理，禁止直接编辑幻灯片的 HTML 文件。这一规则通过路由表实现，确保每个幻灯片都有明确的负责人。

仓库中目前维护三个不同的演示幻灯片，它们各有其专属 Agent：

  1. Vibe Coding → Agentic Engineering：路径为 presentation/vibe-coding-to-agentic-engineering/index.html，由 presentation-vibe-coding Agent 管理。这是演示从“氛围编码”到“智能体工程”概念转变的主要幻灯片。
  2. Claude Code & Gemini CLI：路径为 presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html，由 presentation-claude-gemini Agent 管理。这是一个为 GDG Kolachi 活动准备的、面向非技术受众的对比演示。
  3. Claude Code Best Practice：路径为 presentation/claude-code-best-practice/index.html，由 presentation-claude-code Agent 管理。这是从 GDG 幻灯片中派生出的、可重用的典范最佳实践演示，已去除活动特定内容。

这种设计允许每个演示保持独立的幻灯片编号、层级系统和目标受众。每个专用 Agent 都预加载了其管理幻灯片特定的框架、结构和样式技能，从而实现自我演化，同时避免与其他演示的知识交叉污染。

三个演示的关键差异

尽管共享相同的底层架构，三个演示在具体实现上存在显著差异，这反映了它们不同的设计目标：

  • Vibe Coding 演示：使用完整的 journey bar（旅程进度条）和 4-level 系统（Low, Medium, High, Pro），共有 49 张幻灯片。它通过 data-level 属性在章节分隔幻灯片上驱动旅程条的高度和颜色变化。
  • Claude Code 演示：结构更简单，仅使用 level-badge（级别徽章）系统，没有右侧的旅程条。它拥有 48 张幻灯片，并定义了 LEVEL_LABELS 映射来管理 agents、skills、context、claude-md、commands、workflow 等级别键。
  • Claude Gemini 演示：针对非技术活动受众设计，使用 6-level journey bar（对应两天的学习路径：prompting, agents, skills, memory, building, orchestration），并包含 day-badge（日期徽章）来区分不同学习日的内容。

理解这些差异对于正确路由用户请求至关重要。如果用户说“修改演示”，但未指定哪一个，Agent 必须首先询问澄清。

基础设施：Presentation Skills

专用 Agent 的能力并非凭空而来，它们依赖于仓库中定义的多个技能（Skills）来理解如何操作幻灯片。这些技能构成了演示系统的“基础设施”。

幻灯片结构与格式规范 (presentation-structure)

此技能定义了幻灯片的基本格式和导航规则。每个幻灯片都是一个带有 data-slide 属性的 div 元素，该属性从 1 开始顺序编号。关键格式包括：

  • 普通内容幻灯片：<div class="slide" data-slide="12">
  • 章节分隔幻灯片（触发级别转换）：<div class="slide section-slide" data-slide="10" data-level="low">
  • 标题幻灯片（居中）：<div class="slide title-slide" data-slide="1">

幻灯片通过 goToSlide(n) 函数导航，totalSlides 数量由 JavaScript 从 DOM 中自动计算。技能还规定了严格的 重新编号规则：在添加、删除或重新排序幻灯片后，必须更新所有 data-slide 属性和 goToSlide() 调用，确保连续无间断。

样式与组件库 (presentation-styling)

此技能为 Agent 提供了一套可复用的 CSS 组件类，确保演示视觉一致性：

  • 布局类：如 .two-col 用于两列网格，.col-card 配合 .good 或 .bad 用于对比展示。
  • 内容块类：如 .trigger-box（灰色关键概念框）、.how-to-trigger（绿色操作提示框）、.warning-box（橙色警告框）、.code-block（深色代码块）。
  • 列表与标签类：如 .use-cases 和 .use-case-item 用于图标列表，.matcher-tag 用于标签。
  • 代码高亮语法：在 .code-block 内，使用 .comment（绿色）、.key（蓝色）、.string（橙色）、.cmd（黄色）等 span 类进行语法着色。

概念框架 (vibe-to-agentic-framework)

此技能是 Vibe Coding 演示的核心，它阐释了整个演示叙事的逻辑：开发者如何从无结构的“氛围编码”（Low 级别）逐步走向完整的“智能体工程”（High 级别）。它定义了 4-Level 旅程系统（Low: 25%, Medium: 50%, High: 75%, Pro: 100%）的颜色、高度和过渡逻辑。

该技能以一个 TodoApp 全栈项目为贯穿始终的实例，清晰展示了配置前（vibe coding）和配置后（agentic engineering）的项目结构对比。它规划了从“引言”到“智能体工程”的六部分内容，并详细说明了每个章节如何建立在前一章的基础上，形成渐进式的学习路径。

工作流与维护

这套架构的优越性体现在其维护工作流中。当用户需要对某个演示进行修改时，系统会：

  1. 路由请求：根据规则将请求导向正确的专用 Agent。
  2. 加载上下文：Agent 调用相关的 Presentation Skills 来理解当前幻灯片的结构、样式和概念框架。
  3. 执行修改：在遵循技能规范的前提下，对 HTML 内容进行增删改。
  4. 验证完整性：修改后自动检查 data-slide 顺序、data-level 完整性、以及 goToSlide 引用的正确性。
  5. 同步知识（Self-Evolution）：Agent 在完成任务后，会更新自身知识库（如 Learnings 部分）以及相关的技能文档，确保所有知识与实际文件状态保持同步。

这种“委托-验证-同步”的闭环，确保了演示系统作为一个整体能够长期、稳定地演化。

总结

Claude Code 演示系统的三层架构——内容层（三个独立的幻灯片文件）、控制层（专用的管理 Agent 和委托规则）、知识层（定义格式、样式和概念的 Skills）——构成了一个高度模块化和可维护的系统。它解决了多版本演示协同编辑的难题，并通过将最佳实践编码为技能，提升了内容创作的规范性和效率。

此架构是 Claude Code 强大的扩展点（Subagents、Skills、Rules）在实际文档工程中的完美体现，是从 Vibe Coding 到 Agentic Engineering 转型的一个典型范例。对于希望深入理解如何利用子代理和技能来构建结构化工作流的团队，此项目提供了宝贵的参考。

FAQ

Q: 为什么演示修改必须通过专用 Agent，而不能直接编辑 HTML？ A: 每个幻灯片都有独特的编号、层级系统和受众，直接编辑容易导致不同演示间的结构和知识交叉污染。专用 Agent 配备了特定于该幻灯片的知识库，能确保修改的一致性和正确性，并能自动维护相关技能文档。

Q: 如何为一个新的演示创建类似的管理架构？ A: 可以参照现有模式：首先在 .claude/agents/ 下创建专用的 Agent 定义文件；然后在 .claude/rules/ 中添加路由规则；最后，确保为该幻灯片的结构和样式编写对应的 Skills（可复用或新建），并将其链接到 Agent 的配置中。

Q: 三个演示中的 data-level 转换规则有何不同？ A: Vibe Coding 演示使用4级系统，在幻灯片10, 18, 29, 34上设置 data-level，最终封顶在 High。Claude Code 演示没有 data-level 驱动的旅程条，而是通过 LEVEL_LABELS 管理级别键。Claude Gemini 演示使用6级系统，data-level 对应两天的学习主题，并包含 day-badge。