# Claude Code 项目初始化与脚手架定制实战
## 概述
本教程面向已有 Claude Code 基础使用经验的开发者，深入讲解如何利用 `/init` 命令、自定义 Slash Commands 和可复用模板，构建一套属于自己或团队的项目脚手架体系。学完后，你将能够在 5 分钟内从零引导出一个结构规范、配置完备的新项目，大幅减少重复性环境搭建工作。
**适用人群**：已掌握 Claude Code 基本操作，希望在日常多项目开发中实现"一次配置、处处复用"的中高级开发者。
## 前置条件
| 条件 | 说明 |
|------|------|
| Claude Code 已安装 | 版本 ≥ 1.0.50（支持 `/init` 和 Skills） |
| Node.js ≥ 18 | Claude Code 运行环境 |
| Git 基础 | 理解 `git init`、分支、远程仓库 |
| 命令行熟练度 | 能流畅使用终端操作 |
| 至少一个项目经验 | 了解项目目录结构的基本概念 |
---
## 第一章：理解 Claude Code 的项目初始化生命周期
### 1.1 为什么需要脚手架？
传统项目初始化是一个高度重复的过程：创建目录结构、配置 lint 工具、编写 README、设置 CI/CD、添加 .gitignore……每次新项目都要手动重复这些步骤。即使有 `create-react-app`、`yo generator` 这类工具，也只解决了技术栈层面的初始化，无法覆盖团队规范、AI 协作配置等定制需求。
Claude Code 的脚手架体系解决了这个问题，它将**项目上下文、团队规范、AI 协作指令**三者统一打包为可复用的模板。
### 1.2 Claude Code 项目初始化的三个阶段
一个完整的 Claude Code 项目初始化分为三个阶段：
```mermaid
flowchart LR
A["📋 Phase 1
环境扫描"] --> B["🏗️ Phase 2
结构生成"]
B --> C["⚙️ Phase 3
配置注入"]
A -->|"/init 自动扫描"| A1["识别技术栈
检测框架/语言"]
A -->|"读取已有文件"| A2["提取项目元信息"]
B -->|"目录模板"| B1["生成标准结构"]
B -->|"Slash Command"| B2["执行脚手架命令"]
C -->|"CLAUDE.md"| C1["写入项目指令"]
C -->|".claude/ 目录"| C2["配置 Commands/Skills"]
C -->|"settings.json"| C3["注入 Hooks 和权限"]
```
**Phase 1 — 环境扫描**：Claude Code 读取当前目录中的 `package.json`、`pyproject.toml`、`go.mod` 等文件，识别技术栈和框架。如果是空目录，则等待用户描述需求。
**Phase 2 — 结构生成**：根据识别结果或用户描述，生成项目目录结构、配置文件和基础代码。
**Phase 3 — 配置注入**：写入 `CLAUDE.md`、`.claude/commands/`、`.claude/settings.json` 等文件，为后续 AI 协作提供持久化上下文。
### 1.3 `/init` 命令深度解析
`/init` 是 Claude Code 内置的项目初始化命令，它的工作机制比表面看起来复杂得多：
```bash
# 在已有项目中运行
cd my-existing-project
claude
> /init
```
**`/init` 的内部流程**：
1. **文件扫描**：递归读取项目根目录的关键配置文件（最多 2 层深度）
2. **技术栈推断**：根据文件特征推断语言、框架、构建工具
3. **CLAUDE.md 生成**：自动生成一份结构化的 `CLAUDE.md`，包含：
- 项目概述（从 README/package.json 提取）
- 技术栈描述
- 目录结构说明
- 常用命令（build/test/lint）
- 编码规范建议
4. **规则文件分发**：在子目录中创建 `.claude/rules/*.md`（如果需要）
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `/init` 生成的 CLAUDE.md 太简略 | 项目信息不足 | 先完善 README.md 和 package.json |
| 多模块项目识别错误 | 只扫描根目录 | 手动补充子模块信息到 CLAUDE.md |
| 覆盖了已有的 CLAUDE.md | `/init` 会重写 | 先备份，或使用 `git stash` 暂存 |
---
## 第二章：构建你的第一个项目模板
### 2.1 模板的基本结构
一个 Claude Code 项目模板本质上是一个 Git 仓库，包含以下结构：
```
my-template/
├── CLAUDE.md # AI 协作指令（模板变量占位）
├── .claude/
│ ├── commands/
│ │ ├── scaffold.md # 脚手架 Slash Command
│ │ ├── add-feature.md # 添加功能的 Slash Command
│ │ └── setup-ci.md # CI 配置 Slash Command
│ ├── rules/
│ │ ├── typescript.md # TypeScript 编码规则
│ │ └── testing.md # 测试规则
│ └── settings.json # 项目级 Claude Code 配置
├── templates/
│ ├── react-component.tsx # React 组件模板
│ ├── api-route.ts # API 路由模板
│ └── test-file.test.ts # 测试文件模板
├── package.json.template # package.json 模板
├── tsconfig.json # TypeScript 配置
├── .gitignore
└── README.md
```
### 2.2 实战：创建 Next.js 全栈项目模板
我们来从零创建一个 Next.js + TypeScript + Prisma 的全栈项目模板。
**步骤 1：初始化模板仓库**
```bash
mkdir claude-nextjs-template
cd claude-nextjs-template
git init
mkdir -p .claude/commands .claude/rules templates
```
**步骤 2：编写核心 CLAUDE.md 模板**
创建 `CLAUDE.md`，使用 `$` 前缀的占位符标记可变部分：
```markdown
# 项目：{{PROJECT_NAME}}
## 技术栈
- **框架**：Next.js 15 (App Router)
- **语言**：TypeScript 5.x
- **样式**：Tailwind CSS 4
- **数据库**：Prisma + PostgreSQL
- **认证**：NextAuth.js v5
- **测试**：Vitest + Playwright
## 目录结构规范
- `src/app/` — App Router 页面和布局
- `src/components/` — 可复用 React 组件
- `ui/` — 基础 UI 组件（Button、Input 等）
- `features/` — 业务功能组件
- `src/lib/` — 工具函数和共享逻辑
- `src/server/` — 服务端代码（API routes、actions）
- `prisma/` — 数据库 Schema 和迁移
- `tests/` — 测试文件
## 开发命令
- `pnpm dev` — 启动开发服务器
- `pnpm build` — 生产构建
- `pnpm test` — 运行单元测试
- `pnpm test:e2e` — 运行 E2E 测试
- `pnpm lint` — ESLint 检查
- `pnpm db:push` — 推送 Prisma Schema 变更
## 编码规范
1. 组件使用函数式组件 + hooks，禁止 class 组件
2. 服务端组件优先，仅在需要交互时使用 `"use client"`
3. API 路由使用 Next.js Server Actions
4. 所有数据库操作通过 Prisma Client，禁止原始 SQL
5. 错误处理使用 `result` 模式，避免 try-catch 散落
6. 类型定义放在同文件底部或 `src/types/` 目录
7. 导入路径使用 `@/` 别名
## Git 规范
- 分支命名：`feat/xxx`、`fix/xxx`、`chore/xxx`
- Commit 格式：Conventional Commits
- PR 必须通过 lint + test 才能合并
```
**步骤 3：编写脚手架 Slash Command**
创建 `.claude/commands/scaffold.md`：
```markdown
根据以下参数初始化一个新项目：
项目名称：$ARGUMENTS
请执行以下步骤：
1. 运行 `npx create-next-app@latest $ARGUMENTS --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-pnpm`
2. 安装额外依赖：
- `prisma @prisma/client` — ORM
- `next-auth@beta @auth/prisma-adapter` — 认证
- `zod` — Schema 验证
- `vitest @testing-library/react` — 测试
3. 初始化 Prisma：`npx prisma init`
4. 创建标准目录结构：
- `src/components/ui/`
- `src/components/features/`
- `src/lib/`
- `src/server/`
- `src/types/`
- `tests/unit/`
- `tests/e2e/`
5. 复制模板文件：
- 从 templates/react-component.tsx 创建示例组件
- 从 templates/api-route.ts 创建示例 API 路由
- 从 templates/test-file.test.ts 创建示例测试
6. 配置 vitest.config.ts
7. 更新 .gitignore 添加 node_modules、.env、.env.local
8. 创建初始 git commit
完成后输出项目结构树和下一步操作指南。
```
**步骤 4：编写功能添加 Slash Command**
创建 `.claude/commands/add-feature.md`：
```markdown
为项目添加新功能模块：$ARGUMENTS
请按以下规范生成：
## 文件结构
为功能 $ARGUMENTS 创建以下文件：
1. `src/components/features/$ARGUMENTS/$ARGUMENTS.tsx` — 主组件
2. `src/components/features/$ARGUMENTS/index.ts` — 导出文件
3. `src/components/features/$ARGUMENTS/$ARGUMENTS.types.ts` — 类型定义
4. `src/components/features/$ARGUMENTS/$ARGUMENTS.test.tsx` — 单元测试
5. `src/app/$ARGUMENTS/page.tsx` — 页面路由（如适用）
6. `src/server/actions/$ARGUMENTS.ts` — Server Actions（如适用）
## 组件规范
- 使用函数式组件
- Props 通过 zod schema 验证
- 支持客户端和服务端渲染
- 包含 loading 和 error 状态
## 测试要求
- 使用 vitest + @testing-library/react
- 覆盖渲染、交互、错误状态三个场景
- 使用 MSW mock API 调用
请先阅读现有的组件和编码风格，确保新功能与项目风格一致。
```
**步骤 5：编写编码规则文件**
创建 `.claude/rules/typescript.md`：
```markdown
# TypeScript 编码规则
## 命名规范
- 组件文件：PascalCase（如 `UserProfile.tsx`）
- 工具函数文件：camelCase（如 `formatDate.ts`）
- 常量文件：UPPER_SNAKE_CASE（如 `API_ENDPOINTS.ts`）
- 类型文件：PascalCase + `.types.ts` 后缀
## 类型约束
- 禁止使用 `any`，必须提供明确类型
- 优先使用 `interface` 而非 `type`（除非需要联合类型）
- API 响应必须定义对应的 Zod Schema
- Props 类型必须从组件文件导出
## 导入顺序
1. React/Next.js 核心导入
2. 第三方库
3. @/ 别名导入
4. 相对路径导入
5. 类型导入（使用 `import type`）
```
创建 `.claude/rules/testing.md`：
```markdown
# 测试规则
## 文件命名
- 单元测试：`*.test.ts(x)`
- E2E 测试：`*.spec.ts`
- 测试工具：`test-utils.ts`
## 测试结构（AAA 模式）
```typescript
describe('ComponentName', () => {
it('should render correctly', () => {
// Arrange
const props = { title: 'Test' };
// Act
render();
// Assert
expect(screen.getByText('Test')).toBeInTheDocument();
});
});
```
## 覆盖率要求
- 新功能代码覆盖率 ≥ 80%
- 核心业务逻辑覆盖率 ≥ 95%
- UI 组件覆盖率 ≥ 60%
```
**步骤 6：创建模板文件**
创建 `templates/react-component.tsx`：
```tsx
"use client";
import { forwardRef } from "react";
interface {{ComponentName}}Props {
/** 主要内容 */
children: React.ReactNode;
/** 额外 CSS 类名 */
className?: string;
}
/**
* {{ComponentName}} 组件描述
*
* @example
* <{{ComponentName}}>内容
*/
export const {{ComponentName}} = forwardRef(
function {{ComponentName}}({ children, className = "" }, ref) {
return (
{children}
);
}
);
{{ComponentName}}.displayName = "{{ComponentName}}";
```
创建 `templates/test-file.test.ts`：
```typescript
import { describe, it, expect, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import { {{ComponentName}} } from "./{{ComponentName}}";
describe("{{ComponentName}}", () => {
it("renders children correctly", () => {
render(<{{ComponentName}}>Hello);
expect(screen.getByText("Hello")).toBeInTheDocument();
});
it("applies custom className", () => {
const { container } = render(
<{{ComponentName}} className="custom-class">Test
);
expect(container.firstChild).toHaveClass("custom-class");
});
it("forwards ref correctly", () => {
const ref = { current: null };
render(<{{ComponentName}} ref={ref}>Test);
expect(ref.current).toBeInstanceOf(HTMLDivElement);
});
});
```
**步骤 7：配置项目级 settings.json**
创建 `.claude/settings.json`：
```json
{
"permissions": {
"allow": [
"Bash(npx create-next-app*)",
"Bash(pnpm add*)",
"Bash(pnpm dev*)",
"Bash(pnpm build*)",
"Bash(pnpm test*)",
"Bash(pnpm lint*)",
"Bash(npx prisma*)",
"Bash(mkdir*)",
"Bash(cp *)",
"Bash(mv *)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(curl * | bash)",
"Bash(git push --force*)"
]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $FILE_PATH 2>/dev/null || true"
}
]
}
]
}
}
```
### 2.3 使用模板创建新项目
模板仓库准备就绪后，使用流程非常简洁：
```bash
# 1. 克隆模板
git clone https://github.com/your-org/claude-nextjs-template.git my-new-project
cd my-new-project
# 2. 清理模板的 Git 历史（开始新项目）
rm -rf .git
git init
# 3. 启动 Claude Code 并执行脚手架命令
claude
> /scaffold my-awesome-app
```
Claude Code 会自动读取 `/scaffold` 命令的内容，按照步骤执行项目初始化，包括创建 Next.js 应用、安装依赖、配置 Prisma、设置目录结构等。
```mermaid
sequenceDiagram
participant D as 开发者
participant CC as Claude Code
participant S as 系统
D->>CC: /scaffold my-awesome-app
CC->>S: npx create-next-app my-awesome-app
S-->>CC: 项目骨架生成
CC->>S: pnpm add prisma next-auth zod vitest
S-->>CC: 依赖安装完成
CC->>S: npx prisma init
CC->>S: 创建目录结构
CC->>S: 复制模板文件
CC->>S: 配置 vitest.config.ts
CC->>S: 更新 .gitignore
CC-->>D: ✅ 项目初始化完成
输出结构树和操作指南
Note over D,CC: 后续开发流程
D->>CC: /add-feature dashboard
CC->>CC: 读取现有组件风格
CC->>S: 创建 features/dashboard/ 目录
CC->>S: 生成组件、类型、测试文件
CC-->>D: ✅ 功能模块创建完成
```
---
## 第三章：多模板管理与团队共享
### 3.1 模板索引系统
当你有多个项目模板时（前端、后端、全栈、CLI 工具等），需要一个索引系统来管理。创建一个 `~/.claude/commands/new-project.md`：
```markdown
你是一个项目初始化助手。用户将描述想要创建的项目类型。
## 可用模板
| 模板 | 路径 | 适用场景 |
|------|------|----------|
| Next.js 全栈 | ~/templates/nextjs-fullstack/ | Web 应用、SaaS |
| Express API | ~/templates/express-api/ | REST/GraphQL API |
| CLI 工具 | ~/templates/cli-tool/ | 命令行工具 |
| Python FastAPI | ~/templates/fastapi-service/ | 数据服务、ML API |
| React 组件库 | ~/templates/react-lib/ | npm 包、组件库 |
## 工作流程
1. 根据用户描述匹配最合适的模板
2. 将模板文件复制到目标目录
3. 替换所有模板变量（{{PROJECT_NAME}} 等）
4. 执行模板中的 setup.sh（如果存在）
5. 初始化 Git 仓库
6. 运行 /init 生成 CLAUDE.md
项目描述：$ARGUMENTS
```
这样，你只需要输入 `/new-project 一个博客系统` 就能自动匹配模板并完成初始化。
### 3.2 团队模板仓库的最佳实践
在企业环境中，模板仓库的维护需要额外注意：
**目录组织**：
```
company-claude-templates/
├── templates/
│ ├── frontend/
│ │ ├── nextjs-saas/
│ │ ├── react-admin/
│ │ └── mobile-rn/
│ ├── backend/
│ │ ├── express-api/
│ │ ├── fastapi-service/
│ │ └── go-microservice/
│ └── fullstack/
│ ├── nextjs-prisma/
│ └── remix-supabase/
├── shared/
│ ├── rules/ # 通用规则文件
│ │ ├── code-review.md
│ │ ├── security.md
│ │ └── performance.md
│ ├── commands/ # 通用 Slash Commands
│ │ ├── add-feature.md
│ │ ├── setup-ci.md
│ │ └── generate-api.md
│ └── hooks/ # 通用 Hooks 配置
├── scripts/
│ ├── apply-template.sh # 模板应用脚本
│ └── validate-template.sh # 模板验证脚本
├── CLAUDE.md # 模板仓库自身的指令
└── README.md
```
**版本管理策略**：
```bash
# 使用 Git tags 管理模板版本
git tag -a "nextjs-saas/v1.2.0" -m "Next.js SaaS template v1.2.0"
# 在 apply-template.sh 中引用特定版本
TEMPLATE_VERSION="nextjs-saas/v1.2.0"
git clone --branch "$TEMPLATE_VERSION" --depth 1 \
https://github.com/company/claude-templates.git /tmp/template
```
### 3.3 模板变量替换系统
模板中的占位符需要一个替换机制。创建 `.claude/commands/apply-template.md`：
```markdown
将模板应用到当前项目。请执行以下变量替换：
## 变量映射表
| 占位符 | 来源 | 示例值 |
|--------|------|--------|
| {{PROJECT_NAME}} | 用户输入或目录名 | my-awesome-app |
| {{PROJECT_DESCRIPTION}} | 用户输入 | A task management app |
| {{AUTHOR_NAME}} | git config user.name | Zhang San |
| {{AUTHOR_EMAIL}} | git config user.email | zhang@example.com |
| {{YEAR}} | 当前年份 | 2026 |
| {{COMPONENT_NAME}} | 上下文推断 | UserProfile |
| {{DB_NAME}} | PROJECT_NAME 转换 | my_awesome_app |
## 替换规则
1. 读取模板目录中的所有文件
2. 识别 {{VARIABLE}} 格式的占位符
3. 根据映射表填充实际值
4. 对未映射的变量，提示用户输入
5. 保持文件原有缩进和格式
模板路径：$ARGUMENTS
```
---
## 第四章：实战案例 — 从模板到可运行项目的 10 分钟流程
### 4.1 场景描述
假设你需要创建一个在线书店 Web 应用，技术栈为 Next.js + Prisma + PostgreSQL。使用我们刚才构建的模板，整个流程如下：
### 4.2 完整操作流程
```bash
# Step 1：从模板创建项目（30秒）
git clone https://github.com/your-org/claude-nextjs-template.git online-bookstore
cd online-bookstore
rm -rf .git && git init
# Step 2：启动 Claude Code（5秒）
claude
# Step 3：执行脚手架命令（3分钟）
> /scaffold online-bookstore
# Claude 自动执行：
# ✓ create-next-app
# ✓ 安装额外依赖
# ✓ 初始化 Prisma
# ✓ 创建目录结构
# ✓ 复制模板文件
# ✓ 配置 vitest
# ✓ 创建初始 commit
# Step 4：添加第一个功能模块（2分钟）
> /add-feature books
# Claude 自动创建：
# ✓ src/components/features/books/books.tsx
# ✓ src/components/features/books/books.types.ts
# ✓ src/components/features/books/books.test.tsx
# ✓ src/app/books/page.tsx
# ✓ src/server/actions/books.ts
# Step 5：定义数据库模型（1分钟）
> 设计书籍数据模型，包含标题、作者、价格、ISBN、库存数量、分类，
> 使用 Prisma Schema 定义，并包含种子数据
# Step 6：验证项目（1分钟）
> 运行类型检查和测试，确保一切正常
# Step 7：启动开发（30秒）
> pnpm dev
```
### 4.3 预期输出
项目创建完成后的目录结构：
```
online-bookstore/
├── CLAUDE.md # 自动生成的项目指令
├── .claude/
│ ├── commands/
│ │ ├── scaffold.md
│ │ ├── add-feature.md
│ │ └── setup-ci.md
│ ├── rules/
│ │ ├── typescript.md
│ │ └── testing.md
│ └── settings.json
├── prisma/
│ ├── schema.prisma # 书籍数据模型
│ └── seed.ts # 种子数据
├── src/
│ ├── app/
│ │ ├── layout.tsx
│ │ ├── page.tsx
│ │ └── books/
│ │ └── page.tsx # 书籍列表页
│ ├── components/
│ │ ├── ui/ # 基础 UI 组件
│ │ └── features/
│ │ └── books/ # 书籍功能模块
│ │ ├── books.tsx
│ │ ├── books.types.ts
│ │ └── books.test.tsx
│ ├── lib/
│ │ └── prisma.ts # Prisma Client 单例
│ ├── server/
│ │ └── actions/
│ │ └── books.ts # 书籍 Server Actions
│ └── types/
├── tests/
│ ├── unit/
│ └── e2e/
├── vitest.config.ts
├── tsconfig.json
├── package.json
└── .gitignore
```
### 4.4 常见问题排查
**问题 1：`create-next-app` 执行失败**
```bash
# 原因：Node 版本不兼容或 npm registry 超时
# 解决：指定 registry 和 Node 版本
npx create-next-app@latest my-app --use-pnpm --registry=https://registry.npmmirror.com
```
**问题 2：Prisma 初始化后无法连接数据库**
```bash
# 原因：未配置 DATABASE_URL 环境变量
# 解决：创建 .env 文件
echo 'DATABASE_URL="postgresql://user:password@localhost:5432/bookstore?schema=public"' > .env
npx prisma db push
```
**问题 3：模板变量未被替换**
```
# 原因：Claude Code 将 {{VARIABLE}} 视为普通文本
# 解决：在 Slash Command 中明确指示替换规则
# 或使用 $ARGUMENTS 内置变量传递参数
```
---
## 第五章：进阶技巧 — 智能模板与动态适配
### 5.1 条件性模板生成
通过在 Slash Command 中编写条件逻辑，可以让同一个模板适配不同的技术选择：
创建 `.claude/commands/smart-init.md`：
```markdown
初始化新项目，根据用户描述智能选择技术栈：$ARGUMENTS
## 决策矩阵
根据项目描述中的关键词做出以下决策：
| 条件 | 技术选择 |
|------|----------|
| 包含"SSR"、"SEO"、"营销" | Next.js App Router |
| 包含"SPA"、"管理后台"、"Dashboard" | Next.js + CSR |
| 包含"API"、"微服务" | Express/Fastify |
| 包含"实时"、"聊天" | Next.js + Socket.io |
| 包含"电商"、"支付" | Next.js + Stripe |
| 包含"AI"、"ChatGPT" | Next.js + Vercel AI SDK |
## 执行流程
1. 分析用户描述，从决策矩阵匹配技术栈
2. 列出推荐的技术组合，等待用户确认
3. 确认后执行对应的脚手架流程
4. 根据选择的技术栈调整 CLAUDE.md 内容
5. 安装对应的依赖包
6. 生成匹配的基础代码
## 自适应规则
- 如果选择了数据库，自动配置 Prisma
- 如果选择了认证，自动配置 NextAuth
- 如果选择了测试框架，自动生成测试配置和示例
- 始终配置 ESLint + Prettier + TypeScript strict 模式
```
### 5.2 从现有项目提取模板
你有一个运行良好的项目，想把它变成可复用模板。创建 `.claude/commands/extract-template.md`：
```markdown
将当前项目提取为可复用的 Claude Code 模板。
请执行以下步骤：
1. **分析项目结构**
- 扫描所有文件，识别通用部分和项目特定部分
- 列出需要参数化的硬编码值（项目名、API 地址等）
2. **识别核心配置**
- 提取 CLAUDE.md 中的通用规范
- 分离技术栈相关规则到 .claude/rules/
- 提取可复用的 Slash Commands
3. **参数化处理**
- 将项目特定名称替换为 {{PROJECT_NAME}} 占位符
- 将硬编码值替换为 {{VARIABLE}} 占位符
- 保留通用的工具函数和组件模板
4. **生成模板文件**
- 输出到 ~/templates/项目类型/ 目录
- 包含 CLAUDE.md、.claude/ 目录、templates/ 目录
- 生成 README.md 说明模板使用方法
5. **验证模板**
- 在临时目录中应用模板
- 确认所有变量被正确替换
- 运行生成的项目确保可启动
项目名称：$ARGUMENTS
```
### 5.3 模板质量检查清单
| 检查项 | 标准 | 验证方法 |
|--------|------|----------|
| CLAUDE.md 完整性 | 包含技术栈、命令、规范 | 新成员能否仅凭此文件开始开发 |
| Slash Commands 可执行 | 每个命令都能无错误运行 | 在空白目录中测试 |
| 模板变量一致 | 所有占位符都有映射 | grep 所有 `{{` 检查 |
| 依赖版本锁定 | package.json 使用精确版本 | 检查无 `^` 或 `~` 前缀 |
| Hooks 配置正确 | settings.json 格式合法 | JSON lint 验证 |
| .gitignore 完整 | 覆盖所有敏感文件 | 对比 GitHub 模板 |
---
## 第六章：多技术栈模板实战
### 6.1 Python FastAPI 服务模板
```
fastapi-template/
├── CLAUDE.md
├── .claude/
│ ├── commands/
│ │ ├── scaffold.md
│ │ └── add-endpoint.md
│ └── rules/
│ ├── python.md
│ └── api-design.md
├── templates/
│ ├── endpoint.py
│ ├── model.py
│ ├── schema.py
│ └── test_endpoint.py
├── pyproject.toml.template
└── Dockerfile
```
核心 CLAUDE.md 片段：
```markdown
## 开发命令
- `uv sync` — 安装依赖
- `uv run fastapi dev` — 启动开发服务器
- `uv run pytest` — 运行测试
- `uv run ruff check .` — 代码检查
- `uv run mypy .` — 类型检查
## 编码规范
1. 使用 Python 3.12+ 特性（type hints、match-case、dataclass）
2. API 使用 FastAPI 路由，所有端点有类型注解
3. 数据库操作使用 SQLAlchemy 2.0 async
4. 配置管理使用 pydantic-settings
5. 依赖注入通过 FastAPI 的 Depends
```
### 6.2 Go 微服务模板
```
go-microservice-template/
├── CLAUDE.md
├── .claude/
│ ├── commands/
│ │ ├── scaffold.md
│ │ └── add-handler.md
│ └── rules/
│ └── go.md
├── templates/
│ ├── handler.go
│ ├── handler_test.go
│ └── middleware.go
├── go.mod.template
├── Makefile
└── Dockerfile
```
核心 CLAUDE.md 片段：
```markdown
## 编码规范
1. 项目结构遵循 Go Standard Layout
2. 接口定义在 `internal/interfaces/`
3. 错误处理使用 `fmt.Errorf` 包装，禁止 panic
4. 日志使用 slog 结构化日志
5. 测试使用标准 testing 包 + testify
6. Context 作为第一个参数传递
```
### 6.3 模板选择决策树
```mermaid
flowchart TD
START["🚀 新项目"] --> Q1{"项目类型？"}
Q1 -->|"Web 应用"| Q2{"需要 SSR/SEO？"}
Q2 -->|"是"| T1["📦 nextjs-fullstack"]
Q2 -->|"否"| Q3{"复杂度？"}
Q3 -->|"简单"| T2["📦 react-spa"]
Q3 -->|"复杂"| T1
Q1 -->|"API 服务"| Q4{"语言偏好？"}
Q4 -->|"TypeScript"| T3["📦 express-api"]
Q4 -->|"Python"| T4["📦 fastapi-service"]
Q4 -->|"Go"| T5["📦 go-microservice"]
Q1 -->|"CLI 工具"| Q5{"语言偏好？"}
Q5 -->|"TypeScript"| T6["📦 cli-tool-ts"]
Q5 -->|"Go"| T7["📦 cli-tool-go"]
Q5 -->|"Rust"| T8["📦 cli-tool-rust"]
Q1 -->|"库/组件包"| T9["📦 react-lib"]
T1 --> RUN["运行 /scaffold"]
T2 --> RUN
T3 --> RUN
T4 --> RUN
T5 --> RUN
T6 --> RUN
T7 --> RUN
T8 --> RUN
T9 --> RUN
```
---
## 延伸阅读
- [Claude Code 官方文档 — Extend Claude with Skills](https://code.claude.com/docs/en/skills) — Skills 和 Slash Commands 的权威参考
- [Claude Code 官方文档 — Best Practices](https://code.claude.com/docs/en/best-practices) — 官方推荐的项目配置实践
- [Claude Code Customization Guide: CLAUDE.md vs Skills vs Subagents](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/) — 四层定制体系的决策指南
- [CLAUDE.md Best Practices: The Complete 2026 Guide](https://dev.to/nishilbhave/claudemd-best-practices-the-complete-2026-guide-435j) — CLAUDE.md 编写的最佳实践
- [Claude Starter Kit](https://thedecipherist.com/articles/claude-code-mastery-project-starter-kit/) — 包含 23 个 Slash Commands 的实战启动模板
## 训练营适用性评估
| 评估维度 | 说明 |
|----------|------|
| 适合训练营类型 | AI 辅助开发训练营、全栈工程师速成营、企业工程效能提升 |
| 建议教学时长 | 3-4 小时（含实操练习） |
| 难度级别 | ⭐⭐⭐（中级） |
| 实操占比 | 70%（大量动手创建模板、运行命令、验证结果） |
| 分组建议 | 按技术栈分组（前端组、后端组、全栈组），每组构建一个模板 |
| 考核方式 | 各组完成模板构建 + 跨组互换模板进行项目初始化 |
| 前置要求 | 已完成 Claude Code 入门课程，至少有一个实际项目经验 |
## 参考来源
1. [Extend Claude with skills — Claude Code Docs](https://code.claude.com/docs/en/skills) — Anthropic 官方 Skills 和自定义命令文档
2. [CLAUDE.md Best Practices: The Complete 2026 Guide — dev.to](https://dev.to/nishilbhave/claudemd-best-practices-the-complete-2026-guide-435j) — CLAUDE.md 编写完整指南
3. [Claude Code Skills vs Slash Commands 2026: Complete Guide — yingtu.ai](https://yingtu.ai/en/blog/claude-code-skills-vs-slash-commands) — Skills 与 Slash Commands 架构对比
4. [Claude Code Customization Guide — alexop.dev](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/) — CLAUDE.md / Skills / Subagents 定制决策树
5. [Starting New Projects from the Terminal — Developer Toolkit](https://developertoolkit.ai/en/claude-code/lessons/project-init/) — 项目初始化三阶段工作流
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
