feat: 完善模块化 CLAUDE.md 文档体系

- 新增 admin/CLAUDE.md - 管理后台开发指导文档
  - 修正技术栈为 React + TypeScript + shadcn/ui
  - 提供完整的管理后台架构设计
  - 包含照片管理、分类管理、日志管理等核心功能
  - 详细的开发环境配置和部署指南

- 新增 backend/CLAUDE.md - 后端开发指导文档
  - 基于 Golang + Gin + GORM 技术栈
  - 完整的 API 接口设计和数据库架构
  - 包含认证、权限、文件存储等核心功能
  - 详细的部署和监控配置

- 新增 ui/CLAUDE.md - UI 备份模块管理文档
  - 支持组件备份和 A/B 测试功能
  - 详细的同步策略和实验环境配置
  - 完整的版本管理和协作流程

- 更新 CLAUDE.md 根目录文档
  - 完善模块选择指南和协调机制
  - 新增模块间通信和依赖关系说明
  - 优化文档维护和使用建议
  - 建立完整的模块化开发规范

通过模块化设计最大限度减少 AI 幻觉,提高开发效率。
This commit is contained in:
xujiang
2025-07-09 14:23:15 +08:00
parent 21b1581bdb
commit 73197d8da8
4 changed files with 2380 additions and 15 deletions

107
CLAUDE.md
View File

