Vibe Coding 项目开发流程

Vibe Coding 并不是让 AI 一次性生成整个项目，而是通过明确目标、控制边界、维护上下文、拆分任务、持续验证，让 AI 成为长期的软件开发协作者。AI 最大的问题不是不会写代码，而是在项目复杂后容易忘记初始目标、扩大需求范围、重复实现功能、修改已有设计，最终生成短期可运行但难以维护的代码。因此，Vibe Coding 的核心不是“让 AI 写更多代码”，而是建立一套让 AI 始终可控的开发流程：开发者负责目标、架构和质量判断，AI 负责分析、实现和辅助验证。

核心原则：

上下文先于代码；
边界先于实现；
一次只完成一个可验证任务；
验证比生成更重要；
优先复用成熟方案，不重复造轮子；
重要设计必须沉淀到文档；
Git 保存每一次稳定状态。
AI 最大的问题不是不会写代码，而是在项目变复杂后容易：
忘记最初目标；
随意扩大需求；
重复实现已有功能；
修改已有设计；
生成无法维护的代码。

因此，Vibe Coding 的核心不是“让 AI 写更多代码”，而是建立一套让 AI 始终可控的开发流程。
核心原则：

一句话目标 + 非目标
正交性，功能不要太重复了，（这个分场景）
能抄不写，不重复造轮子，先问 ai 有没有合适的仓库，下载下来改
一定要看官方文档，先把官方文档爬下来喂给 ai
按职责拆模块
接口先行，实现后补
一次只改一个模块
文档即上下文，不是事后补

上下文先于代码；

边界先于实现；
一次只做一个可验证任务；
验证比生成更重要；
重要决定必须写入文档；
每次会话结束都留下 Handoff；
Git 始终保存可回退的稳定版本。

1. 跟 AI 聊想法（Idea）明确目标

先把脑海中的想法完整说出来，包括项目要解决的问题、主要用户、理想使用流程、核心功能和未来可能的发展方向。此时先不要急着讨论框架和代码，重点是让 AI 理解你真正想做的项目。

项目开始时，先完整描述自己的想法，包括：

项目解决什么问题；
目标用户是谁；
核心使用流程；
最重要的功能；
未来可能的发展方向。
这一阶段不要急着写代码，而是让 AI 理解：
我为什么要做这个项目，以及它最终应该解决什么问题。

同时明确：一句话目标，说明项目存在的核心价值。例如：构建一个帮助个人管理技术知识并通过 AI 快速检索的知识系统。
非目标（Not Goal）：明确当前版本不解决什么问题。

例如：

当前版本不做：

- 多用户协作
- 企业权限系统
- 复杂推荐算法
- 微服务拆分

非目标非常重要，因为 AI 天然倾向于增加功能。

2. 需求分析与 PRD

PRD 全称为 Product Requirements Document，即产品需求文档，主要回答项目为什么做、给谁使用、解决什么问题以及需要哪些核心功能。需求分析的目标不是讨论所有可能出现的情况，而是确认能够支撑产品设计的核心需求。AI 生成 PRD 后，不能直接进入开发，而要检查它是否正确理解了你的需求，是否加入了不需要的功能，是否遗漏了关键场景。

PRD（Product Requirements Document）主要描述：

为什么做；
给谁使用；
解决什么问题；
当前版本有哪些功能。
PRD 不是一次完成的最终文档，而是持续迭代的当前共识：

PRD v0.1
    ↓
开发验证
    ↓
发现问题
    ↓
PRD v0.2

剩余未确定的问题记录到：

Open Questions

例如：

- 是否支持移动端？
- URL规则如何设计？
- 是否需要缓存？

这些问题不阻塞当前开发。

当我们确认了大约 10~15 个核心需求后，请主动提醒我："目前信息已经足够支撑 PRD v0.1。"不要继续无限细化需求。剩余问题请整理为 Open Questions，在 PRD 中记录即可。PRD 是可以持续迭代的，不需要等待所有问题都讨论完成。AI 非常擅长发现问题，但不会主动告诉你"现在已经够了，可以进入下一阶段"。

每轮只讨论一个主题。
对于每个问题：

先说明为什么这个问题重要。
给出 3～5 个常见参考方案（仅用于启发思考，不代表推荐）。
明确每种方案的优缺点和适用场景。
最后请我选择、修改或提出新的方案。
在我确认之前，不要继续进入下一个主题。

PRD 为什么不是最终文档
PRD（Product Requirements Document，产品需求文档）本身就是一个持续迭代的文档，并不是一次性完成的最终版本。真实的软件开发通常采用 PRD v0.1 → Review → PRD v0.2 → PRD v1.0 的方式不断完善，而不是等待所有需求都讨论结束再开始编写。PRD 的作用是把当前已经确认的产品需求沉淀下来，为后续架构设计和开发提供依据，因此它更强调"当前共识"，而不是"绝对完整"。

为什么不要一直讨论需求，而要尽早进入 PRD

