02 - 代码实现食谱

从锚定文件到小步迭代，让 AI 写出符合项目规范的高质量代码。

适用场景

食谱	什么时候用	预期产出
1 锚定文件生成	项目初期，建立代码模式	标杆文件，后续代码的参考基准
2 契约先行开发	新功能，先定义再实现	类型 → 测试 → 实现
3 新增 API 端点	后端接口开发	Route + Service + Schema
4 新增前端组件	前端界面开发	组件 + Props 类型 + 样式
5 数据库迁移	数据模型变更	Migration + 类型更新 + 回滚方案
6 小步迭代实现	大功能拆解	每步可验证的增量改动
7 三方服务集成	接入外部 API/SDK	封装层 + 错误处理 + 重试

---

食谱 1：锚定文件生成

场景描述

第一个文件的质量决定后续所有同类文件的风格。锚定文件是"黄金模板"——后续 AI 参考它生成代码，风格一致性大幅提升。

核心模板

我正在搭建 {{项目名}} 的 {{模块名}} 模块。
技术栈：{{技术栈}}

请生成第一个 {{文件类型}}，作为后续同类文件的参考标杆。
文件路径：{{文件路径}}

功能需求：
{{功能描述}}

必须包含的模式：
- {{模式1，如：zod schema 输入校验}}
- {{模式2，如：统一错误处理}}

项目约定：
- {{约定1}}
- {{约定2}}

这个文件会成为锚定文件，后续所有同类文件都参考它，
请确保代码结构清晰、模式完整、注释充分。

变量说明

变量	说明	示例
{{项目名}}	项目名称	TaskFlow
{{技术栈}}	技术栈	Next.js 14 + Prisma + TypeScript
{{文件类型}}	文件种类	API Route / Service / React 组件
{{文件路径}}	目标路径	app/api/users/route.ts
{{模式N}}	代码模式	zod schema 输入校验

好坏对比

❌ 帮我写一个用户 API。 → AI 自由发挥，风格和现有代码不一致。

✅ 指定技术栈、文件路径、必须包含的模式、项目约定，明确标注"锚定文件"用途。

实战案例

请生成 TaskFlow 的第一个 Service 文件。
技术栈：TypeScript + Prisma ORM
文件路径：src/services/user.service.ts

功能：
- createUser：创建用户，去重检查
- getUserById：根据 ID 查询，不存在抛 NotFoundError
- listUsers：分页查询，支持过滤和排序

必须包含：入参出参 TS 类型、AppError 错误处理、Prisma try-catch、JSDoc 注释。
这是锚定文件，后续 order.service.ts 等都参考它。

Claude 增强 💡

• 用 @CLAUDE.md 让 Claude 自动读取项目约定，不用手动列出规则
• 生成后追问：审查这个锚定文件，模式是否足够清晰？
• 写入 CLAUDE.md：新增 API Route 参考 @app/api/users/route.ts 的模式

---

食谱 2：契约先行开发

场景描述

Types → Tests → Implementation 的顺序让 AI 有明确验证目标。先定义类型契约，再写测试，最后实现让测试通过。

核心模板

我要实现 {{功能名称}}。请按契约先行顺序开发：

第一步 — 类型契约（{{类型文件路径}}）：
- 输入类型：{{输入描述}}
- 输出类型：{{输出描述}}
- 错误类型：{{错误场景}}

第二步 — 测试用例（{{测试文件路径}}）：
- 正常路径：{{正常场景}}
- 边界条件：{{边界场景}}
- 异常场景：{{异常场景}}
测试只依赖类型契约，不依赖实现细节。

第三步 — 实现代码（{{实现文件路径}}）：
让类型检查和所有测试通过。

技术栈：{{技术栈}}
每步完成后暂停，我确认后再继续。

变量说明

变量	说明	示例
{{功能名称}}	要实现的功能	订单计算服务
{{类型文件路径}}	类型位置	src/types/order.ts
{{输入/输出描述}}	数据结构	商品列表、优惠券码 → 小计、折扣、税、总价
{{测试文件路径}}	测试位置	src/services/__tests__/order.test.ts

