# Claude Code CLI - 开发准则集成方案

## 📊 集成架构

```
项目根目录/
│
├── Python项目开发准则.md          ← 完整的开发准则（1154 行）
│   （包含 21 章，覆盖所有规范细节）
│
├── CLAUDE.md                       ← 项目 AI 指令（已更新）
│   └── 新增"AI Development Standards"部分
│       └── 自动引用开发准则，AI 自动遵守
│
├── .claude/                        ← Claude Code 本地配置
│   ├── conventions.md              ← 编码约定速查（供 AI 参考）
│   ├── dev-checklist.md            ← 快速检查清单（80 行）
│   └── commands/                   ← 快速命令库
│       ├── dev-guide.md            ← /dev-guide  - 开发指南摘要
│       ├── pydantic-tips.md        ← /pydantic-tips - Pydantic 技巧
│       ├── async-tips.md           ← /async-tips - 异步编程技巧
│       └── api-design.md           ← /api-design - API 设计快速参考
│
└── scripts/
    └── check.py                    ← 自动检查脚本（一键质检）
```

---

## 🎯 三层工作流程

### 第一层：AI 自动遵守（CLAUDE.md）
```
用户任务
  ↓
Claude Code 读取 CLAUDE.md
  ↓
自动找到"AI Development Standards"部分
  ↓
自动引用 Python项目开发准则.md
  ↓
AI 自动遵守所有规范 ✅
```

**无需用户额外操作，AI 自动执行**

### 第二层：快速参考（.claude/ 目录）
用户或 AI 需要快速了解某个规范时：

```bash
# 查看编码约定
@/.claude/conventions.md

# 查看检查清单
@/.claude/dev-checklist.md

# 查看特定技巧
@/.claude/commands/pydantic-tips.md
```

### 第三层：快速命令（Slash Commands）
用户在交互时使用：

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

---

## 🚀 实际使用场景

### 场景 1：新功能开发
```bash
# 用户输入任务
你好，我需要创建一个用户 API 端点

# 不需要额外操作，Claude Code 会：
1. 自动读取 CLAUDE.md 中的规范要求
2. 参考 .claude/commands/api-design.md（如果需要）
3. 生成符合规范的代码（完整类型注解、docstring、测试）
```

### 场景 2：快速查询规范
```bash
# 用户想了解 Pydantic 使用方法
/pydantic-tips

# Claude Code 自动打开 .claude/commands/pydantic-tips.md
# 显示 10+ 个实用示例
```

### 场景 3：代码审查
```bash
# 用户提供代码片段
请按照《Python项目开发准则》审查以下代码

# Claude Code 会：
1. 自动读取完整的规范
2. 检查是否符合 PEP 8、类型注解、docstring 等
3. 给出改进建议
```

### 场景 4：提交前检查
```bash
# 用户想在提交前检查代码质量
uv run python scripts/check.py

# 运行 6 项自动化检查
# 输出详细的检查结果
```

---

## 📖 文件说明

### 主文件

| 文件 | 用途 | 何时查看 |
|------|------|---------|
| `Python项目开发准则.md` | 完整规范（21 章） | 深入学习、参考细节 |
| `CLAUDE.md` | AI 项目指令 | AI 自动读取，用户不需主动操作 |

### 本地文件（.claude/）

| 文件 | 用途 | 行数 |
|------|------|------|
| `conventions.md` | 编码约定速查 | 40 行 |
| `dev-checklist.md` | 检查清单 | 80 行 |
| `commands/dev-guide.md` | 开发指南摘要 | 70 行 |
| `commands/pydantic-tips.md` | Pydantic 实战 | 180 行 |
| `commands/async-tips.md` | 异步编程实战 | 150 行 |
| `commands/api-design.md` | API 设计参考 | 160 行 |

---

## 💡 AI 与开发准则的交互方式

### 方式 1：被动遵守（推荐）✨
```
AI 自动读取 CLAUDE.md
    ↓
发现"AI Development Standards"引用
    ↓
自动参考 Python项目开发准则.md
    ↓
生成的代码自动遵守所有规范
```

**用户无需做任何事，AI 自动执行**

### 方式 2：主动查询
```bash
# 用户想了解某个规范
我需要了解异步编程的最佳实践

# AI 可以：
选项 1: 参考 /async-tips 命令
选项 2: 参考 .claude/dev-checklist.md 的第4项
选项 3: 参考完整文档第10章
```

