08 - 最佳实践

📖 生产环境使用 Claude Code 的实战经验和最佳实践

📋 本章目标

✅ 掌握 Prompt 工程的最佳实践
✅ 学会有效的上下文管理
✅ 了解代码质量保证方法
✅ 建立团队协作规范
✅ 保证安全和隐私

预计阅读时间: 25分钟

🎯 Prompt 工程最佳实践

1. 清晰的需求描述

❌ 模糊的 Prompt

"写一个登录功能"

问题：

不知道技术栈
不知道具体需求
不知道期望的代码风格

✅ 清晰的 Prompt

创建一个用户登录功能，要求：

技术栈：
- React 18 + TypeScript
- React Hook Form 用于表单管理
- Zod 用于验证
- TailwindCSS 用于样式

功能需求：
1. 邮箱+密码登录
2. 记住我功能（localStorage）
3. 密码显示/隐藏切换
4. 实时表单验证
5. Loading 状态处理
6. 错误提示（友好的用户提示）

验证规则：
- 邮箱：标准邮箱格式
- 密码：至少8位，包含大小写字母和数字

API对接：
- POST /api/auth/login
- 返回：{ token, user }

代码风格：
- 函数式组件
- 自定义 hooks 抽取逻辑
- 详细的 TS 类型定义
- 添加注释解释关键逻辑

效果：Claude 能生成精确符合需求的代码

2. 分层次的请求

从概念到实现

# 第一层：架构设计（Chat）
"设计一个电商系统的用户模块，包括：
 - 用户注册/登录
 - 个人信息管理
 - 地址管理
 - 订单历史
 
 请提供：
 1. 数据库 ER 图
 2. API 端点设计
 3. 前端页面结构"

# 第二层：核心实现（Composer）
"基于上面的设计，实现用户注册功能"

# 第三层：细节优化（Inline）
[选中具体函数] 
"添加邮箱验证和防重复注册"

3. 使用示例和参考

提供代码示例

我的项目中已有这样的 API 调用模式：

```typescript
// @api/products.ts
export const getProducts = async (): Promise<Product[]> => {
  const { data, error } = await supabase
    .from('products')
    .select('*')
    .order('created_at', { ascending: false })
  
  if (error) throw error
  return data
}

请按照同样的模式，实现用户相关的 API 调用


**效果**：Claude 会保持一致的代码风格

---

### 4. 明确约束和限制

创建一个图片上传功能，约束条件：

技术限制：

不能使用第三方库（除了标准库）
必须支持 IE11（使用 polyfills）
打包大小<50KB

业务限制：

文件大小限制：5MB
支持格式：jpg, png, webp
需要客户端压缩
上传前显示预览

性能要求：

压缩时不阻塞 UI
使用 Web Worker
上传进度显示

安全要求：

验证文件类型（不只是扩展名）
扫描常见恶意代码特征
使用 CSRF token


---

## 📚 上下文管理策略

### 1. 有效引用文件

#### 使用 @ 符号

好的做法 ✅:

"基于 @src/types/user.ts 中的 User 类型，在 @src/components/UserCard.tsx 中创建用户卡片组件"

不好的做法 ❌:

"创建用户卡片组件" （Claude 不知道 User 类型的定义）


---

#### 在 Composer 中添加相关文件

Cmd + I（Composer）

点击 "Add Context" → 选择相关文件：

src/types/user.ts
src/hooks/useUser.ts
src/styles/theme.ts

然后描述需求： "创建用户详情页面，使用已有的类型和 hooks"


---

### 2. 管理上下文大小

#### 识别无关信息

❌ 包含过多无关文件: @src/ （整个项目，可能超过上下文限制）

✅ 精确选择相关文件: @src/features/user/ （只包含用户相关的模块）


---

#### 定期清理对话

何时清理:

对话偏离主题时
切换到新功能模块时
Claude 开始"健忘"之前的信息时
达到 50+ 轮对话时

如何清理: Cmd/Ctrl + Shift + L（清空对话）或 "让我们重新开始，专注于登录功能"


---

### 3. 分模块开发

项目结构: src/ ├── features/ │ ├── auth/ ← 模块1 │ ├── products/ ← 模块2 │ └── orders/ ← 模块3

开发策略:

一次只专注一个模块
模块开发完成后开新对话
跨模块集成时再引用多个模块

好处:

上下文更聚焦
Claude 理解更深入
减少混淆


---

## ✅ 代码质量保证

### 1. 代码审查流程

#### 自动审查

每次 Claude 生成代码后:

Prompt: "审查刚才的代码，检查：

安全漏洞（SQL注入、XSS等）
性能问题（不必要的重渲染、大对象拷贝等）
边界条件处理
错误处理是否完善
类型安全
代码可维护性"

Claude 会详细分析并提出改进建议


---

#### 人工审查检查清单

```markdown
## 代码审查清单

