CLAUDE.md 项目上下文 — 项目规范记忆、rules 目录与 auto-memory

# 在项目根目录创建 CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目上下文

## 项目概述
这是一个基于 FastAPI 的用户管理系统，使用 PostgreSQL 作为数据库。

## 技术栈
- Python 3.11+
- FastAPI
- SQLAlchemy 2.0
- PostgreSQL 15
- Pydantic v2

## 编码规范
- 使用类型注解
- 函数不超过 50 行
- 每个公开方法必须有 docstring
- 使用 ruff 进行 linting

## 目录结构

## 重要约定
- 所有数据库操作必须通过 service 层
- API 响应统一使用 APIResponse 包装
- 错误使用自定义异常类
EOF

1. ~/.claude/CLAUDE.md          (全局上下文，可选)
2. 项目根目录/CLAUDE.md         (项目级上下文)
3. 当前子目录/CLAUDE.md         (目录级上下文，可选)
4. .claude/CLAUDE.md            (隐藏目录，可选)

# 项目名称 — Claude Code 上下文

## 📋 项目概述
[一句话描述项目是什么]

## 🏗️ 架构概览
[高层架构描述，包含关键组件和数据流]

## 🛠️ 技术栈
- **语言**: [语言及版本]
- **框架**: [框架及版本]
- **数据库**: [数据库类型]
- **工具**: [linting、测试、构建工具]

## 📁 目录结构
```
project/
├── src/
│   ├── api/          # REST API 路由
│   ├── models/       # 数据模型定义
│   ├── services/     # 业务逻辑层
│   ├── schemas/      # Pydantic 模式
│   └── config/       # 配置管理
├── tests/
│   ├── unit/         # 单元测试
│   ├── integration/  # 集成测试
│   └── fixtures/     # 测试夹具
├── docs/             # 文档
└── scripts/          # 运维脚本
```

## 📝 编码规范

### 命名约定
- 变量: snake_case
- 类: PascalCase
- 常量: UPPER_SNAKE_CASE
- 私有方法: _leading_underscore

### 代码风格
- 行长度限制: 120 字符
- 使用类型注解
- 每个模块以 docstring 开头
- 函数不超过 50 行

### Git 提交规范
```
<type>(<scope>): <description>

feat(auth): add JWT token refresh
fix(api): handle null pointer in user endpoint
docs(readme): update installation instructions
```

## 🔧 开发工作流

