Claude Code 项目初始化与脚手架定制实战

flowchart LR
    A["📋 Phase 1<br/>环境扫描"] --> B["🏗️ Phase 2<br/>结构生成"]
    B --> C["⚙️ Phase 3<br/>配置注入"]

    A -->|"/init 自动扫描"| A1["识别技术栈<br/>检测框架/语言"]
    A -->|"读取已有文件"| A2["提取项目元信息"]

    B -->|"目录模板"| B1["生成标准结构"]
    B -->|"Slash Command"| B2["执行脚手架命令"]

    C -->|"CLAUDE.md"| C1["写入项目指令"]
    C -->|".claude/ 目录"| C2["配置 Commands/Skills"]
    C -->|"settings.json"| C3["注入 Hooks 和权限"]

# 在已有项目中运行
cd my-existing-project
claude
> /init

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

mkdir claude-nextjs-template
cd claude-nextjs-template
git init
mkdir -p .claude/commands .claude/rules templates

# 项目：{{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 才能合并

根据以下参数初始化一个新项目：

项目名称：$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

完成后输出项目结构树和下一步操作指南。

为项目添加新功能模块：$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 调用

请先阅读现有的组件和编码风格，确保新功能与项目风格一致。

# 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`）

# 测试规则

## 文件命名
- 单元测试：`*.test.ts(x)`
- E2E 测试：`*.spec.ts`
- 测试工具：`test-utils.ts`

## 测试结构（AAA 模式）
```typescript
describe('ComponentName', () => {
  it('should render correctly', () => {
    // Arrange
    const props = { title: 'Test' };
    // Act
    render(<Component {...props} />);
    // Assert
    expect(screen.getByText('Test')).toBeInTheDocument();
  });
});

**步骤 6：创建模板文件**

创建 `templates/react-component.tsx`：

```tsx
"use client";

import { forwardRef } from "react";

interface {{ComponentName}}Props {
  /** 主要内容 */
  children: React.ReactNode;
  /** 额外 CSS 类名 */
  className?: string;
}

/**
 * {{ComponentName}} 组件描述
 *
 * @example
 * <{{ComponentName}}>内容</{{ComponentName}}>
 */
export const {{ComponentName}} = forwardRef<HTMLDivElement, {{ComponentName}}Props>(
  function {{ComponentName}}({ children, className = "" }, ref) {
    return (
      <div ref={ref} className={className}>
        {children}
      </div>
    );
  }
);

{{ComponentName}}.displayName = "{{ComponentName}}";

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</{{ComponentName}}>);
    expect(screen.getByText("Hello")).toBeInTheDocument();
  });

  it("applies custom className", () => {
    const { container } = render(
      <{{ComponentName}} className="custom-class">Test</{{ComponentName}}>
    );
    expect(container.firstChild).toHaveClass("custom-class");
  });

  it("forwards ref correctly", () => {
    const ref = { current: null };
    render(<{{ComponentName}} ref={ref}>Test</{{ComponentName}}>);
    expect(ref.current).toBeInstanceOf(HTMLDivElement);
  });
});

{
  "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"
          }
        ]
      }
    ]
  }
}

# 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

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: ✅ 项目初始化完成<br/>输出结构树和操作指南

    Note over D,CC: 后续开发流程

    D->>CC: /add-feature dashboard
    CC->>CC: 读取现有组件风格
    CC->>S: 创建 features/dashboard/ 目录
    CC->>S: 生成组件、类型、测试文件
    CC-->>D: ✅ 功能模块创建完成

你是一个项目初始化助手。用户将描述想要创建的项目类型。

## 可用模板

| 模板 | 路径 | 适用场景 |
|------|------|----------|
| 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

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

# 使用 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

将模板应用到当前项目。请执行以下变量替换：

## 变量映射表

| 占位符 | 来源 | 示例值 |
|--------|------|--------|
| {{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 | [email protected] |
| {{YEAR}} | 当前年份 | 2026 |
| {{COMPONENT_NAME}} | 上下文推断 | UserProfile |
| {{DB_NAME}} | PROJECT_NAME 转换 | my_awesome_app |

## 替换规则
1. 读取模板目录中的所有文件
2. 识别 {{VARIABLE}} 格式的占位符
3. 根据映射表填充实际值
4. 对未映射的变量，提示用户输入
5. 保持文件原有缩进和格式

模板路径：$ARGUMENTS

# 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

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

# 原因：Node 版本不兼容或 npm registry 超时
# 解决：指定 registry 和 Node 版本
npx create-next-app@latest my-app --use-pnpm --registry=https://registry.npmmirror.com

# 原因：未配置 DATABASE_URL 环境变量
# 解决：创建 .env 文件
echo 'DATABASE_URL="postgresql://user:password@localhost:5432/bookstore?schema=public"' > .env
npx prisma db push

# 原因：Claude Code 将 {{VARIABLE}} 视为普通文本
# 解决：在 Slash Command 中明确指示替换规则
# 或使用 $ARGUMENTS 内置变量传递参数

初始化新项目，根据用户描述智能选择技术栈：$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 模式

将当前项目提取为可复用的 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

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

## 开发命令
- `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

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

## 编码规范
1. 项目结构遵循 Go Standard Layout
2. 接口定义在 `internal/interfaces/`
3. 错误处理使用 `fmt.Errorf` 包装，禁止 panic
4. 日志使用 slog 结构化日志
5. 测试使用标准 testing 包 + testify
6. Context 作为第一个参数传递

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