需求分析的目标不是讨论所有可能出现的场景，而是确认能够支撑产品设计的核心需求。由于边界情况几乎没有尽头，如果不断追问各种特殊场景，AI 很容易陷入无限需求细化，导致项目长期停留在需求阶段而无法推进。一般当产品定位明确、用户和目标清晰，并确认了约 10～15 个核心需求后，就可以开始编写 PRD v0.1。剩余未确定的问题统一记录到 Open Questions，后续随着设计和开发不断迭代，而不是阻塞整个项目。

Open Questions 的作用

Open Questions（开放问题）用于记录目前尚未决定、但未来需要继续讨论的问题，例如 URL 规则、UI 细节、品牌设计、部署方案等。这些问题不会影响当前阶段推进，因此不应继续消耗需求讨论时间，而是统一记录下来，待进入架构设计或详细设计阶段后再逐项解决。它既避免遗漏需求，也避免 AI 陷入无休止的边界讨论。

AI 为什么容易陷入无限需求分析

大模型的目标通常是尽可能回答完整，因此它会不断发现新的边界情况，例如"删除怎么办""404 怎么处理""缓存怎么办"等。理论上这些问题永远讨论不完，所以 AI 不会主动告诉你什么时候应该停止，而需要人为设定阶段边界。当核心需求已经足够支撑下一阶段时，应主动停止需求细化，进入 PRD 编写，再通过后续迭代不断完善，而不是追求第一次就讨论完所有细节。

3. 明确 MVP 与项目范围 Scope

PRD 确认后，需要进一步确定当前版本实际开发范围。
MVP（Minimum Viable Product）是能够验证项目核心价值的最小可用版本。它不是简单减少功能，而是在最低开发成本下验证：用户真正需要的核心能力是否成立。先验证核心价值，再根据真实需求扩展。

例如：一个 AI 知识库项目：
- 完整目标：笔记管理；AI搜索；知识图谱；多人协作；权限管理
- MVP：Markdown导入 -> AI检索 -> 回答问题

Scope 是当前版本的项目边界，需要明确：

当前版本必须完成什么；
当前版本明确不做什么；
哪些功能以后再实现；
项目属于个人项目、开源项目还是商业产品。

明确 Scope 可以防止 AI 不断增加数据库、登录、微服务、多 Agent 等当前并不需要的内容。

4. 确定技术栈

根据 PRD、Scope、项目规模、开发人数、学习成本和维护成本选择技术栈，而不是盲目使用最新或最复杂的技术。

技术选型应该根据：

项目规模；
维护成本；
学习目标；
社区成熟度；
选择，而不是追求最新技术。
原则：

官方方案 > 成熟开源项目 > 自己实现

开发前优先问 AI：

有没有成熟项目可以参考；
有没有官方 SDK；
有没有类似 GitHub 仓库。
能抄不写，不重复造轮子。

5. 进行架构设计

架构设计解决：系统应该如何组织。

在编码前明确系统整体结构，包括：

项目目录；
模块划分；
页面或接口结构；
数据模型；
模块之间的调用关系；
核心数据流；
错误处理和扩展方式。
但不要追求一次设计完美。个人项目应该：

简单架构开始
      ↓
根据真实需求演进

而不是一开始设计复杂系统。

架构设计解决的是“系统如何组织”，而不是每一行代码如何实现。

6. 整理项目文档

项目讨论过程中的重要信息不能只存在聊天记录中，而应该沉淀到项目文件中。因为随着代码增加，AI 很容易丢失之前的设计决策、需求边界和开发状态。
文档的作用不是增加流程负担，而是为 AI 提供稳定上下文，让后续每次开发都基于已有共识继续推进。

推荐基础文档：
README.md       ← 项目介绍、环境配置、启动方式
PRD.md          ← 产品目标、用户需求、功能范围
DESIGN.md       ← 系统架构、模块划分、数据流
TASKS.md        ← 当前任务列表和开发进度
AGENTS.md       ← AI 协作规则
HANDOFF.md      ← 当前开发状态和下一步计划

当项目规模变大、设计复杂后，再增加：
SPEC.md         ← 详细功能规格、接口输入输出、验收标准
DECISIONS.md    ← 重要技术决策及选择原因

项目文档不是自动产生的，而是在对应阶段由 AI 根据当前共识生成，并经过开发者确认后保存到项目中。AGENTS.md 负责约束后续 AI 如何读取和维护这些上下文，而不是替代人工决策。

只有 Agent.md 被设计为支持读取的上下文文件，会自动加载；其他项目文档通常需要主动让 AI 查看，或者通过规则文件引导它读取。

其中：

README.md：项目介绍、环境配置和启动方式；
PRD.md：记录项目目标、用户需求和功能范围；
DESIGN.md：记录系统架构、模块划分和核心设计；
TASKS.md：记录当前任务和开发进度；
AGENTS.md：定义 AI 协作规则，包括开发流程、代码规范、测试要求等；
HANDOFF.md：记录当前开发状态，方便下一次继续开发；
SPEC.md：复杂项目中记录详细功能规格、接口和验收标准；
DECISIONS.md：记录重要技术决策及其原因。

