# cc-rules

**Repository Path**: nt_qinfei/cc-rules

## Basic Information

- **Project Name**: cc-rules
- **Description**: CLaude Code 个性化规则【含 前端、后端（Python）、以及其他个人习惯】 
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Memory & Rules 配置示例

这是我的 Claude Code **用户级配置示例(User Level)**,用于部署到 `~/.claude/` 并跨项目复用。

> 项目级配置请在具体项目的 `.claude/` 目录中维护(本仓库暂不提供 `examples/project-level/`)。

## 📋 目录结构

```
CC-Rules/
├── README.md                          # 本文件
└── examples/
    ├── user-level/                    # 用户级配置(部署到 ~/.claude/)
    │   ├── CLAUDE.md                 # 个人全局配置(v2.6, uv)
    │   ├── rules/                    # Rules (约束性规范)
    │   │   ├── frontend-style.md     # 前端 UI 风格与工程规范(v2.3新增✨)
    │   │   ├── python-style.md       # Python 开发规范(已合并偏好/复用/测试等共性条目)
    │   │   └── claude-code-defensive.md  # 防御性规则(v2.1新增检查原则✨)
```

## 🆕 2025 年版本更新

**当前版本**: v2.6 - 去除 skills 目录

### v2.6 去除 skills 目录 (2025-12-14)
- ✅ **避免命名冲突**: 不再维护自定义 `skills/`,避免与 Claude Code 内置概念混淆
- ✅ **工作方式收敛到 Rules**: SDD→TDD/Debug 循环/测试层级补充到 `claude-code-defensive.md`

### v2.5 SDD→TDD 工作流 (2025-12-14)
- ✅ **开发流程升级**: 默认 SDD(规格驱动) → TDD(细节测试驱动)
- ✅ **更 AI 向**: 工作流内容压缩为模板/清单(减少人类解释与冗余示例)
- ✅ **防御规则同步**: 复杂任务先写 Spec 再编码

### v2.4 规则精简版 (2025-12-14)
- ✅ **规则去重与引用**: Python 共性规范集中到 `python-style.md`
- ✅ **精简示例**: 删除冗余示例与重复条目,保留最小核心示例
- ✅ **按需加载**: 继续通过 `paths` 限定规则生效范围

### v2.3 User Level 专注版 (2025-12-14)
- ✅ **Python 包管理统一为 uv**
- ✅ **README 移除 project-level/project-local 模板引用**: 项目级配置在具体项目 `.claude/` 中维护
- ✅ **Skills 增加文档落盘约束**: 默认只在对话中输出,除非明确要求保存文件
- ✅ **Pydantic 示例更新为 v2 风格**
- ✅ **新增前端规则**: UI 风格约束 + Vue/React 工程规范

### v2.2 重构优化 (2025-12-13)
- ✅ **Rules 和 Skills 明确分离**: 创建独立 `skills/` 目录
- ✅ **内容精简**: 用户级配置精简 30%
- ✅ **分层优化**: 移除用户级的项目特定内容
- ✅ **结构清晰**: 每个文件职责更加明确

### v2.1 开发原则增强 (2025-12-13)
- ✅ **库复用原则**: 不重复造轮子,优先使用成熟现成库
- ✅ **修改前检查原则**: 防止功能重复和冲突
- ✅ **集中式目录结构**: tests/docs 集中管理
- ✅ **TDD 内环**: Red-Green-Refactor 循环(在 v2.5 起默认前置 SDD 规格)

### v2.0 社区反馈增强 (2025-12-13)
基于 Claude Code 用户社区反馈,解决以下常见问题:
- ✅ **防止测试篡改**(最严重问题): 禁止修改测试来匹配错误代码
- ✅ **避免过度工程化**: 简单需求不要变成复杂系统
- ✅ **确保任务完成**: 不允许中途放弃 TODO 列表
- ✅ **控制文档创建**: 不主动生成中间文件和总结文档
- ✅ **简化沟通**: 减少啰嗦,代码优先

详见: `CHANGES.md`

## 💡 核心概念

### Rules vs Workflows

**Rules (规则)**:
- 约束性规范,告诉 Claude "如何做"/"不要做什么"
- 示例: "禁止修改测试"、"使用 FastAPI 框架"、"代码必须有类型注解"
- 位置: `rules/` 目录

**Workflows (可执行工作流/命令化流程)**:
- 更适合通过 Claude Code 的 workflow/plugin 能力落地(或放到项目级约定里)
- 本仓库不维护自定义 `skills/` 目录；仅保留最小“工作方式”在 `claude-code-defensive.md`

**默认工作方式(精简版)**:
- 复杂任务: 先写 Spec(SDD)+计划,确认后再实现
- 细节层: TDD(必要时加 Contract/Integration/Property-based/E2E)
- 排查: 复现 → 假设 → 隔离变量 → 最小修复 → 回归验证

## 🎯 三层级配置说明
> 这里保留“三层级”的概念说明,但本仓库目前只提供 User Level 示例。

