diff --git a/README.md b/README.md index 7745d21..e21f63f 100644 --- a/README.md +++ b/README.md @@ -101,23 +101,27 @@

⭐ 欢迎 点击此处Star 加速更新 ❤️

-在 AI 时代，把想法变成产品的人，往往技术不是最强，而是最先迈出行动。 +在 AI 时代，把想法变成产品的人，往往不是技术最强的那一个，而是最先迈出行动的那一个。 -很多人即便有了 AI 助手，依然会被“代码看不懂”、“环境不会配”劝退。**Easy-Vibe 为此而生。** 假设每个人都是零基础，手把手带你从写出第一行代码，到理解前后端逻辑，最后把产品上线。 - -- **面向人群**：初学者、产品经理、前后端 / 全栈开发者 -- **主题**：AI 编程、全栈 Web 应用开发、AI Agent、工作流和 RAG 系统 +即便有了 AI 助手，"代码看不懂"、"环境不会配"依然足以让大多数人止步。Easy-Vibe 为此而来——假设每个人都是零基础，手把手带你从写出第一行代码，到理解前后端逻辑，最终把产品上线。 --- -Easy-Vibe 通过以下几个阶段，带你从 0 到 1： +## 学习路径 -| 阶段 | 核心技能 | 产出 | -| ------------ | -------------------------------- | ----------------------------------------- | -| **第一阶段** | AI 编程入门、产品思维、原型设计 | 互动小游戏、Web 应用原型（新手入门 & PM） | -| **第二阶段** | 全栈开发、AI 集成、数据库 | 完整的全栈 AI 应用 | -| **第三阶段** | Claude Code 进阶、多平台开发 | 生产级多平台应用 | -| **附录** | 帮你理解计算机、人工智能基础概念 | 9 大知识领域、80+ 交互式专题 | +> 根据你的基础水平，推荐从不同阶段开始： +> - **零基础**：从 Stage 0 开始，建立编程思维和产品意识 +> - **有一定经验**：从 Stage 1 开始，快速掌握 AI 编程工具和原型设计 +> - **开发者**：从 Stage 2 开始，深入全栈开发和 AI 集成 +> - **进阶开发者**：直接进入 Stage 3，探索 Claude Code 和多平台开发 + +| 阶段 | 核心技能 | 产出 | +| :--- | :--- | :--- | +| **Stage 0** | 学习地图、AI 编程入门、寻找产品想法 | 互动小游戏、Web 应用原型 | +| **Stage 1** | AI IDE、产品思维、原型设计、AI 能力集成 | 完整的产品原型 | +| **Stage 2** | 全栈开发、数据库、AI 集成、部署运维 | 可上线的全栈 AI 应用 | +| **Stage 3** | Claude Code 进阶、多平台开发 | 生产级多平台应用 | +| **附录** | 计算机基础、AI 入门、9 大知识领域 | 80+ 交互式专题 | ## 🔥 News diff --git a/docs/zh-cn/stage-2/backend/2.3-ai-interface-code/index.md b/docs/zh-cn/stage-2/backend/2.3-ai-interface-code/index.md index 18c9953..f42e65f 100644 --- a/docs/zh-cn/stage-2/backend/2.3-ai-interface-code/index.md +++ b/docs/zh-cn/stage-2/backend/2.3-ai-interface-code/index.md @@ -1,3 +1,161 @@ # 大模型辅助编写接口代码与接口文档 -> 本章节正在编写中，敬请期待... +在之前的课程中，我们学习了如何使用 Figma 等工具完成 UI 设计稿、如何借助 AI 快速生成前端静态页面，以及如何利用 Supabase 构建数据库并实现初步的用户身份验证。现在，一个自然而然的问题摆在了面前：前端页面中那些动感十足的按钮点击后，究竟是如何把数据悄无声息地存进 Supabase 的？当我们需要执行更复杂的业务逻辑（如并发支付、定时推送、数据敏感处理）时，直接让前端连接数据库是安全的吗？ + +这就引出了现代 Web 开发架构中至关重要的一环——**后端 API 接口**。 + +相比于过去纯手工敲出成百上千行的后端路由、控制器与参数校验逻辑，如今我们完全可以借助大模型的强大代码生成能力，将繁杂的基础代码交由 AI 编写。在本节课中，我们将跳出“AI 写的又虚又泛”的怪圈，以真实的业务场景为依托，向你展示如何通过高质量的提示词（Prompt）引导大模型写出健壮、符合行业规范的 Node.js 后端接口，并自动完成接口文档与测试用例的生成。 + +> 💡 **前置知识** +> +> 在学习本节之前，建议你先了解以下内容： +> - [从数据库到 Supabase](../2.2-database-supabase/) - 了解数据库和数据模型的概念。 +> - [Git 和 GitHub 工作流](../2.4-git-workflow/) - 熟悉如何在项目开发中进行版本控制。 +> - [什么是终端/命令行](/zh-cn/appendix/2-development-tools/command-line-shell) - 项目初始化与启动离不开基础的命令操作。 + +# 你将学到 + +1. **什么是 API 接口**：理解前后端通信的桥梁与 RESTful 设计规范。 +2. **大模型赋能服务构建**：如何通过结构化的 Prompt 让 AI 帮你搭建 Node.js + Express 基础工程。 +3. **接口逻辑开发**：引导大模型生成包含严谨业务校验、对接 Supabase 数据库的 CRUD（增删改查）接口。 +4. **自动化接口文档**：让大模型根据代码逆向生成跨团队协作标配的 OpenAPI/Swagger 文档。 +5. **测试与联调闭环**：利用大模型生成 Postman 测试合集与 Jest 单元测试用例，为代码质量兜底。 + +--- + +# 1. 为什么我们需要 API 接口？ + +在传统的理解中，前端是“看得到的部分”，数据库是“存东西的仓库”。但这中间缺少了一个调度员。如果你把整个应用想象成一家餐厅： +- **前端（客户端）** 是餐厅的菜单和点餐桌，客人在这里浏览菜品并提出需求。 +- **数据库（Supabase 等）** 是餐厅的后厨仓库，里面存放着所有的食材和账本。 +- **后端 API 接口** 就是餐厅的服务员。客人不能直接冲进后厨拿食材（不仅混乱，而且容易引发安全问题），而是需要把“点单诉求”（HTTP Request）告诉服务员。服务员进行核对（参数校验、权限鉴权）后，去后厨调取对应的内容，再将“做好的菜”（HTTP Response，通常是 JSON 格式的数据）端回给客人。 + +通过 API 接口，我们实现了明确的**前后端分离**：前端只关心页面如何渲染，后端只专注于业务逻辑、数据处理与安全防护。 + +--- + +# 2. 项目架构设计与初始化 + +一个结构清晰的项目骨架，是大模型能写出好代码的先决条件。我们在让 AI 写代码前，自己心里必须对工程结构有个底。 + +## 2.1 常见的 API 工程结构 +即使是使用大模型生成代码，我们也绝不能把所有代码都塞进一个 `server.js` 文件中。一个易于维护的 Node.js 后端架构通常如下所示： + +```text +my-api-project/ +├── .env # 敏感环境变量（如 API Keys、数据库连接串） +├── server.js # 项目入口（服务器启动、全局中间件注册） +├── package.json # 依赖管理文件 +├── src/ +│ ├── routes/ # 路由层：定义 URL 路径与请求方法 +│ ├── controllers/ # 控制器层：处理业务请求参数，调用服务并返回响应 +│ ├── services/ # 服务层：封装数据库交互和核心业务逻辑 +│ └── middlewares/ # 中间件：登录鉴权、错误全局捕获 +└── docs/ # API 文档存放目录 +``` + +## 2.2 借助 AI 完成工程初始化 +与其手动 `npm init` 并一个个安装依赖，不如直接将上述规范以 Prompt 的形式喂给大模型： + +> 🗣️ **给大模型的提示词（Prompt 示例）：** +> "帮我搭建一个 Node.js 后端项目，要能连接 Supabase 数据库，结构清晰一点，方便以后维护。" + +运行 AI 返回的代码后，你就能在 `localhost:3000` 获得一个具备企业级雏形的后端应用了。 + +--- + +# 3. 核心实战：大模型辅助接口开发 + +这是本章节最核心的部分。大模型写出的代码往往容易存在“逻辑漏洞”或“表面敷衍”，原因在于开发者给的上下文不足。**大模型不怕需求复杂，最怕需求模糊。** + +以我们在 [数据库章节](../2.2-database-supabase/) 中提到的 `menu_items` (菜单表) 的新增接口为例，看如何写出一份高质量的 Prompt。 + +## 3.1 赋予大模型完整上下文 +在请求 AI 写接口之前，一定要提供**数据库字段定义（Schema）**和**具体的约束条件**。 + +> 🗣️ **高质量提示词（Prompt）模板：** +> "帮我写一个新增菜单的接口，菜单有商品名、价格、分类（汉堡、小食、饮料）、是否上架这几个信息。商品名和价格必须填，价格不能是负数。用户输入不对的时候要提示错误。" + +## 3.2 审查大模型生成的代码 +大模型生成的代码通常会像下面这样清晰地拆分了职责： + +```javascript +// services/menuService.js +const { createClient } = require('@supabase/supabase-js'); +const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY); + +exports.createMenuItem = async (menuData) => { + // 调用 Supabase SDK 将数据推入表内 + const { data, error } = await supabase + .from('menu_items') + .insert([menuData]) + .select(); + + if (error) throw new Error(`数据库插入失败: ${error.message}`); + return data[0]; +}; +``` + +你可以发现，通过这种方式生成的代码，不仅结构合理，而且将 Supabase 的初始化、错误捕获以及异常处理都考虑在内，这与简单要求“写个新增接口”得到的面条式代码（Spaghetti Code）有着天壤之别。 + +--- + +# 4. 解放双手：自动生成接口文档 + +对于开发团队而言，没有文档的 API 就是一个盲盒。前端工程师无法猜测你需要传入什么参数，也不能预测会返回什么结构。业界最通用的 API 描述规范是 **OpenAPI (此前也称 Swagger)**。 + +过去，手写 YAML 或者 JSON 格式的 Swagger 文档极其痛苦且容易出错。现在，这也成了大模型最擅长的领域。 + +你可以直接选中你刚才写的 `routes` 和 `controllers` 代码，然后丢给大模型： + +> 🗣️ **生成文档的提示词：** +> "帮我根据上面的代码生成一份接口文档，要写清楚每个参数是什么意思、返回什么数据，方便前端同事对接。" + +在这个过程中，你甚至可以要求 AI 补全字段的说明（Description）和 Mock 数据（如 `price_cents: 1200` 代表 12 美元），极大地降低了沟通成本。 + +--- + +# 5. 保驾护航：生成测试代码与 Postman 集合 + +代码写好、文档出炉，还差最后一步：验证代码到底能不能跑通。 + +## 5.1 生成 Postman / Apifox 测试配置 +在接口开发中，我们通常使用 Postman 这样的可视化工具来模拟前端发送 HTTP 请求。如果不使用大模型，你需要手动填入 URL、逐个添加 Header（请求头）以及拼接 JSON 请求体。 + +你只需向 AI 发送指令： +> "帮我把这份接口文档转成 Postman 可以导入的格式，要包含正常请求和错误请求的例子。" + +拿到 JSON 文本后，保存为 `menu_api.json` 并拖入 Postman，你瞬间就获得了一套开箱即用的测试点击面板。 + +## 5.2 编写自动化单元测试 +如果你追求更严谨的工程质量，可以让大模型帮你使用 `Jest` 等测试框架编写单元测试（Unit Tests），对核心业务逻辑进行边界测试（比如传入负数价格时，数据库层的校验是否生效）。 + +--- + +# 6. 后端接口必知的最佳实践 + +即使有 AI 的协助，作为整个系统的“把关人”，你依然需要了解并审核以下这些核心准则： + +1. **RESTful 规范的路径命名**： + - 好的设计：`GET /api/users`（获取用户列表）、`POST /api/users`（创建用户）。URL 应该代表“资源”的名词。 + - 错误的设计：`POST /api/getUser` 或 `POST /api/createUser`。动词应该交由 HTTP Method (GET/POST/PUT/DELETE) 来体现。 +2. **规范的 HTTP 状态码**： + - 200/201：请求成功 / 资源创建成功。 + - 400：Bad Request，前端传参格式错误、少传了必填项。 + - 401/403：Unauthorized / Forbidden，用户未登录或无权操作。 + - 404：NotFound，资源不存在。 + - 500：Server Error，后端代码报错或数据库挂了，绝对尽量避免将报错调用栈直接暴露给前端（会有安全隐患）。 +3. **永远不信任用户的输入**：前端的输入可能是伪造的，所有核心参数校验必须在后端接口中再做一次。 + +# 7. 总结 + +通过本章节的学习，你实现了开发视角的真正转变：你不再是被困在语法和标点符号中的“打字员”，而是上升成为了**系统设计师和架构指挥官**。 +你已经掌握了： +1. **API 接口与前后端分离**的核心系统思维。 +2. **如何通过提供上下文与分层结构理念**，大幅提高大模型生成服务端代码的质量。 +3. 把繁琐的**文档编写**和**测试用例构建**，巧妙地转化为 AI 擅长的自动化任务。 +4. 结合此前学过的 **Supabase** 知识，打通了从客户端请求到底层数据库更新的完整数据流。 + +::: tip 💡 下一步 +当你的数据流和后端服务都准备就绪后，它目前还只能在你的本地电脑上“自娱自乐”。在接下来的章节中，我们将学习如何把这套辛辛苦苦建立的服务**部署（Deploy）到公网服务器上**，让你的产品能被全世界的用户访问。 +::: \ No newline at end of file diff --git a/docs/zh-cn/stage-3/core-skills/workflow/index.md b/docs/zh-cn/stage-3/core-skills/workflow/index.md index 9c8160a..18e8e04 100644 --- a/docs/zh-cn/stage-3/core-skills/workflow/index.md +++ b/docs/zh-cn/stage-3/core-skills/workflow/index.md @@ -1,684 +1,942 @@ -# Claude Code 工作流最佳实践 +# AI 辅助开发工作流 -## 前言 +在前面的章节中，我们学习了如何使用 AI IDE 进行代码编写、如何使用 Git 管理代码版本、如何设计和实现 API 接口。但是，当你面对一个真实的开发任务时，你可能会遇到这些问题： -Claude Code 不仅仅是一个 AI 编程助手，更是一种全新的开发方式。它改变了开发者与代码、与工具、与团队的交互模式。掌握正确的工作流，可以让你的开发效率提升 10 倍，代码质量显著提高，同时减少重复性工作带来的疲惫感。 +- "这个项目有上千个文件，我该从哪里开始？" +- "老板让我加个新功能，但我不熟悉这部分代码" +- "这个 Bug 不知道在哪，代码太多了" +- "要重构这堆代码，但怕改出问题" -### 为什么需要专门的工作流？ +这些问题的本质是：**如何在真实的开发场景中，高效地使用 AI 工具完成工作？** -传统的开发工作流是基于人类开发者设计的：阅读文档、理解代码、编写实现、手动测试、代码审查。而 AI 辅助开发需要一种全新的协作模式： +在本节课中，我们将学习如何建立一套系统化的 AI 辅助开发工作流，让你能够在不同的开发场景下，都能高效地使用 AI 工具。我们会通过具体的案例，演示如何在新功能开发、Bug 修复、代码重构等场景下使用 AI。 -- **上下文管理**：AI 有上下文窗口限制，需要策略性地传递信息 -- **任务分解**：复杂任务需要拆分成 AI 可以理解和执行的小步骤 -- **验证机制**：AI 生成的代码需要系统化的验证流程 -- **知识沉淀**：团队需要共享 AI 的配置和项目知识 +> 💡 **前置知识** +> +> 在学习本节之前，建议你先了解以下内容： +> - [AI IDE 基础](../../stage-1/ai-ide/) - 掌握 AI IDE 的基本使用 +> - [Git 和 GitHub 工作流](../../stage-2/backend/2.4-git-workflow/) - 了解代码版本管理 +> - [大模型辅助编写接口代码](../../stage-2/backend/2.3-ai-interface-code/) - 了解 AI 辅助开发的基本概念 -### 本文涵盖的内容 +::: info 📚 你将学到 -本文将系统介绍 Claude Code 在不同场景下的最佳实践，包括： +1. 理解 AI 在开发流程中的定位和能力边界 +2. 掌握不同项目类型的 AI 辅助开发策略 +3. 学会在新功能开发、Bug 修复、代码重构等场景下使用 Claude Code +4. 建立项目知识库，提高与 Claude Code 的协作效率 +5. 掌握提高 AI 协作效率的实用技巧 -1. **日常开发工作流** - 新功能开发、Bug 修复的标准流程 -2. **代码重构工作流** - 安全、高效地进行大规模重构 -3. **Code Review 工作流** - 利用 AI 提升代码审查质量 -4. **团队协作配置** - 共享配置、统一规范、知识管理 -5. **CI/CD 集成** - 将 Claude Code 融入自动化流程 - -### 核心原则 - -使用 Claude Code 需要建立正确的工作方式。它能力强大，但并非万能，需要合理的分工和有效的协作。 - -**合理的分工** - -Claude 适合处理重复性工作，例如阅读代码、生成样板、查找 Bug、统一代码格式等。但架构设计、业务理解、关键决策等需要由人来把控。 - -**建立信任** - -初次使用时，建议从简单任务开始（如变量重命名、简单函数重构），观察 Claude 的理解能力和执行效果。随着对其能力边界的了解，再逐步增加任务复杂度。 - -**清晰的上下文传递** - -项目背景应通过 CLAUDE.md 文档提供，具体修改目标需使用 `@文件名` 明确指向，预期结果也要描述清楚。模糊的指令会导致偏离预期的输出。 - -**验证环节不可省略** - -Claude 生成的代码需要经过测试验证、类型检查和风格审查。最终的代码质量责任仍在于开发者，AI 是辅助工具而非替代品。 - -## 日常开发工作流 - -日常开发占据了程序员大部分的工作时间。建立标准化的日常开发工作流，可以让你更高效地完成新功能开发和 Bug 修复，同时保持代码质量。 - -### 新功能开发流程 - -新功能开发是最常见的开发任务。一个完整的 AI 辅助开发流程包含以下步骤： - -``` -1. 理解需求 → 2. 分析现有代码 → 3. 设计实现方案 -→ 4. 编写代码 → 5. 测试与调试 → 6. 代码审查 → 7. 提交代码 -``` - -#### 快速开始 - -**1. 了解项目结构** - -```text -@directory src/ -``` - -让 Claude 快速浏览项目目录结构，了解： - -- 代码组织方式（是否分层、模块如何划分） -- 使用的技术栈（框架、库类型） -- 现有的命名和文件组织规范 - -> **为什么？** 在不熟悉的项目中开发，盲目动手容易写出不符合项目风格的代码。让 Claude 先"看"一遍项目，生成的代码会更契合现有架构。 - ---- - -**2. 查找相关代码** - -```text -@grep "关键词" --glob "*.ts" -``` - -查找与当前任务相关的现有代码： - -- 是否已有类似功能可以复用 -- 其他人是如何处理类似场景的 -- 需要修改或关联哪些文件 - -> **为什么？** 避免"重复造轮子"，同时确保新代码与现有代码风格一致。 - ---- - -**3. 制定计划** - -```text -使用 /plan 或直接描述需求 -``` - -让 Claude 制定详细的实施计划： - -- 涉及哪些文件的修改 -- 实现的先后顺序 -- 可能遇到的技术难点 - -> **为什么？** 复杂任务拆分成小步骤后，执行更可控，出错也更容易定位。 - ---- - -**4. 生成代码** - -```text -让 Claude 根据计划生成代码框架 -``` - -按计划逐步生成代码，从基础框架开始： - -- 先生成类型定义和接口 -- 再生成核心逻辑 -- 最后处理边界情况和错误处理 - -> **为什么？** 框架先行可以确保结构合理，细节后填可以边写边验证。 - ---- - -**5. 运行测试** - -```text -!npm test -``` - -每次代码修改后立即运行测试： - -- 单元测试验证函数逻辑 -- 集成测试验证模块交互 -- 手动测试验证用户交互 - -> **为什么？** 及早发现问题，避免错误累积到最后难以定位。 - ---- - -**6. 代码审查** - -```text -使用 /review 或让 Claude 审查变更 -``` - -让 Claude 从多个维度审查代码： - -- 安全问题（SQL 注入、XSS 等） -- 性能问题（N+1 查询、内存泄漏等） -- 代码风格（是否符合项目规范） - -> **为什么？** AI 能发现人眼容易遗漏的问题，提高代码质量。 - ---- - -**7. 提交代码** - -```text -/commit -``` - -生成符合规范的提交信息： - -- 自动分析代码变更 -- 生成 conventional commit 格式的提交信息 -- 包含变更摘要和关键细节 - -> **为什么？** 清晰的提交信息让代码历史更易读，后续回溯问题更方便。 - -### Bug 修复流程 - -Bug 修复需要快速定位问题、理解根因、实施修复并验证。 - -**标准流程：** - -1. **收集错误信息** - 错误消息、复现步骤、环境信息 -2. **定位问题代码** - 搜索相关代码、分析调用链 -3. **分析根因** - 理解为什么会出错、评估影响范围 -4. **实施修复** - 编写修复代码、添加回归测试 -5. **提交修复** - 生成提交信息、记录 Bug 原因 - -**实用命令：** - -```bash -# 搜索错误信息 -@grep "错误消息" --glob "*.ts" - -# 查看函数调用链 -@grep "functionName" --context 5 - -# 运行相关测试 -!npm test -- 文件名.test.ts - -# 查看最近改动 -!git diff -``` - -### 日常开发 Checklist - -| 阶段 | 检查项 | 操作命令/方法 | -|-----|--------|--------------| -| **开始前** | 了解项目结构 | `@directory src/` | -| | 查看相关代码 | `@grep "keyword" --glob "*.ts"` | -| **编码中** | 制定实施计划 | `/plan` | -| | 生成代码框架 | 直接描述需求 | -| **测试阶段** | 运行单元测试 | `!npm test` | -| | 检查测试覆盖率 | `!npm run test:coverage` | -| **审查阶段** | 自动代码审查 | `/review` | -| | 类型检查 | `!npm run typecheck` | -| **提交阶段** | 生成提交信息 | `/commit` | - -### 常见陷阱 - -**陷阱 1：一次性给太多任务** - -``` -❌ "帮我实现一个完整的电商系统" -✅ "先实现用户注册功能" -``` - -**陷阱 2：不提供足够的上下文** - -``` -❌ "修复这个 bug" -✅ "登录功能报错'Invalid token'，错误在 src/middleware/auth.ts" -``` - -**陷阱 3：不验证 AI 生成的代码** - -``` -❌ 直接接受所有修改 -✅ 每次修改后运行测试，手动验证关键功能 -``` - -## 代码重构工作流 - -重构就是"在不改变功能的前提下，改善代码结构"。听起来简单，但实际操作中很容易出问题。 - -### 重构前：先看清楚再动手 - -动手之前，先搞清楚两件事：要改哪些文件？这些文件被谁引用？ - -```bash -# 找出需要重构的文件 -@grep "旧模式代码" --glob "*.ts" - -# 看看这些文件被哪些地方引用 -@grep "import.*ModuleName" --glob "*.ts" -``` - -### 创建安全网 - -重构就像走钢丝，需要安全网。 - -```bash -# 第一步：创建新分支，别在主分支上搞 -!git checkout -b refactor/描述你的重构 - -# 第二步：确认现有测试都能通过 -!npm test -``` - -如果测试本来就不过，先修测试再重构。否则你根本不知道重构是不是搞坏了东西。 - -### 自动验证配置 - -让 Claude 每次改代码后自动跑测试，省心又安全： - -::: details 点击查看配置 -```json -// .claude/settings.json -{ - "hooks": { - "afterEdit": ["npm run test:related"], - "beforeCommit": ["npm run test"] - } -} -``` ::: -这样配置后，每次 Claude 修改代码都会自动运行测试，失败了会提醒你。 +# 1. 理解 AI 的能力边界 -### 重构的核心原则 +在开始使用 AI 辅助开发之前，我们需要先理解 AI 能做什么、不能做什么。这样才能建立正确的协作方式。 -记住三句话： +## 1.1 AI 擅长什么 -1. **小步走** - 别想着一次改完，改一点验证一点 -2. **有测试才动** - 没测试的代码先补测试，再重构 -3. **重构别改功能** - 只改结构，不改行为。想优化性能？另开一个 PR +把 AI 想象成一个很聪明但需要明确指令的助手。它能根据你的描述快速生成代码框架，也能在几秒钟内读完几千行代码找到你要的部分。遇到明显的语法错误、常见的安全漏洞，它也能帮你发现。那些重复性的工作，比如批量重命名变量、格式化代码、生成文档注释，交给它最合适不过。 -### 重构检查清单 +简单来说，AI 擅长的是那些有明确规则、可以自动化的工作。 -每改完一批代码，跑一遍这些检查： +## 1.2 AI 不擅长什么 -| 检查项 | 命令 | 通过标准 | -|--------|------|----------| -| 类型检查 | `npm run type-check` | 无类型错误 | -| 相关测试 | `npm run test:related` | 相关测试通过 | -| 全部测试 | `npm test` | 所有测试通过 | -| 代码风格 | `npm run lint` | 无 lint 错误 | -| 构建测试 | `npm run build` | 构建成功 | +但 AI 也有它的局限性。它不了解你的业务逻辑——除非你详细告诉它，否则它不知道你们公司的订单流程是怎么走的。技术选型、架构设计这种需要权衡利弊的决策，它也做不了，因为这需要你的经验和对项目的理解。你们团队的特殊规范，比如"所有 API 都要加日志"、"错误码必须用枚举"，AI 也不会知道，需要你配置或者明确告诉它。 -只要有一项不过，别继续改，先修复。 +最重要的是，AI 生成的代码不能直接用，你必须审查和测试。它可能会写出看起来对但实际有问题的代码，也可能忽略一些边界情况。 -## Code Review 工作流 +## 1.3 怎么和 AI 协作 -代码审查就是让同事检查你的代码，帮你发现问题和改进点。但这事儿挺累人的——看代码费眼，还容易漏掉问题。 +理解了 AI 的能力边界，协作方式就清楚了：你负责想清楚要做什么、做决策、把关质量；AI 负责执行具体的编码工作、查找信息、发现明显的问题。 -Claude 可以帮你做第一轮审查，把明显的问题先筛出来，人只要关注重要的东西就行。 +就像你和一个初级开发者合作一样——你告诉他要做什么，他去实现，然后你审查代码。区别是 AI 的执行速度快得多，但判断力不如人。 -### 审查要看什么？ +# 2. 不同项目类型的开发策略 -按优先级排个序： +不同类型的项目，开发方式和 AI 使用策略也不一样。选择合适的策略可以大大提高开发效率。 -| 优先级 | 检查项 | 说明 | -| :--- | :--- | :--- | -| 🔴 最高 | 安全问题 | SQL 注入、密码硬编码、权限漏洞 | -| 🟡 高 | 性能问题 | N+1 查询、内存泄漏 | -| 🟢 中 | 代码质量 | 命名不规范、重复代码 | -| ⚪ 低 | 风格问题 | 缺少空格、注释不完整 | +## 2.1 全新项目（从零开始） -### 提交 PR 前：先自己审一遍 +**项目特点：** +- 没有历史包袱，可以自由设计 +- 需要建立项目结构和代码规范 +- 适合快速迭代和试错 -```text -@file src/你改的文件.ts 审查这段代码，看看有没有安全问题 +**推荐工作流：** + +**第一步：规划项目结构** + +在开始编码之前，先让 AI 帮你规划项目结构和技术选型： + +``` +我要做一个任务管理应用，功能包括： +- 用户注册和登录 +- 创建、编辑、删除任务 +- 任务分类和标签 +- 任务提醒 + +请帮我： +1. 推荐合适的技术栈 +2. 设计项目目录结构 +3. 规划数据库表结构 ``` -让 Claude 帮你检查： +**第二步：搭建基础框架** -- 有没有安全漏洞 -- 有没有性能问题 -- 逻辑有没有明显错误 +根据规划，让 AI 创建基础的项目结构： -### 写好 PR 描述 +``` +按照刚才的规划，帮我： +1. 创建项目目录结构 +2. 初始化配置文件（package.json、.env 等） +3. 创建基础的服务器代码 +``` -好的 PR 描述能让审查者快速理解你在做什么。 +**第三步：逐个实现功能** -::: details 标准模板 +按照优先级，逐个实现功能模块： + +``` +现在实现用户注册功能，要求： +- 邮箱和密码注册 +- 密码加密存储 +- 邮箱验证 +``` + +**关键点：** +- 一开始就建立好代码规范，让 AI 按照规范生成代码 +- 每完成一个功能模块就测试验证 +- 及时更新项目文档 + +## 2.2 成熟项目（已有大量代码） + +**项目特点：** +- 代码量大，有历史规范 +- 需要保持代码风格一致性 +- 修改需要考虑影响范围 + +**推荐工作流：** + +**第一步：了解项目结构** + +在修改代码之前，先让 AI 帮你了解项目： + +``` +这是一个电商项目，我需要添加优惠券功能。 +请帮我： +1. 分析项目的整体结构 +2. 找到订单相关的代码 +3. 看看其他类似功能是怎么实现的 +``` + +**第二步：找到参考代码** + +让 AI 找到项目中类似的实现，作为参考： + +``` +找一下项目中其他促销活动（如满减、折扣）是怎么实现的 +``` + +**第三步：模仿现有风格** + +让 AI 参考现有代码的风格来实现新功能： + +``` +参考满减活动的实现方式，帮我实现优惠券功能 +保持相同的代码风格和目录结构 +``` + +**关键点：** +- 先理解再动手，避免破坏现有架构 +- 保持代码风格一致性 +- 修改后要测试相关功能 + +## 2.3 快速原型（验证想法） + +**项目特点：** +- 追求速度，不太在意代码质量 +- 用于验证产品想法或技术方案 +- 可能会被丢弃或重写 + +**推荐工作流：** + +**直接描述需求，快速实现：** + +``` +做一个简单的待办事项应用，要求： +- 能添加、删除、标记完成任务 +- 数据存储在本地 +- 界面简洁，能用就行 +``` + +**快速迭代：** + +``` +加个搜索功能 +改成深色主题 +添加任务分类 +``` + +**关键点：** +- 不用太在意代码质量和规范 +- 快速验证想法，及时调整方向 +- 如果原型成功，后续需要重构 + +## 2.4 维护项目（修 Bug 为主） + +**项目特点：** +- 代码已经稳定，主要是修复问题 +- 需要快速定位问题 +- 修改要谨慎，避免引入新问题 + +**推荐工作流：** + +**第一步：定位问题** + +``` +用户反馈：点击"提交订单"按钮后，页面卡住不动 +控制台报错：TypeError: Cannot read property 'id' of undefined + +请帮我： +1. 分析可能的原因 +2. 找到相关的代码 +``` + +**第二步：分析根因** + +``` +看看这个错误是在什么情况下产生的 +检查一下数据流向 +``` + +**第三步：实施修复** + +``` +修复这个问题，并： +1. 添加防御性代码，避免类似问题 +2. 添加错误提示，提升用户体验 +``` + +**关键点：** +- 修复后要充分测试，确保不影响其他功能 +- 添加防御性代码，提高系统健壮性 +- 记录问题和解决方案，方便后续参考 + +# 3. 常见开发任务的工作流 + +在日常开发中，我们会遇到各种不同的任务。下面介绍几种最常见任务的 AI 辅助工作流。 + +## 3.1 开发新功能 + +**场景：** 产品经理给了你一个新需求，需要实现一个新功能。 + +**完整工作流：** + +**步骤 1：理解需求**（你自己完成） + +在开始编码之前，先搞清楚： +- 要实现什么功能？ +- 输入和输出是什么？ +- 有哪些边界条件和异常情况？ +- 性能和安全要求是什么？ + +**步骤 2：了解现有代码**（让 AI 帮你） + +``` +我需要实现用户评论功能，请帮我： +1. 看看项目中有没有类似的功能 +2. 找到用户数据和文章数据的存储方式 +3. 了解项目的数据库操作规范 +``` + +**步骤 3：制定实现计划**（和 AI 一起） + +``` +基于刚才的分析，实现评论功能需要： +1. 创建评论数据模型 +2. 实现评论的增删改查 API +3. 在前端添加评论展示和发表功能 + +请帮我确认这个计划是否合理，有没有遗漏的地方 +``` + +**步骤 4：实现功能**（AI 生成，你审查） + +``` +按照计划，先实现评论数据模型 +要求： +- 包含评论内容、作者、文章 ID、创建时间 +- 支持评论的嵌套回复 +- 添加必要的索引 +``` + +``` +现在实现评论的 API 接口 +要求： +- 发表评论 +- 删除评论（只能删除自己的） +- 获取文章的所有评论 +- 支持分页 +``` + +``` +最后实现前端的评论组件 +要求： +- 显示评论列表 +- 评论发表表单 +- 支持回复评论 +``` + +**步骤 5：测试验证**（你自己完成） + +- 手动测试主要流程 +- 测试边界情况（空内容、超长内容等） +- 测试权限控制（不能删除别人的评论） +- 让 AI 帮你写自动化测试 + +**实际对话示例：** + +``` +你：我要加一个用户评论功能，用户可以对文章发表评论 + +AI：好的，我先了解一下项目结构。 + [AI 分析项目代码] + 我看到项目已经有用户系统（models/user.js）和文章系统（models/article.js）。 + + 实现评论功能需要： + 1. 创建评论数据模型（models/comment.js） + 2. 添加评论相关的 API（routes/comment.js） + 3. 在文章详情页添加评论展示和发表功能 + + 需要我开始实现吗？ + +你：好的，开始吧。先创建数据模型 + +AI：[生成 models/comment.js 代码] + 我已经创建了评论数据模型，包含以下字段： + - id: 评论 ID + - content: 评论内容 + - userId: 作者 ID + - articleId: 文章 ID + - parentId: 父评论 ID（用于嵌套回复） + - createdAt: 创建时间 + + 接下来实现 API 接口吗？ + +你：是的，实现 API 接口 +``` + +## 3.2 修复 Bug + +**场景：** 用户报告了一个问题，需要快速定位和修复。 + +**完整工作流：** + +**步骤 1：收集信息**（你自己完成） + +记录以下信息： +- 错误信息是什么？ +- 如何复现这个问题？ +- 什么时候开始出现的？ +- 影响范围有多大？ + +**步骤 2：定位问题**（让 AI 帮你） + +``` +用户反馈：点击"提交订单"按钮后，页面卡住不动 +浏览器控制台报错：TypeError: Cannot read property 'id' of undefined +错误发生在 checkout.js 第 45 行 + +请帮我： +1. 分析可能的原因 +2. 找到相关的代码 +3. 检查数据流向 +``` + +**步骤 3：分析根因**（和 AI 一起） + +``` +看看这个 user 对象是从哪里来的 +检查一下在什么情况下 user 会是 undefined +``` + +**步骤 4：实施修复**（AI 生成，你审查） + +``` +修复这个问题，要求： +1. 添加防御性代码，检查 user 是否存在 +2. 如果 user 不存在，跳转到登录页 +3. 添加友好的错误提示 +``` + +**步骤 5：验证修复**（你自己完成） + +- 按照原来的步骤复现，确认问题解决 +- 测试相关功能，确保没有引入新问题 +- 思考是否有其他地方存在类似问题 + +**实际对话示例：** + +``` +你：用户反馈登录后刷新页面就退出了 + +AI：这通常是 token 存储或验证的问题。让我检查一下： + 1. token 是存在哪里的？localStorage 还是 cookie？ + 2. 刷新页面时有没有重新读取 token？ + + 请告诉我 token 相关的代码在哪个文件 + +你：在 utils/auth.js + +AI：[分析 utils/auth.js] + 我找到问题了：token 存在 sessionStorage 里， + 刷新页面后 sessionStorage 会清空。 + + 解决方案：改用 localStorage 存储 token + + 需要我修改吗？ + +你：好的，改一下 + +AI：[修改代码] + 已经修改完成，现在 token 会存储在 localStorage 中， + 刷新页面后不会丢失。 + + 建议你测试一下： + 1. 登录后刷新页面，确认还是登录状态 + 2. 关闭浏览器重新打开，确认还是登录状态 +``` + +## 3.3 重构代码 + +**场景：** 代码变得难以维护，需要重构以提高代码质量。 + +**完整工作流：** + +**步骤 1：确定重构目标**（你自己完成） + +明确以下问题： +- 要解决什么问题？（代码重复？结构混乱？性能问题？） +- 重构的范围有多大？ +- 能接受的风险程度？ + +**步骤 2：制定重构计划**（和 AI 一起） + +``` +这三个函数（getUserList、getArticleList、getCommentList） +有很多重复代码，都是做分页、排序、筛选。 + +请帮我： +1. 分析重复的部分 +2. 提出重构方案 +3. 评估重构的风险 +``` + +**步骤 3：准备安全网**（让 AI 帮你） + +``` +在重构之前，先帮我写测试用例 +确保重构后功能不变 +``` + +**步骤 4：逐步重构**（AI 执行，你验证） + +``` +按照刚才的方案，先提取公共函数 +``` + +``` +现在优化数据结构 +``` + +``` +最后更新调用的地方 +``` + +**步骤 5：验证结果**（你自己完成） + +- 运行所有测试，确保通过 +- 手动测试关键功能 +- 检查代码质量是否提升 + +**实际对话示例：** + +``` +你：这三个函数有很多重复代码，能帮我重构一下吗？ + [贴上三个函数的代码] + +AI：我分析了一下，这三个函数的主要区别是： + - getUserList：获取用户列表 + - getArticleList：获取文章列表 + - getCommentList：获取评论列表 + + 它们的共同逻辑是：分页、排序、筛选 + + 重构方案： + 1. 提取通用的 getList 函数 + 2. 将不同的部分作为参数传入 + + 这样可以减少 80% 的重复代码。 + + 需要我实现吗？ + +你：好的，但是先帮我写测试用例 + +AI：[生成测试用例] + 我已经为这三个函数写了测试用例， + 覆盖了主要的使用场景。 + + 现在可以开始重构了吗？ + +你：可以，开始重构 + +AI：[重构代码] + 重构完成。我创建了一个通用的 getList 函数， + 三个原来的函数现在都调用这个通用函数。 + + 请运行测试确认功能正常：npm test +``` + +## 3.4 代码审查 + +**场景：** 同事提交了代码，需要你审查。 + +**完整工作流：** + +**步骤 1：快速了解改动**（让 AI 帮你） + +``` +总结一下这次 PR 做了什么改动 +主要修改了哪些文件 +``` + +**步骤 2：检查常见问题**（让 AI 帮你） + +``` +检查这次改动： +1. 有没有安全问题（SQL 注入、XSS 等） +2. 有没有性能问题（N+1 查询、内存泄漏等） +3. 有没有明显的 Bug +4. 代码风格是否符合项目规范 +``` + +**步骤 3：深入审查**（你自己完成） + +- 业务逻辑是否正确 +- 是否考虑了边界情况 +- 是否有更好的实现方式 +- 是否需要添加测试 + +**步骤 4：给出反馈**（你自己完成） + +- 指出需要修改的地方 +- 解释为什么要这样改 +- 提供改进建议 + +**实际对话示例：** + +``` +你：帮我审查一下这个 PR + [提供 PR 链接或代码] + +AI：我审查了这次改动，发现以下问题： + + 1. 安全问题： + - 第 23 行：用户输入没有转义，可能有 XSS 风险 + - 第 45 行：SQL 查询直接拼接字符串，有注入风险 + + 2. 性能问题： + - 第 67 行：在循环里查询数据库，会产生 N+1 问题 + + 3. 代码质量： + - handleSubmit 函数太长（200 行），建议拆分 + - 缺少错误处理 + + 需要我详细说明这些问题吗？ + +你：详细说一下 SQL 注入的问题 + +AI：在第 45 行： + ```javascript + const query = `SELECT * FROM users WHERE name = '${userName}'`; + ``` + + 这种写法直接将用户输入拼接到 SQL 语句中， + 如果用户输入 `' OR '1'='1`，就会变成： + ```sql + SELECT * FROM users WHERE name = '' OR '1'='1' + ``` + 这会返回所有用户数据。 + + 正确的做法是使用参数化查询： + ```javascript + const query = 'SELECT * FROM users WHERE name = ?'; + db.query(query, [userName]); + ``` + + 需要我修改吗？ +``` + +# 4. 建立项目知识库 + +为了让 AI 更好地理解你的项目，建议在项目中建立知识库。这样 AI 就能按照你的规范和习惯工作。 + +## 4.1 创建项目说明文件 + +在项目根目录创建 `CLAUDE.md` 或 `AGENTS.md` 文件，记录项目的关键信息： ```markdown -## 做了什么 -用一句话说清楚改了啥 +# 项目说明 -## 为什么改 -说明改动的背景和原因 +## 项目概述 +这是一个在线教育平台，提供课程管理、用户学习、作业提交等功能。 -## 改了哪些地方 -- 改动点 1 -- 改动点 2 +## 技术栈 +- 前端：React 18 + TypeScript + Vite +- 后端：Node.js + Express + PostgreSQL +- 部署：Vercel（前端）+ Railway（后端） -## 测试情况 -- [ ] 单元测试通过 -- [ ] 手动验证通过 +## 项目结构 +``` +src/ +├── components/ # React 组件 +├── pages/ # 页面组件 +├── api/ # API 调用 +├── utils/ # 工具函数 +└── types/ # TypeScript 类型定义 +``` + +## 代码规范 +- 使用 ESLint 和 Prettier 格式化代码 +- 组件文件使用 PascalCase（如 UserProfile.tsx） +- 工具函数使用 camelCase（如 formatDate.ts） +- 常量使用 UPPER_SNAKE_CASE（如 API_BASE_URL） + +## 开发流程 +1. 从 main 分支创建功能分支 +2. 开发完成后提交 PR +3. 代码审查通过后合并 + +## 常见任务 +- 启动开发服务器：`npm run dev` +- 运行测试：`npm test` +- 构建生产版本：`npm run build` +- 代码格式化：`npm run format` ## 注意事项 -如果会影响其他功能，在这里说明 +- 所有 API 调用都要添加错误处理 +- 用户输入必须做验证和转义 +- 数据库操作使用参数化查询，避免 SQL 注入 +- 敏感信息（密码、token）不能记录到日志 + +## 数据库表结构 +- users: 用户表（id, email, password_hash, created_at） +- courses: 课程表（id, title, description, teacher_id） +- enrollments: 选课表（id, user_id, course_id, enrolled_at） ``` +## 4.2 记录常见问题和解决方案 + +在项目中创建 `docs/troubleshooting.md`，记录常见问题： + +```markdown +# 常见问题 + +## 开发环境问题 + +### 问题：npm install 失败 +**原因：** Node 版本不兼容 +**解决方案：** 使用 Node.js 18 或更高版本 + +### 问题：数据库连接失败 +**原因：** 环境变量未配置 +**解决方案：** 复制 .env.example 为 .env，填写数据库连接信息 + +## 功能问题 + +### 问题：用户登录后刷新页面就退出 +**原因：** Token 存储在 sessionStorage +**解决方案：** 改用 localStorage 存储 token + +### 问题：图片上传失败 +**原因：** 文件大小超过限制 +**解决方案：** 在前端添加文件大小检查，限制为 5MB +``` + +## 4.3 维护技术决策记录 + +创建 `docs/decisions/` 目录，记录重要的技术决策： + +```markdown +# ADR-001: 选择 PostgreSQL 作为数据库 + +## 状态 +已采纳 + +## 背景 +项目需要选择一个关系型数据库，候选方案有 MySQL 和 PostgreSQL。 + +## 决策 +选择 PostgreSQL + +## 理由 +1. 更好的 JSON 支持，适合存储课程内容 +2. 更强大的全文搜索功能 +3. 团队成员更熟悉 PostgreSQL + +## 后果 +- 需要学习 PostgreSQL 特有的功能 +- 部署时需要 PostgreSQL 环境 +``` + +# 5. 提高 AI 协作效率的技巧 + +掌握一些实用技巧，可以让你和 AI 的协作更加高效。 + +## 5.1 描述要清晰具体 + +**不好的描述：** +``` +这个功能有问题 +帮我优化一下 +``` + +**好的描述：** +``` +用户点击"提交"按钮后，表单没有提交 +浏览器控制台报错：Uncaught TypeError: Cannot read property 'value' of null +错误发生在 form.js 第 23 行 + +这个列表加载很慢，有 1000 条数据 +请帮我添加分页功能，每页显示 20 条 +``` + +**关键点：** +- 提供具体的错误信息 +- 说明期望的结果 +- 给出相关的上下文 + +## 5.2 一次只做一件事 + +**不好的做法：** +``` +帮我实现登录、注册、找回密码、个人中心、 +修改密码、邮箱验证这些功能 +``` + +**好的做法：** +``` +先实现登录功能，要求： +- 邮箱和密码登录 +- 记住登录状态 +- 错误提示 + +（完成后）现在实现注册功能 + +（完成后）现在实现找回密码功能 +``` + +**关键点：** +- 将大任务拆分成小任务 +- 每完成一个任务就测试验证 +- 确认没问题再继续下一个 + +## 5.3 及时验证结果 + +**不好的做法：** +- 让 AI 连续修改了 10 个文件 +- 最后发现第一个就错了 +- 浪费了大量时间 + +**好的做法：** +- 修改一个文件，立即测试 +- 确认没问题，再继续 +- 发现问题及时纠正 + +**关键点：** +- 小步快跑，快速反馈 +- 不要盲目信任 AI +- 保持对代码的掌控 + +## 5.4 善用上下文 + +**技巧 1：引用之前的对话** +``` +按照刚才的方案实现 +参考之前的 getUserList 函数 +``` + +**技巧 2：提供相关代码** +``` +这是现有的用户模型代码： +[贴上代码] + +请参考这个风格实现文章模型 +``` + +**技巧 3：说明项目背景** +``` +这是一个电商项目，使用 React + Node.js +已经有用户系统和商品系统 +现在要添加购物车功能 +``` + +## 5.5 保存有用的对话 + +**场景：** 解决了一个复杂问题 + +**做法：** +1. 将解决方案记录到项目文档 +2. 下次遇到类似问题可以参考 +3. 分享给团队其他成员 + +**示例：** + +在 `docs/solutions/` 目录创建文档： + +```markdown +# 解决 N+1 查询问题 + +## 问题描述 +获取文章列表时，每篇文章都要查询一次作者信息， +导致性能问题。 + +## 解决方案 +使用 JOIN 查询，一次性获取所有数据： + +```sql +SELECT articles.*, users.name as author_name +FROM articles +LEFT JOIN users ON articles.author_id = users.id +``` + +**效果：** 查询时间从 2000ms 降低到 50ms + +## 5.6 学会提问的艺术 + +**技巧 1：先问"为什么"** +``` +为什么这段代码会导致内存泄漏？ +为什么要使用 useCallback 而不是普通函数？ +``` + +**技巧 2：请求多个方案** +``` +实现用户认证有哪几种方案？ +各有什么优缺点？ +``` + +**技巧 3：请求解释** +``` +这段代码是怎么工作的？ +能详细解释一下这个算法吗？ +``` + +# 6. 常见问题解答 + +## Q1：AI 生成的代码能直接用吗？ + +**A：** 不能直接用，需要审查和测试。 + +AI 生成的代码可能存在以下问题： +- 逻辑错误或边界情况处理不当 +- 不符合项目的代码规范 +- 存在安全隐患 +- 性能不够优化 + +你需要： +- 仔细阅读生成的代码 +- 理解代码的逻辑 +- 测试各种情况 +- 确认符合项目规范 + +## Q2：AI 理解错了我的意思怎么办？ + +**A：** 及时纠正，重新描述需求。 + +``` +不是这样的，我的意思是... +这个理解不对，应该是... +让我重新描述一下需求... +``` + +如果多次纠正还是不对，可以： +- 提供更多上下文信息 +- 给出具体的代码示例 +- 拆分成更小的任务 + +## Q3：遇到 AI 不会的问题怎么办？ + +**A：** AI 不是万能的，有些问题需要你自己解决。 + +AI 可能无法解决的问题： +- 非常新的技术（AI 的知识有截止日期） +- 你们团队特有的业务逻辑 +- 需要访问外部系统的问题 +- 复杂的性能优化问题 + +这时你需要： +- 查阅官方文档 +- 搜索相关解决方案 +- 咨询有经验的同事 +- 在社区提问 + +## Q4：怎么判断 AI 的建议是否合理？ + +**A：** 用你的经验和知识判断。 + +评估标准： +- 是否符合最佳实践 +- 是否考虑了边界情况 +- 是否有潜在的安全风险 +- 是否符合项目的技术栈 +- 性能是否可接受 + +如果不确定，可以： +- 让 AI 解释为什么这样做 +- 请求提供其他方案 +- 咨询团队成员 + +## Q5：团队协作时怎么用 AI？ + +**A：** 建立共同的规范和知识库。 + +团队协作建议： +- 共享项目的 CLAUDE.md 配置 +- 统一代码规范和风格 +- 记录常见问题的解决方案 +- 定期分享有用的提示词 +- 在代码审查时检查 AI 生成的代码 + +## Q6：如何避免过度依赖 AI？ + +**A：** 保持学习和思考，AI 是辅助工具而不是替代品。 + +建议： +- 理解 AI 生成的代码，不要盲目复制 +- 遇到不懂的概念，主动学习 +- 定期复习基础知识 +- 尝试自己解决问题，再用 AI 验证 +- 参与代码审查，学习他人的经验 + +# 7. 总结 + +通过本章节的学习，你已经掌握了： + +1. **AI 的能力边界**：理解 AI 擅长什么、不擅长什么，建立正确的协作方式 +2. **项目类型策略**：针对全新项目、成熟项目、快速原型、维护项目的不同开发策略 +3. **常见任务工作流**：掌握新功能开发、Bug 修复、代码重构、代码审查的完整流程 +4. **项目知识库**：学会建立项目文档，让 AI 更好地理解你的项目 +5. **协作技巧**：掌握提高 AI 协作效率的实用技巧 + +**关键要点：** + +- **明确分工**：你做决策和把关，AI 做执行和辅助 +- **清晰沟通**：描述要具体，一次做一件事 +- **及时验证**：不要盲目信任，要测试验证 +- **持续学习**：了解 AI 的能力边界，不断优化协作方式 + +记住：AI 是工具，不是替代品。它能让你更高效，但最终的代码质量还是要靠你把关。从简单任务开始，逐步建立信任，你会发现 AI 能帮你节省大量时间，让你专注于更有价值的工作。 + +::: tip 💡 下一步 +在下一章节中，我们将学习如何使用 AI 进行代码审查和质量保证，确保代码的可维护性和安全性。 ::: - -### 审查别人的 PR - -用 Claude 帮你快速了解 PR 的内容： - -```text -帮我审查这个 PR，重点检查安全问题和性能问题 -``` - -Claude 会列出发现的问题，你再重点看这些问题是否属实。 - -### 本地预提交检查 - -在提交前自动跑一遍快速检查： - -::: details 点击查看配置 - -```bash -#!/bin/bash -# .git/hooks/pre-commit - -echo "检查代码..." - -claude "快速检查暂存的代码： -1. 有没有明显的安全问题 -2. 有没有明显的 bug" --strict || exit 1 -``` - -::: - -配置后，每次提交都会自动检查，发现问题会阻止提交。 - -## 团队协作配置共享 - -在团队中使用 Claude Code，需要建立共享的配置和知识库，确保所有成员都能获得一致的 AI 辅助体验。 - -### 项目级配置 - -将 Claude Code 配置提交到仓库，实现团队共享： - -**配置结构：** - -```text -.claude/ -├── settings.json # 团队共享配置 -├── settings.local.json # 个人本地配置（不提交） -├── CLAUDE.md # 项目主文档 -├── .claudeignore # 忽略文件配置 -└── memory/ # 项目记忆 - ├── project-context.md - ├── conventions.md - ├── architecture.md - └── common-pitfalls.md -``` - -**团队共享配置示例：** - -::: details 点击查看 settings.json - -```json -{ - "hooks": { - "beforeEdit": ["npm run type-check"], - "afterEdit": ["npm run lint"], - "beforeCommit": ["npm run test"] - }, - "permissions": { - "allow": [ - "Bash(git status)", - "Bash(git log:*)", - "Bash(npm test:*)", - "Edit(src/**/*.{ts,tsx})" - ], - "ask": [ - "Bash(git commit:*)", - "Bash(git push:*)" - ] - } -} -``` - -::: - -### 项目记忆系统 - -**记忆系统结构：** - -- **project-context.md** - 项目整体上下文 -- **conventions.md** - 代码规范和约定 -- **architecture.md** - 架构设计说明 -- **common-pitfalls.md** - 常见陷阱和解决方案 - -### 团队协作最佳实践 - -| 实践 | 说明 | 实施方法 | -| :--- | :--- | :--- | -| **共享配置** | 将 .claude/ 加入版本控制 | `git add .claude/` | -| **文档规范** | 在 memory/ 中记录项目约定 | 每次架构决策更新文档 | -| **代码审查** | 用 Claude 辅助 Code Review | 提交前运行审查 | -| **统一 Hooks** | 团队使用相同的 pre-commit hooks | 配置在 settings.json | -| **知识同步** | 定期更新项目记忆 | 每迭代更新一次 | - -## CI/CD 集成 - -将 Claude Code 集成到 CI/CD 流程中，可以实现自动化的代码审查、测试生成、安全检查等。 - -### GitHub Actions 集成 - -#### 场景 1：PR 自动审查 - -::: details 点击查看配置 - -```yaml -# .github/workflows/claude-review.yml -name: Claude Code Review - -on: - pull_request: - types: [opened, synchronize] - -jobs: - claude-review: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - - - name: Install Claude Code - run: npm install -g @anthropic-ai/claude-code - - - name: Run Claude Review - env: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - run: | - CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(ts|tsx|js|jsx)$' || true) - - if [ -z "$CHANGED_FILES" ]; then - echo "No relevant files changed" - exit 0 - fi - - claude "审查以下文件的变更： - $CHANGED_FILES - - 检查维度： - 1. 安全漏洞 - 2. 性能问题 - 3. 代码质量 - - 输出格式： - - 🔴 严重问题（阻塞） - - 🟡 警告（建议修复） - - 🟢 建议（可选）" \ - --output pr-review.md - - - name: Comment PR - uses: actions/github-script@v7 - with: - script: | - const fs = require('fs'); - const review = fs.readFileSync('pr-review.md', 'utf8'); - - const hasBlockingIssues = review.includes('🔴'); - - const header = hasBlockingIssues - ? '## ❌ Code Review 未通过\n\n' - : '## ✅ Code Review 通过\n\n'; - - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: header + review - }); - - if (hasBlockingIssues) { - core.setFailed('发现严重问题'); - } -``` - -::: - -#### 场景 2：部署前安全检查 - -::: details 点击查看配置 - -```yaml -# .github/workflows/pre-deploy-security.yml -name: Pre-deploy Security Check - -on: - push: - branches: [main] - -jobs: - security-check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - - - name: Install Claude Code - run: npm install -g @anthropic-ai/claude-code - - - name: Security Scan - env: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - run: | - claude "对代码进行全面的安全扫描： - - 检查以下安全问题： - 1. SQL 注入漏洞 - 2. XSS（跨站脚本攻击） - 3. CSRF（跨站请求伪造） - 4. 敏感信息泄露 - 5. 不安全的依赖项 - - 输出格式： - - 🔴 高危漏洞（立即修复） - - 🟡 中危漏洞（建议修复） - - 🟢 低危漏洞（可选修复）" \ - --output security-report.md - - - name: Check for critical issues - run: | - if grep -q "🔴" security-report.md; then - echo "发现高危安全漏洞！" - cat security-report.md - exit 1 - fi -``` - -::: - -### 本地 Pre-commit Hook - -::: details 点击查看配置 - -```bash -#!/bin/bash -# .git/hooks/pre-commit - -set -e - -echo "🔍 运行 Claude Code 预提交检查..." - -STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$' || true) - -if [ -z "$STAGED_FILES" ]; then - echo "✅ 没有需要检查的代码文件" - exit 0 -fi - -claude "对以下文件进行快速检查： -$STAGED_FILES - -检查项目： -1. 明显的语法错误 -2. 类型错误 -3. 明显的安全问题 -4. 代码风格问题 - -如果发现严重问题，返回非零退出码。" \ - --strict || { - echo "❌ 预提交检查失败" - exit 1 - } - -echo "✅ 预提交检查通过！" -``` - -::: - -### CI/CD 集成最佳实践 - -**分层检查策略：** - -```text -本地开发 → Pre-commit → PR 审查 → 合并前检查 → 部署前检查 - ↓ ↓ ↓ ↓ ↓ - 快速检查 基础检查 深度审查 全面检查 安全检查 - (1-2秒) (10-30秒) (1-2分钟) (3-5分钟) (5-10分钟) -``` - -**成本控制：** 只在必要时运行 Claude 检查，通过条件判断避免不必要的 API 调用。 - -## 工作流速查表 - -| 场景 | 命令/操作 | -| :--- | :--- | -| **开始新功能** | `@directory src/` 了解项目结构 | -| **查找代码** | `@grep "functionName"` | -| **理解代码** | 直接描述代码文件让 Claude 解释 | -| **重构代码** | 描述重构需求，让 Claude 制定计划 | -| **修复 Bug** | 提供错误信息和复现步骤 | -| **代码审查** | 让 Claude 审查指定文件或目录 | -| **生成测试** | "为 xxx 文件生成单元测试" | -| **提交代码** | `/commit` | - -## 总结 - -掌握这些工作流后，你会发现： - -1. **日常开发**：用 @语法快速理解代码，让 Claude 处理重复工作 -2. **代码重构**：让 Claude 制定计划，逐步验证 -3. **Code Review**：自动发现潜在问题，提高代码质量 -4. **团队协作**：共享配置和记忆，保持团队一致性 -5. **CI/CD**：将 Claude 集成到自动化流程中 - -**核心原则：** -- 让 Claude 做它擅长的事：理解代码、生成代码、发现问题 -- 你做决策：审查结果、做架构选择、把控方向 -- 逐步信任：从简单任务开始，建立对 Claude 的信任 -- 持续优化：根据项目特点调整工作流