AGENTS.md 的作用

AGENTS.md 是 AI Coding Agent 在项目中的协作规则文件，本质上是提供给 AI 的项目级上下文和行为约束。当 Codex、Claude Code 等 Agent 开始工作时，会读取项目中的 AGENTS.md，理解当前项目的目标、开发规范、技术约束和协作方式，从而避免每次对话重新解释项目背景，也减少 AI 随意修改架构、扩大需求或生成不符合项目风格的代码。它并不是记录具体业务需求的产品文档，而是定义“AI 应该如何参与这个项目”。通常放在项目根目录，通过 Markdown 编写，内容包括项目背景、开发原则、代码规范、目录结构说明、测试要求、提交规范以及禁止事项等。例如可以规定：“修改代码前先说明计划；一次只完成当前 Task；不要修改无关文件；优先复用已有实现；完成后必须运行测试；遇到需求不明确时先询问。”随着项目发展，可以逐步补充新的规则，使 AGENTS.md 成为 AI 长期协作的稳定入口。

7. 拆分 Task

不能直接把“完成整个项目”交给 AI，而要拆成可以独立实现和验证的小任务。

一个 Task 应明确：

任务目标；
修改范围；
涉及文件；
输入输出；
验收标准；
测试方式。

一次只完成一个 Task，任务过大时继续拆分。

8. 初始化 Git

从项目开始时就使用 Git：

git init
git add .
git commit -m "chore: initialize project"

Git 不只是为了上传 GitHub，更重要的是记录 AI 的每次修改并提供回滚能力。建议一个完整 Task 对应一个 Commit。

9. Coding → Test → Review → Commit

每个 Task 遵循固定循环：

读取上下文
   ↓
确认任务
   ↓
制定计划
   ↓
修改代码
   ↓
运行验证
   ↓
Review
  ↓
Commit
  ↓
更新文档

Coding

开始前让 AI：

阅读相关文档；
理解当前代码；
说明修改计划。
开发过程中：

只实现当前 Task；
不扩大 Scope；
不随意重构；
不替换已有技术方案。

Test Strategy 与自动化验证

代码生成不代表完成。
必须验证：

是否能启动；
是否编译通过；
测试是否通过；
是否符合需求；
是否影响已有功能。
原则：
AI 负责生成，人负责验证。

Test Strategy       AI设计测试方案:根据当前Task和需求设计测试方案：
								- 单元测试
								- 集成测试
								- 边界测试
								- 异常测试
 ↓
Generate Tests      AI生成测试代码
 ↓
Run Tests           AI执行测试
 ↓
Human Validation    人工验证,人工关注：
							- 产品行为；
							- 用户体验；
							- 核心流程；
							- 架构合理性。

Review

让 AI 检查：

是否存在 Bug；
是否有重复代码；
是否违反规范；
是否过度设计；
是否真正满足需求。
AI时代：

AI Review       代码质量、规范、安全
+
Human Review    需求、架构、设计取舍

Commit

确认稳定后提交 Git：

git status
git diff

git add .

git commit -m "feat: complete task"

Git 的作用：

保存稳定版本；
支持回滚 AI 修改；
记录开发过程。

建议：
一个完整 Task 对应一个 Commit。

10. 更新项目上下文

完成任务后，应同步更新：

TASKS.md：标记任务状态并确定下一任务；
HANDOFF.md：记录本次完成内容、当前状态、已知问题和下一步；
SPEC.md：功能规格发生真实变化时更新；
DECISIONS.md：产生重要技术选择时记录；
README.md：启动、配置或使用方式变化时更新。
HANDOFF.md 相当于会话接力文档。下次打开 Codex 后，先读取它，就能快速知道上次做到哪里。

11. 进入下一 Task

完成 Commit、文档更新和 Handoff 后，再开始下一个 Task，重复执行：

读取上下文
→ 确认任务与边界
→ 制定计划
→ Coding
→ Test
→ Review
→ Commit
→ 更新 Handoff
→ 下一 Task

12. 沉淀学习文档

对于以学习为目的的项目，核心模块完成后可以将知识整理到：

docs/learning/

内容可以包括：

模块解决什么问题；
核心执行流程；
底层原理；
为什么这样设计；
替代方案和优缺点；
企业项目中的常见做法；
常见面试问题；
本项目中的实际调用链。
学习文档不是每个小改动都必须生成，只在完成重要模块或出现有价值的设计经验时整理。

13.最终流程

Idea
 ↓
目标 + 非目标
 ↓
需求分析
 ↓
PRD v0.1
 ↓
MVP + Scope
 ↓
技术选型
 ↓
架构设计
 ↓
项目上下文
 ↓
Task拆分
 ↓
Git初始化
 ↓