好坏对比

❌ 实现文档创建功能，包括类型、实现和测试。 → AI 先写实现再补测试，测试沦为实现的镜像。

✅ 明确三步顺序 + 每步暂停确认 + 测试不依赖实现细节。

实战案例

实现订单计算服务。按契约先行顺序：

1. 在 src/types/order.ts 定义：
   - CalculateOrderInput: { items: OrderItem[], couponCode?: string }
   - CalculateOrderOutput: { subtotal, discount, tax, total }
   - 错误：InvalidCouponError, EmptyOrderError

2. 在 __tests__/order-calculator.test.ts 写测试：
   - 正常：3 个商品计算总价
   - 边界：空订单、数量为 0
   - 优惠券：有效券、过期券、不存在的券

3. 在 order-calculator.service.ts 实现，让测试通过。

技术栈：TypeScript，纯函数。每步完成后暂停。

Claude 增强 💡

• 第一步后运行 npx tsc --noEmit，第二步后运行测试（预期全部失败）
• 引用已有类型风格：参考 @src/types/user.ts 的定义风格

---

食谱 3：新增 API 端点

场景描述

基于锚定文件新增 API 端点，保持校验、错误处理、响应格式与现有端点一致。

核心模板

参考 @{{锚定文件路径}} 的模式，新增 API 端点。

端点：{{HTTP方法}} {{API路径}}
功能：{{功能描述}}

请求参数：
{{参数列表，含类型和是否必填}}

业务规则：
{{业务规则列表}}

保持和锚定文件相同的 zod 校验、错误处理和响应格式。

变量说明

变量	说明	示例
{{锚定文件路径}}	参考文件	app/api/users/route.ts
{{HTTP方法}} {{API路径}}	端点	POST /api/projects/[id]/members
{{参数列表}}	入参定义	userId (body, required), role (body, optional)
{{业务规则列表}}	业务逻辑	用户必须存在、不能重复添加

好坏对比

❌ 写一个添加项目成员的 API。 → AI 自选校验库、自定义错误格式，风格不一致。

✅ 引用锚定文件 + 列出参数和业务规则 + 明确保持相同模式。

实战案例

参考 @app/api/users/route.ts，实现端点：

POST /api/documents — 创建文档

请求体（zod schema）：
- title: string, 1-200 字符
- content: string, 最大 50000 字符
- tags: string[], 0-10 个
- isPublic: boolean, 默认 false

业务规则：同一用户下 title 不能重复、session 获取 userId（未登录 401）、成功返回 201

生成：route.ts + document.schema.ts + document.service.ts

Claude 增强 💡

• 用 @app/api/users/route.ts 直接引用锚定文件，Claude 自动读取
• 生成后运行 npx tsc --noEmit 检查类型
• /code-standards Skill 自动检查代码是否符合项目规范
• 如果项目使用 apiHandler 包装器，新增路由应采用声明式写法（permission + audit + handler），同步注册 OpenAPI 路由。详见 doc-17 §5

---

食谱 4：新增前端组件

场景描述

基于已有组件模式新增 UI 组件，Props 类型、组件结构、状态管理与现有组件保持一致。

核心模板

参考 @{{锚定组件路径}} 的结构，新增组件。

组件：{{组件名}}
路径：{{文件路径}}
用途：{{组件用途}}

Props：
{{Props 字段列表，含类型和描述}}

交互行为：
{{交互描述列表}}

UI 要求：
- 组件库：{{组件库}}
- 状态管理：{{状态方案}}

约束：不自己写基础 UI，优先用 {{组件库}}；Props 定义为独立 type。

变量说明

变量	说明	示例
{{锚定组件路径}}	参考组件	src/components/user-card.tsx
{{组件名}}	组件名称	ProjectMemberList
{{组件库}}	UI 组件库	shadcn/ui
{{状态方案}}	状态管理	useState + React Query