### 方式 3：提示词指导
```bash
# 用户明确指定规范
请严格遵守《Python项目开发准则》完成以下任务：
- 完整类型注解 + docstring
- 异常处理规范
- 编写 ≥80% 覆盖率的测试

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

---

## 🔧 常见操作

### 1. 让 AI 生成符合规范的代码
```bash
# 直接任务（AI 自动遵守 CLAUDE.md）
实现一个用户数据验证模块

# 或带明确指引
请严格遵守《Python项目开发准则》实现用户验证模块：
- 使用 Pydantic v2 数据验证（Ch11）
- 完整的类型注解和 docstring（Ch3, Ch4）
- 单元测试覆盖率 ≥80%（Ch5）
- 捕获具体异常（Ch4）
```

### 2. 查看某个规范的详细内容
```bash
# 快速命令
/pydantic-tips    # 看 Pydantic 使用方法
/api-design       # 看 REST API 设计
/async-tips       # 看异步编程最佳实践

# 或直接查看
@/.claude/dev-checklist.md
@/Python项目开发准则.md#11-数据验证规范
```

### 3. 自动检查代码质量
```bash
# 在提交前运行
uv run python scripts/check.py

# 或分别运行
uv run black src/ tests/ --check
uv run ruff check src/ tests/
uv run mypy src/
uv run pytest --cov=src --cov-fail-under=80
```

### 4. 审查现有代码
```bash
# 请求审查
请按照《Python项目开发准则》审查以下代码：

[代码片段]

# AI 会检查：
- PEP 8 规范
- 类型注解完整性
- Docstring 质量
- 异常处理规范
- 日志记录
```

---

## 📋 检查清单：集成验证

部署完成后，验证集成是否生效：

```bash
# 1. 验证 CLAUDE.md 已更新
grep -n "AI Development Standards" CLAUDE.md
# ✅ 应该找到"AI Development Standards"部分

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

# 3. 验证命令文件存在
ls .claude/commands/
# ✅ 应该包含：dev-guide.md, pydantic-tips.md, async-tips.md, api-design.md

# 4. 测试快速命令（在 Claude Code 中）
/dev-guide     # 应该返回开发指南摘要
/pydantic-tips # 应该返回 Pydantic 技巧

# 5. 验证自动检查脚本
uv run python scripts/check.py
# ✅ 应该运行 6 项检查
```

---

## 🎓 团队培训建议

### 第1天：快速上手
- 介绍 `/dev-guide` 命令
- 展示 `scripts/check.py` 的使用
- 演示一个完整的开发流程

### 第2-3天：深入理解
- 学习 Pydantic 验证（/pydantic-tips）
- 学习异步编程（/async-tips）
- 学习 API 设计（/api-design）

### 第4周+：持续遵守
- 代码审查时参考规范
- 定期运行自动检查
- 有疑问时查看完整文档

---

## 🚀 最佳实践建议

### 推荐的工作流程

```bash
# 1. 开始新功能
git checkout -b feature/user-validation

# 2. 开发（AI 自动遵守规范）
# 创建代码...

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

# 4. 推送
git add .
git commit -m "feat(user): add user validation with Pydantic"
git push
```

### 与 AI 的协作建议

```bash
# 方式 1：简单任务（AI 自动执行）
"创建一个用户验证模块"

# 方式 2：详细任务（明确指引）
"请严格遵守《Python项目开发准则》创建用户验证模块：
 - 使用 Pydantic v2（Ch11）
 - 完整的类型注解和 docstring
 - 单元测试覆盖率 ≥80%"

# 方式 3：审查需求
"请按照《Python项目开发准则》审查以下代码..."
```

---

## 📞 遇到问题？

| 问题 | 解决方案 |
|------|--------|
| 不知道如何编写某个功能 | 查看 /dev-guide 或对应的命令文件 |
| 不确定是否符合规范 | 运行 `scripts/check.py` |
| 想深入学习某个规范 | 查看完整文档的相应章节 |
| AI 没有遵守规范 | 检查 CLAUDE.md 是否已更新 |

---

## 总结

这个集成方案包含：

✅ **完整的开发准则**（1154 行，21 章）
✅ **项目级 AI 指令**（CLAUDE.md）
✅ **快速参考文件**（.claude/ 目录）
✅ **实用命令库**（4 个命令）
✅ **自动化检查脚本**（scripts/check.py）

**结果：AI 自动遵守规范，无需用户额外操作！** 🎉
