Skip to content

COMMON_PITFALLS.md

Latest commit

 

History

History
603 lines (451 loc) · 8.69 KB

COMMON_PITFALLS.md

File metadata and controls

603 lines (451 loc) · 8.69 KB

Claude Code 常见陷阱与解决方案

版本: 1.0 | 陷阱数: 30+ | 更新: 2026-03-22

🚨 新手陷阱

陷阱1: 直接推送不检查

问题:

# 写完代码直接推送
git add .
git commit -m "add feature"
git push

后果:

  • 代码有bug
  • 测试没通过
  • 链接失效

解决方案:

# 1. 运行测试
pytest tests/

# 2. 检查代码风格
flake8 .

# 3. 检查链接
./scripts/check-links.sh

# 4. 确认无误后推送
git push

预防: 建立SOP，每次推送前检查

陷阱2: 提示词太模糊

问题:

claude generate --prompt "写个函数"

后果:

  • 生成代码不符合预期
  • 需要多次返工
  • 浪费Token

解决方案:

创建用户注册API：
- 使用 FastAPI
- JWT 认证
- bcrypt 加密
- 邮箱验证
- 错误处理

预防: 使用结构化提示词

陷阱3: 跳过 Plan Mode

问题:

# 不研究代码库直接修改
claude generate --prompt "修改用户模块"

后果:

  • 不了解现有代码
  • 修改破坏其他功能
  • 返工率高

解决方案:

# 1. 启用 Plan Mode
claude --plan

# 2. 研究代码库
"分析用户模块的现有代码"

# 3. Claude 提出计划
# 审核计划

# 4. 切换到 Accept Edits
# 执行修改

预防: 修改前先用 Plan Mode

💡 提示词陷阱

陷阱4: 提供过多上下文

问题:

## 背景
我们是一家电商公司，使用微服务架构，
技术栈包括 FastAPI, PostgreSQL, Redis,
Docker, Kubernetes, Prometheus, Grafana...
（省略100行）

后果:

  • Token浪费
  • 上下文混乱
  • 生成质量下降

解决方案:

## 背景
FastAPI后端，PostgreSQL数据库

预防: 精简到必要信息

陷阱5: 没有提供示例

问题:

claude generate --prompt "写个好的函数"

后果:

  • Claude 不知道什么是"好"
  • 生成结果随机
  • 质量不稳定

解决方案:

claude generate \
  --prompt "创建用户API" \
  --example good_example.py \
  --example bad_example.py

预防: 始终提供示例

陷阱6: 约束条件不明确

问题:

优化这段代码

后果:

  • 不知道优化什么
  • 优化方向错误
  • 破坏功能

解决方案:

优化目标：
- 减少内存使用50%
- 保持API兼容性
- 不改变业务逻辑

预防: 明确约束条件

🔧 技术陷阱

陷阱7: 使用错误的模型

问题:

# 简单任务用 Opus
claude generate --model opus --prompt "Hello World"

后果:

  • 成本高3x
  • 速度慢5x
  • 质量提升不明显

解决方案:

# 简单任务用 Haiku
claude generate --model haiku --prompt "Hello World"

预防: 按任务选择模型

陷阱8: 没有启用缓存

问题:

# 每次都重新生成
claude generate --prompt "..."
claude generate --prompt "..."
claude generate --prompt "..."

后果:

  • 速度慢
  • 成本高
  • Token浪费

解决方案:

# 启用缓存
claude config set cache.enabled true

预防: 始终启用缓存

陷阱9: 忽略错误处理

问题:

# 没有错误处理
def get_user(user_id):
    return db.query(User).get(user_id)

后果:

  • 程序崩溃
  • 用户体验差
  • 难以调试

解决方案:

def get_user(user_id):
    """获取用户信息"""
    try:
        user = db.query(User).get(user_id)
        if not user:
            raise ValueError(f"User {user_id} not found")
        return user
    except Exception as e:
        logger.error(f"Error getting user: {e}")
        raise

预防: 所有函数都要有错误处理

📊 性能陷阱

陷阱10: 串行处理

问题:

# 逐个处理
for file in *.py; do
  claude review --file $file
done

后果:

  • 速度慢
  • 效率低
  • 时间浪费

解决方案:

# 并行处理
claude batch-review --files *.py --parallel 4

预防: 批量并行处理

陷阱11: Token 超限

问题:

# 一次性生成大文件
claude generate --prompt "创建完整的电商平台（100个模块）"

后果:

  • Token超限
  • 生成失败
  • 需要重新开始

解决方案:

