受控式文档驱动 Vibe Coding 方案设计

方案概述

本方案针对当前企业级 AI 辅助开发(Vibe Coding)过程中存在的不可控､无标准､难维护､迭代低效等问题,构建一套轻量化､可落地､可标准化的 Vibe Coding 执行体系｡核心是通过"文档固化业务规则､分级管控开发权限､分步落地编码执行､沉淀可复用资产",实现 AI 辅助开发的效率提升与质量可控,降低团队协作成本与技术债累积｡

方案核心目标

解决传统 Vibe Coding 野蛮生成､逻辑跑偏的问题,实现 AI 开发可控化;
建立标准化开发流程与文档规范,统一团队开发口径,降低协作成本;
平衡 AI 提效与代码质量,减少调试成本,提升研发交付效率;
沉淀业务与技术资产,实现需求迭代可追溯､新人上手可快速衔接;
隔离开发风险,明确 AI 与人工的职责边界,保障系统稳定性｡

一､当前 Vibe Coding 痛点分析

结合企业实际研发场景,当前 Vibe Coding 应用过程中存在以下核心痛点,严重影响研发效率和代码质量:

逻辑不可控,调试成本高:直接将需求丢给 AI 生成全量代码,AI 易脑补业务逻辑､遗漏边界场景､断裂业务流程,导致生成代码无法直接使用,调试时间比重写代码更长,违背 AI 提效初衷｡
产出无标准,维护难度大:无统一编码与文档规范,AI 每次生成的代码风格､结构､异常处理方式不一致,团队协作时需反复适配,长期维护易出现代码混乱､难以追溯的问题｡
业务无沉淀,需求迭代困难:需求迭代时,AI 无法记忆历史业务规则与开发逻辑,需开发人员反复重新描述业务背景,易出现理解偏差,导致迭代返工率高､周期长｡
风险无隔离,线上隐患突出:未明确 AI 开发权限边界,AI 自主编写事务控制､并发处理､权限校验､批量数据操作等高风险逻辑,易造成阴性线上故障｡
文档与代码脱节,资产无法复用:缺乏结构化设计文档,开发过程中"代码即设计",业务规则､数据结构仅存在于代码中,或文档与实际代码逻辑不一致造成业务理解出现偏差,新人接手困难,业务资产无法沉淀与复用,技术债快速累积｡

二､方案核心思想

本方案核心思想为｢轻量化文档驱动 + 人主导架构 + AI 辅助方案设计 + AI 执行落地 + 分级风险管控 + 迭代可沉淀｣,彻底摒弃"野蛮 Vibe"与"过度管控"两个极端,实现 AI 辅助开发的标准化与可控化｡

核心逻辑如下:

人定规则,把控核心:开发人员主导需求理解､业务流程梳理､功能边界划分､步骤编排､风险判断,负责定义业务规则与开发标准,守住高风险逻辑底线｡
AI 执行,提升效率:AI 仅作为文档辅助编写和编码执行层,严格按照既定文档､步骤､规范实现代码,不自由发挥､不脑补业务逻辑,专注于基础编码､参数校验､结果封装等机械性工作｡
文档先行,固化标准:通过 4 份轻量化 Markdown 文档,固化业务规则､功能清单､开发步骤､数据结构,作为 AI 开发､人工审核､需求迭代的唯一标准(4份文档职责边界清晰,无内容重叠)｡
分步开发,控制粒度:将功能拆解为"模块￫功能点￫有序任务步骤"的黄金粒度,AI 按照既定步骤分布开发,兼顾开发效率与逻辑可控性｡
契约分层,轻量化落地:数据契约不做前期过度设计,但是前期必须定义表结构,后期实体类､DTO､枚举等细节待代码落地后,由 AI 反向提炼,增量更新文档,减少前期设计成本,确保文档与代码一致｡
迭代闭环,沉淀资产:所有需求迭代遵循"文档说明￫代码开发￫契约同步"的闭环,不删除历史内容､不全局重写文档,实现业务与技术资产的长期沉淀｡

三､方案核心优势(企业落地价值)

可控性强,降低调试成本:AI 所有开发行为均基于标准化文档,无自由发挥空间,代码逻辑贴合业务需求,大幅减少调试返工,提升交付效率｡
标准化程度高,协作成本低:统一文档规范､开发流程､AI 产出标准,4份文档职责清晰无重叠,团队成员无需反复沟通编码风格与业务规则,新人可快速上手,跨团队协作无障碍｡
落地成本极低,无需额外投入:无需引入复杂工具､搭建专用脚手架,仅通过 4 份轻量化 MD 文档与 AI 工具(如 Claude)和文档专属编写skills 即可落地,不增加团队额外工作负担｡
迭代可持续,技术债可控:业务规则与数据结构永久沉淀在文档中,需求迭代时仅需增量更新,避免重复开发与逻辑混乱,长期维护成本大幅降低｡
风险可控,保障系统稳定:明确 AI 界限,高风险逻辑由人工兜底,从源头规避线上故障,适配企业级系统的稳定性要求｡
资产可复用,提升长期效率:文档沉淀的业务流程､功能步骤､数据契约可跨项目复用,后续同类需求开发可直接参考,进一步提升研发效率｡

四､核心文档体系

所有文档统一存放于项目 `/docs` 目录,每个业务模块仅维护 4 份固定文档,持续迭代更新,不新增冗余文档,确保轻量化与可维护性;4份文档职责边界清晰,内容少量重叠,各负其责形成闭环支撑｡

4.1 {module}-flow.md(业务流程文档)

作用

定义模块全局主流程､分支场景､流转逻辑,作为 AI 理解业务的核心依据,避免 AI 脑补逻辑;核心聚焦"业务怎么流转",不涉及功能实现与开发细节｡

必含内容

模块概述:明确模块核心价值､业务范围(一句话概括,不展开细节),避免开发范围跑偏;
前置依赖:上游关联模块､外部接口,明确开发前置条件;
主业务流程:按执行顺序,步骤化描述核心业务流转逻辑,搭配Mermaid流程图更佳,不冗余､不遗漏关键节点;
分支业务流程:枚举所有分支场景(如正常流程､异常流程､特殊场景),明确分支触发条件与流转逻辑;

禁止内容

不列出具体功能点､不描述功能的输入输出､不涉及开发实现细节与数据结构｡

4.2 {module}-feature_list.md(功能清单文档)

作用

承上启下的核心衔接作用,向上承接整体业务流程,将流程节点落地为可执行的功能清单;向下支撑任务拆解,为全流程开发落地与后续迭代维护提供统一､可追溯的基准依据;核心聚焦"系统要做什么",不涉及流程细节与开发实现｡

必含内容

功能总览表:包含功能名称､核心目标､依赖流程节点(引用{module}-flow.md对应节点);
功能详情:每个功能的具体描述､触发条件､业务边界､非功能需求(性能､安全等),明确功能开发范围与风险点;

禁止内容

不描述具体业务流转步骤(仅引用{module}-flow.md即可)､不涉及开发执行步骤､不涉及数据结构｡

4.3 {module}-feature_task.md(任务步骤文档,AI 开发核心指导文档)

作用

AI 编码的直接依据,将功能清单中的每个功能拆解为有序､可执行的任务步骤,控制 AI 开发粒度,确保逻辑可控;核心聚焦"代码怎么落地",不重复描述业务背景与流程细节｡

必含内容

有序任务步骤:严格按业务执行顺序拆解细分任务,每一步清晰定义执行目标､核心实现逻辑､任务难度、各类边界场景适配规则,确保流程闭环无遗漏;
数据关联引用:精简标注当前步骤涉及的数据表(引用{module}-feature_data.md的表名),关联引用数据契约文档,不重复罗列字段详情,保持文档简洁性与一致性;
引用依据:每步任务需明确引用{module}-flow.md的对应流程节点与{module}-feature_list.md的对应功能点,确保开发不偏离业务与功能要求｡

禁止内容

不重复大段描述业务背景与流程细节(仅引用相关文档)､不罗列完整字段详情(仅引用表名)､不涉及数据结构的具体定义｡

4.4 {module}-feature_data.md(数据契约文档)

作用

统一数据口径,沉淀数据表､实体､DTO､枚举､字段约束等数据规则,确保代码与数据结构一致,避免数据错乱;核心聚焦"数据怎么存",前期仅定义核心表结构,其余细节后置生成,兼顾可控性与开发效率｡

必含内容(前置定义,编码前完成人工审核)

数据库表结构:创表ddl语句,明确表名､表注释､字段名､字段类型､主键/外键/索引､非空约束､默认值,以及表关联关系;

后置增量生成内容(编码完成后,AI反向提炼更新)

核心枚举:枚举名称､枚举值､释义､使用场景;
数据转换规则:字段映射､默认值､脱敏规则､状态转换逻辑;
实体类/DO定义､DTO/VO定义(入参､出参);

禁止内容

不涉及业务流程､功能逻辑､开发步骤,不提前定义实体类､DTO等细节内容｡

4.5 项目代码风格规范（统一AI的写作风格）

作用

统一全项目编码标准，约束 AI 与人工代码格式，保证代码可读性、一致性，降低维护成本，适配团队协作与 AI 自动化开发。

必含规范

基础格式：统一缩进、换行、空格规则，禁用无意义空行，代码层级清晰；
命名规范：类名、方法名、变量名、常量名遵循统一命名规则，望文知义，禁用拼音、无意义缩写；
注释规范：核心类、公共方法、复杂逻辑必须添加注释，字段 / 枚举标注业务含义，简洁无冗余；
代码结构：按分层架构编写代码（控制层 / 业务层 / 数据层），方法单一职责，禁止超大方法、冗余代码；
异常规范：统一异常处理格式，禁止裸捕异常、空 catch 块，异常信息包含业务场景描述；
校验规范：入参必填校验、格式校验统一实现。

示例

复制代码

# 代码规范和风格指南

## 设计原则

### 高内聚低耦合
这是本项目最重要的代码设计原则

**高内聚**：
- 一个类或方法应该专注于单一职责
- 相关的功能应该放在一起
- 内部元素之间紧密关联

**低耦合**：
- 模块之间的依赖应该尽可能少
- 通过接口或抽象来解耦

**如何实现**：
- **识别依赖关系**：明确哪些类/方法依赖哪些
- **封装变化点**：将容易变化的部分封装起来
- **依赖倒置**：依赖抽象而不是具体实现
- **设计模式**：接口不满足的情况下考虑设计模式，例如常用设计模式（单例模式，工厂模式，建造者模式，适配器模式，代理模式 ，策略模式，模板方法模式 等等）
- **单一职责**：每个类/方法只做一件事


## 编码规范

### Java 代码规范

