# Claude Code CLI 快速开始指南

## 🎯 3 分钟快速开始

### 步骤 1：检查集成是否生效（30 秒）

```bash
# 验证 CLAUDE.md 已更新
grep "AI Development Standards" CLAUDE.md
# ✅ 应该看到新增的部分

# 验证 .claude 目录结构
ls -la .claude/
# ✅ 应该包含：conventions.md, dev-checklist.md, commands/, INTEGRATION.md
```

### 步骤 2：使用快速命令（1 分钟）

在 Claude Code 中尝试以下命令：

```bash
/dev-guide        # 查看开发指南摘要
/pydantic-tips    # 查看 Pydantic 使用技巧
/async-tips       # 查看异步编程技巧
/api-design       # 查看 API 设计快速参考
```

### 步骤 3：让 AI 生成符合规范的代码（1.5 分钟）

```bash
# 任务：创建用户验证模块
"请创建一个用户数据验证模块，使用 Pydantic"

# Claude Code 会自动：
# 1. 读取 CLAUDE.md 中的"AI Development Standards"
# 2. 参考 Python项目开发准则.md
# 3. 生成符合规范的代码（完整类型注解、docstring、测试）
```

---

## 📚 文件结构详解

```
.claude/                          ← Claude Code 本地配置
├── INTEGRATION.md                ← 📖 集成方案详细说明（本文件）
├── conventions.md                ← 编码约定速查（40 行）
├── dev-checklist.md              ← 快速检查清单（80 行）
└── commands/                      ← 快速命令库
    ├── dev-guide.md              ← /dev-guide 命令
    ├── pydantic-tips.md          ← /pydantic-tips 命令
    ├── async-tips.md             ← /async-tips 命令
    ├── api-design.md             ← /api-design 命令
    └── openspec/                 ← OpenSpec 命令（已存在）
        ├── proposal.md
        ├── apply.md
        └── archive.md
```

---

## 🚀 实际使用场景

### 场景 1：开发新功能
```bash
# 用户：我需要实现一个用户管理 API

# Claude Code 自动：
1. 读取 CLAUDE.md（包含开发规范引用）
2. 参考 Python项目开发准则.md
3. 查看 /api-design 获取 REST 规范
4. 生成完整的、符合规范的代码
```

### 场景 2：快速查询规范
```bash
# 用户：我不确定如何使用 Pydantic

# 选项 1：使用快速命令
/pydantic-tips
# 📖 自动打开 .claude/commands/pydantic-tips.md
# 显示 10+ 个实用示例

# 选项 2：查看检查清单
@/.claude/dev-checklist.md
# 看第3部分"数据验证"

# 选项 3：查看完整文档
@/Python项目开发准则.md#11-数据验证规范
```

### 场景 3：代码审查
```bash
# 用户：请审查这段代码

# Claude Code：
1. 读取 CLAUDE.md 中的规范要求
2. 检查是否符合 PEP 8、类型注解、docstring 等
3. 查看 .claude/dev-checklist.md
4. 给出改进建议（有具体示例）
```

### 场景 4：提交前质检
```bash
# 运行自动检查脚本
uv run python scripts/check.py

# 输出：
# ==============================
# 运行: Black 代码格式检查
# ✅ 通过
# 运行: Ruff 代码检查
# ✅ 通过
# 运行: MyPy 类型检查
# ✅ 通过
# 运行: Pytest 单元测试（覆盖率≥80%）
# ✅ 通过
# 总体结果: 4/4 项通过
# ==============================
```

---

## 💡 关键特性

### 特性 1：AI 自动遵守规范（🌟 推荐）
```
不需要做任何事！
   ↓
Claude Code 读取 CLAUDE.md
   ↓
自动发现"AI Development Standards"引用
   ↓
自动遵守 Python项目开发准则.md 中的所有规范
   ↓
生成的代码自动符合规范 ✅
```

### 特性 2：快速命令库
4 个常用命令，快速查询：
- `/dev-guide` - 开发指南摘要
- `/pydantic-tips` - Pydantic 使用技巧
- `/async-tips` - 异步编程技巧
- `/api-design` - REST API 设计快速参考

### 特性 3：分层参考
根据需要选择合适的文档：
- 快速查询 → `.claude/dev-checklist.md`（80 行）
- 学习技巧 → `.claude/commands/xxx.md`（150-180 行）
- 深入理解 → `Python项目开发准则.md`（1154 行）

### 特性 4：自动化检查
```bash
# 一键检查 6 项质量标准
uv run python scripts/check.py
```

---

## 🎓 与 AI 的三种协作方式

### 方式 1：被动遵守（推荐，最简单）
```bash
# 直接说需求，AI 自动遵守规范
"实现一个用户管理系统"

# AI 会自动：
✅ 添加完整的类型注解
✅ 编写 Google 风格 docstring
✅ 捕获具体异常
✅ 添加日志记录
✅ 编写 ≥80% 覆盖率的测试
```

