第 1 章：环境搭建与 CLAUDE.md 配置

你将学到什么

• 安装 gstack 和 superpowers 两套技能包
• 用 /init 生成 CLAUDE.md 项目说明文件
• 理解 CLAUDE.md 的结构——它怎么让 Claude "认识"你的项目

1.1 什么是 gstack 和 superpowers

在开始之前，先搞清楚这两套工具是什么、各自管什么。

gstack 是一套设计导向的技能包。它擅长：

• 从多个角色视角审查你的需求（CEO 视角、设计师视角、工程师视角）
• 生成 UI 设计方案并让你对比选择
• 审查视觉设计和页面质量

superpowers 是一套开发导向的技能包。它擅长：

• 把需求拆成详细的编码计划
• 自动派出 subagent（子代理）写代码、写测试、做代码审查
• 从计划到测试到发布的完整开发闭环

用一个比喻：gstack 是产品经理和设计师，superpowers 是开发团队。

flowchart TB
    subgraph gstack["gstack（产品+设计）"]
        A1[需求碰撞] --> A2[视觉设计] --> A3[设计审查]
    end

    subgraph superpowers["superpowers（开发团队）"]
        B1[实施计划] --> B2[编码+测试] --> B3[代码审查] --> B4[发布]
    end

    gstack --> superpowers

    style gstack fill:#eef2ff,stroke:#4f46e5
    style superpowers fill:#ecfdf5,stroke:#059669

1.2 安装技能包

安装 gstack

在终端中运行：

# 方法一：通过 Claude Code 内置安装器
# 在 Claude Code 中输入：
/install-gstack

# 方法二：手动安装
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup

安装 superpowers

# 在 Claude Code 中输入：
/install-superpowers

# 或手动安装
git clone https://github.com/anthropics/superpowers.git ~/.claude/skills/superpowers

验证安装

# 检查 skill 目录
ls ~/.claude/skills/gstack/
ls ~/.claude/skills/superpowers/skills/

你应该看到类似这样的输出：

# gstack 目录
design-consultation  design-review  design-shotgun
plan-ceo-review      plan-design-review  plan-eng-review
review  qa  ship  retro  investigate ...

# superpowers/skills 目录
brainstorming  writing-plans  subagent-driven-development
test-driven-development  requesting-code-review  finishing-a-development-branch ...

看到这些目录说明安装成功。

1.3 创建项目目录

mkdir noteflow && cd noteflow
npm create vite@latest . -- --template react

这创建了一个空的 React 项目，作为我们的起点。

1.4 什么是 CLAUDE.md

CLAUDE.md 是一个放在项目根目录的文件。它的作用是告诉 Claude Code："这个项目是做什么的、用什么技术栈、怎么构建和测试。"

你可以把它理解为给 AI 看的 README。

每次 Claude Code 启动时，它会自动读取这个文件。有了它，Claude 就知道：

• 项目是 React 应用，用 Vite 构建
• 测试用 vitest 跑
• 代码风格偏好是什么
• 哪些目录是重要的

1.5 用 /init 生成 CLAUDE.md

在 Claude Code 中输入：

/init

Claude 会分析你的项目结构，然后生成一个 CLAUDE.md 文件。

自动生成的 CLAUDE.md 长什么样

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Test Commands
- `npm run dev` — Start development server
- `npm run build` — Build for production
- `npm test` — Run tests with vitest
- `npm run test:watch` — Run tests in watch mode

## Architecture
- React 18 SPA with Vite
- Components in `src/components/`
- Custom hooks in `src/hooks/`
- Uses localStorage for data persistence

手动补充 gstack + superpowers 配置

在 CLAUDE.md 末尾加上工作流说明：

## AI Workflow
- Design phase: Use gstack skills (design-consultation, design-shotgun, design-review)
- Development phase: Use superpowers skills (writing-plans, subagent-driven-development, tdd)
- All code changes require tests before commit

1.6 /doctor 诊断环境

运行 /doctor 确认一切就绪：

/doctor

它会检查：

• Claude Code 版本是否最新
• Node.js 版本是否兼容
• 项目配置是否正确
• skill 包是否正常加载

如果一切正常，你会看到绿色的 "All checks passed"。

1.7 CLAUDE.md 进阶：怎么写更好

CLAUDE.md 不是写一次就不管了。随着项目推进，你应该持续更新它。

好的 CLAUDE.md 包含：

不要写的东西：

• 显而易见的规则（"写好代码"）
• 通用开发实践（"添加错误处理"）
• 每个文件每个组件的完整列表（这会变化，靠 Claude 自己看）

动手做

1. 安装 gstack 和 superpowers
2. 创建 noteflow 项目
3. 运行 /init 生成 CLAUDE.md
4. 运行 /doctor 确认环境就绪
5. 手动在 CLAUDE.md 中补充 AI 工作流配置

完成这些后，你的项目就准备就绪了。下一章我们开始用 gstack 做需求碰撞。

本章小结

关键点： CLAUDE.md 是整个流程的基础。后面的 gstack 和 superpowers 命令都依赖它来理解项目上下文。花 5 分钟写好 CLAUDE.md，后面省 50 分钟反复解释项目背景。