### 1️⃣ 用户级配置(User Level)
**部署位置**: `~/.claude/`
**作用范围**: 你的所有项目
**共享范围**: 仅你自己

**包含内容**:
- 个人编码风格偏好(缩进、命名、注释习惯)
- 通用工作流程(需求分析、PRD 撰写、代码审查)
- 跨项目的技术栈偏好(FastAPI vs Django, PostgreSQL 设置)

**何时修改**:
- 你改变了编码习惯
- 学习了新的最佳实践
- 换了新的工具或技术栈

### 2️⃣ 项目级配置(Project Level)
**部署位置**: `./.claude/` 或项目根目录
**作用范围**: 当前项目
**共享范围**: 通过 Git 与团队共享

**包含内容**:
- 项目架构和技术栈
- 业务领域规则(CRO 行业术语、流程)
- 团队编码规范和约定
- API 设计标准
- 数据库设计规范

**何时修改**:
- 新增功能模块
- 团队约定变更
- 发现新的最佳实践
- 修复了重要 Bug 后总结规则

### 3️⃣ 本地私有配置(Project Local)
**部署位置**: `./CLAUDE.local.md`
**作用范围**: 当前项目
**共享范围**: 仅你自己(自动 gitignore)

**包含内容**:
- 本地开发环境配置(数据库 URL、API Key)
- 个人调试偏好
- 临时笔记和 TODO
- 正在实验的功能

**何时修改**:
- 切换开发环境
- 需要记录调试信息
- 临时记录想法

## 📦 部署指南

### 步骤 1: 部署用户级配置

```bash
# 0. 确保 Claude Code 已初始化(必须存在 ~/.claude)
test -d ~/.claude || (echo "ERROR: ~/.claude 不存在，请先安装并运行一次 Claude Code" >&2; exit 1)

# 1. 推荐: 一键部署(会把旧 CLAUDE.md 和 rules/ 移动到本仓库的 backup/ 下)
./deploy_user_level.sh

# 2. 或手动部署
mkdir -p ~/.claude/rules
cp examples/user-level/CLAUDE.md ~/.claude/CLAUDE.md
cp examples/user-level/rules/* ~/.claude/rules/

# 3. 验证
ls -la ~/.claude/
# 应该看到 CLAUDE.md 和 rules/ 目录
```

### 步骤 2: (可选)在项目中启用项目级配置

```bash
# 在具体项目里维护 .claude/ (本仓库不提供 project-level 模板)
mkdir -p .claude/rules
touch .claude/CLAUDE.md
```

### 步骤 3: (可选)项目本地私有配置

```bash
# 在项目根目录创建本地私有配置,并确保 gitignore
touch CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore
```

## 🔧 验证部署

### 使用 Claude Code 验证

```bash
# 1. 在项目目录启动 Claude Code
cd ~/projects/cro-platform
claude

# 2. 在 Claude Code 中执行
/memory

# 3. 你应该看到加载的 memory 文件列表:
# - User memory: ~/.claude/CLAUDE.md
# - User rules: ~/.claude/rules/*.md
# - Project memory: ./.claude/CLAUDE.md (如果存在)
# - Project rules: ./.claude/rules/**/*.md (如果存在)
# - Project local: ./CLAUDE.local.md (如果存在)
```

### 测试 rules 生效

```bash
# 在 Claude Code 中,让它帮你写一段代码
# 观察它是否遵循了你设置的规则:

用户: 帮我创建一个受试者入组的 API 端点

# 期望 Claude Code 会:
# 1. 使用 FastAPI 框架
# 2. 包含类型注解和 docstring
# 3. 遵循你项目自己的领域规则(项目级 .claude/rules/)
# 4. 添加必要的安全与审计约束(项目级规则优先)
# 5. 使用正确的响应格式
```

## 📝 使用技巧

### 1. 快速添加新规则

使用 Claude Code 的 `#` 快捷键:

```
# 在 Claude Code 输入框开头输入:
# 所有 API 端点必须包含限流装饰器

# Claude 会询问保存到哪个文件,选择合适的 rules 文件
```

### 2. 使用 paths 字段精确控制

在 rules 文件的 YAML frontmatter 中使用 `paths`:

```yaml
---
paths: ["**/models/subject*.py", "**/api/**/subjects.py"]
---

# 这条规则只在处理受试者相关代码时生效
```

### 3. 定期审查和更新

建议频率:
- **用户级规则**: 每月审查一次
- **项目级规则**: 每个 Sprint 结束后审查
- **本地配置**: 随时更新

### 4. 使用符号链接共享通用规则

如果你有多个 CRO 项目,可以创建共享规则库:

```bash
# 1. 创建共享规则库
mkdir -p ~/cro-shared-rules

# 2. 将通用规则移到共享库
mv .claude/rules/cro-domain ~/cro-shared-rules/

# 3. 在各个项目中创建符号链接
cd ~/projects/smo-system
ln -s ~/cro-shared-rules/cro-domain .claude/rules/cro-domain

cd ~/projects/edc-system
ln -s ~/cro-shared-rules/cro-domain .claude/rules/cro-domain
```