#### 方法注释强制要求
每个public方法必须包含完整的JavaDoc注释，包括：
- 方法功能描述
- 参数说明（每个参数）
- 返回值说明
- 异常说明（如果有）

#### 命名规范
- 类名：PascalCase（如DocumentService）
- 方法名：camelCase（如processDocument）
- 常量名：UPPER_SNAKE_CASE（如MAX_FILE_SIZE）
- 包名：全部小写，用点分隔（如com.example.viberag）

#### 异常处理
- 捕获具体异常
- 重要异常必须记录日志
- 向上层抛出异常时提供有意义的错误信息


## 风格要求

### 代码格式
- 使用IDE自动格式化（如IntelliJ IDEA或VSCode的Prettier）
- 缩进：4空格
- 行宽：100字符
- 空行：逻辑块之间使用空行分隔

### 注释规范
- 复杂的业务逻辑必须添加注释
- 注释使用简体中文
- 不要用注释解释显而易见的代码
- 注释应说明"为什么"而不是"是什么"

## 代码审查要点

1. **功能完整性**：代码实现是否满足需求
2. **代码规范**：是否符合以上所有规范
3. **注释完整**：方法是否都有完整注释
4. **异常处理**：是否有合理的异常处理
5. **性能考虑**：是否有性能问题
6. **安全性**：是否有安全漏洞
7. **可维护性**：代码是否易于理解和维护遵循**高内聚低耦合**原则

4.6 项目技术栈（统一项目技术约束）

作用

明确项目全链路技术选型，统一开发环境、框架与工具版本，避免技术碎片化，为 AI 编码提供固定技术依据。

必含内容

后端技术栈：开发语言、核心框架、ORM 框架、工具类库；
前端技术栈：框架、UI 组件库、构建工具；
数据存储：关系型数据库、缓存中间件、消息队列（如有）；
通用组件：接口规范、日志组件、工具包、部署环境；
规范约束：统一依赖版本、开发环境、编码 SDK 版本。

示例

复制代码

# 技术栈和依赖版本

## 后端核心框架

| 组件         | 版本      | 用途     |
|------------|---------|--------|
| Spring Boot | 3.5.11  | 应用框架   |
| Java       | 21      | 开发语言   |
| Maven      | 3.8+    | 构建工具   |
| MyBatis    | 3.0.3   | ORM框架   |
| RedisTemplate   | 无指定   | redis常规操作   |
| Redission      | 无指定   | 并发下的redis分布式锁增强     |


## 前端核心框架
| 组件         | 版本      | 用途     |
| vue        | 3       | 前端框架   |
| element-plus | 与vue3适配 | 前端UI框架 |
| TypeScript | 与vue3适配 | 前端ts |
| Composition | 与vue3适配 | 逻辑复用 |
| Pinia | 与vue3适配 | 状态管理 |

## Spring AI 组件

| 组件 | 版本 | 用途 |
|------|------|------|
| spring-ai-core | 1.0.0-M6 | Spring AI核心 |
| spring-ai-starter-vector-store-milvus | 1.1.1 | Milvus 向量数据库集成 |

## LangChain4j 组件

| 组件 | 版本 | 用途 |
|------|------|------|
| langchain4j-spring-boot-starter | 1.11.0 | LangChain4j Spring Boot集成 |
| langchain4j-open-ai | 1.11.0 | LangChain4j OpenAI支持 |


## 数据存储

| 组件     | 版本 | 用途     |
|--------|------|--------|
| MySQL  | 8.0 | 元数据存储  |
| Milvus | 2.4.x | 向量数据库  |
| Elasticsearch | 8.11.3 | 元数据库   |
| Redis  | 无指定 | 缓存     |
| MyBatis| 3.0.3 | ORM框架   |
| Spring Data Commons | 自动管理 | 分页支持 |

---

## 开发工具库

| 组件 | 版本 | 用途 |
|------|------|------|
| lombok | 1.18.30 | 简化 Java 代码 |
| hutool-all | 5.8.23 | 工具类库 |
| spring-boot-starter-actuator | 3.5.13 | 应用监控 |
| spring-boot-starter-validation | 3.5.13 | 参数校验 |

五､方案完整实现步骤

5.1 新需求开发流程(核心流程)

阶段 1:需求梳理与规则定义(开发人员主导,AI 辅助)
- 吃透业务需求,梳理主流程､分支流程､异常场景､边界规则;
- 划分功能点,明确每个功能的依赖关系;
阶段 2:前置文档生成与审核(AI 编写 + 人工审核)
- AI 基于需求梳理结果,生成 {module}-flow.md､ {module}-feature_list.md､ {module}-feature_task.md 三份前置文档,以及{module}-feature_data.md的前置表结构内容;
- 开发人员审核文档,重点校验业务流程､功能边界､步骤逻辑､风险等级划分､表结构合理性的准确性,修改后定稿｡
阶段 3:AI 分步编码执行(AI 执行 + 人工管控)
- AI 严格按照 {module}-feature_task.md 的步骤顺序,一次开发 1~3 个内聚步骤,遵循编码规范;
- 低风险步骤(如参数校验､结果封装、简单的curd):AI 全权开发;
- 中风险步骤(如普通业务逻辑):AI 开发后,人工核对步骤逻辑与业务规则;
- 高风险步骤(如事务､涉及多个模块、高度复杂逻辑):开启plan模式，人工全程监视审查AI编写的代码｡
阶段 4:数据契约后置生成与审核(AI 提炼 + 人工审核)
- 单个功能编码完成后,AI 扫描当前功能所有代码,反向提炼实体类､DTO､枚举､字段约束等信息;
- AI 以增量方式更新{module}-feature_data.md,保留前置定义的表结构内容,仅补充当前功能相关的后置数据规则;
- 开发人员审核数据契约,确保与代码一致,补充必要的约束说明｡
阶段 5:轻量化审核与提交
- 完成代码审核,重点校验高风险逻辑､数据一致性､业务规则落地情况;
- 将 4 份文档与代码同步提交至版本管理工具(如 Git),确保文档与代码版本一致｡

5.2 需求迭代流程(闭环维护)

阶段 1:迭代范围划定
- 明确迭代需求:新增/ 修改/ 废弃的功能､业务规则变更范围,以及需调整的表结构;
- 定位需更新的文档与代码模块,避免无差别修改｡
阶段 2:文档增量更新
- AI 读取存量 4 份文档,仅增量更新对应模块(新增功能追加区块､修改功能编辑对应片段､废弃功能标注状态;表结构需修改时,更新{module}-feature_data.md的前置内容);
- 人工审核更新后的文档,确保变更符合业务规则,不影响原有稳定功能,表结构修改合理｡
阶段 3:代码迭代开发(AI 执行 + 人工管控)
- AI 按照更新后的{module}-feature_task.md,迭代修改对应代码,不改动无关逻辑;
- 人工把控高风险逻辑的迭代,确保变更后系统稳定性｡
阶段 4:数据契约同步更新
- AI 扫描迭代后的代码,增量更新{module}-feature_data.md的后置内容,同步修改字段､枚举､约束等变更内容;
- 人工审核,确保数据契约(前置表结构+后置细节)与迭代后代码一致｡
阶段 5:审核提交与测试
- 完成代码与文档的最终审核,执行单元测试､集成测试;
- 同步提交迭代后的代码与文档,形成迭代闭环｡

六､AI 工具落地支撑

本方案依托 Claude 工具实现全流程标准化落地,无需额外引入第三方工具,通过自定义专属 Skill 统一固化产出规范,减少人工重复约束与沟通成本,保障交付一致性｡

文件放置规则

文件存放规则说明：

Claude 生成的 .md 必须按照以下内容放入指定的目录

