vibe-to-agentic-framework

从“氛围编程”到 Agentic Engineering 框架

此技能讲解演示文稿背后的概念模型。每张幻灯片和每个章节都围绕同一个故事展开：开发者如何逐步从无结构的“氛围编程”（低阶）转向高阶的 Agentic Engineering（高阶）。

核心概念

**氛围编程（低阶）**指开发者在没有结构的情况下使用 Claude Code——没有项目上下文、没有约定，也没有可复用的知识。每个提示词都像掷硬币一样充满不确定性。Claude 可能会创建随机端点、忽略现有模式、跳过测试，并生成不一致的代码。代码库会在每次交互后逐渐走向混乱。

**Agentic Engineering（高阶）**指 Claude Code 作为一个配置完备的工程系统运行。它了解项目架构（CLAUDE.md），遵循限定范围的约定（Rules），按需加载领域专业知识（Skills），将任务委派给专业工作者（Agents），编排多步骤工作流（Commands），自动处理生命周期事件（Hooks），并连接外部工具（MCP Servers）。每个提示词都能生成一致、经过测试且达到生产质量的代码。

在这两个极端之间的旅程是渐进且不断累积的。每项最佳实践都建立在前一项的基础上，演示文稿会按照开发者应该采用这些实践的顺序来讲解。

4 级旅程系统

演示文稿使用 4 级评分系统，而不是百分比进度条：

级别	顺序	颜色	旅程栏高度	描述
低	1	红／橙（hsl(0, 70%, 45%)）	25%	氛围编程领域——没有结构
中	2	黄色（hsl(40, 70%, 45%)）	50%	结构化工作流，一定程度的自动化
高	3	浅绿（hsl(80, 70%, 45%)）	75%	领域知识、技能、自定义 Agent
专家	4	深绿（hsl(120, 70%, 45%)）	100%	完整的 Agentic Engineering、多 Agent 团队

第 1 张幻灯片（标题页）会隐藏旅程栏，从第 2 张幻灯片开始显示。级别通过关键过渡幻灯片上的 data-level 属性设置，并沿用到后续幻灯片，直到级别再次变更。级别发生变化时，JS 会在幻灯片的 h1 上注入 .level-badge（不要在 HTML 中硬编码）。

持续示例：TodoApp 单体仓库

每种技术都会通过一个真实的全栈项目来演示。演示文稿展示了项目从普通状态（氛围编程）转变为配置完备的 Claude Code 项目（Agentic Engineering）的过程：

之前（氛围编程）：

todoapp/
├── backend/          # FastAPI (Python)
│   ├── main.py
│   ├── routes/
│   ├── models/
│   └── tests/
└── frontend/         # Next.js (TypeScript)
    ├── components/
    ├── pages/
    └── lib/

之后（Agentic Engineering）：

todoapp/
├── .claude/                  # Claude Code config
│   ├── agents/               # Custom subagents
│   ├── skills/               # Domain knowledge
│   ├── commands/             # Slash commands
│   ├── hooks/                # Lifecycle scripts
│   ├── rules/                # Modular instructions
│   ├── settings.json         # Team settings
│   └── settings.local.json   # Personal settings
├── backend/
│   └── CLAUDE.md             # Backend instructions
├── frontend/
│   └── CLAUDE.md             # Frontend instructions
├── .mcp.json                 # Managed MCP servers
└── CLAUDE.md                 # Project instructions

**为什么选择 TodoApp？**它足够小，可以放进幻灯片，又足够复杂，能够展示真实问题：具有路由模式和测试约定的后端、具有组件层级和设计令牌的前端，以及一种跨领域问题（例如添加新功能）需要前后端协作的单体仓库结构。

TodoApp 将氛围编程的问题具体化：没有结构时，让 Claude“添加一个 notes 功能”，会生成一个不符合 routes/todos.py 模式的随机 /api/notes 端点、一张没有侧边栏导航的独立页面，以及零个测试。采用完整的 Agentic 配置后，同样的请求会生成符合现有模式的路由、集成到侧边栏中的页面，以及风格与 test_todos.py 一致的测试。

旅程脉络：为何采用此顺序

