使用 Claude 生产真实代码的实战笔记

## 项目：分析仪表板  
这是一个用于可视化用户分析的 Next.js 仪表板：  
### 架构决策  
- 默认使用服务器组件，仅在必要时使用客户端组件  
- 使用 tRPC 进行类型安全的 API 调用  
- 使用 Prisma 进行数据库访问，使用显式 select 语句  
- 使用 Tailwind 进行样式设计（无自定义 CSS 文件）  
### 代码风格  
- 格式化：使用 100 字符行的 Prettier  
- 导入：使用 simple-import-sort 排序  
- 组件：Pascal 命名法，与测试共置  
- Hooks：始终以 'use' 前缀  
### 要遵循的模式  
- 数据获取发生在服务器组件中  
- 客户端组件接收数据作为 props  
- 对所有外部数据使用 Zod 模式  
- 在每个数据显示组件周围使用错误边界  
### 不要做什么  
- 不要使用 useEffect 进行数据获取  
- 不要在没有明确批准的情况下创建全局状态  
- 不要用 'any' 类型绕过 TypeScript

// AIDEV-NOTE: 此组件使用虚拟滚动以提高性能  
// 参见：https://tanstack.com/virtual/latest  
// 不要转换为常规映射——我们处理 10k+ 项目  
export function DataTable({ items }: DataTableProps) {  
  // Claude，当你编辑这个时，保持虚拟滚动  
  ...  
}

## 锚点注释  
在代码库中适当位置添加特殊格式的注释，作为可以轻松 `grep` 的内联知识。  
### 指南：  
- 使用 `AIDEV-NOTE:`、`AIDEV-TODO:` 或 `AIDEV-QUESTION:`（全大写前缀）作为针对 AI 和开发者的注释。  
- 保持简洁（≤ 120 字符）。  
- **重要：** 在扫描文件之前，始终首先尝试在相关子目录中**定位现有锚点** `AIDEV-*`。  
- **更新相关锚点**当修改相关代码时。  
- **不要删除 `AIDEV-NOTE`s**除非有明确的人工指令。  
示例：  
# AIDEV-NOTE: perf-hot-path; 避免额外分配（参见 ADR-24）  
async def render_feed(...):  
    ...

# AIDEV-NOTE: API 合约边界 - v2.3.1  
# 任何更改都需要版本升级和迁移计划  
# 参见：docs/api-versioning.md  
@router.get("/users/{user_id}/feed")  
async def get_user_feed(user_id: UUID) -> FeedResponse:  
    # Claude：这里的响应形状是神圣的  
    # 更改会破坏生产中的真实应用  
    ...

# `CLAUDE.md` - Julep 后端服务  
## 黄金法则  
当不确定实现细节时，始终询问开发者。  
## 项目上下文  
Julep 使开发者能够使用声明式工作流构建有状态的 AI 代理。  
## 关键架构决策  
### 为什么使用 Temporal？  
我们使用 Temporal 进行工作流编排，因为：  
1. 工作流可以运行数天/数周，具有完美的可靠性  
2. 从任何失败点自动恢复  
### 为什么使用 PostgreSQL + pgvector？  
1. 工作流状态的 ACID 合规性（不能丢失用户数据）  
2. 代理记忆的向量相似性搜索  
### 为什么使用 TypeSpec？  
API 定义的单一真相来源：  
- OpenAPI 规范  
- TypeScript/Python 客户端  
- 验证模式  
## 代码风格和模式  
### 锚点注释  
在代码库中适当位置添加特殊格式的注释，作为可以轻松 `grep` 的内联知识。  
### 指南：  
- 使用 `AIDEV-NOTE:`、`AIDEV-TODO:` 或 `AIDEV-QUESTION:`（全大写前缀）作为针对 AI 和开发者的注释。  
- **重要：** 在扫描文件之前，始终首先尝试**grep 现有锚点** `AIDEV-*` 在相关子目录中。  
- **更新相关锚点**当修改相关代码时。  
- **不要删除 `AIDEV-NOTE`s**除非有明确的人工指令。  
- 确保在以下情况下添加相关锚点注释，每当文件或代码片段：  
  * 太复杂，或  
  * 非常重要，或  
  * 令人困惑，或  
  * 可能有错误  