|--------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| 文件类型 | 目标目录 | 备注 |
| 项目整体CLAUDE说明 | CLAUDE.md | claude项目级行为约束，项目的整体结构和指明文档放置规则等 |
| 编码规范 | .claude/rules/*.md | 项目的技术栈，编码风格，命名规范等 code-standards.md（项目代码风格规范） tech-stack.md（项目技术栈） |
| 自定义技能 | .claude/skills/<name>/SKILL.md | 自定义的工作流程skill，例如module-documents，module-tasks |
| 业务文档 | docs/module/{module}-xxx.md | 项目沉淀的业务描述 {module}-flow.md（业务流程文档） {module}-feature-list.md（功能清单文档） {module}-feature-task.md（任务步骤文档，AI开发核心指导文档） {module}-feature-data.md（数据契约文档） |
| 产品需求 | docs/{module}-xxx-prd.md | 需求文档 |
| 功能状态 | docs/project-status-xxx.md | 需求实现进度（个人保存，方便AI继续工作） |
| 审查报告 | docs/temp/xxx.md | 代码审查报告文件（个人保存，完成后清理） |
| superpowers | docs/superpowers/xxx/xxx.md | superpowers工具生成的设计初稿（个人保存，完成后清理） |

辅助能力：superpowers:brainstorming（需求前期和代码编写阶段专属使用）

安装并启用 superpowers 能力,需求初期阶段专属调用superpowers:brainstorming,基于原始 PRD 需求文档,快速梳理业务脉络,产出文档初稿;

- 依托头脑风暴能力,全面拆解业务场景､分支流程､异常边界､功能范围;
- 初步梳理输出 {module}-flow.md 业务流程初稿､{module}-feature_list.md 功能清单初稿;

参考提示词

/superpowers:brainstorming @docs/prd/document-chunking-agent-prd.md 根据这个需求文档给我规划下业务流程文档和功能清单文档的初稿

自定义Skill（module-documents）：业务文档标准化生成与维护规范

根据初稿生成符合企业标准的 {module}-flow.md 业务流程､ {module}-feature_list.md 功能清单(严格遵循文档职责边界,不产生内容重叠);

自定义Skill （module-tasks）：任务步骤文档生成

根据审核后的文档,生成符合企业标准的 {module}-feature_task.md,指导AI 的代码编写(仅引用前置文档,不重复业务背景);

自定义 Skill (module-data):

编码完成后,反向提炼实体类､DTO､枚举等内容,增量更新{module}-feature_data.md的后置部分,不修改前置表结构(除非人工明确要求)｡

七､职责划分

明确开发人员与 AI 的职责边界,确保流程有序执行,责任可追溯，为后续优化提供指导，是人出了问题，还是AI编写出了问题｡

开发人员职责

需求理解､业务流程梳理､功能边界划分､风险等级判断;
文档审核､代码审核,重点把控业务流程准确性､功能边界合理性､表结构规范性､高风险逻辑开发;
定义 AI 开发规则与编码规范,维护文档与代码的一致性,确保4份文档无内容重叠;
迭代范围划定,确保迭代变更符合业务需求,表结构修改合理｡

AI 职责

按规范生成增量更新 4 份文档,严格遵循各文档职责边界,不自由发挥､不产生内容重叠;
按 {module}-feature_task.md 分步实现低､中风险代码,遵循编码规范;
代码自检､格式优化､注释补充,辅助人工完成开发;
编码完成后,反向提炼实体类､DTO､枚举等数据细节,增量更新{module}-feature_data.md的后置部分,不随意修改前置表结构｡

八､方案落地保障

规范培训:组织团队学习本方案的文档规范､执行流程､AI 使用规则,重点明确4份文档的职责边界与内容禁忌,确保全员掌握;
示例参考:提供一套完整的业务模块示例(如员工管理),包含 4 份文档与代码,明确各文档的内容划分,供团队参考;
定期复盘:每季度复盘方案落地情况,优化文档模板､执行流程,适配团队研发节奏,重点检查文档重叠问题与数据契约前后置划分合理性;
版本管控:文档与代码同步提交､同步版本,确保历史可追溯,避免文档与代码脱节,重点保障数据契约前置表结构与代码的一致性｡

九､方案总结

本方案通过"轻量化文档驱动､分级管控､分步执行､迭代闭环"的核心逻辑,彻底解决了传统 Vibe Coding 不可控､难维护､迭代低效的痛点,实现了 AI 辅助开发的标准化与企业级落地｡方案保留4份文档结构,明确各文档职责边界､消除内容重叠,同时采用"数据契约核心表结构前置､其余细节后置"的务实设计,既避免前期过度设计,又守住数据底座可控性｡

方案无需额外投入,落地成本低､可执行性强,既保留了 AI 提效的核心价值,又通过文档沉淀与风险管控,保障了代码质量与系统稳定性,适配企业业务系统长期迭代､团队协作的核心需求,可快速在企业内部推广落地,提升整体研发效率,降低技术债累积｡

附录（以上方案的思路参考）

Vibe Coding 对话工程技巧

迭代式对话的艺术

一、对话工程和提示词工程？

很多朋友把和 AI 交流称为 "写提示词"、或者 "提示词工程"，我之前也是这样的。但如今，随着 AI 对模糊指令的理解能力越来越强，我觉得这个说法其实不够全面，因为它暗示了一种单向的、一次性的交流方式 ------ 你写一个完美的提示词，AI 给你一个完美的答案。

但实际上，Vibe Coding 更像是一场对话。你和 AI 是在一起工作、一起探索、一起完善想法。这个过程是 双向的、迭代的。

举个例子，传统的 提示词思维 是这样的：

"请帮我用 React 和 Tailwind CSS 写一个响应式的导航栏，包含 Logo、菜单项（首页、关于、联系）、搜索框和用户头像，要支持移动端折叠菜单，颜色是深蓝色背景白色文字，Logo 在左边，菜单在中间，用户信息在右边......"

你想要在一句话里把所有需求都说清楚。但往往会遗漏一些细节，或者说得不够准确。

而 对话思维 是这样的：

你：我想做一个导航栏，你能帮我吗？

AI：当然可以。你想用什么技术栈？有什么设计要求吗？

你：我用 React 和 Tailwind CSS。设计上希望简洁专业，深蓝色背景。

AI：好的。导航栏需要包含哪些元素？

你：Logo、几个菜单项、搜索框和用户头像。

AI：明白了。需要支持移动端吗？

你：对，移动端要能折叠成汉堡菜单。

看到区别了吗？

对话思维让你可以逐步明确需求，而不是一开始就要想清楚所有细节。这样更自然，也更容易得到好结果。

对话的好处

使用对话思维有几个明显的好处：

降低认知负担：你不需要一次性想清楚所有细节，可以边聊边想。
更容易发现问题：AI 的提问会帮你发现自己遗漏的地方。
结果更准确：通过多轮交流，AI 能更准确地理解你的需求。
学习效果更好：在对话过程中，你会学到很多新知识和最佳实践。

二、迭代式对话的核心技巧

下面分享几个最重要的对话技巧。

技巧一：从大到小，逐步细化

不要一开始就陷入细节。先从整体开始，然后逐步细化。

比如你想做一个博客系统，不要一上来就说：帮我写一个支持 Markdown、代码高亮、评论、点赞、分类、标签、搜索、RSS 订阅的博客系统。

而是这样开始：

我想做一个简单的博客系统，用户能发布和查看文章
文章需要支持 Markdown 格式
能不能加上代码高亮功能
我还想要一个简单的评论功能

每一步都很小，很容易理解和实现。这样 AI 就不会被复杂的需求搞晕，你也能随时调整方向。

技巧二：具体而非抽象

AI 不擅长理解抽象的概念，但很擅长处理具体的描述。

❌ 不好的例子：做一个好看的按钮

✅ 好的例子：做一个圆角按钮，蓝色背景（#3B82F6），白色文字，padding 上下 12px 左右 24px，鼠标悬停时背景变深蓝色（#2563EB）。

❌ 不好的例子：加一个用户友好的错误提示

✅ 好的例子：当用户输入的邮箱格式不对时，在输入框下方显示红色文字 "请输入有效的邮箱地址"。

描述越具体，AI 就越能准确地实现你的需求。

技巧三：提供参考和示例

你可以通过文字描述或者图片举例来帮助 AI 理解需求。

用文字描述，你可以这样说：

我想要一个类似 GitHub 的个人主页布局：左边是用户信息卡片，右边是活动时间线。
按钮的样式参考 Stripe 的设计：简洁、现代、有微妙的阴影。
表单验证的提示方式参考 Airbnb：实时验证，错误提示在输入框下方。

AI 见过很多网站和应用，你提供的参考能帮它快速理解你想要什么。

更直接的方法是用图片，现在的很多 AI 大模型（比如 Claude、GPT、Gemini）都支持图片理解，你可以：

截图你想要的设计效果，让 AI 照着做
截图出现的 bug 或错误，让 AI 看到具体问题
截图参考网站的布局，让 AI 模仿

比如下面这些提示词：

请参考这个截图的布局来设计我的页面：【上传截图】
我的页面在移动端显示不正常，看这个截图：【上传截图】，应该怎么修复？

一图胜千言，图片能让 AI 更准确地理解你的需求，特别是 UI 设计、网站开发和 Bug 修复时。

技巧四：分步骤提问

跟技巧 1 有点类似。对于复杂的功能，不要一次性要求 AI 全部完成。把它拆成多个步骤，一步一步来。

比如实现用户登录功能：

先帮我创建一个登录表单，包含邮箱和密码输入框，还有一个登录按钮。
现在给表单添加客户端验证：邮箱要符合格式，密码至少 6 位。
当用户点击登录按钮时，发送 POST 请求到 /api/login，携带邮箱和密码。
如果登录成功，跳转到首页；如果失败，显示错误信息。

每完成一步，你都可以测试一下，确保没问题再继续。这样即使出错，也容易定位问题。

技巧五：用提问来引导思考

有时候，你不确定该怎么做，可以让 AI 帮你分析。

我想在这里加一个缓存机制，但不确定用哪种方案。你能分析一下 Redis 和 Memcached 的优缺点吗？
这个页面加载有点慢，你觉得可能是什么原因？有什么优化建议？
我在考虑用 SSR 还是 CSR，你能帮我分析一下这两种方案在我这个项目中的适用性吗？

这样的提问能让 AI 发挥它的知识优势，帮你做出更好的决策。

三、如何描述清楚需求？

描述需求是对话中最重要的环节。描述得好，AI 就能做对；描述得不好，就会南辕北辙。

使用需求描述框架

在描述需求时，可以用一个系统化的框架来组织你的想法。这里推荐一个实用的框架：

基础版（5要素）：

是什么（What）：要做什么功能或组件？
为什么（Why）：这个功能的目的是什么？
怎么做（How）：技术实现有什么要求？
什么样（Style）：外观和交互有什么要求？
什么情况（When/Where）：在什么场景下使用？

举个例子：

我需要一个搜索框（What）
让用户能快速找到文章（Why）
用 React 实现，输入时实时搜索（How）
样式要简洁，有搜索图标，输入框圆角（Style）
放在页面顶部导航栏的右侧（Where）

当然，不是每次都要说全五个要素，但建议至少要包含前三个。

进阶版（6要素）：

如果你想要更专业的输出，可以补充这个要素：

6）受众（Audience）：这个功能是给谁用的？他们的技术水平如何？

比如："这个搜索功能是给普通用户用的，要简单易懂，不需要高级筛选。"

这样 AI 就能根据受众调整实现方案和交互设计。

说明技术背景

如果你想让 AI 帮你优化已有项目，那么 AI 需要知道你的项目用的是什么技术，才能给出合适的代码。

每次开始新对话时，建议先说明技术背景，比如：我的项目用的是 Next.js 15（App Router）、TypeScript、Tailwind CSS 和 Supabase。

如果有特殊的代码规范，也要说明，比如：我们的项目使用函数式组件，不用 class 组件。所有的 API 调用都用自定义的 useFetch hook。

这样 AI 生成的代码就能和你的项目保持一致。

虽然现在很多 AI 编程工具会引导 AI 先分析你已有的项目代码，但是人工明确技术栈可以让 AI 生成的内容更准确。

不过如果你不是一名程序员，或者不太懂这些技术，那么这一点就可以完全忽略掉了。这就是为什么在 AI 时代，我们仍然需要学习编程，因为懂技术的人更能引导和利用 AI。

描述期望的输出

告诉 AI 你期望什么样的输出。比如：

请给我完整的组件代码，包括 TypeScript 类型定义
只给我核心逻辑，不需要样式代码
请给我一个可以直接运行的完整示例
请分步骤解释这段代码的工作原理

明确输出格式，能让 AI 更好地满足你的需求，否则 AI 可能会给你输出一大堆乱七八糟的内容。

我发现越强的 AI 就越容易把简单的需求搞复杂。像我之前就遇到过让 AI 生成一个小项目，结果它给我生成了 7 ~ 8 个文档，浪费了贼多 Token。

四、追问和纠偏的技巧

AI 第一次给出的答案往往不够完美。这时候，你需要通过追问和纠偏来改进结果。

追问的艺术

如果 AI 的回答不够详细，不要重新问一遍，而是追问细节。

❌ 不好的追问：再详细一点（太模糊）

✅ 好的追问：

你提到了使用 useEffect，能详细解释一下为什么要在这里用它吗？
这个函数的性能如何？处理大量数据时会有问题吗？
你选择用 Map 而不是 Object，是基于什么考虑？

具体的追问更能得到具体的答案。

让 AI 主动追问你

有时候，你可能不知道该提供哪些信息。这时候，可以让 AI 主动追问你：

我想做【你的需求】。请你在回答前，先问我几个问题，了解更多细节，然后再给出方案。

这样 AI 会根据它的理解，问你一些关键问题，比如技术栈、使用场景、设计要求等。通过回答这些问题，你能把需求描述得更清楚，AI 也能给出更准确的方案。

这种方式特别适合你对需求还不够明确的时候，让 AI 帮你理清思路。

纠偏的方法

如果 AI 理解错了你的意思，要及时纠正。

不对，我想要的不是这样。我的意思是......
这个方案不太适合我的场景，因为......你能给我另一个方案吗？
你误解了我的需求。我要的是 A，不是 B。

不要不好意思纠正 AI，请尽情地骂它、羞辱它、甚至可以把它当做臭狗一样教训。它不会生气，反而会根据你的反馈给出更好的答案。

要求解释

如果你不理解 AI 给出的代码或方案，可以要求它解释。

这段代码是什么意思？能逐行解释一下吗？
为什么要这样写？有没有其他写法？
这个方案的优缺点是什么？

理解了原理，你才能真正掌握这些知识。

五、如何引导 AI 的输出？

有时候，AI 会给出一些不太理想的方案。这时候，你需要引导它往正确的方向走。

设定约束条件

通过设定约束，让 AI 在特定范围内思考。

请给我一个不依赖第三方库的纯 JavaScript 实现。
这个功能要在 100ms 内完成，请考虑性能优化。
代码要尽可能简洁，不超过 20 行
要考虑边界情况，比如空数组、null 值等

这些约束能让 AI 的输出更符合你的实际需求。

要求多个方案

不要满足于第 1 个方案，而是让 AI 给你多个选择。

请给我 3 种不同的实现方式，分别说明它们的优缺点。
这个问题有没有更简单的解决方案？
除了你刚才说的方法，还有其他方案吗？

多个方案能让你做出更明智的选择。

此外，鱼皮在做一个大项目时，会让多个不同的 AI 模型或 AI 产品同时给出方案，然后再人工进行挑选。这种方法适用于有一定专业知识的朋友。

使用角色扮演

让 AI 扮演特定角色，能得到更专业的建议。

请以一个资深前端工程师的角度，审查这段代码并给出改进建议。
假设你是一个 UX 设计师，这个交互流程有什么问题？
作为一个性能优化专家，你会如何改进这个页面的加载速度？

角色扮演能激发 AI 在特定领域的专业知识。

如果你不知道该让 AI 扮演什么角色，可以让 AI 自己选择最合适的专家：

我想探讨【你的问题】。请你先选一位最适合的领域专家来思考它，可以是真实存在的名人或专家。然后以这个专家的视角来回答我的问题。

比如你想优化一个产品的用户体验，可以让 AI 选择合适的 UX 专家。AI 可能会选择某个知名的设计师或产品经理，然后以他们的视角给出建议。这样的回答往往更专业、更有深度。

六、对话模板库

为了提高效率，你可以准备一些常用的对话模板。

1）开始新功能的模板

我要开发一个新功能：【功能描述】。我的技术栈是【技术栈】。请帮我：

1）分析这个功能的核心需求

2）建议一个合理的实现方案

3）列出可能遇到的问题

2）调试问题的模板

我遇到了一个问题：【问题描述】。报错信息是：【错误信息】。相关代码是：【代码片段】。请帮我：

1）分析可能的原因

2）给出解决方案

3）解释为什么会出现这个问题

3）优化代码的模板

这是我的代码：【代码片段】。它的功能是【功能说明】。请帮我：

1）找出可能的性能问题

2）改进代码的可读性

3）指出潜在的 bug

4）学习新知识的模板

我想学习【技术/概念】。请：

1）用简单的语言解释它是什么

2）给我一个实际的使用例子

3）告诉我什么时候应该用它

Vibe Coding 上下文管理技巧

让 AI 真正理解你的项目

你可能遇到过这样的情况：刚开始和 AI 对话时，它表现得很聪明，生成的代码也很符合你的要求。但聊了一会儿之后，它开始失忆了，忘记了你之前说过的技术栈、忘记了项目的设计风格，甚至开始用完全不同的方案来实现功能。

这不是 AI 变笨了，而是它的记忆出了问题。下面我就来教你如何通过 上下文工程，给 AI 装上一个可靠的 "记忆补丁"。

一、什么是上下文工程

在讲具体方法之前，我们先要理解什么是上下文。

上下文就是 AI 的工作记忆

想象一下，你在和一个新同事合作开发项目。如果你每次都要从头解释项目是什么、用的什么技术、有什么规范，那效率会很低。但如果你们有一份共享的项目文档，新同事看一眼就能明白，那合作就会顺畅很多。

上下文就是这份 "项目文档"。它包含了 AI 需要知道的所有背景信息：

你的项目是什么
用的什么技术栈
有什么设计规范
已经完成了哪些功能
当前在做什么

有了这些信息，AI 才能给出准确、一致的答案。

上下文的重要性

很多人把精力放在 "写好提示词" 上，但其实，上下文可能比提示词更重要。

一个好的提示词能让 AI 理解你当前的需求，但一个好的上下文能让 AI 理解你的整个项目。前者是 "点"，后者是 "面"。

举个例子，如果你只说 "帮我写一个按钮"，AI 可能会用原生 HTML 写，也可能用 React 写，样式也是它自己决定的。

但如果你提供了完整的上下文 "项目用 React、Tailwind CSS、设计风格是简约现代、主色调是蓝色"，AI 就能给你一个完全符合项目风格的按钮。这就是上下文的力量。

上下文的 3 个层次

上下文可以分为 3 个层次：

项目级上下文：整个项目的基本信息，比如技术栈、设计规范、目录结构等。
功能级上下文：当前正在开发的功能的信息，比如这个功能要做什么、依赖哪些其他功能等。
对话级上下文：当前对话中的临时信息，比如刚才讨论的问题、生成的代码片段等。

管理好这三个层次的上下文，你就能让 AI 始终 "在状态"。

二、AI 的短期记忆

我们先从最基础的开始 ------ 如何管理 AI 的短期记忆？

什么是上下文窗口？

AI 有一个上下文窗口（Context Window），可以理解为它的短期记忆容量。这个窗口是有限的，通常是几千到几十万个 token（大约相当于几千到几十万个单词）。

当你和 AI 对话时，每条消息都会占用这个窗口的空间。对话越长，窗口就越满。当窗口满了，早期的对话内容就会被遗忘。

这就是为什么 AI 会失忆，不是它真的忘了，而是早期的信息已经被挤出窗口了。

一个对话，一个任务

最简单的管理方法就是：一个对话只做一件事。

不要在一个对话里既讨论登录功能，又讨论支付功能，还讨论性能优化。这样会让上下文变得混乱，AI 也容易搞混。

正确的做法是：

做登录功能时，开一个新对话
做完了，测试通过了，再开一个新对话做支付功能
遇到性能问题，又开一个新对话专门讨论优化

每个对话都聚焦一个任务，上下文就会保持清晰。

当然，如果是多个简单的功能，都放在一个对话里也没有问题，灵活一点~

定期压缩上下文

如果一个任务确实需要很长的对话，你可以定期压缩上下文。

具体做法是：当对话进行到一半时，让 AI 总结一下到目前为止的进展。

有些 AI 编程工具自带了总结上下文的指令，可以直接使用：

也可以手动输入提示词来总结：

复制代码

请总结一下我们到目前为止做了什么，包括：
1）完成了哪些功能
2）使用了哪些技术方案
3）还有哪些待解决的问题

然后，你可以用这个总结开始一个新对话，继续后面的工作。这样就相当于把之前的长对话压缩成了一个简短的总结。

善用回顾

在新对话开始时，让 AI 简单回顾一下之前的内容。

比如：

复制代码

我们之前做了一个登录表单，使用了 React Hook Form 和 Zod 验证。现在我想在登录成功后跳转到首页。

这样 AI 就能快速回忆起之前的工作，给出连贯的答案。

三、AI 的长期记忆

除了对话中的短期记忆，你还需要给项目建立长期记忆，典型的做法是 提供项目文档。

README.md 项目的身份证

README.md 是项目最重要的文档，它应该包含：

项目简介：这个项目是做什么的，解决什么问题
技术栈：用了哪些技术、框架、库
目录结构：主要文件和文件夹的作用
开发规范：代码风格、命名规则等
如何运行：安装依赖、启动项目的命令

一个好的 README.md 应该让任何人（包括 AI）看一眼就能理解项目的基本情况。

举个例子：

复制代码

# 我的博客系统

一个简洁的个人博客系统，支持 Markdown 写作和代码高亮。

## 技术栈

- 前端：Next.js 14 (App Router) + TypeScript + Tailwind CSS
- 后端：Supabase (PostgreSQL + Auth)
- 部署：Vercel

## 目录结构

- `/app` - Next.js 页面和路由
- `/components` - 可复用组件
- `/lib` - 工具函数和配置
- `/public` - 静态资源

## 开发规范

- 使用函数式组件，不用 class 组件
- 所有组件都要有 TypeScript 类型
- 样式使用 Tailwind CSS，不写自定义 CSS
- API 调用统一使用 `/lib/api.ts` 中的函数

## 如何运行

```bash
npm install
npm run dev
```

鱼皮开源项目的 README.md 基本都是遵循这种结构化格式的，比如 AI 零代码应用生成平台项目，供大家参考。

每次开始新对话时，把 README.md 的内容贴给 AI，它就能快速了解你的项目。

TODO.md 项目的任务清单

TODO.md 记录了项目的待办事项和进度，它应该包含：

已完成的功能：哪些功能已经做好了
正在开发的功能：当前在做什么
待开发的功能：接下来要做什么
已知问题：有哪些 bug 或待优化的地方

举个例子：

复制代码

# 开发进度

## 已完成 ✅

- [x] 用户注册和登录
- [x] 文章列表页
- [x] 文章详情页
- [x] Markdown 渲染

## 进行中 🚧

- [ ] 文章编辑功能
  - [x] 编辑器界面
  - [ ] 保存草稿
  - [ ] 发布文章

## 待开发 📋

- [ ] 评论功能
- [ ] 搜索功能
- [ ] 标签系统

## 已知问题 🐛

- 移动端导航栏在某些设备上显示不正常
- 代码高亮在暗色主题下对比度不够

TODO.md 能让你和 AI 都清楚地知道项目的进度，避免重复工作或遗漏功能。

及时更新文档

文档最大的问题就是过时。所以，每次完成一个功能或做了重要改动，都要及时更新 README.md 和 TODO.md。

你可以让 AI 帮你更新：

复制代码

我们刚才完成了文章编辑功能。请帮我更新 TODO.md，把 "文章编辑功能" 标记为已完成。

AI 自然也知道这件事的重要性，所以在我们生成代码时 AI 可能会自动为我们生成这些文档。

四、AI 编程工具的上下文策略

不同的 AI 工具对上下文的处理方式不同，你需要了解它们的特点。

Cursor 的 .cursorrules

Cursor 支持在项目根目录创建 .cursorrules 文件，作为项目的系统提示词。

你可以在这个文件里写上：

复制代码

这是一个 Next.js 的博客项目。

技术栈：
- Next.js 16 (App Router)
- TypeScript
- Tailwind CSS
- Supabase

代码规范：
- 使用函数式组件
- 所有组件必须有 TypeScript 类型定义
- 样式只用 Tailwind CSS
- 不要使用 any 类型

设计风格：
- 简约、现代
- 主色调：#3B82F6 (蓝色)
- 圆角：8px
- 阴影：subtle

请始终遵循这些规范。

这样，Cursor 在生成代码时就会自动参考这些规则。

💡 注意，随着 AI 编程工具的更新，这些规则可能会有变化，建议还是多看看官方文档。

Claude Code 的 CLAUDE.md

Claude Code 会读取项目根目录下的 CLAUDE.md 文件作为上下文。

你可以在这个文件里放更详细的信息：

复制代码

# 项目上下文

## 项目概述
个人博客系统，支持 Markdown 写作。

## 技术栈
- Next.js 16 + TypeScript + Tailwind CSS
- Supabase (数据库 + 认证)

## 重要决策
1. 为什么选择 Supabase：简单、免费额度够用、自带认证
2. 为什么用 App Router：这是 Next.js 的未来方向
3. 为什么不用 Redux：项目简单，用 React Context 就够了

## 已知问题
- 移动端导航栏需要优化
- 代码高亮主题需要调整

## 下一步计划
- 实现评论功能
- 添加搜索

这个文件相当于给 AI 的项目手册。

通用策略：上下文文件夹

如果你用的工具不支持特定的上下文文件，可以创建一个 /docs 文件夹，把所有文档放在里面：

复制代码

/docs
  - README.md (项目概述)
  - TECH_STACK.md (技术栈详情)
  - DESIGN.md (设计规范)
  - API.md (API 文档)
  - TODO.md (任务清单)

每次开始新对话时，把相关文档的内容贴给 AI 就好。

五、上下文断裂的修复技巧

即使你做好了上下文管理，有时候 AI 还是会断片儿。这时候，你需要知道如何修复。

怎么识别断裂？

上下文断裂一般有这些表现：

AI 突然用了不同的技术栈（比如你明明用 React，它却给你写 Vue 代码）
AI 忘记了之前讨论的设计方案
AI 生成的代码风格和之前的不一致
AI 重复问你已经回答过的问题

一旦发现这些信号，就要及时修复。

修复方法 1、重新提供上下文

最简单的方法就是重新把上下文贴一遍。

复制代码

等等，我们的项目用的是 React 和 TypeScript，不是 Vue。
这是我们的技术栈：【贴上 README.md 的技术栈部分】。请用正确的技术栈重新生成代码。

修复方法 2、引用之前的内容

如果是忘记了之前讨论的内容，可以引用一下。

复制代码

还记得我们之前决定用 Context API 管理状态吗？请继续用这个方案，不要改用 Redux。

修复方法 3、开新对话

如果上下文已经混乱到无法修复（比如同一个 Bug 多次修复都没有结果），最好的办法就是开一个新对话。

在新对话中，先提供完整的上下文，然后继续工作。这样虽然要重新开始，但能保证后续的对话质量。

修复方法 4、回到正轨提示词

有时候，你可以用一个明确的提示让 AI 回到正轨。

复制代码

请暂停。我们现在的目标是实现登录功能，使用 React Hook Form 和 Supabase Auth。
请确认你理解了这个目标，然后我们继续。

这相当于给 AI 一个重启的机会。不过鱼皮测试下来，有时这个提示词不一定会生效。

六、上下文管理的最佳实践

基于我的经验和社区的总结，这里是一些上下文管理的最佳实践。

1、项目开始时就建立文档

不要等到项目做到一半才想起来写文档。从第一天就创建 README.md 和 TODO.md，并保持更新。

这样不仅能帮助 AI，也能帮助你自己理清思路。

2、用工具的原生上下文机制

如果你用的工具支持特定的上下文文件（比如 .cursorrules），优先使用这些机制，它们是最高效的。

3、保持上下文简洁

上下文不是越多越好。太多的信息反而会让 AI 困惑。

建议只提供最重要、最相关的信息。如果一个信息对当前任务没用，就不要放进上下文，还会浪费 tokens。

实践四：用层次化的结构

建议把上下文分成不同的层次和文件，而不是全部堆在一个文件里。

比如：

README.md 放项目概述和基本信息
TECH_STACK.md 放详细的技术栈说明
DESIGN.md 放设计规范
每个功能模块有自己的文档

实践五：定期回顾和更新

每周或每完成一个大功能，回顾一下文档，看看有没有过时的内容，及时更新。

你可以让 AI 帮你检查：

复制代码

请检查我的 README.md，看看有没有和当前代码不一致的地方。

6、用注释增强代码上下文

在代码里加上有意义的注释，解释 "为什么" 而不只是 "是什么"。

❌ 不好的注释：

复制代码

// 获取用户数据
const user = await getUser(id);

✅ 好的注释：

复制代码

// 从 Supabase 获取用户数据
// 注意：这里不包含敏感信息（如密码），只返回公开字段
const user = await getUser(id);

好的注释能帮助 AI 理解代码的意图，在修改时做出更合理的决策。

七、实战案例：建立完整的上下文体系

让我用一个真实的例子，展示如何为项目建立完整的上下文体系。

假设你要做一个在线笔记应用。

第一步、创建 README.md

复制代码

# 在线笔记应用

一个简洁的在线笔记应用，支持 Markdown 编辑和实时保存。

## 技术栈

- 前端：React 18 + TypeScript + Vite
- UI 库：Tailwind CSS + Headless UI
- 编辑器：CodeMirror 6
- 后端：Supabase (PostgreSQL + Realtime)
- 部署：Vercel

## 核心功能

1. 用户注册和登录
2. 创建、编辑、删除笔记
3. Markdown 实时预览
4. 笔记自动保存
5. 笔记搜索

## 目录结构

- `/src/components` - React 组件
- `/src/pages` - 页面组件
- `/src/lib` - 工具函数和 API
- `/src/hooks` - 自定义 Hooks
- `/src/types` - TypeScript 类型定义

## 开发规范

- 组件使用函数式组件 + Hooks
- 所有组件必须有 TypeScript 类型
- 样式只用 Tailwind CSS
- API 调用统一使用 `/src/lib/api` 中的函数
- 状态管理使用 Zustand

## 设计风格

- 简约、专业
- 主色调：#6366F1 (Indigo)
- 圆角：6px
- 字体：Inter

第二步、创建 TODO.md

复制代码

# 开发进度

## 已完成 ✅

- [x] 项目初始化
- [x] Supabase 配置
- [x] 用户认证（注册/登录）
- [x] 笔记列表页面

## 进行中 🚧

- [ ] 笔记编辑器
  - [x] CodeMirror 集成
  - [x] Markdown 语法高亮
  - [ ] 实时预览
  - [ ] 自动保存

## 待开发 📋

- [ ] 笔记搜索
- [ ] 笔记分类/标签
- [ ] 导出功能
- [ ] 暗色主题

## 已知问题 🐛

- 编辑器在移动端性能不佳
- 长笔记加载较慢

第三步、创建 rules 规则文件

复制代码

项目：在线笔记应用

技术栈：
- React 18 + TypeScript + Vite
- Tailwind CSS + Headless UI
- CodeMirror 6
- Supabase
- Zustand (状态管理)

代码规范：
- 使用函数式组件
- 所有组件必须有 TypeScript 类型定义
- Props 类型命名：组件名 + Props (如 EditorProps)
- 样式只用 Tailwind CSS
- 不使用 any 类型
- API 调用必须有错误处理

设计规范：
- 主色调：#6366F1
- 圆角：rounded-md (6px)
- 间距：使用 Tailwind 的标准间距 (4, 8, 12, 16...)
- 按钮：px-4 py-2, hover 时变深色
- 输入框：border-gray-300, focus 时 border-indigo-500

命名规范：
- 组件文件：PascalCase (如 NoteEditor.tsx)
- 工具函数：camelCase (如 formatDate.ts)
- 常量：UPPER_SNAKE_CASE (如 API_URL)

请始终遵循这些规范。

第四步、在代码中添加上下文注释

复制代码

// src/lib/api/notes.ts

/**
 * 笔记 API 函数集合
 * 
 * 技术选择说明：
 * - 使用 Supabase Client 而不是直接的 SQL
 * - 所有函数都返回 { data, error } 格式
 * - 错误统一在这里处理，不抛出异常
 */