Coding Loop

Plan
 ↓
Code
 ↓
Test Strategy
 ↓
Generate Tests
 ↓
Run Tests
 ↓
AI Review
 ↓
Human Review
 ↓
Commit
 ↓
Update Context

 ↓

Next Task

Claude Code 使用指南

1. 上下文压缩控制

1.1 核心概念

Claude Code 的上下文窗口有限（通常约 200K tokens）。随着对话进行，历史消息、代码片段、工具调用结果不断累积，最终会触发"上下文窗口满"的情况。有效的上下文管理是保持长会话生产力的最关键技能。

1.2 `/compact` 命令

这是最重要的上下文管理命令。

/compact

工作原理：

Claude 读取完整对话历史，生成结构化摘要
摘要内容包括：已完成的任务、已做的决策、修改过的文件、关键事实
早期对话被替换为压缩摘要，仅保留最近的若干轮完整对话
压缩后释放大量上下文空间，可以继续工作

使用时机：

✅ 主动压缩：每 30-50 轮对话后主动执行，不要等 Claude "开始遗忘"才压缩
✅ 任务切换时：完成一个大任务、开始新任务前
✅ 响应变慢时：对话历史过长会导致处理速度下降
✅ 开始出现遗忘迹象：Claude 开始忽略早期指令时

注意事项：

压缩是不可逆的——压缩后无法恢复被丢弃的原始对话
压缩质量取决于对话结构的清晰度——如果对话混乱，摘要也会遗漏信息
压缩前可以手动总结关键点告诉 Claude

1.3 自动压缩（Auto-Compact）

Claude Code 在上下文接近上限时会自动触发压缩，你会在界面看到提示。但依赖自动压缩有以下问题：

自动压缩发生在"快满"的时候，此时 Claude 可能已经因为上下文拥挤而表现下降
主动 /compact 比被动等待自动压缩效果更好

1.4 减少上下文消耗的技巧

控制输出量

精准提问：明确指定你需要什么，避免开放式问题产生大量输出
文件读取策略：不要一次性读取整个大文件，指定行范围或搜索特定函数
避免不必要的工具调用：不要让 Claude 重复读取同一文件

CLAUDE.md 精简

CLAUDE.md 在每次会话启动时加载到上下文中。保持精简（建议 50-100 行）：

# 项目概述
简短描述（2-3 行）

# 常用命令
npm run dev      # 启动开发服务器
npm test         # 运行测试
npm run build    # 构建

# 关键约定
- 使用 TypeScript 严格模式
- 组件文件用 PascalCase
- API 路由放在 src/routes/

使用 `.gitignore` 风格的上下文过滤

Claude Code 会自动忽略 .gitignore 中的文件和二进制文件，不会将它们加载到上下文中。善用这个特性减少无关文件进入上下文。

1.5 上下文状态查看

你可以通过以下方式了解当前上下文使用情况：

Claude 在每次响应后会显示 token 使用统计（部分版本）
观察响应速度：明显变慢 → 可能需要 /compact
如果 Claude 开始"忘记"本轮对话中你说过的重要信息 → 上下文可能已经滚动或压缩过

2. Memory 记忆管理

2.1 三层记忆体系

Claude Code 的记忆系统分为三个层次：

层次	位置	作用域	加载时机
项目级 CLAUDE.md	`<project>/CLAUDE.md`	当前项目	每次会话启动
项目级 MEMORY.md	`<project>/.claude/MEMORY.md`	当前项目	会话中可按需检索
用户级 MEMORY.md	`~/.claude/MEMORY.md`	所有项目	会话中可按需检索

2.2 CLAUDE.md —— 项目宪法

CLAUDE.md 是最重要的记忆载体，它在每次会话初始化时完整加载到上下文中。

应该包含的内容：

# 项目名称

## 概述
这是一个 xxx 项目，用于 xxx。技术栈：React + TypeScript + Node.js。

## 构建与运行
```bash
npm install          # 安装依赖
npm run dev          # 启动开发服务器（端口 3000）
npm test             # 运行单元测试
npm run test:e2e     # 运行端到端测试
npm run build        # 生产构建

项目结构

src/components/ - React 组件
src/pages/ - 页面路由
src/api/ - API 调用层
src/utils/ - 工具函数

编码规范

组件使用函数式组件 + Hooks
状态管理使用 Zustand
API 请求统一走 src/api/client.ts
使用 Tailwind CSS，不要自行写 CSS 文件

重要约定

不要直接修改 src/generated/，那是自动生成的
环境变量通过 .env.example 声明
PR 之前运行 npm run lint && npm test


**创建方式**：
- 手动创建：直接编写 `.md` 文件放在项目根目录
- `/init` 命令：交互式引导创建 CLAUDE.md

**最佳实践**：
- ✅ 保持简短（建议不超过 200 行），信息密度高
- ✅ 优先写"约定"而非"文档"——告诉 Claude **怎么做**而非**是什么**
- ✅ 定期更新——项目演进后及时同步
- ❌ 不要把整个 README 复制进去
- ❌ 不要写 Claude 可以从代码中自动推断的信息

### 2.3 Memory 文件 —— 持久化记忆

Claude Code 支持将**单个事实或偏好**存储为独立的记忆文件。

**文件结构**：
```markdown
---
name: prefer-tabs-over-spaces
description: 用户偏好使用 Tab 缩进
metadata:
  type: user