## ⚠️ 注意事项

### 1. 规则冲突处理

**优先级**(高到低):
1. 项目级 rules(`.claude/rules/`)
2. 项目级 CLAUDE.md(`.claude/CLAUDE.md`)
3. 用户级 rules(`~/.claude/rules/`)
4. 用户级 CLAUDE.md(`~/.claude/CLAUDE.md`)

**示例**:
- 用户级偏好用 2 空格缩进
- 项目级要求用 4 空格缩进
- **结果**: Claude 会使用 4 空格(项目级优先)

### 2. 避免规则过载

**最佳实践**:
- 单个 rules 文件控制在 **150-300 行**
- 整个项目的 rules 总量建议 < **2000 行**
- 只添加真正必要的规则,避免"为了完整而完整"

**检查信号**:
- Claude 回答变得模糊不清
- 经常出现"我不确定该遵循哪条规则"
- 输出质量下降

**解决方法**:
- 删除过时的规则
- 合并重复的规则
- 使用 `paths` 字段限定作用范围

### 3. 敏感信息保护

**绝对不要在 Git 提交的文件中包含**:
- API Keys
- 数据库密码
- 真实的受试者数据
- 生产环境配置

**正确做法**:
- 敏感信息放在 `CLAUDE.local.md`(已 gitignore)
- 或使用 `.env` 文件(已 gitignore)
- 在示例中使用占位符

### 4. 团队协作

**当修改项目级 rules 时**:
1. 创建 feature 分支
2. 修改 rules 文件
3. 提交 Pull Request
4. 团队 Code Review(包括 rules 变更)
5. 合并到主分支

**沟通**:
- 重大 rules 变更需要团队讨论
- 在 PR 中说明变更理由
- 更新后通知团队成员

## 📊 维护策略

### 每月维护清单

```markdown
## Memory & Rules 月度维护

### User Level (~/.claude/)
- [ ] 审查个人偏好是否仍然适用
- [ ] 删除不再使用的工具/库的规则
- [ ] 更新工作流程(如有变化)

### Project Level (.claude/)
- [ ] 检查是否有过时的业务规则
- [ ] 补充新增功能的领域规则
- [ ] 更新技术栈版本相关规则
- [ ] 清理临时添加的规则

### Project Local (CLAUDE.local.md)
- [ ] 更新本地环境配置
- [ ] 清理已完成的 TODO
- [ ] 归档已解决的调试笔记
```

### 规则文件版本化

建议在项目 CHANGELOG.md 中记录重要的 rules 变更:

```markdown
## [1.2.0] - 2025-01-15

### Rules Changes
- Added: EDC 数据验证规则引擎规范
- Updated: SMO 中心启动流程要求
- Removed: 旧的 Django REST framework 规则(已迁移到 FastAPI)
```

## 🚀 进阶用法

### 1. 条件规则

```yaml
---
paths: "**/models/*.py"
---

# 仅对 models 目录生效的规则
```

### 2. 多项目规则共享

```bash
# 创建规则模板仓库
git clone https://github.com/your-org/claude-rules-templates.git ~/claude-rules

# 在项目中引用
ln -s ~/claude-rules/cro-common .claude/rules/common
```

### 3. 规则测试

创建 `tests/test_rules_compliance.py`:

```python
"""测试代码是否符合 rules."""

def test_all_api_endpoints_have_docstrings():
    """所有 API 端点必须有 docstring."""
    # 扫描 api/ 目录下的所有路由函数
    # 验证每个函数都有 docstring
    pass

def test_all_models_have_audit_fields():
    """所有模型必须有审计字段."""
    # 扫描 models/ 目录
    # 验证每个模型都有 created_at, updated_at 等字段
    pass
```

## 📚 参考资源

### 官方文档
- [Claude Code Memory 官方文档](https://code.claude.com/docs/en/memory)
- [Claude Code Rules 指南](https://code.claude.com/docs/en/rules)

### 社区资源
- [Awesome Cursor Rules](https://github.com/PatrickJS/awesome-cursorrules) - 大量 rules 示例
- [Awesome Cursor Rules MDC](https://github.com/sanjeed5/awesome-cursor-rules-mdc) - MDC 格式规则

### 相关文章
- 本配置基于的指导文章: [别再只写 CLAUDE.md 了：用 Rules 重构 Claude Code 的记忆系统]

## 🤝 贡献

如果你发现了更好的规则组织方式或有新的 CRO 领域规则,欢迎:
1. Fork 本仓库
2. 创建你的规则文件
3. 提交 Pull Request

## 📄 许可证

本示例配置遵循 MIT 许可证,可自由使用和修改。

---

**最后更新**: 2025-12-13
**维护者**: Atlas
**项目**: 我爱的 CC 规则