演示文稿遵循精心设计的教学顺序。每个章节都会解锁一个新的能力层：

Part 0：引言（幻灯片 1–4，不计级别）

目的： 铺垫内容。介绍 TodoApp，定义氛围编程，并展示最终目标。

• 标题页以旅程为隐喻，开启整个过程
• 示例项目展示转变：对比 TodoApp 的前后状态——普通的项目结构与配置齐全的 Claude Code 项目（.claude/、CLAUDE.md、.mcp.json 等）
• “什么是氛围编程？”展示 0% 的基线状态，也就是痛点
• 旅程地图提供可点击的目录，展示接下来的完整路径

Part 1：先决条件（幻灯片 5–9，不计级别）

目的： 安装并运行 Claude Code。此部分纯属准备工作，不涉及工程实践。

• 安装、身份验证、首次会话、界面概览
• 不计级别，因为了解如何安装工具并不能提升代码质量
• “首次会话”就是氛围编程——这是有意安排的，让开发者亲身体验 0% 状态

Part 2：改进提示词（幻灯片 10–17，级别：低）

目的： 首次真正的改进。即使不进行任何项目配置，更好的输入也能带来更好的输出。

• 好提示词与坏提示词： 明确、范围清晰的提示词与模糊请求的对比。这是最简单的改进。
• 提供上下文： 使用 @files 为 Claude 提供所需代码，立即减少幻觉。
• 上下文窗口与 /compact： 了解有限的上下文窗口，避免长时间会话中的回复质量下降。
• 计划模式： /plan 要求先思考再编码，避免在错误的方法上白费力气。

为什么是低级别： 提示词是基础，但作用有限。它能改进单次交互，却无法形成持久的项目知识。每次会话都从零开始。

Part 3：项目记忆（幻灯片 18–24，级别：中）

目的： 从会话级知识跃升到项目级知识。现在 Claude 能够在不同会话之间记住信息。

• CLAUDE.md 与 /init： 项目的“Claude 使用说明”。用于说明架构、技术栈和约定。这是影响最大的单个文件。
• 应包含的内容： 编写有效 CLAUDE.md 内容的实用指南（控制在 150 行以内，重点写 Claude 需要了解的信息）。
• 规则： 在 .claude/rules/ 中定义按路径限定的约定。规则能发挥倍增作用——它们会自动应用于所有匹配的文件，无需开发者费力，就能确保一致性。只需一条 backend-testing.md 规则，就能永久确保每项测试都遵循相同模式。

为什么是中级别： 项目记忆让 Claude 从无状态工具转变为了解上下文的协作者。但仅有知识还不足以形成工作流。

Part 4：结构化工作流（幻灯片 25–28，级别：中）

目的： 采用系统化的方法，避免浪费精力并提升执行质量。

• 任务列表： 将复杂工作拆分成可跟踪的步骤，避免范围偏移并确保工作完整。
• 模型选择： 选择合适的模型（架构设计用 Opus，实施用 Sonnet，快速任务用 Haiku），以优化成本和质量。

为什么仍是中级别： 工作流很重要，但概念相对简单。它们以 Part 3 的项目记忆为基础，并以更系统的方式加以运用。迈向高级别的关键在于领域知识。

第 5 部分：领域知识（幻灯片 29–33，级别：高级）

目的： 可复用、按需调用的专业知识。Skills 是静态记忆（CLAUDE.md/Rules）与动态 Agent 之间的桥梁。

• 什么是 Skills： 将 Skills 作为封装好的领域知识，在相关时由 Claude 加载。渐进式披露的概念。
• 创建 Skills： 动手实践：为 TodoApp 构建一个 frontend-conventions skill，讲解 Tailwind 令牌、组件模式和侧边栏集成。
• Skill Frontmatter 与调用： 技术细节：YAML frontmatter、手动调用与自动发现调用，以及 context: fork 选项。

为什么是高级级别： Skills 是第一个“倍增器”概念——一个 skill 定义就能改善该领域未来的每次交互。但 Skills 是被动知识；需要 Agent 才能将其激活。

第 6 部分：Agentic 工程（幻灯片 34–46，级别：高级）

目的： 本次演示的终点。能够协同工作、端到端构建功能的自主专业 Agent。

