Claude Code 项目初始化最佳实践：新项目 5 分钟搭建完美 AI 编程环境

# [项目名称]

## 项目概述
[一段话描述项目：做什么/给谁用/核心价值]

## 技术栈
- 语言：Python 3.12 / TypeScript 5.x
- 框架：FastAPI / Next.js 15
- 数据库：PostgreSQL 16 + Redis 7
- 测试：pytest / Jest + Playwright
- CI/CD：GitHub Actions

## 代码规范
- Python：遵循 PEP 8，使用 ruff 格式化
- TypeScript：ESLint + Prettier，严格模式
- 提交信息：遵循 Conventional Commits 规范
- 函数长度：单个函数不超过 50 行
- 注释：复杂逻辑必须有注释，简单操作不需要

## 项目结构
src/
  api/        # API 路由层（只做路由，不写业务逻辑）
  services/   # 业务逻辑层
  models/     # 数据模型
  utils/      # 工具函数
tests/        # 测试文件（与 src 结构镜像）

## 常用命令
- 启动开发服务器：`npm run dev` / `uvicorn main:app --reload`
- 运行测试：`npm test` / `pytest`
- 代码检查：`npm run lint` / `ruff check .`
- 构建：`npm run build`

## 重要约定
- 所有 API 响应统一用 `{"code": 0, "data": ..., "msg": "ok"}` 格式
- 数据库操作必须在 service 层，不允许在 route 层直接查库
- 密钥和配置通过环境变量传入，禁止硬编码
- 新功能必须有对应的单元测试

## 禁止操作（必须先确认）
- 修改数据库 Schema（migration 文件）
- 修改 CI/CD 配置文件
- 修改 .env.example
- 直接 push 到 main 分支

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(pytest *)",
      "Bash(ruff check *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

cd my-project
claude --init

# Claude 会：
# 1. 扫描项目文件，识别技术栈
# 2. 自动生成 CLAUDE.md 初稿
# 3. 根据 .gitignore 生成 .claudeignore 建议
# 4. 生成推荐的 settings.json

# CLAUDE.md 前端专项补充

## 组件规范
- 组件文件使用 PascalCase 命名（UserCard.tsx）
- 每个组件一个文件，不超过 200 行
- Props 必须有 TypeScript 类型定义
- 样式优先使用 Tailwind，避免内联 style

## 状态管理
- 本地状态用 useState/useReducer
- 全局状态用 Zustand（已安装）
- 服务端状态用 TanStack Query

## 测试规范
- 组件测试用 @testing-library/react
- E2E 测试用 Playwright
- 覆盖率目标：核心组件 > 80%

# CLAUDE.md 后端专项补充

## API 设计规范
- RESTful 风格，版本前缀 /api/v1/
- 成功响应：200/201，失败：400/401/403/404/500
- 分页统一用 ?page=1&limit=20

## 数据库规范
- 使用 SQLAlchemy 2.0 async 模式
- 所有查询必须有超时设置（默认 30s）
- 禁止在循环中执行数据库查询（N+1 问题）

## 安全规范
- 所有接口必须经过认证（除 /health 和 /docs）
- 输入参数用 Pydantic 验证
- 日志中不得出现密码、Token 等敏感信息