好坏对比

❌ 写一个项目成员列表组件。 → 可能自己写 table 样式，Props 没类型定义。

✅ 引用锚定组件 + Props 明确定义 + 指定组件库和状态方案。

实战案例

参考 @src/components/task-card.tsx，新增组件。

组件：CreateDocumentForm
路径：src/components/create-document-form.tsx

Props：onSuccess: (doc: Document) => void, defaultTags?: string[]

表单字段：title（必填）、content（@tiptap/react 富文本）、tags（最多 10 个）、isPublic（开关）

行为：react-hook-form + zod resolver 校验、提交调 POST /api/documents、
提交中禁用按钮显示 loading、成功调 onSuccess 失败显示 toast

用 shadcn/ui 的 Form, Input, Switch, Button, toast。

Claude 增强 💡

• 用 @src/components/ 浏览目录，找最合适的锚定组件
• 生成后：如果超过 200 行请拆分子组件
• /code-standards Skill 确保 Props 独立定义、named export

---

食谱 5：数据库迁移

场景描述

数据模型变更需要迁移脚本。重点是安全性：有数据的表不能随意删列，NOT NULL 字段要分步迁移。

核心模板

修改数据库 schema。

ORM：{{ORM}}
当前模型：参考 @{{schema文件路径}}

变更需求：
{{变更描述列表}}

请按以下步骤操作：
1. 修改 schema 文件
2. 生成迁移脚本（{{迁移命令}}）
3. 同步更新 TypeScript 类型
4. 列出对现有代码的影响

安全检查：
- 是否有数据丢失风险？如有，给出数据迁移步骤
- 提供回滚方案
- NOT NULL 新字段必须指定默认值或分步迁移

变量说明

变量	说明	示例
{{ORM}}	使用的 ORM	Prisma / Drizzle / TypeORM
{{schema文件路径}}	schema 位置	prisma/schema.prisma
{{变更描述列表}}	具体变更	User 新增 avatarUrl，新建 UserProfile 表
{{迁移命令}}	迁移命令	npx prisma migrate dev --name add-profile

好坏对比

❌ 给 User 表加一个 avatar 字段。 → 没考虑已有数据、回滚、关联代码。

✅ 指定 ORM + 引用当前 schema + 列出变更 + 要求安全检查和回滚方案。

实战案例

修改数据库 schema，支持多租户。ORM：Prisma，参考 @prisma/schema.prisma

变更：
1. 新增 Workspace 模型（id, name, slug, plan, createdAt）
2. 新增 WorkspaceMember 模型（workspaceId, userId, role）
3. Project 模型增加 workspaceId 外键（NOT NULL）

⚠️ Project 已有数据，NOT NULL 字段需分步迁移：
Step 1 添加可选 → Step 2 数据迁移脚本 → Step 3 改为 NOT NULL

请生成完整迁移方案和回滚步骤。

Claude 增强 💡

• 用 @prisma/schema.prisma 让 Claude 直接读取当前 schema
• 生成后运行 npx prisma migrate dev && npx prisma generate 验证
• 追问：检查所有引用变更类型的文件，列出需要同步修改的地方

---

食谱 6：小步迭代实现

场景描述

大功能拆解为可独立验证的小步骤。每步改动小、可测试、可回滚，避免一次性输出几百行难以调试的代码。

核心模板

我要实现 {{大功能描述}}。
请不要一次性实现，拆解为小步迭代计划。

约束：
- 每步不超过 {{文件数上限}} 个文件
- 每步有明确的验证方式（测试/类型检查/手动验证）
- 每步完成后提交一个 commit

技术栈：{{技术栈}}
相关文件：{{已有文件列表}}

先输出迭代计划（步骤、产出、验证方式），确认后开始第一步。

变量说明

