451 lines
12 KiB
Markdown
451 lines
12 KiB
Markdown
# 自动归档配置使用指南
|
||
|
||
本文档说明如何使用项目的自动归档配置和辅助脚本。
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
### `.claude/file_organization.json`
|
||
|
||
这是主配置文件，定义了项目的文件组织规则，包括：
|
||
|
||
- **目录结构定义**: 归档目录、文档目录、源码目录的路径和用途
|
||
- **文件类型规则**: 不同文件扩展名的默认存放位置
|
||
- **命名规范**: Bug修复、功能更新、版本发布的命名模板
|
||
- **工作流规则**: 各类归档的标准流程
|
||
- **自动分类规则**: 根据关键词自动识别归档类型
|
||
- **模板路径**: 文档模板的位置
|
||
- **脚本路径**: 辅助脚本的位置
|
||
|
||
### 配置加载
|
||
|
||
配置文件会被以下工具自动读取：
|
||
- Claude Code AI (自动识别文件组织规则)
|
||
- 辅助脚本 (使用配置生成归档)
|
||
|
||
---
|
||
|
||
## 文档模板
|
||
|
||
模板位置: `.claude/templates/`
|
||
|
||
### 1. `bug_fix_template.md`
|
||
Bug修复文档模板，包含以下占位符：
|
||
- `{{BUG_DESCRIPTION}}` - Bug描述
|
||
- `{{DATE}}` - 日期
|
||
- `{{AUTHOR}}` - 作者
|
||
- `{{COMMIT_HASH}}` - Git提交哈希
|
||
- `{{FILE_PATH}}` - 文件路径
|
||
- 等等...
|
||
|
||
### 2. `feature_update_template.md`
|
||
功能更新文档模板，包含以下占位符：
|
||
- `{{FEATURE_NAME}}` - 功能名称
|
||
- `{{DATE}}` - 日期
|
||
- `{{AUTHOR}}` - 开发者
|
||
- `{{COMMIT_HASH}}` - Git提交哈希
|
||
- 等等...
|
||
|
||
### 3. `release_notes_template.md`
|
||
版本发布说明模板，包含以下占位符：
|
||
- `{{VERSION}}` - 版本号
|
||
- `{{RELEASE_DATE}}` - 发布日期
|
||
- `{{RELEASE_TYPE}}` - 发布类型
|
||
- `{{COMMIT_COUNT}}` - 提交数量
|
||
- 等等...
|
||
|
||
---
|
||
|
||
## 辅助脚本
|
||
|
||
脚本位置: `scripts/`
|
||
|
||
### 1. Bug修复归档脚本
|
||
|
||
**脚本**: `scripts/archive_bug_fix.sh`
|
||
|
||
**功能**:
|
||
- 自动创建Bug修复归档目录结构
|
||
- 生成Bug修复文档
|
||
- 复制文档到快速查阅目录
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 基本用法
|
||
./scripts/archive_bug_fix.sh <bug名称>
|
||
|
||
# 指定作者
|
||
./scripts/archive_bug_fix.sh <bug名称> "作者名称"
|
||
|
||
# 示例
|
||
./scripts/archive_bug_fix.sh path_tracking_error
|
||
./scripts/archive_bug_fix.sh csv_load_issue "张三"
|
||
```
|
||
|
||
**执行流程**:
|
||
1. 验证是否在项目根目录
|
||
2. 创建归档目录: `archives/bug_fixes/YYYYMMDD_<bug名称>/`
|
||
3. 创建子目录: `code/`, `docs/`, `tests/`
|
||
4. 从模板生成文档并替换占位符
|
||
5. 复制文档到 `docs/fixes/` 供快速查阅
|
||
6. 显示下一步操作提示
|
||
|
||
**创建的目录结构**:
|
||
```
|
||
archives/bug_fixes/20251115_path_tracking_error/
|
||
├── code/ # 存放修复的代码文件
|
||
├── docs/ # 存放详细文档
|
||
│ └── BUG_path_tracking_error_20251115.md
|
||
└── tests/ # 存放测试文件
|
||
|
||
docs/fixes/ # 文档快速查阅副本
|
||
└── BUG_path_tracking_error_20251115.md
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 功能更新归档脚本
|
||
|
||
**脚本**: `scripts/archive_feature.sh`
|
||
|
||
**功能**:
|
||
- 自动创建功能更新归档目录结构
|
||
- 生成功能更新文档
|
||
- 复制文档到快速查阅目录
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 基本用法
|
||
./scripts/archive_feature.sh <功能名称>
|
||
|
||
# 指定开发者
|
||
./scripts/archive_feature.sh <功能名称> "开发者名称"
|
||
|
||
# 示例
|
||
./scripts/archive_feature.sh adaptive_lookahead
|
||
./scripts/archive_feature.sh dynamic_obstacle_avoidance "李四"
|
||
```
|
||
|
||
**执行流程**:
|
||
1. 验证是否在项目根目录
|
||
2. 创建归档目录: `archives/updates/YYYYMMDD_<功能名称>/`
|
||
3. 创建子目录: `code/`, `docs/`, `tests/`
|
||
4. 从模板生成文档并替换占位符
|
||
5. 复制文档到 `docs/updates/` 供快速查阅
|
||
6. 显示下一步操作提示
|
||
|
||
**创建的目录结构**:
|
||
```
|
||
archives/updates/20251115_adaptive_lookahead/
|
||
├── code/ # 存放新增/修改的代码
|
||
├── docs/ # 存放详细文档
|
||
│ └── UPDATE_adaptive_lookahead_20251115.md
|
||
└── tests/ # 存放测试文件
|
||
|
||
docs/updates/ # 文档快速查阅副本
|
||
└── UPDATE_adaptive_lookahead_20251115.md
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 版本发布脚本
|
||
|
||
**脚本**: `scripts/create_release.sh`
|
||
|
||
**功能**:
|
||
- 创建版本归档目录
|
||
- 生成Release Notes
|
||
- 创建Git Tag
|
||
- 可选备份完整代码
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 基本用法
|
||
./scripts/create_release.sh <版本号>
|
||
|
||
# 指定发布类型
|
||
./scripts/create_release.sh <版本号> <Major|Minor|Patch>
|
||
|
||
# 示例
|
||
./scripts/create_release.sh 1.2.0
|
||
./scripts/create_release.sh 2.0.0 Major
|
||
./scripts/create_release.sh 1.2.1 Patch
|
||
```
|
||
|
||
**版本号格式**: X.Y.Z
|
||
- **X** (Major): 重大版本，可能包含不兼容的API变更
|
||
- **Y** (Minor): 次要版本，新增功能但向后兼容
|
||
- **Z** (Patch): 补丁版本，仅bug修复
|
||
|
||
**执行流程**:
|
||
1. 验证版本号格式和git仓库
|
||
2. 确定发布类型 (自动或手动指定)
|
||
3. 创建版本目录: `archives/versions/vX.Y.Z/`
|
||
4. 统计提交和文件变更
|
||
5. 生成Release Notes
|
||
6. 创建Git Tag
|
||
7. 可选：备份源码到归档目录
|
||
8. 显示推送tag的命令
|
||
|
||
**创建的目录结构**:
|
||
```
|
||
archives/versions/v1.2.0/
|
||
├── release_notes.md # 版本发布说明
|
||
└── backup/ # 可选：完整代码备份
|
||
└── source_code.tar.gz
|
||
```
|
||
|
||
---
|
||
|
||
## 完整工作流程
|
||
|
||
### Bug修复流程
|
||
|
||
1. **在主代码目录修复bug**
|
||
```bash
|
||
vim src/path_tracker.cpp
|
||
# 修复bug...
|
||
```
|
||
|
||
2. **提交git**
|
||
```bash
|
||
git add src/path_tracker.cpp
|
||
git commit -m "fix: 修复路径跟踪误差累积问题"
|
||
```
|
||
|
||
3. **创建归档**
|
||
```bash
|
||
./scripts/archive_bug_fix.sh path_tracking_error "你的名字"
|
||
```
|
||
|
||
4. **编辑文档**
|
||
```bash
|
||
vim archives/bug_fixes/20251115_path_tracking_error/docs/BUG_path_tracking_error_20251115.md
|
||
# 填写详细的bug信息、原因分析、修复方案等
|
||
```
|
||
|
||
5. **复制相关文件到归档**
|
||
```bash
|
||
# 复制修复的代码
|
||
cp src/path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/code/
|
||
|
||
# 如有测试文件
|
||
cp tests/test_path_tracker.cpp archives/bug_fixes/20251115_path_tracking_error/tests/
|
||
```
|
||
|
||
6. **提交归档**
|
||
```bash
|
||
git add archives/bug_fixes/ docs/fixes/
|
||
git commit -m "archive: Bug修复 - path_tracking_error"
|
||
```
|
||
|
||
---
|
||
|
||
### 功能更新流程
|
||
|
||
1. **在主代码目录开发新功能**
|
||
```bash
|
||
vim src/adaptive_lookahead.cpp
|
||
vim include/adaptive_lookahead.h
|
||
# 开发新功能...
|
||
```
|
||
|
||
2. **提交git**
|
||
```bash
|
||
git add src/adaptive_lookahead.cpp include/adaptive_lookahead.h
|
||
git commit -m "feature: 实现自适应前视距离算法"
|
||
```
|
||
|
||
3. **创建归档**
|
||
```bash
|
||
./scripts/archive_feature.sh adaptive_lookahead "你的名字"
|
||
```
|
||
|
||
4. **编辑文档**
|
||
```bash
|
||
vim archives/updates/20251115_adaptive_lookahead/docs/UPDATE_adaptive_lookahead_20251115.md
|
||
# 填写功能说明、设计方案、使用方法等
|
||
```
|
||
|
||
5. **复制相关文件到归档**
|
||
```bash
|
||
# 复制新增的代码
|
||
cp src/adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/code/
|
||
cp include/adaptive_lookahead.h archives/updates/20251115_adaptive_lookahead/code/
|
||
|
||
# 如有测试和示例
|
||
cp tests/test_adaptive_lookahead.cpp archives/updates/20251115_adaptive_lookahead/tests/
|
||
cp examples/example_adaptive.cpp archives/updates/20251115_adaptive_lookahead/code/
|
||
```
|
||
|
||
6. **提交归档**
|
||
```bash
|
||
git add archives/updates/ docs/updates/
|
||
git commit -m "archive: 功能更新 - adaptive_lookahead"
|
||
```
|
||
|
||
---
|
||
|
||
### 版本发布流程
|
||
|
||
1. **确保所有变更已提交**
|
||
```bash
|
||
git status
|
||
# 应该显示 "working tree clean"
|
||
```
|
||
|
||
2. **运行发布脚本**
|
||
```bash
|
||
./scripts/create_release.sh 1.2.0
|
||
```
|
||
|
||
3. **编辑Release Notes**
|
||
```bash
|
||
vim archives/versions/v1.2.0/release_notes.md
|
||
# 填写版本概述、新增功能、bug修复等
|
||
```
|
||
|
||
4. **提交归档**
|
||
```bash
|
||
git add archives/versions/
|
||
git commit -m "release: v1.2.0"
|
||
```
|
||
|
||
5. **推送tag**
|
||
```bash
|
||
git push origin v1.2.0
|
||
```
|
||
|
||
6. **在GitHub/GitLab创建Release**
|
||
- 上传编译好的二进制文件
|
||
- 复制Release Notes内容
|
||
- 发布
|
||
|
||
---
|
||
|
||
## AI辅助使用
|
||
|
||
当使用Claude Code时，AI会自动读取 `.claude/file_organization.json` 配置，并根据以下规则工作：
|
||
|
||
### 自动识别归档类型
|
||
|
||
AI会根据关键词自动识别任务类型：
|
||
|
||
- **Bug修复关键词**: bug, fix, 修复, 错误, 问题
|
||
- 文件归档到: `archives/bug_fixes/`
|
||
- 文档归档到: `docs/fixes/`
|
||
|
||
- **功能更新关键词**: feature, update, 新增, 功能, 更新, add, implement
|
||
- 文件归档到: `archives/updates/`
|
||
- 文档归档到: `docs/updates/`
|
||
|
||
- **版本发布关键词**: version, release, 版本, 发布
|
||
- 文件归档到: `archives/versions/`
|
||
|
||
### 示例对话
|
||
|
||
```
|
||
用户: 我发现了一个路径跟踪的bug，帮我修复并归档
|
||
|
||
AI: 我会帮你修复这个bug并按照项目规范归档。根据配置，我会：
|
||
1. 修复代码
|
||
2. 创建归档目录 archives/bug_fixes/YYYYMMDD_path_tracking/
|
||
3. 生成修复文档
|
||
4. 复制代码和文档到相应位置
|
||
```
|
||
|
||
```
|
||
用户: 实现一个新的自适应前视距离功能
|
||
|
||
AI: 我会实现这个新功能并归档。根据配置，我会：
|
||
1. 开发新功能代码
|
||
2. 创建归档目录 archives/updates/YYYYMMDD_adaptive_lookahead/
|
||
3. 生成功能文档
|
||
4. 创建使用示例
|
||
```
|
||
|
||
---
|
||
|
||
## 目录快速参考
|
||
|
||
```
|
||
project_root/
|
||
├── .claude/
|
||
│ ├── file_organization.json # 主配置文件
|
||
│ └── templates/ # 文档模板
|
||
│ ├── bug_fix_template.md
|
||
│ ├── feature_update_template.md
|
||
│ └── release_notes_template.md
|
||
│
|
||
├── scripts/ # 辅助脚本
|
||
│ ├── archive_bug_fix.sh # Bug修复归档
|
||
│ ├── archive_feature.sh # 功能更新归档
|
||
│ └── create_release.sh # 版本发布
|
||
│
|
||
├── archives/ # 归档目录
|
||
│ ├── bug_fixes/ # Bug修复归档
|
||
│ │ └── YYYYMMDD_bug名称/
|
||
│ │ ├── code/
|
||
│ │ ├── docs/
|
||
│ │ └── tests/
|
||
│ ├── updates/ # 功能更新归档
|
||
│ │ └── YYYYMMDD_功能名称/
|
||
│ │ ├── code/
|
||
│ │ ├── docs/
|
||
│ │ └── tests/
|
||
│ └── versions/ # 版本归档
|
||
│ └── vX.Y.Z/
|
||
│ ├── release_notes.md
|
||
│ └── backup/
|
||
│
|
||
├── docs/ # 当前文档
|
||
│ ├── fixes/ # Bug修复文档（快速查阅）
|
||
│ ├── updates/ # 功能更新文档（快速查阅）
|
||
│ ├── guides/ # 使用指南
|
||
│ └── protocol/ # 协议文档
|
||
│
|
||
├── src/ # 源代码（主工作目录）
|
||
├── include/ # 头文件（主工作目录）
|
||
└── examples/ # 示例代码（主工作目录）
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么要同时保存到归档目录和docs目录?
|
||
|
||
A:
|
||
- **归档目录** (`archives/`): 完整归档，包含代码、文档、测试，用于长期保存和追溯
|
||
- **文档目录** (`docs/`): 文档副本，方便快速查阅最新的修复和更新
|
||
|
||
### Q: 脚本在Windows上能用吗?
|
||
|
||
A: 脚本是bash脚本，需要在Git Bash、WSL或Cygwin中运行。也可以手动执行脚本中的步骤。
|
||
|
||
### Q: 如何自定义模板?
|
||
|
||
A: 直接编辑 `.claude/templates/` 下的模板文件，使用 `{{占位符}}` 格式添加自定义字段。
|
||
|
||
### Q: AI如何知道要使用这些配置?
|
||
|
||
A: AI会自动读取 `.claude/file_organization.json` 配置文件，并根据其中的规则工作。
|
||
|
||
### Q: 可以修改归档路径吗?
|
||
|
||
A: 可以，编辑 `.claude/file_organization.json` 中的 `directories` 部分，修改路径配置。
|
||
|
||
---
|
||
|
||
## 维护建议
|
||
|
||
1. **定期检查归档**: 每月检查归档目录，确保文档完整
|
||
2. **更新模板**: 根据实际需求不断完善文档模板
|
||
3. **脚本优化**: 根据使用反馈优化脚本功能
|
||
4. **配置同步**: 团队成员保持配置文件一致
|
||
|
||
---
|
||
|
||
最后更新: 2025-11-15
|