@ -40,9 +40,14 @@ photography/
├── .gitea/workflows/ # ⚙️ CI/CD 模块
│ ├── CLAUDE.md # CI/CD 配置指导
│ └── deploy-frontend.yml # 自动部署工作流
├── admin/ # 📋 管理后台 (预留)
├── backend/ # 🔧 后端 API (预留)
── ui/ # 🎨 UI 组件备份
├── admin/ # 📋 管理后台模块
│ └── CLAUDE.md # 管理后台开发指导
── backend/ # 🔧 后端 API 模块
│ └── CLAUDE.md # 后端开发指导
├── ui/ # 🎨 UI 备份模块
│ └── CLAUDE.md # UI 备份模块管理
└── scripts/ # 🛠️ 工具脚本
└── README.md # 脚本说明
```
## 🎯 模块化工作指南
@ -73,6 +78,30 @@ cd .gitea/workflows/
```
**适用场景**: 自动部署、构建流程、环境配置、工作流优化
#### 📋 管理后台开发
```bash
# 切换到管理后台模块
cd admin/
# 参考 admin/CLAUDE.md
```
**适用场景**: 管理界面开发、用户管理、内容管理、权限控制
#### 🔧 后端 API 开发
```bash
# 切换到后端模块
cd backend/
# 参考 backend/CLAUDE.md
```
**适用场景**: API 接口开发、数据库设计、认证服务、文件存储
#### 🎨 UI 备份和实验
```bash
# 切换到 UI 备份模块
cd ui/
# 参考 ui/CLAUDE.md
```
**适用场景**: 组件备份、A/B 测试、实验性功能、版本对比
#### 📚 文档和架构
```bash
# 在根目录工作
@ -168,6 +197,9 @@ git push origin main # 触发自动部署
- **前端问题**: 查看 `frontend/CLAUDE.md`
- **部署问题**: 查看 `docs/deployment/CLAUDE.md`
- **CI/CD 问题**: 查看 `.gitea/workflows/CLAUDE.md`
- **管理后台问题**: 查看 `admin/CLAUDE.md`
- **后端问题**: 查看 `backend/CLAUDE.md`
- **UI 备份问题**: 查看 `ui/CLAUDE.md`
### 通用问题
```bash
@ -190,11 +222,16 @@ cd frontend && make clean && make install
- ✅ 代码质量控制 (ESLint + Prettier + TypeScript)
- ✅ Pre-commit hooks
### 开发中功能
- 📋 管理后台 (架构设计完成)
- 📋 后端 API (架构设计完成)
- 📋 UI 备份系统 (已实现)
### 计划中功能
- 📋 管理后台
- 📋 后端 API
- 📋 多环境部署
- 📋 性能监控
- 📋 AI 功能集成
- 📋 数据分析系统
## 🎨 模块协调原则
@ -202,12 +239,18 @@ cd frontend && make clean && make install
1. **前端模块** (`frontend/CLAUDE.md`): 组件、样式、前端逻辑变更时
2. **部署模块** (`docs/deployment/CLAUDE.md`): 服务器、配置、部署流程变更时
3. **CI/CD 模块** (`.gitea/workflows/CLAUDE.md`): 工作流、构建流程变更时
4. **根目录** (`CLAUDE.md`): 项目架构、模块关系变更时
4. **管理后台模块** (`admin/CLAUDE.md`): 后台功能、权限管理变更时
5. **后端模块** (`backend/CLAUDE.md`): API 接口、数据库架构变更时
6. **UI 备份模块** (`ui/CLAUDE.md`): 组件备份、实验功能变更时
7. **根目录** (`CLAUDE.md`): 项目架构、模块关系变更时
### 模块间通信
- 前端构建产物 → 部署模块使用
- CI/CD 协调 → 所有模块的构建和部署
- 配置变更 → 相关模块的 CLAUDE.md 同步更新
- **前端 ↔ 后端**: API 接口调用和数据交换
- **管理后台 ↔ 后端**: 管理接口和数据操作
- **UI 备份 ↔ 前端**: 组件同步和实验功能验证
- **前端构建产物 → 部署模块**: 静态文件部署
- **CI/CD 协调 → 所有模块**: 构建和部署流程
- **配置变更 → 相关模块**: CLAUDE.md 同步更新
## 🔄 最佳实践
@ -219,11 +262,45 @@ cd frontend && make clean && make install
5. 提交代码触发自动部署
### 文档维护
- 每个模块的 CLAUDE.md 保持独立和聚焦
- 模块间的依赖关系在根目录 CLAUDE.md 中说明
- 重要的全局配置统一在根目录管理
- **模块独立**: 每个模块的 CLAUDE.md 保持独立和聚焦
- **架构统一**: 模块间的依赖关系在根目录 CLAUDE.md 中说明
- **配置集中**: 重要的全局配置统一在根目录管理
- **及时更新**: 功能变更后立即更新对应的 CLAUDE.md
- **一致性**: 保持各模块文档的格式和风格一致
### 上下文优化
- Claude 工作时只需关注单个模块的 CLAUDE.md
- 减少上下文长度,提高处理效率
- 模块化降低复杂性,提高开发效率
- **聚焦开发**: Claude 工作时只需关注单个模块的 CLAUDE.md
- **减少负载**: 避免加载无关模块的文档,减少上下文长度
- **提高效率**: 模块化降低复杂性,提高开发效率
- **避免幻觉**: 精确的模块指导减少 AI 产生错误信息的可能性
- **快速定位**: 问题出现时能快速定位到相关模块和文档
## 📋 模块 CLAUDE.md 文件列表
### 核心模块
- ✅ **根目录** (`CLAUDE.md`) - 项目总览和模块协调
- ✅ **前端模块** (`frontend/CLAUDE.md`) - 前端开发指导
- ✅ **部署模块** (`docs/deployment/CLAUDE.md`) - 部署配置指导
- ✅ **CI/CD 模块** (`.gitea/workflows/CLAUDE.md`) - 自动化部署指导
### 新增模块
- ✅ **管理后台模块** (`admin/CLAUDE.md`) - 管理界面开发指导
- ✅ **后端模块** (`backend/CLAUDE.md`) - API 服务开发指导
- ✅ **UI 备份模块** (`ui/CLAUDE.md`) - 组件备份和实验指导
### 辅助模块
- ✅ **工具脚本** (`scripts/README.md`) - 自动化脚本说明
## 🎯 使用建议
### 选择正确的模块
1. **明确任务类型**: 根据要解决的问题选择对应的模块
2. **切换工作目录**: 进入相应的模块目录进行开发
3. **参考模块文档**: 仔细阅读模块的 CLAUDE.md 文件
4. **遵循模块规范**: 按照模块的开发规范和流程进行工作
### 跨模块协作
1. **理解依赖关系**: 了解模块间的依赖和数据流向
2. **协调接口变更**: 涉及多个模块时,确保接口一致性
3. **同步更新文档**: 跨模块变更时,同步更新相关文档
4. **测试集成功能**: 确保模块间的集成功能正常工作