# Claude Code CLI - 开发准则集成

这个目录包含所有与 Claude Code 协作开发的规范和指南。

## 📁 目录结构

```
.claude/
├── README.md                      ← 本文件
├── QUICKSTART.md                  ← ⭐ 新手必读（3 分钟快速开始）
├── INTEGRATION.md                 ← 集成方案详细说明
├── conventions.md                 ← 编码约定速查（PEP 8、命名等）
├── dev-checklist.md               ← 开发检查清单（10 项检查）
└── commands/                       ← 快速命令库
    ├── dev-guide.md               ← /dev-guide 开发指南摘要
    ├── pydantic-tips.md           ← /pydantic-tips Pydantic 实战
    ├── async-tips.md              ← /async-tips 异步编程实战
    ├── api-design.md              ← /api-design API 设计快速参考
    └── openspec/                  ← OpenSpec 命令
```

## 🚀 快速开始

### 对于新用户：
1. 阅读 **QUICKSTART.md**（5 分钟）
2. 尝试快速命令：`/dev-guide`
3. 开始开发，AI 自动遵守规范

### 对于项目维护者：
1. 查看 **INTEGRATION.md** 了解集成原理
2. 参考 **dev-checklist.md** 进行代码审查
3. 在 CI/CD 中集成 `scripts/check.py`

## 📚 文档说明

| 文件 | 用途 | 何时查看 |
|------|------|---------|
| **QUICKSTART.md** | 快速开始指南 | 第一次使用时 |
| **INTEGRATION.md** | 详细的集成方案 | 需要深入了解时 |
| **conventions.md** | 编码约定速查 | 开发过程中快速查阅 |
| **dev-checklist.md** | 10 项检查清单 | 代码审查和提交前 |
| **commands/** | 快速命令库 | 需要学习特定规范时 |

## 🎯 关键特性

### 1. AI 自动遵守规范
- CLAUDE.md 已更新，包含"AI Development Standards"
- AI 自动读取并应用 Python项目开发准则.md
- 无需用户额外操作，自动执行

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

### 3. 自动化检查
```bash
# 提交前运行
uv run python scripts/check.py

# 检查内容：
# ✅ Black 代码格式
# ✅ Ruff 代码检查
# ✅ MyPy 类型检查
# ✅ Pytest 单元测试（≥80% 覆盖率）
# ✅ Bandit 安全检查
```

## 💡 与 AI 的协作方式

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

### 方式 2：主动指引
```bash
# 明确指定规范
"请严格遵守《Python项目开发准则》实现..."
```

### 方式 3：快速查询
```bash
# 使用快速命令
/pydantic-tips    # 查看 Pydantic 技巧
/async-tips       # 查看异步编程技巧
```

## 🔗 关键引用

- **完整规范**：`@/Python项目开发准则.md`
- **项目指令**：`@/CLAUDE.md`
- **自动检查**：`uv run python scripts/check.py`

## 📝 使用示例

### 例子 1：开发新功能
```bash
# 用户任务
"创建用户验证模块"

# AI 自动：
✅ 使用 Pydantic v2 数据验证
✅ 完整的类型注解和 docstring
✅ 异常处理和日志记录
✅ 单元测试（≥80% 覆盖率）
```

### 例子 2：快速查询规范
```bash
# 需要了解异步编程
/async-tips

# 显示：
✅ 基础异步函数
✅ 并发执行多个任务
✅ 限制并发数量
✅ 超时控制
✅ 异步测试
✅ 常见模式
```

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

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

## ✅ 验证集成

```bash
# 检查 CLAUDE.md 是否已更新
grep "AI Development Standards" ../CLAUDE.md

# 验证目录结构
ls -la

# 测试快速命令（在 Claude Code 中）
/dev-guide

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

## 📞 需要帮助？

1. **快速开始**：查看 QUICKSTART.md
2. **详细说明**：查看 INTEGRATION.md
3. **编码约定**：查看 conventions.md
4. **开发检查**：查看 dev-checklist.md
5. **特定技巧**：使用快速命令（/dev-guide 等）

## 🎉 现在你拥有

- ✅ 完整的开发准则（1154 行）
- ✅ 自动化的 AI 规范执行
- ✅ 4 个快速命令库
- ✅ 10 项开发检查清单
- ✅ 自动化质量检查脚本

**祝开发愉快！** 🚀