---

用户在所有项目中使用 Tab 而非空格进行缩进。
**Why:** 用户认为 Tab 更灵活，每个开发者可以自行设置宽度。
**How to apply:** 所有代码编辑使用 Tab 缩进，宽度为 4。

记忆类型：

类型	用途
`user`	用户身份、角色、偏好
`feedback`	用户给出的纠正和反馈
`project`	项目目标、约束、非代码事实
`reference`	外部资源链接

关联记忆：使用 [[slug-name]] 语法关联相关的记忆文件。

关键命令：

直接告诉 Claude 记住某事："记住我使用 pnpm 而非 npm"
Claude 会自动创建/更新对应的记忆文件

2.4 记忆管理原则

不存代码能推导的信息：项目结构、git 历史、代码内容不应放入记忆
不存仅限本次对话的信息：只在本次对话相关的临时事实不需要持久化
及时更新：偏好改变时告知 Claude 更新记忆
定期审查：~/.claude/MEMORY.md 中的内容可能会过时

3. 代码回退管理

3.1 安全检查点策略

在让 Claude 做重大改动之前，务必创建检查点：

# 方案1：Git commit 作为检查点
git add -A && git commit -m "checkpoint: before refactoring auth module"

# 方案2：Git stash（不想 commit 时）
git stash push -m "checkpoint: before claude changes"

# 方案3：创建专用分支
git checkout -b experiment/claude-refactor

3.2 撤销 Claude 的改动

根据改动状态选择不同的回退方式：

# 级别1：文件还未 staged，完全丢弃改动
git checkout -- <file>          # 单个文件
git checkout -- .               # 所有文件
git restore .                   # 现代写法

# 级别2：文件已 staged 但未 commit
git reset HEAD <file>           # 取消暂存
git checkout -- <file>          # 丢弃改动

# 级别3：已 commit 但未 push
git reset --soft HEAD~1         # 保留改动在 working tree
git reset --hard HEAD~1         # 完全丢弃改动

# 级别4：已 push
git revert HEAD                 # 创建反向提交（安全，建议用这个）
git reset --hard HEAD~1 && git push --force  # 强制回退（危险！）

3.3 Git Worktree 隔离

Worktree 允许在独立目录中工作，不影响主工作区：

# 创建隔离工作区
git worktree add ../project-experiment experiment-branch

# 查看所有 worktree
git worktree list

# 在隔离区完成工作后，清理
git worktree remove ../project-experiment

适用场景：

试验性重构
并行处理多个任务
Claude Code 的 /batch 功能底层就是 worktree

3.4 Claude Code 内置的回退机制

对话中的自然撤销

直接告诉 Claude：

"撤销你刚才的改动" —— Claude 会尝试反操作
"恢复到 xxx 之前的状态" —— 指定回退点
"把 xxx 文件恢复到改之前" —— 针对特定文件

备份目录

Claude Code 在 ~/.claude/backups/ 维护了文件备份（如果启用了该功能）。可以在需要时手动恢复。

File History

~/.claude/file-history/ 目录保存了文件修改历史记录。

3.5 安全建议

重要的代码先 commit：这条怎么强调都不过分
在专用分支工作：别在 main 分支上直接试验
定期检查 diff：git diff 看看 Claude 改了什么
理解改动再继续：如果你看不懂某个改动，让 Claude 解释
小步提交：每次小改动后 commit，而不是等所有工作完成

4. 自定义技能开发

4.1 技能系统概述

技能（Skills）是 Claude Code 的扩展机制，分为内置技能和自定义技能。每个技能是一个可以被 /skill-name 调用的功能单元。

4.2 创建自定义技能

方式一：通过 settings.json 注册简单技能

最简单的技能就是一个指令模板：

{
  "skills": {
    "test": "Run the project tests. Use: npm test",
    "deploy-staging": "Deploy to staging. Steps: 1) npm run build 2) npm run deploy:staging 3) Verify at staging.example.com"
  }
}

配置在：

项目级：<project>/.claude/settings.local.json
用户级：~/.claude/settings.json

方式二：通过插件目录创建技能

在 ~/.claude/plugins/ 下创建技能文件：

~/.claude/plugins/
└── my-skill/
    └── skill.md          # 技能定义

skill.md 的结构：

---
name: my-skill
description: 运行自定义的 lint 检查并自动修复
---

# my-skill

## 触发条件
当用户输入 `/my-skill` 或提到 "运行 lint 检查" 时触发。