• 什么是 Agent： 使用受限工具并预加载 Skills 的专业子 Agent 概念。
• 前端工程师 Agent： 一个具体的 Agent，使用 TodoApp 的前端约定，将路由添加到侧边栏，并遵循设计令牌。前后对比展示了这种转变。
• 后端工程师 Agent： 并行处理后端的 Agent——遵循 FastAPI 路由模式和 SQLAlchemy 模型，并按照现有风格编写测试。
• 命令与编排： 终极模式：Command → Agent → Skills。单个 /add-feature 命令可协调前端和后端 Agent，每个 Agent 都有自己的 Skills，从而交付完整功能。这是架构设计的巅峰。
• Hooks 与 MCP： 生命周期自动化（提交前检查、声音通知）和外部工具集成。最终的自动化层。
• Command → Agent → Skills： 完整的架构图。展示所有部分如何连接：命令调用 Agent，Agent 加载 Skills，Skills 提供知识。这张幻灯片展示了“高级级别”的理解。

为什么是高级级别： 本部分涵盖了本次演示教授的最高价值实践。此前所有内容都是为此做铺垫。编排和 Agentic 工作流代表了本课程所涵盖内容的上限——完整的 Pro（多 Agent 团队、高级编排模式）不在本次演示的范围内。

高级级别幻灯片（幻灯片 44）

庆祝时刻。展示完整的 TodoApp 配置：

• 用于项目上下文的 CLAUDE.md
• 用于按路径限定约定的 Rules
• 用于领域知识的 Skills
• 用于一致执行的 Agent
• 用于编排工作流的 Commands
• 用于生命周期自动化的 Hooks
• 用于外部工具的 MCP 服务

附录（幻灯片 47+，不计权重）

目的： 参考资料。涵盖每条命令、每项设置和每个配置选项。不计权重，因为这些是供查阅的内容，而非学习旅程的里程碑。包括：工具用法、所有斜杠命令、提交/PR 工作流、自定义选项、调试技巧和黄金法则。

编辑幻灯片时如何使用此框架

创建或修改幻灯片时，请考虑：

1. 这个概念在学习路径中处于什么位置？ 关于“提示词中更完善的错误消息”的幻灯片属于第 2 部分（提示词，低级）。关于“Agent 记忆范围”的幻灯片属于第 6 部分（Agentic，高级）。

2. 前后有什么变化？ 每张重要的幻灯片都应隐含或明确地展示对比：低级（vibe coding）下会发生什么，与使用这项技术后会发生什么。使用 TodoApp 让说明更具体。

3. 级别划分是否合理？ 级别会在各部分的分界处转换。某一部分中的各张幻灯片沿用该部分的级别。

4. 内容是否承接前文？ 技能默认开发者已经了解 CLAUDE.md 和规则。Agent 默认他们了解技能。命令默认他们了解 Agent。不要在某个概念所属的部分之前引用它。

5. 使用 TodoApp。 抽象的解释会让受众难以理解。展示实际的 routes/todos.py 代码、实际的 Sidebar.tsx 组件，以及实际的 CLAUDE.md 内容。这个贯穿始终的示例能让框架更加具体。

级别转换参考表

幻灯片	幻灯片名称	data-level	级别标签
10	更完善的提示词（部分分隔页）	data-level="low"	低
18	项目记忆（部分分隔页）	data-level="medium"	中
29	领域知识（部分分隔页）	data-level="high"	高
34	Agentic 工程（部分分隔页）	data-level="high"	高

所有其他幻灯片都沿用此前最后设置的 data-level 属性对应的级别。第 1–9 张幻灯片（简介 + 前置知识）没有级别；在第 2 张幻灯片显示“低”之前，级别条保持隐藏（第 2–9 张幻灯片位于第 10 张幻灯片的首次级别转换之前，因此级别条显示为空／零，直至第 10 张幻灯片）。

注意：主演示文稿（presentation/index.html）的级别上限为高——不会使用 data-level="pro"。作为理论上限，旅程条上仍会显示 Pro 刻度，但填充不会到达该刻度。视频演示文稿（1-video-workflow.html）的级别上限为中。