### 功能性
- [ ] 满足所有需求
- [ ] 边界条件处理正确
- [ ] 错误处理完善

### 安全性
- [ ] 无 SQL 注入风险
- [ ] 无 XSS 漏洞
- [ ] 敏感信息已保护
- [ ] 权限验证正确

### 性能
- [ ] 无性能瓶颈
- [ ] 数据库查询优化
- [ ] 前端渲染优化

### 可维护性
- [ ] 代码结构清晰
- [ ] 命名语义化
- [ ] 注释充分
- [ ] 符合项目规范

2. 测试驱动开发

先写测试

Step 1: 生成测试
Prompt: "为用户注册功能生成完整的测试用例，包括：
- 成功场景
- 失败场景（邮箱格式错误、密码强度不足等）
- 边界条件
- 异步处理"

Step 2: 实现功能
Prompt: "实现这些测试"

Step 3: 运行测试
通过 Terminal Skill 或手动运行

Step 4: 修复问题
如有测试失败，让 Claude 修复

3. 持续集成实践

// .cursorrules
{
  "preCommit": {
    "checks": [
      "npm run lint",      // 代码规范检查
      "npm run type-check",// 类型检查
      "npm test",          // 运行测试
      "npm run build"      // 确保可以构建
    ]
  }
}

👥 团队协作规范

1. 统一的 AI 使用规范

团队 .cursorrules

// .cursorrules (项目根目录)
{
  "model": "claude-3-5-sonnet-20241022",
  
  "rules": [
    "代码风格：严格遵循 ESLint 和 Prettier 配置",
    "命名规范：camelCase for variables, PascalCase for components",
    "注释：为所有导出的函数和组件添加 JSDoc",
    "测试：核心功能必须有单元测试",
    "错误处理：使用统一的错误处理模式",
    "日志：使用项目的 logger，禁止 console.log"
  ],
  
  "codeStyle": {
    "typescript": {
      "strictMode": true,
      "noImplicitAny": true
    },
    "react": {
      "style": "functional",
      "hooks": "preferred"
    }
  },
  
  "review": {
    "autoCheck": [
      "security",
      "performance",
      "bestPractices"
    ]
  }
}

2. Prompt 模板库

## 团队 Prompt 模板

### 创建新组件

创建一个 React 组件：[组件名]

功能描述： [描述]

技术要求：

使用 TypeScript
遵循项目的组件模式（@components/Example.tsx）
使用 Tailwind CSS 样式
添加 PropTypes 和 JSDoc 注释
导出组件和类型定义

参考：@components/Button.tsx


### API 调用

创建 API 调用函数：[函数名]

端点：[API 端点] 方法：[GET/POST/...] 参数：[参数列表]

要求：

遵循 @api/base.ts 的模式
使用 axios 实例
完整的错误处理
添加请求/响应类型
添加单元测试

参考：@api/users.ts


---

### 3. 代码所有权和追踪