## 执行步骤
1. 运行 `npm run lint` 获取所有 lint 错误
2. 按错误类型分组
3. 对于可自动修复的错误（如 prettier 格式），自动应用修复
4. 对于需要手动判断的错误，逐一向用户确认
5. 修复后再次运行 lint 确认无错误

4.3 Hooks 钩子系统

Hooks 允许在特定事件前后自动执行脚本。

支持的 Hook 类型


Hook	触发时机
`pre-command`	执行任意命令之前
`post-command`	执行任意命令之后
`on-start`	Claude Code 会话启动时
`on-complete`	Claude Code 工作完成时
`pre-edit`	编辑文件之前
`post-edit`	编辑文件之后

配置示例

{
  "hooks": {
    "pre-command": {
      "command": "echo 'Claude 即将执行命令'",
      "description": "记录所有即将执行的命令"
    },
    "post-command": {
      "command": "./scripts/check-breaking-changes.sh",
      "description": "检查是否引入了破坏性变更"
    },
    "on-start": {
      "command": "git fetch --all",
      "description": "启动时拉取最新远程分支"
    }
  }
}

Hook 脚本可以访问的环境变量


变量	说明
`CLAUDE_EVENT_TYPE`	事件类型（pre-command / post-command 等）
`CLAUDE_COMMAND`	将要执行或已执行的命令
`CLAUDE_FILE_PATH`	正在编辑的文件路径
`CLAUDE_WORKING_DIR`	当前工作目录

4.4 权限管理

通过 settings.json 精细化控制 Claude 的操作权限：

{
  "permissions": {
    "allow": [
      "npm test",
      "npm run lint",
      "git status",
      "git diff"
    ],
    "allow-dry-run": [
      "rm -rf",
      "git push"
    ],
    "deny": [
      "rm -rf /",
      "git push --force origin main"
    ]
  }
}

权限级别：

allow：无需确认直接执行
allow-dry-run：先展示计划，需要确认才执行
ask：每次询问（默认）
deny：完全禁止

使用 /fewer-permission-prompts 技能可以自动分析你的使用记录并生成合理的权限配置。

5. 代码审查

5.1 内置审查命令概览


命令	用途	审查范围
`/code-review`	代码质量审查	当前工作区 diff
`/review`	PR 审查	指定的 Pull Request
`/verify`	手动验证改动	实际运行应用确认功能
`/security-review`	安全审查	当前分支变更

5.2 `/code-review` 详解

/code-review            # 默认审查（中等深度）
/code-review --fix      # 审查并自动修复发现的问题
/code-review --comment  # 审查并将发现发布为 PR 内联评论

审查维度：

🐛 正确性 Bug：逻辑错误、边界情况遗漏、空值处理
🔒 安全性：注入漏洞、敏感信息泄露、权限问题
♻️ 代码复用：重复代码、可以简化的逻辑
📐 代码风格：命名规范、代码结构、可读性
⚡ 性能：不必要的计算、内存泄漏、异步处理

Effort 级别：


级别	深度	耗时	适用场景
`low`	快速扫描	少	小改动、格式修复
`medium`	标准审查	中	常规 PR
`high`	深度分析	多	核心逻辑、安全敏感代码
`xhigh`/`max`	全面审查	最多	关键基础设施、安全审计

5.3 `/review` —— PR 审查

/review <PR_URL>

工作原理：

检出 PR 分支
分析完整 diff
生成结构化审查报告：

## Code Review Summary

### Critical Issues
- [file:line] 未处理的 Promise rejection 可能导致未捕获异常

### Suggestions
- [file:line] 考虑将重复的 fetch 逻辑提取为自定义 Hook
- [file:line] 建议使用 useMemo 缓存计算结果

### Praise
- 错误边界处理得很好
- 测试覆盖率充分

5.4 `/verify` —— 手动验证

/verify

适用于需要实际运行应用来确认改动生效的场景：

前端 UI 改动：启动开发服务器，在浏览器中检查
API 改动：发送实际请求验证响应
CLI 工具：运行命令行确认输出

5.5 `/security-review` —— 安全审查

专门针对安全问题的深度审查：

SQL 注入、XSS、CSRF
敏感信息（API Key、密码）是否被提交
依赖项是否有已知漏洞
认证授权逻辑是否正确

5.6 最佳实践

commit 前审查：养成 /code-review 再 commit 的习惯
分级审查：普通改动 medium，核心模块 high 或 max
结合测试：先让 Claude 写测试，再用 /verify 确认通过
大 PR 分文件审查：一次改 20 个文件则分多次审查
审查后不要盲从：Claude 的审查建议需要人工判断是否采纳

6. 实用技巧与进阶功能

6.1 对话管理技巧

任务分解

长任务拆分为多个短对话，每个对话聚焦一个子任务：

❌ "重构整个认证模块、数据层、UI 层"
✅ 对话1："重构认证模块的 token 管理"
   对话2："重构认证的数据层查询"
   对话3："重构登录和注册页面 UI"