变量	说明	示例
{{大功能描述}}	完整功能	项目成员管理：邀请、角色变更、移除
{{文件数上限}}	每步上限	3
{{技术栈}}	技术栈	Next.js + Prisma + React Query
{{已有文件列表}}	现有代码	prisma/schema.prisma, app/api/projects/route.ts

好坏对比

❌ 实现完整的项目成员管理功能。 → 改动 10+ 文件，出错难定位。 ✅ 要求拆解 + 每步限制文件数 + 先出计划再执行 + 每步验证。

实战案例

给 TaskFlow 添加通知系统（指派通知、状态变更通知、偏好设置、WebSocket 推送）。
请拆解为小步迭代，每步不超过 3 个文件。
先做核心（应用内通知），再加扩展（邮件、WebSocket）。
已有文件：@prisma/schema.prisma, @src/services/task.service.ts
先出计划。

Claude 增强 💡

• 每步用 /commit Skill 提交，步骤间运行 npm test && npx tsc --noEmit
• 出问题时 git diff HEAD~1 精确定位改动

---

食谱 7：三方服务集成

场景描述

集成外部 API/SDK 的关键是隔离层设计——不让第三方细节泄漏到业务代码，方便后续更换供应商。

核心模板

集成 {{第三方服务名}}。

用途：{{业务用途}}
SDK/API：{{SDK包名或API文档链接}}

请按以下结构实现：

1. 封装层（{{adapter文件路径}}）：
   - 暴露业务语义接口，不暴露第三方类型
   - 第三方错误转换为业务错误
   - 配置从环境变量读取

2. 类型定义（{{类型文件路径}}）：
   - 业务级输入/输出类型，不依赖第三方 SDK

3. 重试与容错：
   - 网络错误重试 {{重试次数}} 次（指数退避）
   - 降级策略：{{降级方案}}

4. 环境变量：列出需要的 .env 变量

约束：业务代码只依赖封装层，不直接 import 第三方 SDK。

变量说明

变量	说明	示例
{{第三方服务名}}	服务名称	Resend（邮件）
{{业务用途}}	集成目的	发送事务性邮件
{{adapter文件路径}}	封装层路径	src/lib/email/email.adapter.ts
{{类型文件路径}}	类型路径	src/lib/email/email.types.ts
{{降级方案}}	降级策略	记录到队列，后续重试

好坏对比

❌ 用 Resend 发送验证邮件。 → 业务代码直接依赖 SDK，换供应商改遍调用点。 ✅ 定义封装层结构 + 业务级类型 + 重试容错 + 明确隔离约束。

实战案例

集成 AWS S3 文件存储。用途：用户头像和文档附件上传
SDK：@aws-sdk/client-s3 + @aws-sdk/s3-request-presigner

封装层 src/lib/storage/：adapter.ts + types.ts + config.ts
接口：uploadFile / getSignedUrl / deleteFile
安全：文件类型校验（图片/PDF）、大小限制 10MB、presigned URL 上传
环境变量：AWS_S3_BUCKET, AWS_S3_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
生成封装层后，再写测试文件 Mock 掉 S3 客户端。

Claude 增强 💡

• 让 Claude 先确认 SDK 用法：搜索 resend npm 包最新 API
• 生成后追问：这个封装层是否容易 Mock？请生成 Mock 实现

---

组合技巧

技巧	组合路径
锚定+契约+小步三连	食谱 1（标杆）→ 2（契约）→ 6（小步实现）
新功能完整流程	/plan → 5（DB）→ 2（契约）→ 3（API）→ 4（组件）→ /review
集成功能流程	7（封装层）→ 2（契约）→ 3（API）→ 4（前端对接）

---

相关资源

• doc-15 Prompt 工程实战 — 提示词理论框架与速查表
• doc-12 效率最佳实践 — 锚定文件与契约先行的原理详解
• /code-standards Skill — 编码规范自动守卫
• /plan Skill — 项目规划与任务分解
• 01-架构设计食谱 — 上一阶段：技术选型与系统设计
• 03-测试验证食谱 — 下一阶段：测试策略与验证方法