import { supabase } from './supabase';
import type { Note } from '@/types';

有了这个完整的上下文体系，无论你什么时候开始新对话，只要把相关文档贴给 AI，它就能快速进入状态，给出准确的答案。

总结

上下文工程是 Vibe Coding 中最容易被忽视，但又极其重要的一环。很多人把精力都放在 "怎么问" 上，却忽略了 "怎么让 AI 记住"。

让我总结一下本文的要点：

上下文是 AI 的工作记忆：它决定了 AI 能否理解你的项目。
管理好三个层次：项目级、功能级、对话级上下文都要照顾到。
建立文档体系：README.md、TODO.md、上下文文件缺一不可。
利用工具特性：不同工具有不同的上下文机制，要善用它们。
及时修复断裂：发现 AI 失忆了，要立刻修复，不要继续往下走。
保持简洁和更新：上下文要精炼、准确、及时更新。

掌握了上下文工程，你就能让 AI 始终保持状态，大大提高开发效率。

Vibe Coding 团队协作技巧

和其他人一起用 Vibe Coding 做项目

在实际工作中，很多项目是团队协作完成的。

你可能会想：用 AI 开发还需要团队协作吗？每个人自己用 AI 不就行了？

其实不然。团队协作中有很多问题需要解决，比如不同人用 AI 生成的代码不一致（A 用 React，B 用 Vue）、A 改了代码 B 不知道、大家都在改同一个文件导致冲突等等......