每次对话结束后，在下一个对话开始时提供上下文摘要。

精确引用

引用文件时使用 file.ts:42 格式，Claude 会直接定位到具体行：

请查看 src/api/auth.ts:120-150 的 token 刷新逻辑

利用 Plan Mode

在复杂任务开始前进入 Plan Mode 确认方案：

这个任务比较复杂，请先进入 Plan Mode 设计方案。

Plan Mode 中 Claude 会探索代码库、设计实施路径，在得到你的确认后再动手写代码。这避免了返工。

6.2 子代理（Sub-agent）并行处理

Claude Code 可以派生子代理并行处理独立任务：

适用场景：

同时研究多个技术方案
并行审查多个文件
同时搜索不同维度的信息

示例提示：

请同时做三件事：
1. 审查 src/api/ 下所有文件的错误处理
2. 审查 src/components/ 下所有组件的性能
3. 审查 src/utils/ 下所有工具函数的测试覆盖

Claude 会自动决定哪些任务可以并行处理。

6.3 Keyboard Shortcuts


快捷键	功能
`Ctrl+C`	取消当前操作 / 中断 Claude 输出
`Ctrl+D`	退出会话
`↑/↓`	浏览命令历史
`Ctrl+L`	清屏
`Ctrl+R`	搜索命令历史
`Enter`	发送消息
`Shift+Enter`	换行（多行输入模式）

可通过 ~/.claude/keybindings.json 自定义。

6.4 IDE 集成

VS Code 扩展

安装 Claude Code VS Code 扩展后：

在编辑器内直接与 Claude 对话
选中代码后 Cmd+Shift+L 发送给 Claude
内联编辑建议
文件 diff 预览

JetBrains 插件

支持 IntelliJ IDEA、WebStorm、PyCharm 等。

6.5 MCP 服务器扩展

MCP（Model Context Protocol）允许为 Claude Code 添加额外工具：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

常见的 MCP 服务器：数据库查询、文件系统操作、API 集成、第三方服务。

6.6 Token 预算与成本控制

设置 Effort Level

# 命令行参数
claude --effort low     # 快速、省 token
claude --effort medium  # 默认
claude --effort high    # 深度分析

# 或在 settings.json 中
{
  "effortLevel": "high"
}

理解 Effort Level

low：快速回答，较少工具调用，适合简单问题
medium：标准分析深度，适合日常开发
high：深度分析，更多验证步骤，适合复杂重构
xhigh/max：最大深度，多次交叉验证，适合安全审计等关键任务

6.7 环境变量速查


变量	说明
`ANTHROPIC_BASE_URL`	自定义 API 端点（如使用代理）
`ANTHROPIC_AUTH_TOKEN`	API 认证 Token
`ANTHROPIC_MODEL`	默认模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	轻量任务使用的模型
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	设为 `1` 禁用遥测
`CLAUDE_CODE_EFFORT_LEVEL`	全局 Effort Level

6.8 管道和脚本集成

Claude Code 支持管道输入：

# 将文件内容管道给 Claude
cat error.log | claude "分析这个错误日志"

# 将 git diff 管道给 Claude
git diff | claude "审查这些改动"

# 非交互式执行
claude -p "解释 src/main.ts 的架构" > analysis.md

6.9 回话管理

# 恢复上一次会话
claude --resume

# 列出最近的会话
claude --list-sessions

# 指定会话名称
claude --session "debug-auth-issue"

6.10 不太为人所知但非常实用的功能

1. `/loop` 定时循环

/loop 5m /code-review
/loop 10m "检查 CI 状态"

定期自动执行指定任务。适合监控场景。

2. `/statusline` 状态栏

/statusline

在终端底部显示持久状态栏：当前任务、token 用量、活跃模型。

3. 非交互模式

# 一次性问答
claude -p "这个项目的入口文件是什么？"

# 输出到文件
claude -p "生成 API 文档" > api-docs.md

4. 文件搜索效率

不要用 cat/head/tail 等 shell 命令查看文件，直接让 Claude 读：

❌ "运行 cat src/utils.ts"
✅ "查看 src/utils.ts"

Claude 有专门的 Read 工具，比 shell 命令更高效。

5. 利用 `!` 前缀在对话中运行命令

在对话中输入 !<command> 会直接在当前会话执行：

!git status
!npm test

6. Debug 模式

/debug

开启详细日志，用于排查权限问题、连接问题等。

7. Team Onboarding

/team-onboarding

根据你的使用模式生成团队上手指南。

7. 配置参考速查

7.1 配置文件位置


文件	作用域	优先级
`<project>/.claude/settings.local.json`	项目	最高
`~/.claude/settings.json`	用户	中
环境变量	会话	最低

