claude-code-best-practice-zh: Skill for Claude Code

"从 Vibe 编码到智能体工程"框架

本技能教授演示文稿背后的概念模型。每张幻灯片和每个章节的存在都是为了讲述一个故事：开发者如何逐步从无结构的"Vibe 编码"（低等级）发展到高水平的智能体工程（高等级）。

核心概念

**Vibe 编码（低等级）**是指开发者在没有任何结构的情况下使用 Claude Code —— 没有项目上下文、没有规范、没有可复用的知识。每次提示都是在碰运气。Claude 可能会创建随机的端点、忽略现有模式、跳过测试，并产生不一致的代码。每次交互都会使代码库趋向混乱。

**智能体工程（高等级）**是指 Claude Code 作为一个完全配置好的工程系统运行。它了解项目架构（CLAUDE.md），遵循有范围的规范（Rules），按需加载领域专业知识（Skills），委派给专业工作者（Agents），编排多步骤工作流（Commands），自动化生命周期事件（Hooks），并连接外部工具（MCP 服务器）。每次提示都能产生一致、经过测试、生产级的代码。

这两个极端之间的旅程是渐进和累积的。每个最佳实践都建立在前一个之上，演示文稿按照开发者应该采用的顺序教授它们。

4 级旅程系统

演示使用 4 级评分系统而非百分比进度条：

等级	顺序	颜色	旅程栏高度	描述
低	1	红色/橙色 (hsl(0, 70%, 45%))	25%	Vibe 编码领域 —— 无结构
中	2	黄色 (hsl(40, 70%, 45%))	50%	结构化工作流，一定程度的自动化
高	3	浅绿色 (hsl(80, 70%, 45%))	75%	领域知识、技能、自定义智能体
专业	4	深绿色 (hsl(120, 70%, 45%))	100%	完整的智能体工程，多智能体团队

旅程栏在第 1 张幻灯片（标题幻灯片）上隐藏，从第 2 张幻灯片开始显示。等级通过在关键过渡幻灯片上设置 data-level 属性来设定，并由后续幻灯片继承，直到下一个等级变化。当等级变化时，.level-badge 会被 JS 注入到幻灯片的 h1 中（请勿在 HTML 中硬编码这些）。

贯穿示例：TodoApp 单体仓库

每种技术都通过真实的全栈项目演示。演示展示了从普通项目（Vibe 编码）到具有完整 Claude Code 配置的项目（智能体工程）的转换：

之前（Vibe 编码）：

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

之后（智能体工程）：

todoapp/
├── .claude/                  # Claude Code 配置
│   ├── agents/               # 自定义子智能体
│   ├── skills/               # 领域知识
│   ├── commands/             # 斜杠命令
│   ├── hooks/                # 生命周期脚本
│   ├── rules/                # 模块化指令
│   ├── settings.json         # 团队设置
│   └── settings.local.json   # 个人设置
├── backend/
│   └── CLAUDE.md             # 后端指令
├── frontend/
│   └── CLAUDE.md             # 前端指令
├── .mcp.json                 # 托管 MCP 服务器
└── CLAUDE.md                 # 项目指令

**为什么选择 TodoApp？**它足够小可以放在幻灯片上，但又足够复杂可以展示真实问题：具有路由模式和测试约定的后端、具有组件层次结构和设计令牌的前端，以及需要跨后端和前端协调的单体仓库结构。