在 Vibe Coding 团队协作中，除了传统的团队协作方法，还可以利用 AI 开发工具的特性来提升效率。本文我就来分享一些团队使用 Vibe Coding 的最佳实践。

一、代码规范和风格

团队协作的第一步是统一代码规范。

为什么需要统一规范？

如果每个人用 AI 生成的代码风格都不一样，项目会变得很混乱。比如 A 用 React Class 组件，B 用函数组件；A 用 CSS Modules，B 用 Tailwind；A 的变量名是 camelCase，B 的是 snake_case......

这样的代码很难维护，也很难协作。所以，团队需要统一的代码规范。

建立代码规范文档

可以创建一个 CODE_STYLE.md 文档，明确规定下面的内容。

1）技术栈规范：

前端框架：React 19 + TypeScript
状态管理：Zustand
样式方案：Tailwind CSS
路由方案：React Router v6

2）代码风格规范：

组件：函数式组件 + Hooks
命名：组件用 PascalCase，函数用 camelCase，常量用 UPPER_SNAKE_CASE
文件组织：一个组件一个文件，文件名和组件名一致
导入顺序：React → 第三方库 → 项目内部模块

3）注释规范：

复杂逻辑必须加注释
注释要说明 "为什么" 而不只是 "是什么"
使用 JSDoc 格式为函数添加文档