# 分段生成
for module in user product order payment; do
  claude generate --prompt "创建$module模块"
done

预防: 分段处理大任务

陷阱12: 没有监控

问题:

# 不知道使用情况
claude generate --prompt "..."
claude generate --prompt "..."
claude generate --prompt "..."

后果:

  • 成本失控
  • 超出预算
  • 没有预警

解决方案:

# 设置预算
claude config set daily_budget 10.00

# 监控使用
claude usage --today

预防: 设置预算和监控

🎓 学习陷阱

陷阱13: 跳过基础

问题:

# 直接做复杂项目
claude generate --prompt "创建完整的电商平台"

后果:

  • 基础不牢
  • 遇到问题不会解决
  • 效率低

解决方案:

# 从简单开始
1. Hello World
2. 简单函数
3. 文件操作
4. API开发
5. 复杂项目

预防: 循序渐进

陷阱14: 不做笔记

问题:

# 学完就忘
claude generate --prompt "..."
# 第二次遇到同样问题
claude generate --prompt "..."

后果:

  • 重复学习
  • 效率低
  • 进步慢

解决方案:

# 记录学习笔记
## 今天学了什么
- Plan Mode 使用
- 提示词技巧
- 常见错误

## 遇到的问题
- Token超限 → 分段处理
- 代码质量差 → 提供示例

预防: 及时记录

陷阱15: 不分享经验

问题:

# 自己学自己的
# 不分享给他人

后果:

  • 没有反馈
  • 进步慢
  • 错过学习机会

解决方案:

# 分享方式
1. 写博客文章
2. 录制视频
3. 参与社区讨论
4. 创建开源项目

预防: 主动分享

🔒 安全陷阱

陷阱16: 硬编码密钥

问题:

API_KEY = "sk-ant-..."

后果:

  • 密钥泄露
  • 账户被盗
  • 损失惨重

解决方案:

import os
API_KEY = os.environ.get("ANTHROPIC_API_KEY")

预防: 使用环境变量

陷阱17: 不验证输入

问题:

def get_user(user_id):
    return db.query(f"SELECT * FROM users WHERE id = {user_id}")

后果:

  • SQL注入
  • 数据泄露
  • 安全漏洞

解决方案:

from pydantic import BaseModel

class UserId(BaseModel):
    id: int

def get_user(user_id: int):
    validated = UserId(id=user_id)
    return db.query("SELECT * FROM users WHERE id = ?", (validated.id,))

预防: 验证所有输入

陷阱18: 不做权限检查

问题:

@app.route("/admin/users")
def get_all_users():
    return db.query("SELECT * FROM users")

后果:

  • 权限绕过
  • 数据泄露
  • 未授权访问

解决方案:

@app.route("/admin/users")
@require_admin
def get_all_users():
    return db.query("SELECT * FROM users")

预防: 所有接口都要权限检查

🚀 部署陷阱

陷阱19: 没有测试就部署

问题:

# 写完直接部署
git push

后果:

  • 线上bug
  • 用户受影响
  • 回滚麻烦

解决方案:

# 1. 运行测试
pytest tests/

# 2. 代码审查
claude review --file app.py

# 3. 预发布测试
./deploy.sh staging

# 4. 生产部署
./deploy.sh production

预防: 测试后再部署

陷阱20: 没有回滚方案

问题:

# 直接部署新版本
./deploy.sh

后果:

  • 出问题无法回滚
  • 停机时间长
  • 用户受影响

解决方案:

# 蓝绿部署
./deploy.sh blue  # 部署新版本
./switch.sh green  # 切换流量

# 如果有问题
./switch.sh blue  # 快速回滚

预防: 部署前准备回滚方案

📊 陷阱统计

类别 陷阱数 常见度
新手陷阱 5个 ⭐⭐⭐⭐⭐
提示词陷阱 3个 ⭐⭐⭐⭐
技术陷阱 3个 ⭐⭐⭐
性能陷阱 3个 ⭐⭐⭐
学习陷阱 3个 ⭐⭐⭐⭐
安全陷阱 3个 ⭐⭐⭐⭐⭐

✅ 预防检查清单

每次使用前:

  • 检查提示词是否清晰
  • 是否需要 Plan Mode
  • 是否提供示例
  • 是否明确约束

每次推送前:

  • 运行测试
  • 代码审查
  • 检查链接
  • 准备回滚方案

每次学习后:

  • 记录笔记
  • 总结经验
  • 分享心得
  • 持续改进

创建时间: 2026-03-22 版本: 1.0 状态: 🟢 实用指南