# 自动归档配置使用指南

本文档说明如何使用项目的自动归档配置和辅助脚本。

---

## 配置文件

### `.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