统一 AI 配置

如果团队都用 Cursor，可以在项目中添加 .cursorrules 文件，统一 AI 的行为：

复制代码

项目：【项目名称】

技术栈：
- React 18 + TypeScript
- Tailwind CSS
- Zustand

代码规范：
- 使用函数式组件
- 所有组件必须有 TypeScript 类型定义
- 样式只用 Tailwind CSS
- 不使用 any 类型

请所有团队成员都遵循这些规范。

这样，不同人用 AI 生成的代码风格会更一致。

如果团队使用 Claude 或其他 AI 工具，也可以通过类似的方式统一规范。比如在每次对话开始时，先让 AI 读取项目的规范文档，或者在系统提示词中加入团队的代码规范。不同工具的具体做法可能不同，建议查看 AI 工具的官方文档。

二、AI 编程工具的团队协作功能

现代 AI 编程工具提供了专门的团队协作功能，能大大提升团队效率。

Cursor 团队版

Cursor 提供了专门的团队版，包含下面这些功能：

1）团队管理和权限控制

可以创建团队，邀请成员，设置不同的角色和权限。管理员可以控制谁能访问哪些功能，查看团队的使用情况和账单。

2）共享配置文件

通过共享规则文件，团队可以统一 AI 的行为规范。所有成员使用的 AI 都会遵循相同的代码规范、技术栈要求和输出格式，确保生成的代码风格一致。

3）使用分析和监控

团队管理员可以查看团队的 AI 使用情况，包括哪些成员使用最多、使用了哪些模型、花费了多少成本等。这能帮助优化团队的 AI 使用策略。

Claude 共享能力

Claude 提供了 Projects 功能，特别适合团队协作：

1）项目级别的知识库

可以为每个项目创建独立的知识库，上传项目相关的文档、代码、规范等。团队成员在这个项目中使用 Claude 时，AI 会自动参考这些知识，保持上下文一致。

2）自定义指令

可以为每个项目设置自定义指令，比如 "使用正式的语气"、"从数据分析师的角度回答" 等。团队成员使用时，AI 会自动遵循这些指令。

3）对话分享

Claude Team 用户可以将优秀的对话分享到团队的活动流中。其他成员可以看到别人是如何使用 AI 的，学习不同的提问技巧和解决方案，提升整个团队的 AI 使用水平。

4）团队共享 CLAUDE.md 文件

即使不使用 Projects 功能，也可以把 CLAUDE.md 文件用 Git 来管理，实现团队成员的共同分享和维护。

每当发现 Claude 做错了什么，就将它添加到 CLAUDE.md 中，这样 Claude 下次就知道不要这样做了。这个文件会逐渐沉淀团队的开发经验和规范，成为团队的共享知识库。

三、文档驱动开发

好的文档是团队协作的基础。

项目文档的重要性

在团队中，文档比个人开发时更重要。因为你写的代码不只是给自己看的，还要给其他人看。好的文档能让团队成员快速了解项目，减少沟通成本。

必备的文档包括：

README.md：项目概述和使用说明
CONTRIBUTING.md：如何参与开发
CODE_STYLE.md：代码规范
API.md：API 接口文档
CHANGELOG.md：版本更新记录

README.md 的内容

README.md 是项目的门面，就像一本书的封面和目录。它是新成员加入项目时第一个看的文件，也是其他开发者了解你项目的窗口。一个好的 README 能让人快速理解项目、快速上手开发。

一个好的 README.md 应该包含：

项目简介：这个项目是做什么的，解决什么问题
快速开始：如何安装依赖、配置环境、运行项目
技术栈：用了哪些技术、为什么选择这些技术
目录结构：主要文件夹的作用
开发规范：代码风格、提交规范等
常见问题：新人容易遇到的问题和解决方案

API 文档

如果项目有后端 API，要写清楚每个接口的用法。可以用 Swagger、Postman 等工具或者 AI 来生成 API 文档。

每个接口要说明：

请求方法和路径
请求参数（类型、是否必填、说明）
响应格式
错误码说明
使用示例

让 AI 帮你写文档

写文档很枯燥，但 AI 可以帮你。

如果你使用 Cursor、Claude Code 等 AI 编程工具，工具会自动读取项目结构作为上下文，你甚至不用自己贴代码，直接说：

复制代码

请为这个项目生成 API 文档

AI 就能根据代码自动生成。

如果使用其他 AI 工具，可以手动贴代码：

复制代码

请为这个 API 接口生成文档：
【贴上你的代码】

文档应该包括：接口说明、请求参数、响应格式、使用示例

AI 会生成一份基础的文档，你再根据实际情况调整。

四、Git 协作流程

Git 是一个版本控制系统，也是团队协作的核心工具。就像给代码拍照存档，可以随时回到之前的任何版本。它能记录谁在什么时候改了什么代码，团队成员可以同时开发不同功能，最后再合并到一起。

分支管理策略

分支就像是代码的平行世界。你可以在自己的分支里随便改代码，不会影响别人。改好了再合并到主分支，就像把你的工作成果搬到正式版本里。

团队开发要利用好分支功能，常见的分支策略是：

main 分支：稳定的生产代码，只接受经过测试的代码
develop 分支：开发分支，日常开发在这里进行
feature 分支：每个新功能开一个分支，比如 feature/user-login、feature/post-editor
bugfix 分支：修复 bug 时开的分支，比如 bugfix/login-error

工作流程是：

从 develop 分支创建 feature 分支
在 feature 分支上开发，开发完成后提交 Pull Request
经过审查后合并到 develop
定期将 develop 合并到 main

提交规范

统一的提交信息能让团队更容易追踪变更。可以安装通义灵码插件自动生成提交commit，这是一种标准化的提交信息格式，让每次提交的目的一目了然。

比如：

复制代码

feat: 添加用户登录功能
fix: 修复导航栏在移动端的显示问题
docs: 更新 API 文档
style: 格式化代码
refactor: 重构用户服务
test: 添加登录功能的测试
chore: 更新依赖包

类型 + 冒号 + 空格 + 简短描述，大家一看就知道这次提交做了什么。

现在很多 AI 编程工具都支持生成提交信息，更容易遵循规范。

解决冲突

多人协作时，代码冲突是常见问题。当两个人修改了同一个文件的同一部分，Git 会提示冲突。

解决冲突的步骤是：首先拉取最新代码 git pull origin develop，Git 会标记出冲突的地方。然后手动编辑文件，决定保留哪部分代码。解决完冲突后，要测试确保功能正常，最后提交解决后的代码。

为了减少冲突，建议：

经常拉取最新代码，不要长时间不同步
功能开发完就及时合并，不要拖太久
如果要修改公共文件，提前和团队沟通

五、代码审查流程

代码审查（Code Review）是保证团队代码质量的关键。

为什么要做代码审查？

代码审查有很多好处。

首先，能在代码上线前就发现潜在的 Bug，避免问题流入生产环境。其次，能统一代码风格，让项目代码保持一致，不会出现每个人写的代码风格都不一样的情况。

更重要的是，代码审查是一个很好的学习机会。审查者能看到别人的代码思路，被审查者能得到改进建议，双方都能学到东西。而且，知道代码会被审查，写的时候自然就会更认真，这能从源头提高代码质量。

审查的重点

审查代码时，重点关注这些方面：

功能正确性：代码是否正确实现了需求？有没有遗漏的边界情况？
代码质量：代码是否清晰易懂？有没有重复代码？命名是否规范？
性能问题：有没有明显的性能问题？数据结构选择是否合理？
安全问题：有没有安全漏洞？用户输入是否验证？
测试覆盖：是否有足够的测试？测试是否覆盖了主要场景？

审查的技巧

审查时要注意方法。不要只说 "这里不对"，要说清楚为什么不对、应该怎么改。要用建议的语气，而不是命令的语气。比如 "我建议这里用 useMemo 优化性能" 而不是 "这里必须用 useMemo"。当然，团队如果有硬性要求除外。

如果有多个问题，分清主次。先指出重要的问题（比如 bug、安全漏洞），再提改进建议（比如命名、注释）。

审查不是一次性的，可以多轮讨论。第一轮指出主要问题，修改后再审查，确认没问题再合并。

让 AI 辅助审查

可以让 AI 帮你做初步审查：

复制代码

请审查这段代码，从功能、性能、安全、代码质量等角度分析：
【贴上代码】

AI 会给你一份详细的审查报告。但要注意，AI 的审查不能完全替代人工审查，最终还是要人来把关。

Claude Code 自动化代码审查

如果使用 Claude Code，可以在代码审查的 Pull Request 中标记 @.claude，这样 Claude 会自动把审查建议添加到 CLAUDE.md 文件中。再利用 GitHub Action 实现自动化更新，这样文档会逐渐沉淀团队的代码质量标准和常见问题。

这也是 Claude Code 创始人推荐的做法，让代码审查的经验自动积累下来。

多个 AI 交叉验证

为了更保险，可以让多个不同的 AI 审查同一段代码。比如先让 Claude 审查一遍，再让 GPT 审查一遍，对比它们的建议。

不同的 AI 可能会发现不同的问题，交叉验证能提高审查的全面性。

六、团队协作最佳实践

定期同步

团队要定期开会同步进度，比如每天的站会（5 ~ 10 分钟），每周的周会（30 ~ 60 分钟）。

站会主要说三件事：昨天做了什么、今天计划做什么、遇到了什么问题。

周会可以深入讨论技术方案、分享经验、规划下周工作。

除了会议，还可以用工具同步。比如用 Jira 等工具管理任务，用企微、飞书、Slack 等工具日常沟通，用 Notion、语雀等工具共享文档。

结对编程

对于复杂的功能，可以尝试结对编程。两个人一起开发，一个人写代码（Driver），一个人审查和提建议（Navigator），这样不仅能提高代码质量，也能促进知识分享。