### 环境设置
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
```

### 运行测试
```bash
pytest tests/ -v --cov=src
```

### 代码质量检查
```bash
ruff check src/
mypy src/
```

## ⚠️ 重要注意事项
- 不要直接修改数据库，使用迁移脚本
- 所有 API 变更必须更新 OpenAPI 文档
- 敏感配置通过环境变量注入

.claude/
└── rules/
    ├── general.md          # 通用规则
    ├── security.md         # 安全规则
    ├── testing.md          # 测试规则
    ├── documentation.md    # 文档规则
    └── performance.md      # 性能规则

<!-- .claude/rules/security.md -->
# 安全规则

## 输入验证
- 所有用户输入必须经过验证
- 使用 Pydantic 模型进行请求体验证
- 禁止使用 `eval()` 或 `exec()`

## 认证与授权
- 所有 API 端点必须有认证装饰器
- 使用 JWT token 进行身份验证
- 角色权限检查在服务层完成

## 数据安全
- 密码必须使用 bcrypt 哈希
- 敏感数据不在日志中输出
- API 密钥通过环境变量管理

## SQL 安全
- 使用参数化查询
- 禁止字符串拼接 SQL
- 使用 SQLAlchemy ORM 而非原始 SQL

.claude/rules/ 目录中的规则按以下优先级应用：

1. 目录级规则（最具体）
   .claude/rules/src/api/security.md

2. 通用规则
   .claude/rules/security.md

3. CLAUDE.md 中的内联规则
   CLAUDE.md 中的编码规范部分

// .claude/settings.json
{
  "memory": {
    "enabled": true,
    "autoSave": true,
    "maxEntries": 100,
    "categories": [
      "architecture_decisions",
      "coding_preferences",
      "project_conventions",
      "known_issues"
    ]
  }
}

.claude/
└── memory/
    ├── active.json         # 当前活跃记忆
    ├── archive/            # 归档记忆
    │   ├── 2024-01.json
    │   └── 2024-02.json
    └── index.json          # 记忆索引

# 查看当前记忆
claude memory list

# 添加记忆
claude memory add "项目使用 UUID 作为主键"

# 搜索记忆
claude memory search "主键"

# 删除记忆
claude memory delete <memory-id>

# 导出记忆
claude memory export > memory-backup.json

# 导入记忆
claude memory import memory-backup.json

<!-- .claude/memory/categories.md -->

# 记忆分类

## architecture_decisions
- 为什么选择 FastAPI 而非 Flask
- 数据库分片策略
- 缓存层设计方案

## coding_preferences
- 偏好函数式编程风格
- 使用 dataclass 而非 dict
- 异步优先于同步

## project_conventions
- 错误处理使用 try/except 而非 if/else
- 日志使用结构化 JSON 格式
- API 版本通过 URL 路径管理

## known_issues
- 用户模块存在竞态条件（计划 2024 Q2 修复）
- 文件上传大小限制为 10MB

# 将 CLAUDE.md 纳入版本控制
git add CLAUDE.md
git add .claude/rules/
git commit -m "feat: 添加 Claude Code 项目上下文配置"

# .gitignore — 排除个人配置
.claude/settings.json     # 个人设置
.claude/memory/           # 个人记忆

<!-- CLAUDE.md 中的团队协作部分 -->

## 🤝 团队协作

### 审查规则
- PR 必须通过自动审查
- 至少一名团队成员 approve
- CI 全部通过才能合并

### 沟通约定
- 重大架构变更需在 PR 描述中说明原因
- 使用 Conventional Commits
- 功能分支命名: `feat/feature-name`

### Claude Code 协作
- 所有开发者使用相同的 CLAUDE.md
- 个人偏好写入 .claude/settings.json（不提交）
- 团队规则写入 .claude/rules/（提交到 Git）

# CLAUDE.md

## 项目概述
这是一个基于 FastAPI 的用户管理系统...

## 技术规范
@import .claude/rules/coding-standards.md
@import .claude/rules/security.md
@import .claude/rules/testing.md

## 架构说明
@import docs/architecture.md

// .claude/settings.json — 团队规则同步配置
{
  "teamRules": {
    "source": "https://github.com/company/claude-rules",
    "branch": "main",
    "sync": "auto",
    "includes": ["security.md", "coding-standards.md"]
  }
}

#!/bin/bash
# check-claude-config.sh — 检查 CLAUDE.md 配置质量

echo "🔍 检查 CLAUDE.md 配置..."

# 检查文件是否存在
if [ ! -f "CLAUDE.md" ]; then
  echo "❌ CLAUDE.md 不存在"
  exit 1
fi

# 检查必需部分
required_sections=("项目概述" "技术栈" "编码规范" "目录结构")
for section in "${required_sections[@]}"; do
  if grep -q "$section" CLAUDE.md; then
    echo "✅ 找到: $section"
  else
    echo "⚠️ 缺失: $section"
  fi
done

# 检查 rules 目录
if [ -d ".claude/rules" ]; then
  rule_count=$(find .claude/rules -name "*.md" | wc -l)
  echo "✅ rules 目录存在，包含 $rule_count 个规则文件"
else
  echo "⚠️ .claude/rules 目录不存在"
fi

# 检查文件大小
size=$(wc -c < CLAUDE.md)
if [ $size -gt 20000 ]; then
  echo "⚠️ CLAUDE.md 过大 (${size} bytes)，建议精简"
else
  echo "✅ CLAUDE.md 大小合理 (${size} bytes)"
fi

echo "✅ 检查完成"