7.2 settings.json 完整示例

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "effortLevel": "high",
  "theme": "dark",
  "permissions": {
    "allow": [
      "npm test",
      "npm run lint",
      "git status",
      "git diff",
      "git log"
    ],
    "deny": [
      "rm -rf /",
      "git push --force origin main"
    ]
  },
  "hooks": {
    "pre-command": {
      "command": "echo '[Claude] 即将执行命令'"
    }
  },
  "skills": {
    "deploy-staging": "Deploy current branch to staging. Steps: npm run build && npm run deploy:staging"
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"]
    }
  }
}

7.3 目录结构总览

~/.claude/
├── settings.json          # 用户全局配置
├── MEMORY.md              # 用户级记忆
├── memory/                # 分文件的记忆存储
├── history.jsonl          # 命令历史
├── keybindings.json       # 自定义快捷键
├── plugins/               # 自定义技能插件
├── backups/               # 文件备份
├── file-history/          # 文件修改历史
├── sessions/              # 会话存档
├── projects/              # 项目级记忆（按项目存储）
└── plans/                 # Plan Mode 保存的计划

<project>/
├── CLAUDE.md              # 项目级记忆（会话启动时加载）
└── .claude/
    ├── settings.local.json # 项目级配置
    └── MEMORY.md           # 项目级记忆

附录：典型工作流

A. 新功能开发流程

1. git checkout -b feature/new-login
2. git commit -m "checkpoint: before new login feature"  # 创建检查点
3. 在 Claude Code 中描述需求
4. Claude 进入 Plan Mode 设计方案
5. 确认方案后 Claude 开始编码
6. /code-review 审查改动
7. /verify 手动验证功能
8. git commit -m "feat: new login flow"

B. Bug 修复流程

1. git checkout -b fix/login-timeout
2. 向 Claude 描述 Bug 现象和复现步骤
3. Claude 定位问题并修复
4. /code-review --fix 审查并自动修复小问题
5. npm test 确认无回归
6. git commit

C. 代码审查流程

1. 完成本地改动后
2. /code-review（审查工作区 diff）
3. 根据建议修改
4. /verify 验证
5. 提交 PR
6. /review <PR_URL>（可选，让 Claude 再审查一遍 PR）

注意：本文档基于 Claude Code 截至 2026 年 7 月的功能编写。Claude Code 迭代频繁，建议定期查阅官方文档获取最新信息。如果你使用了第三方 API 代理（如 DeepSeek），部分功能的行为可能与官方版本存在差异。

Vibe Coding 项目开发流程

Vibe Coding 项目开发流程

1. 跟 AI 聊想法（Idea）明确目标

2. 需求分析与 PRD

3. 明确 MVP 与项目范围 Scope

4. 确定技术栈

5. 进行架构设计

6. 整理项目文档

7. 拆分 Task

8. 初始化 Git

9. Coding → Test → Review → Commit

Coding

Test Strategy 与自动化验证

Review

Commit

10. 更新项目上下文

11. 进入下一 Task

12. 沉淀学习文档

13.最终流程

Claude Code 使用指南

目录

1. 上下文压缩控制

1.1 核心概念

1.2 /compact 命令

1.3 自动压缩（Auto-Compact）

1.4 减少上下文消耗的技巧

控制输出量

CLAUDE.md 精简

使用 .gitignore 风格的上下文过滤

1.5 上下文状态查看

2. Memory 记忆管理

2.1 三层记忆体系

2.2 CLAUDE.md —— 项目宪法

项目结构

编码规范

重要约定

2.4 记忆管理原则

3. 代码回退管理

3.1 安全检查点策略

3.2 撤销 Claude 的改动

3.3 Git Worktree 隔离

3.4 Claude Code 内置的回退机制

对话中的自然撤销

备份目录

File History

3.5 安全建议

4. 自定义技能开发

4.1 技能系统概述

4.2 创建自定义技能

方式一：通过 settings.json 注册简单技能

方式二：通过插件目录创建技能

4.3 Hooks 钩子系统

支持的 Hook 类型

配置示例

Hook 脚本可以访问的环境变量

4.4 权限管理

5. 代码审查

5.1 内置审查命令概览

5.2 /code-review 详解

5.3 /review —— PR 审查

5.4 /verify —— 手动验证

5.5 /security-review —— 安全审查

5.6 最佳实践

6. 实用技巧与进阶功能

6.1 对话管理技巧

任务分解

精确引用

利用 Plan Mode

6.2 子代理（Sub-agent）并行处理

6.3 Keyboard Shortcuts

6.4 IDE 集成

VS Code 扩展

JetBrains 插件

6.5 MCP 服务器扩展

6.6 Token 预算与成本控制

设置 Effort Level

理解 Effort Level

6.7 环境变量速查

6.8 管道和脚本集成

6.9 回话管理

1.2 `/compact` 命令

使用 `.gitignore` 风格的上下文过滤

5.2 `/code-review` 详解

5.3 `/review` —— PR 审查

5.4 `/verify` —— 手动验证

5.5 `/security-review` —— 安全审查

1. `/loop` 定时循环

2. `/statusline` 状态栏

5. 利用 `!` 前缀在对话中运行命令