说实话，我很少见到有公司真的这么做，因为成本太高了。

不过仔细想想，在 Vibe Coding 中，和 AI 一起开发，不就是一种结对编程吗？

AI 是你的编程搭档，你提需求，它写代码；你审查，它改进。这种 "人机结对" 可能比 "人人结对" 更高效。

建立共享资源

团队可以建立一些共享资源，比如：

提示词模板库：常用的提示词模板
代码片段库：常用的组件和函数
问题解决方案库：遇到的问题和解决方法
最佳实践文档：总结的经验和技巧

这些资源能让新人快速上手，也能提高整个团队的效率。

可以通过 Git + GitHub 来管理和共享代码文件，也可以用各种云盘软件来存储多媒体，选择团队习惯的工具就好。

明确分工

虽然都用 AI，但还是要明确分工。谁负责前端、谁负责后端、谁负责测试、谁负责部署。每个人有自己的职责，避免重复工作或遗漏。

同时，要避免 AI 依赖症。不要所有人都依赖 AI，要有人能在 AI 出问题时顶上。保持团队的技术能力，不要完全依赖工具。

这也是为什么如今程序员依然关键 ------ AI 只是工具，真正理解业务、把控质量、做出决策的还是人。所以不用担心 AI 会淘汰程序员，会用 AI 的程序员只会变得更强大**。**

虽然在企业中大家会分工合作，但我建议大家努力拓宽自己的能力边界。前端会一点后端、后端会一点前端、测试会一点开发，这样不仅能更好地理解整个系统，也能在关键时刻顶上。在 AI 时代，争取成为能独立完成全栈项目的 超级个体，会让你更有竞争力。

总结

团队协作开发比个人开发复杂得多，但也更有价值。一个配合默契的团队 + AI，能做出远超个人 + AI 的项目。

最后总结一下本文重点，团队协作开发中需要：

统一代码规范：用文档和工具确保代码风格一致。
利用 AI 工具的团队功能：比如 Cursor 团队版、Claude Projects 等，实现配置共享、知识共享、对话分享，让 AI 成为团队的共享大脑
文档驱动开发：写好文档，让团队成员快速了解项目
规范 Git 流程：用分支管理、提交规范、PR 流程保证代码质量
认真做代码审查：审查不是形式，而是提高质量的关键。
建立协作机制：定期同步、结对编程、知识分享、共享资源
明确分工：每个人有自己的职责，同时保持技术能力。

Vibe Coding 不会改变团队协作的本质，它只是一个工具。好的团队协作，需要的是清晰的规范、良好的沟通和互相的信任。

Vibe Coding 代码重构技巧

避免 AI 生成混乱的意大利面代码

你可能遇到过这样的情况：刚开始用 AI 做项目时，代码清晰简洁，看起来很舒服。但随着功能越加越多，代码开始变得混乱。最后，你自己都不敢动这些代码了，因为改一个地方，可能会影响到其他地方。

这种情况在 Vibe Coding 中特别常见，因为 AI 可能只关注 "能不能跑"，忽略了 "好不好维护"。下面我就来教你如何识别和偿还技术债，让你的代码始终保持优雅。

一、什么是技术债？

技术债是一个很形象的比喻。

想象一下，你要盖一栋房子。为了快速完工，你用了一些临时的方案：地基没打牢，墙没砌直，电线随便拉。房子是盖起来了，也能住人，但隐患很多。如果不及时修复，以后问题会越来越大，修复的成本也会越来越高。

技术债就是这样。为了快速实现功能，你（或 AI）采用了一些不够好的方案。这些方案当时能用，但会给未来埋下隐患。随着项目发展，这些隐患会变成实际的问题，拖慢你的开发速度。

在今年的研究中发现，AI 生成的代码特别容易产生技术债。因为 AI 擅长快速实现功能，但不擅长考虑长远的架构和可维护性。它会给你一个 "高度功能化但系统性缺乏架构判断" 的代码。

技术债的表现

那么，如何判断你的项目有没有技术债呢？最明显的信号是：改代码变得越来越困难，你开始害怕修改代码，因为不知道会影响到哪里。如果你发现自己经常觉得 "这个地方不敢动"、"改了这里可能会影响那里"，那就说明技术债已经比较严重了。

技术债的危害

技术债的危害是累积的。刚开始可能只是代码有点乱，不影响功能。但随着时间推移，问题会越来越严重。

开发速度变慢，因为要花更多时间理解和修改代码。
Bug 越来越多，因为代码太复杂，容易出错。
新功能难以添加，因为现有架构不支持。
团队协作困难，因为没人能完全理解代码。

最糟糕的是，到了某个临界点，你可能不得不重写整个项目。这就是技术债的 "破产"。

二、AI 生成代码的常见问题

用 AI 做 Vibe Coding 时，如果上下文管理不当、需求描述不够清晰，或者让 AI 一次性实现太复杂的功能，生成的代码可能会出现一些质量问题。下面是几个典型场景，了解它们能帮你更好地引导 AI。

过度嵌套

AI 为了确保代码能运行，有时会生成嵌套很深的代码。

什么是嵌套？

就是 if 里面套 if，循环里面套循环，像俄罗斯套娃一样。比如：

复制代码

function processData(data: any) {
  if (data) {
    if (data.items) {
      if (data.items.length > 0) {
        data.items.forEach(item => {
          if (item.active) {
            if (item.price > 0) {
              // 实际逻辑
            }
          }
        });
      }
    }
  }
}

这种代码很难读，也很难维护。更好的写法是提前返回：

复制代码

function processData(data: any) {
  if (!data?.items?.length) return;
  
  const activeItems = data.items.filter(item => 
    item.active && item.price > 0
  );
  
  activeItems.forEach(item => {
    // 实际逻辑
  });
}

显然，第二种写法更清晰，也更容易理解。

重复代码

AI 可能不会主动复用代码，而是为每个需求生成新的代码。

举个例子，假设你让 AI 分别实现用户列表页、文章列表页、评论列表页。AI 会给你三套几乎一样的代码，只是数据字段不同。或者你可能在多个组件里都有这样的代码：

复制代码

const handleSubmit = async () => {
  setLoading(true);
  try {
    const response = await fetch('/api/data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    const result = await response.json();
    setData(result);
  } catch (error) {
    console.error(error);
  } finally {
    setLoading(false);
  }
};

这些重复代码应该提取成一个公共函数或自定义 Hook。

缺少抽象

AI 倾向于写具体的、直接的代码，而不是抽象的、可复用的代码。

比如，你要显示用户列表和文章列表，AI 可能会给你两个完全独立的组件，即使它们的结构几乎一样。

更好的做法是创建一个通用的列表组件，然后用不同的数据和渲染函数来复用。

命名随意

AI 有时候会用相对随意的命名，比如 data、result、temp、handleClick。这些名字不能准确表达意图，会让代码难以理解。

出现这种情况可能是因为你的需求描述不够具体，AI 不知道这个变量或函数的真实用途。

好的命名应该是 见名知意 的，比如 userData、apiResponse、temporaryBuffer、handleLoginButtonClick。

如果你发现 AI 生成的命名太随意，可以在需求中明确说明：请使用有意义的变量名和函数名，能清楚表达它们的用途。

三、如何利用 AI 重构代码？

既然 AI 会产生技术债，那能不能用 AI 来偿还技术债呢？

答案是可以的。这也是 Vibe Coding 的一大优势 ------ AI 既能快速写代码，也能快速改代码。

让 AI 识别问题

你可以把代码贴给 AI，让它从专业的角度审查，帮你找出代码中的问题。

复制代码

请审查这段代码，找出可以改进的地方：
```typescript
【贴上你的代码】
```

请从以下角度分析：
1. 有没有重复代码？
2. 函数是否太长？
3. 命名是否清晰？
4. 有没有过度嵌套？
5. 能否提取公共逻辑？

AI 会给你一份详细的分析报告。

让 AI 提供重构方案

找到问题后，让 AI 给你重构方案，比如：

你提到了这段代码有重复逻辑。请给我一个重构方案，把重复的部分提取成公共函数。
这个函数太长了。请帮我把它拆分成几个小函数，每个函数只做一件事。

AI 会给你具体的重构代码。

小步重构

注意，不建议一次性重构整个项目，这样风险太大，说不定重构完你整个项目都无法运行了。

正确的做法是小步重构，每次只改一小部分。

比如，你发现一个函数太长了，不要一次性把它拆成 10 个小函数。先拆成 2 个，测试通过了，再继续拆。每一步都要确保功能不变，测试都通过。

这样即使出了问题，也容易回退。

重构的时机

什么时候应该重构？

我的建议是：

1）不要专门安排时间重构，而是在日常开发中随时重构。当你发现代码有问题时，立刻改掉，不要拖到以后。

2）完成功能后重构。功能做完了，测试通过了，花 10 ~ 15 分钟看看代码，有没有可以改进的地方。

3）添加新功能前重构。如果你发现现有代码不适合添加新功能，先重构一下，让代码更容易扩展。

4）定期集中重构。每个月或每个大版本，花半天时间集中重构，处理积累的技术债。

四、模块化和代码复用

模块化是避免技术债的关键。而且，模块化的代码对 AI 也更友好 ------ 当你需要修改某个功能时，AI 只需要阅读相关的小模块，而不是整个几百行的大文件，这样 AI 能更准确地理解和修改代码。

什么是模块化？

模块化就是把代码分成独立的、可复用的模块。每个模块只做一件事，做好一件事。模块之间通过清晰的接口通信，互不干扰。

好的模块化有这些特点：

高内聚：模块内部的代码紧密相关
低耦合：模块之间的依赖尽可能少
单一职责：每个模块只负责一件事
接口清晰：模块的输入输出明确

组件的拆分

在前端开发框架 React 中，组件是最基本的模块。你可以把组件理解为页面上的一个个独立部分，比如导航栏、搜索框、用户卡片等。

但很多人（包括 AI）会写出很 "笨重" 的组件。

比如，一个用户资料页面，AI 可能会把所有逻辑都写在一个组件里：获取数据、表单验证、提交处理、错误提示...... 结果就是一个几百行的巨型组件。

更好的做法是拆分成多个小组件：

复制代码

// 主组件，负责协调
function ProfilePage() {
  const { user, loading, error } = useUser();
  
  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  
  return (
    <div>
      <ProfileHeader user={user} />
      <ProfileForm user={user} />
    </div>
  );
}

// 子组件，各司其职
function ProfileHeader({ user }) {
  return (
    <div>
      <Avatar src={user.avatar} />
      <h1>{user.name}</h1>
    </div>
  );
}

function ProfileForm({ user }) {
  // 表单逻辑
}

这样一来，每个组件都很小，很容易理解和测试。

即使你不了解前端或 React，也能理解这个思想 ------ 把大的功能拆成小的、独立的部分，每个部分只做一件事。这个原则适用于所有编程语言和框架。

函数的提取

当你发现一段代码在多个地方重复出现时，就应该提取成函数。

比如，你在多个地方都需要格式化日期：

复制代码

// 重复的代码
const formattedDate1 = new Date(date1).toLocaleDateString('zh-CN');
const formattedDate2 = new Date(date2).toLocaleDateString('zh-CN');
const formattedDate3 = new Date(date3).toLocaleDateString('zh-CN');

// 提取成函数
function formatDate(date: Date | string): string {
  return new Date(date).toLocaleDateString('zh-CN');
}

const formattedDate1 = formatDate(date1);
const formattedDate2 = formatDate(date2);
const formattedDate3 = formatDate(date3);

这样不仅减少了重复，还让代码更容易维护。如果以后要改日期格式，只需要改一个地方。

自定义 Hook 的使用

在前端开发框架 React 中，自定义 Hook 是复用逻辑的好方法。Hook 是一种特殊的函数，用来管理状态和副作用。

你不需要理解什么是 Hook、组件、状态管理这些专业术语。只需要告诉 AI：

复制代码

这段逻辑在多个地方重复了，请帮我提取成可复用的模块。

然后 AI 会自动帮你做好抽象和复用。

举个例子，你在多个组件里都需要获取用户数据，可以把获取用户数据这部分代码提取成 Hook，在其他地方复用：

复制代码

// 提取前：每个组件都重复这些逻辑
function ProfilePage() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    fetchUser().then(setUser).catch(setError).finally(() => setLoading(false));
  }, []);
  
  // ...
}