```typescript
// 在关键代码中添加元信息

/**
 * 用户认证服务
 * 
 * @author Generated by Claude (Reviewed by: @zhang-san)
 * @created 2024-12-22
 * @aiAssisted true
 * @reviewRequired true
 * 
 * @description
 * 处理用户登录、注册、密码重置等认证相关功能
 * 
 * @security
 * - 密码使用 bcrypt 加密
 * - JWT token 有效期 7天
 * - 实现了速率限制防止暴力破解
 */
export class AuthService {
  // ...
}

4. 知识共享

建立 AI 使用最佳实践库

team-docs/
├── ai-best-practices/
│   ├── effective-prompts.md
│   ├── common-patterns.md
│   ├── troubleshooting.md
│   └── examples/
│       ├── feature-development.md
│       ├── bug-fixing.md
│       └── refactoring.md

🔒 安全与隐私

1. 敏感信息保护

永远不要向 AI 透露

❌ 禁止内容:
- 生产环境的 API Keys
- 密码和私钥
- 用户个人信息（PII）
- 内部系统架构细节（如果是机密）
- 商业机密代码

✅ 安全做法:
- 使用环境变量占位符
- 脱敏的示例数据
- 通用的架构描述

示例：安全的 Prompt

❌ 不安全:
"连接到数据库：
 postgresql://admin:MySecret123@prod.db.company.com:5432/maindb"

✅ 安全:
"连接到数据库：
 使用环境变量 DATABASE_URL
 
 示例（开发环境）：
 postgresql://user:pass@localhost:5432/dev_db"

2. 代码审计

审查 AI 生成的代码

重点检查:

1. 认证和授权
   - 是否正确验证用户身份？
   - 是否检查权限？

2. 输入验证
   - 是否验证所有用户输入？
   - 是否防止注入攻击？

3. 数据保护
   - 敏感数据是否加密？
   - 是否安全传输？

4. 错误处理
   - 错误信息是否泄露敏感信息？
   - 是否有适当的日志记录？

使用安全检查工具

# ESLint 安全插件
npm install --save-dev eslint-plugin-security

# 依赖扫描
npm audit

# 代码扫描
npm install -g snyk
snyk test

# 让 Claude 审查安全性
Prompt: "审查这段代码的安全性，
        特别关注 OWASP Top 10 漏洞"

3. 合规性

开源许可证

使用 AI 生成的代码时:

1. 了解 Claude 的使用条款
2. 确保生成的代码不侵犯版权
3. 如使用开源代码模式，遵守相应许可证

Prompt 示例:
"生成代码时，请避免复制任何有明确版权的代码，
 使用通用的实现模式"

数据隐私

GDPR/CCPA 合规:

1. 不向 AI 提供用户数据
2. 使用匿名/脱敏数据进行测试
3. 审查生成的代码是否符合隐私要求

Example:
❌ "分析这些用户数据：[真实用户数据]"
✅ "分析这种结构的数据：[示例/脱敏数据]"

📈 持续改进

1. 反馈循环

建立改进循环:

1. 使用 → 记录
   - 哪些 Prompt 有效
   - 哪些 Prompt 无效
   - 生成代码的质量

2. 分析 → 学习
   - 总结成功模式
   - 识别常见问题
   - 优化 Prompt 模板

3. 应用 → 验证
   - 使用优化后的方法
   - 测量改进效果
   - 继续迭代

2. 度量指标

// 追踪 AI 辅助开发的效果

interface AIMetrics {
  // 效率指标
  developmentTime: {
    before: number  // 使用 AI 前
    after: number   // 使用 AI 后
    improvement: number  // 改进百分比
  }
  
  // 质量指标
  codeQuality: {
    bugCount: number
    testCoverage: number
    codeReviewComments: number
  }
  
  // 使用情况
  usage: {
    promptCount: number
    successRate: number
    averageIterations: number
  }
}

3. 知识沉淀

建立团队知识库:

1. 优秀 Prompt 集合
   - 按场景分类
   - 包含实际效果
   - 持续更新

2. 常见问题解决方案
   - 问题描述
   - 解决方法
   - 预防措施

3. 最佳实践案例
   - 成功故事
   - 经验教训
   - 可复制的模式

✅ 最佳实践检查清单

日常开发

[ ] Prompt 清晰明确
[ ] 引用相关文件
[ ] 分步骤进行
[ ] 审查生成的代码
[ ] 运行测试
[ ] 符合项目规范

代码质量

[ ] 通过 linter
[ ] 类型检查通过
[ ] 测试覆盖充分
[ ] 无安全漏洞
[ ] 性能可接受
[ ] 文档完整

团队协作

[ ] 遵循团队规范
[ ] 使用统一模板
[ ] 代码有追踪信息
[ ] 知识及时分享

安全隐私

[ ] 无敏感信息泄露
[ ] 代码经过审计
[ ] 符合合规要求
[ ] 权限控制正确

🎯 实战建议

新手开发者

1. 从小功能开始
   - 先做简单的 CRUD
   - 逐步增加复杂度

2. 学习优秀 Prompt
   - 收集有效的 Prompt
   - 理解为什么有效

3. 保持审视
   - 不要盲目接受生成的代码
   - 理解每一行代码
   - 不懂就问 Claude

经验开发者

1. 利用专业知识
   - 提供明确的技术要求
   - 引导 Claude 使用最佳实践
   - 快速识别问题

2. 自动化工作流
   - 使用 Skills 和 MCP
   - 建立自己的模板
   - 优化开发流程

3. 指导团队
   - 分享经验
   - 建立规范
   - 持续优化

📚 延伸阅读

09 - 使用诀窍 - 更多实用技巧
10 - 配置优化 - 优化你的环境
05 - Claude Skills - 提升自动化程度
06 - MCP 协议 - 扩展能力边界

📖 最佳实践是长期实践的积累

不断尝试、反思、改进，形成自己的工作流！

"Excellence is not a skill, it's an attitude."