### 方式 2：主动指引（中等复杂度）
```bash
# 明确指定需要遵守的规范

"请严格遵守《Python项目开发准则》实现用户管理系统：
- 使用 Pydantic v2 数据验证（Ch11）
- REST API 设计规范（Ch14）
- 异步编程最佳实践（Ch10）
- 单元测试覆盖率 ≥80%（Ch5）"

# AI 会以更严格的标准执行
```

### 方式 3：快速查询（最灵活）
```bash
# 需要快速了解某个规范时

"我需要学习 Pydantic，能否给我一些实用示例？"

# 用户或 AI 可以：
选项 1: 查看 /pydantic-tips（快速命令）
选项 2: 查看 .claude/dev-checklist.md 第3部分
选项 3: 查看 Python项目开发准则.md 第11章
```

---

## 📊 规范覆盖范围

集成方案覆盖了开发准则的所有关键部分：

| 规范 | 快速命令 | 检查清单 | 完整文档 |
|------|--------|--------|--------|
| 类型注解 | ✅ dev-guide | ✅ 第1项 | ✅ Ch3, Ch11 |
| Docstring | ✅ dev-guide | ✅ 第1项 | ✅ Ch3 |
| 异常处理 | ✅ dev-guide | ✅ 第2项 | ✅ Ch4 |
| 数据验证 | ✅ pydantic-tips | ✅ 第3项 | ✅ Ch11 |
| 异步编程 | ✅ async-tips | ✅ 第4项 | ✅ Ch10 |
| 日志记录 | ✅ dev-guide | ✅ 第5项 | ✅ Ch15 |
| API 设计 | ✅ api-design | ✅ 第10项 | ✅ Ch14 |
| 测试覆盖 | ✅ dev-guide | ✅ 第6项 | ✅ Ch5 |
| 安全检查 | ✅ dev-guide | ✅ 第7项 | ✅ Ch12 |

---

## ⚡ 常见操作速查

### 操作 1：查看编码约定
```bash
@/.claude/conventions.md
```

### 操作 2：检查是否符合规范
```bash
# 查看快速清单
@/.claude/dev-checklist.md

# 或运行自动检查
uv run python scripts/check.py
```

### 操作 3：学习 Pydantic
```bash
/pydantic-tips
```

### 操作 4：学习异步编程
```bash
/async-tips
```

### 操作 5：学习 API 设计
```bash
/api-design
```

### 操作 6：深入了解某个规范
```bash
# 查看完整文档
@/Python项目开发准则.md#[章节号]-[标题]

# 例如：
# @/Python项目开发准则.md#11-数据验证规范
# @/Python项目开发准则.md#10-异步编程规范
# @/Python项目开发准则.md#14-api-设计规范
```

---

## 🎯 开发流程建议

```bash
# 1. 创建新分支
git checkout -b feature/xxx

# 2. 与 AI 协作开发（AI 自动遵守规范）
"实现 xxx 功能..."

# 3. 提交前自动检查
uv run python scripts/check.py

# 4. 提交
git add .
git commit -m "feat(xxx): implement xxx"
git push

# ✅ 完成！代码自动符合规范
```

---

## ❓ 常见问题

### Q1：AI 没有遵守规范怎么办？
A：
1. 检查 CLAUDE.md 是否已更新（grep "AI Development Standards"）
2. 使用明确的提示词：
   ```bash
   "请严格遵守《Python项目开发准则》..."
   ```

### Q2：找不到快速命令怎么办？
A：
1. 确认 `.claude/commands/` 目录存在
2. 命令名对应文件名（不含 .md 后缀）
3. 使用 `@` 符号引用文件：`@/.claude/commands/xxx.md`

### Q3：代码检查失败怎么办？
A：
1. 查看错误信息
2. 参考 `.claude/dev-checklist.md` 的对应项
3. 运行对应的工具修复：
   ```bash
   uv run black src/ tests/  # 格式化
   uv run ruff check src/ --fix  # 自动修复
   ```

### Q4：想要更详细的规范说明？
A：
查看完整文档：`@/Python项目开发准则.md`

---

## 🎉 集成完成！

你现在拥有：

✅ **完整的开发准则**（1154 行）
✅ **自动化的 AI 规范执行**（通过 CLAUDE.md）
✅ **快速参考库**（4 个命令 + 2 个文档）
✅ **自动检查脚本**（一键质检）

**AI 会自动遵守所有规范，无需额外操作！** 🚀

---

## 📞 下一步

1. **验证集成**：运行 `uv run python scripts/check.py` 确保工具链正常
2. **尝试快速命令**：在 Claude Code 中试试 `/dev-guide`
3. **开发新功能**：AI 会自动遵守规范生成代码
4. **分享给团队**：让团队成员了解新的开发标准

**祝开发愉快！** 🎊