// 提取后：创建自定义 Hook
function useUser() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    fetchUser().then(setUser).catch(setError).finally(() => setLoading(false));
  }, []);
  
  return { user, loading, error };
}

// 使用时很简单
function ProfilePage() {
  const { user, loading, error } = useUser();
  // ...
}

自定义 Hook 让代码更简洁，也更容易测试。

重构的步骤

如何把玩具项目重构成商业产品？

我建议分步进行：

1）整理目录结构。把代码按功能或类型分类，放到不同的文件夹里。比如组件放 components，工具函数放 lib，类型定义放 types。

2）提取重复代码。找出重复的逻辑，提取成公共函数或组件。这一步能大大减少代码量。

3）拆分大文件。把大的文件拆成小的文件，每个文件只负责一件事。比如一个大的 utils.ts 可以拆成 format.ts、validate.ts、storage.ts 等。

4）添加类型定义。如果用 TypeScript，给所有函数和组件加上完整的类型。这能帮你发现很多潜在问题。

5）改进命名。把不清晰的变量名、函数名改成描述性的名字。这能让代码更容易理解。

6）添加测试和文档。为核心功能写测试，为项目写 README，为复杂逻辑加注释。

以上这些步骤也都可以通过 AI 主导 + 人工校验来完成。关键是每一步都要确保功能不变、顺利通过测试。不要贪多，一步一步来。

六、实战案例 - 重构一个混乱的项目

让我用一个真实的例子，展示如何重构一个混乱的项目。

初始状态

假设你用 AI 做了一个待办事项应用，所有代码都在一个 App.tsx 文件里，大概 500 行。

复制代码

// App.tsx (500 行)
function App() {
  const [todos, setTodos] = useState([]);
  const [input, setInput] = useState('');
  const [filter, setFilter] = useState('all');
  const [loading, setLoading] = useState(false);
  
  // 100 行的数据获取逻辑
  useEffect(() => { /* ... */ }, []);
  
  // 50 行的添加逻辑
  const handleAdd = () => { /* ... */ };
  
  // 50 行的删除逻辑
  const handleDelete = () => { /* ... */ };
  
  // 50 行的编辑逻辑
  const handleEdit = () => { /* ... */ };
  
  // 50 行的过滤逻辑
  const filteredTodos = todos.filter(/* ... */);
  
  // 200 行的 JSX
  return (
    <div>
      {/* 很多很多代码 */}
    </div>
  );
}

虽然代码能用，但是所有功能逻辑都写到一起，不利于阅读和维护。

重构步骤

第一步、提取自定义 Hook

首先，我们把所有和待办事项数据相关的逻辑（获取、添加、删除、更新）都提取到一个独立的 Hook 里。这样主组件就不用关心数据是怎么管理的，只需要调用这些方法就行。

复制代码

// hooks/useTodos.ts
function useTodos() {
  const [todos, setTodos] = useState([]);
  const [loading, setLoading] = useState(false);
  
  const addTodo = async (text: string) => { /* ... */ };
  const deleteTodo = async (id: string) => { /* ... */ };
  const updateTodo = async (id: string, text: string) => { /* ... */ };
  
  useEffect(() => {
    // 获取数据
  }, []);
  
  return { todos, loading, addTodo, deleteTodo, updateTodo };
}

第二步、拆分组件

接下来，把 UI 部分拆分成多个小组件。每个组件只负责显示和处理自己那一部分的逻辑，比如输入框只管输入、列表只管显示、过滤器只管筛选。这样每个组件都很简单，容易理解和修改。

复制代码

// components/TodoList.tsx
function TodoList({ todos, onDelete, onEdit }) {
  return (
    <div>
      {todos.map(todo => (
        <TodoItem 
          key={todo.id} 
          todo={todo} 
          onDelete={onDelete}
          onEdit={onEdit}
        />
      ))}
    </div>
  );
}

// components/TodoItem.tsx
function TodoItem({ todo, onDelete, onEdit }) {
  // 单个待办项的逻辑
}

// components/TodoInput.tsx
function TodoInput({ onAdd }) {
  // 输入框的逻辑
}

// components/TodoFilter.tsx
function TodoFilter({ filter, onChange }) {
  // 过滤器的逻辑
}

第三步、重组主组件

最后，把提取出来的 Hook 和拆分好的组件组装起来。现在主组件只需要协调这些部分，告诉它们该做什么，而不用关心具体怎么做。

复制代码

// App.tsx (50 行)
function App() {
  const { todos, loading, addTodo, deleteTodo, updateTodo } = useTodos();
  const [filter, setFilter] = useState('all');
  
  const filteredTodos = useFilteredTodos(todos, filter);
  
  if (loading) return <LoadingSpinner />;
  
  return (
    <div>
      <TodoInput onAdd={addTodo} />
      <TodoFilter filter={filter} onChange={setFilter} />
      <TodoList 
        todos={filteredTodos} 
        onDelete={deleteTodo}
        onEdit={updateTodo}
      />
    </div>
  );
}

看到区别了么？代码一下子从 500 行变成了 50 行，而且每个部分都很清晰。

重构的效果

重构后的代码有这些优势：

每个文件都很小，容易理解
职责清晰，每个组件只做一件事
容易测试，可以单独测试每个组件和 Hook
容易扩展，要加新功能只需要添加新组件
容易维护，改一个地方不会影响其他地方
AI 更好理解：当你需要修改某个功能时，AI 只需要阅读相关的小文件（比如 50 行的 TodoInput.tsx），而不是整整 500 行的 App.tsx。这样 AI 能更准确地理解上下文，生成更好的代码。

这就是从玩具项目代码到商业产品代码的转变。

总结

重构和技术债管理是 Vibe Coding 中需要人工介入的环节。AI 能帮你快速写代码，但不能始终帮你保持代码的优雅，需要你有意识地去做。

理解技术债：知道什么是技术债，它是如何产生的，有什么危害。
识别 AI 代码的问题：过度嵌套、重复代码、缺少抽象、命名随意，这些都是常见问题。
利用 AI 重构：AI 既能产生技术债，也能帮你偿还技术债。
小步重构：不要一次改太多，每次只改一小部分，确保功能不变。
模块化思维：把代码拆成独立的、可复用的模块，保持高内聚、低耦合。
及时重构：不要拖延，发现问题立刻改，不要让技术债积累。

记住，优雅的代码是需要用心维护、不断重构出来的。

希望这些重构技巧能帮你避免代码变成依托屎山，让你的 Vibe Coding 项目始终保持优雅。

受控式文档驱动 Vibe Coding 方案设计

方案概述

方案核心目标

一､当前 Vibe Coding 痛点分析

二､方案核心思想

三､方案核心优势(企业落地价值)

四､核心文档体系

4.1 {module}-flow.md(业务流程文档)

作用

必含内容

禁止内容

4.2 {module}-feature_list.md(功能清单文档)

作用

必含内容

禁止内容

4.3 {module}-feature_task.md(任务步骤文档,AI 开发核心指导文档)

作用

必含内容

禁止内容

4.4 {module}-feature_data.md(数据契约文档)

作用

必含内容(前置定义,编码前完成人工审核)

后置增量生成内容(编码完成后,AI反向提炼更新)

禁止内容

4.5 项目代码风格规范（统一AI的写作风格）

作用

必含规范

4.6 项目技术栈（统一项目技术约束）

必含内容

五､方案完整实现步骤

5.1 新需求开发流程(核心流程)

5.2 需求迭代流程(闭环维护)

六､AI 工具落地支撑

文件放置规则

辅助能力：superpowers:brainstorming（需求前期和代码编写阶段专属使用）

自定义Skill（module-documents） ：业务文档标准化生成与维护规范

自定义Skill （module-tasks）：任务步骤文档生成

自定义 Skill (module-data):

七､职责划分

开发人员职责

AI 职责

八､方案落地保障

九､方案总结

附录（以上方案的思路参考）

Vibe Coding 对话工程技巧

一、对话工程和提示词工程？

对话的好处

二、迭代式对话的核心技巧

技巧一：从大到小，逐步细化

技巧二：具体而非抽象

技巧三：提供参考和示例

技巧四：分步骤提问

技巧五：用提问来引导思考

三、如何描述清楚需求？

使用需求描述框架

说明技术背景

描述期望的输出

四、追问和纠偏的技巧

追问的艺术

让 AI 主动追问你

纠偏的方法

要求解释

五、如何引导 AI 的输出？

设定约束条件

要求多个方案

使用角色扮演

六、对话模板库

Vibe Coding 上下文管理技巧

一、什么是上下文工程

上下文就是 AI 的工作记忆

上下文的重要性

上下文的 3 个层次

二、AI 的短期记忆

什么是上下文窗口？

一个对话，一个任务

定期压缩上下文

善用回顾

三、AI 的长期记忆

README.md 项目的身份证

TODO.md 项目的任务清单

自定义Skill（module-documents）：业务文档标准化生成与维护规范