## 领域词汇表（Claude，学习这些！）  
- **代理**: 具有记忆、工具和定义行为的 AI 实体  
- **任务**: 由步骤组成的工作流定义（不是 Celery 任务）  
- **执行**: 任务的运行实例  
- **工具**: 代理可以调用的函数（浏览器、API 等）  
- **会话**: 具有记忆的对话上下文  
- **条目**: 会话中的单个交互  
## AI 绝不能做的事情  
1. **永远不要修改测试文件** - 测试编码人类意图  
2. **永远不要更改 API 合约** - 破坏真实应用  
3. **永远不要更改迁移文件** - 数据丢失风险  
4. **永远不要提交秘密** - 使用环境变量  
5. **永远不要假设业务逻辑** - 始终询问  
6. **永远不要删除 AIDEV- 注释** - 它们在那里是有原因的  
记住：我们优化可维护性而不是聪明。  
当有疑问时，选择无聊的解决方案。

# AIDEV-NOTE: 关键性能路径 - 这服务于 100k req/sec  
# 不要在这里添加数据库查询  
def get_user_feed(user_id: UUID, cached_data: FeedCache) -> List[FeedItem]:  
    # 我们需要避免修改缓存数据  
    items = cached_data.items[:]  
    # AIDEV-TODO: 实现分页（票据：FEED-123）  
    # 需要基于游标的分页用于无限滚动  
    # AIDEV-QUESTION: 为什么我们在这里而不是在缓存中过滤私有项目？  
    # AIDEV-ANSWER: 历史上下文：隐私规则可能在缓存更新之间改变  
    filtered = [item for item in items if user_has_access(user_id, item)]  
    return filtered

# 创建 AI 游乐场而不污染主分支  
git worktree add ../ai-experiments/cool-feature -b ai/cool-feature  
# 让 Claude 在隔离的 worktree 中疯狂  
cd ../ai-experiments/cool-feature  
# ... 大量实验性提交 ...  
# 将好东西 cherry-pick 回主分支  
cd ../main-repo  
git cherry-pick abc123  # 只是有效的提交  
# 完成后清理  
git worktree remove ../ai-experiments/cool-feature

feat: 实现用户 feed 缓存 [AI]  
- 为用户 feeds 添加基于 Redis 的缓存  
- 在用户登录时实现缓存预热  
- 添加缓存命中率指标  
AI 辅助：核心逻辑生成，测试人工编写

class RateLimiter:  
    def __init__(self, max_requests: int, window_seconds: int):  
        self.max_requests = max_requests  
        self.window_seconds = window_seconds  
        self.requests = defaultdict(list)  
    def is_allowed(self, user_id: str) -> bool:  
        now = time.time()  
        user_requests = self.requests[user_id]  
        # 清理旧请求  
        self.requests[user_id] = [  
            req_time for req_time in user_requests  
            if now - req_time < self.window_seconds  
        ]  
        if len(self.requests[user_id]) < self.max_requests:  
            self.requests[user_id].append(now)  
            return True  
        return False

def test_rate_limiter():  
    limiter = RateLimiter(max_requests=3, window_seconds=60)  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == False  # 达到限制

## 测试纪律  
| 什么 | AI 可以做什么 | AI 绝不能做什么 |  
|------|-----------|----------------|  
| 实现 | 生成业务逻辑 | 触摸测试文件 |  
| 测试规划 | 建议测试场景 | 编写测试代码 |  
| 调试 | 分析测试失败 | 修改测试期望 |  
如果 AI 工具触摸测试文件，PR 被拒绝。没有例外。

为 GET /users/{id} 端点添加 Redis 缓存。  
上下文：  
- 此端点服务于 50k 请求/分钟  
- 我们在负载均衡器后面运行 12 个 API 服务器  
- 用户数据很少变化（每天几次）  
- 我们已经在 cache.redis.internal:6379 有 Redis  
- 使用我们的标准缓存键模式："user:v1:{id}"  
- 包含缓存命中/未命中指标（我们使用 Prometheus）  
- 实现缓存旁路模式，TTL 1 小时  
- 使用概率早期过期处理缓存雪崩  
参见我们的缓存指南：docs/patterns/caching.md

# SPEC.md - 错误层次结构设计（人工编写）  
## 错误哲学  
- 客户端错误（4xx）必须包含可操作的反馈  
- 系统错误（5xx）必须包含用于调试的跟踪 ID  
- 所有错误必须是 JSON 可序列化的  
- 错误代码必须稳定（客户端依赖它们）  
## 层次结构  
BaseError  
├── ClientError (4xx)  
│   ├── ValidationError  
│   │   ├── SchemaValidationError - 请求不匹配模式  
│   │   ├── BusinessRuleError - 有效模式，无效业务逻辑  
│   │   └── RateLimitError - 请求过多  
│   └── AuthError  
│       ├── AuthenticationError - 你是谁？  
│       └── AuthorizationError - 你不能那样做  
└── SystemError (5xx)  
    ├── DatabaseError - 连接、超时、死锁  
    ├── ExternalServiceError - API、webhook 失败  
    └── InfrastructureError - 磁盘满、OOM 等  
## 错误响应格式  
{  
  "error": {  
    "code": "VALIDATION_FAILED",     // 客户端的稳定代码  
    "message": "邮箱已存在", // 人类可读  
    "details": { ... },               // 结构化数据  
    "trace_id": "abc-123-def"         // 用于调试  
  }  
}

### 给 Claude 的提示：  
重构我们的错误处理以匹配 SPEC.md。  
当前状态：  
- raise ValueError("无效邮箱")  
- return {"error": "出错了"}, 500  
目标状态：  
- 使用 SPEC.md 中的错误层次结构  
- 包含适当的错误代码  
- 为所有 5xx 错误添加 trace_id  
从 auth 模块开始。在实现之前向我展示计划。

1. 在 `common/errors.py` 中创建错误层次结构  
2. 创建错误响应格式化器  
3. 系统性地更新每个模块  
4. 添加错误处理中间件

# 之前（Claude 找到这些模式）：  
if not user:  
    raise Exception("用户未找到")  
# 之后（Claude 的重构）：  
if not user:  
    raise AuthenticationError(  
        message="用户未找到",  
        code="USER_NOT_FOUND",  
        details={"identifier": email}  
    )

□ 阅读团队 `CLAUDE.md` 文件（从根开始，然后是特定服务）  
□ 设置开发环境  
□ 制作第一个 PR（人工编写，无 AI）

□ 使用团队模板设置 Claude  
□ 在 AI 协助下完成"玩具问题"  
□ 练习提示模式  
□ 创建第一个 AI 辅助 PR（有监督）

□ 发布第一个重要的 AI 辅助功能  
□ 为另一个开发者的 AI 输出编写测试  
□ 领导一个代码审查会话

# 我们的 .gitmessage 模板  
# feat/fix/docs: <描述> [AI]?  
#  
# [AI] - 重要的 AI 协助（>50% 生成）  
# [AI-minor] - 轻微的 AI 协助（<50% 生成）  
# [AI-review] - 仅用于代码审查的 AI  
#   
# 示例：  
# feat: 为用户服务添加 Redis 缓存 [AI]  
#  
# AI 生成了缓存实现和 Redis 客户端设置。  
# 我设计了缓存键结构并编写了所有测试。  
# 手动验证缓存失效逻辑工作正常。

# 这是神圣的土地  
# 没有 AI 可以通过  
def test_critical_business_logic():  
    """这个测试编码了价值 1000 万美元的领域知识"""  
    pass

-- migrations/2024_01_15_restructure_users.sql  
-- 不要让 AI 碰这个  
-- 一个错误的举动 = 数据丢失 = 职业生涯丢失  
ALTER TABLE users ADD COLUMN subscription_tier VARCHAR(20);  
UPDATE users SET subscription_tier = 'free' WHERE subscription_tier IS NULL;  
ALTER TABLE users ALTER COLUMN subscription_tier SET NOT NULL;

# auth/jwt_validator.py  
# 仅限人类眼睛 - 安全边界  
def validate_token(token: str) -> Optional[UserClaims]:  
    # 这里的每一行都经过安全审查  
    # 更改需要安全团队批准  
    # AI 建议在这里主动危险

# openapi.yaml  
# 破坏这个 = 破坏每个客户端  
# AI 不理解移动应用发布周期  
paths:  
  /api/v1/users/{id}:  
    get:  
      responses:  
        200:  
          schema:  
            $ref: '#/definitions/UserResponse'  # 冻结直到 v2

# config/production.py  
DATABASE_URL = os.environ["DATABASE_URL"]  # 永远不要硬编码  
STRIPE_SECRET_KEY = os.environ["STRIPE_SECRET_KEY"]  # 显然  
FEATURE_FLAGS = {  
    "new_pricing": False,  # 需要产品决策  
}