agv/agv-control-slam

Fork 0

Files

CaiXiang ec1d6f0cee 项目结构调整

2025-11-15 14:31:47 +08:00

12 KiB

Raw Blame History

自动归档配置使用指南

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

配置文件

`.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修复文档
复制文档到快速查阅目录

使用方法:

# 基本用法
./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 "张三"

执行流程:

验证是否在项目根目录
创建归档目录: archives/bug_fixes/YYYYMMDD_<bug名称>/
创建子目录: code/, docs/, tests/
从模板生成文档并替换占位符
复制文档到 docs/fixes/ 供快速查阅
显示下一步操作提示

创建的目录结构:

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

功能:

自动创建功能更新归档目录结构
生成功能更新文档
复制文档到快速查阅目录

使用方法:

# 基本用法
./scripts/archive_feature.sh <功能名称>

# 指定开发者
./scripts/archive_feature.sh <功能名称> "开发者名称"

# 示例
./scripts/archive_feature.sh adaptive_lookahead
./scripts/archive_feature.sh dynamic_obstacle_avoidance "李四"

执行流程:

验证是否在项目根目录
创建归档目录: archives/updates/YYYYMMDD_<功能名称>/
创建子目录: code/, docs/, tests/
从模板生成文档并替换占位符
复制文档到 docs/updates/ 供快速查阅
显示下一步操作提示

创建的目录结构:

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
可选备份完整代码

使用方法:

# 基本用法
./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修复

执行流程:

验证版本号格式和git仓库
确定发布类型 (自动或手动指定)
创建版本目录: archives/versions/vX.Y.Z/
统计提交和文件变更
生成Release Notes
创建Git Tag
可选：备份源码到归档目录
显示推送tag的命令

创建的目录结构:

archives/versions/v1.2.0/
├── release_notes.md   # 版本发布说明
└── backup/            # 可选：完整代码备份
    └── source_code.tar.gz

完整工作流程

Bug修复流程

在主代码目录修复bug

vim src/path_tracker.cpp
# 修复bug...

提交git

git add src/path_tracker.cpp
git commit -m "fix: 修复路径跟踪误差累积问题"

创建归档

./scripts/archive_bug_fix.sh path_tracking_error "你的名字"

编辑文档

vim archives/bug_fixes/20251115_path_tracking_error/docs/BUG_path_tracking_error_20251115.md
# 填写详细的bug信息、原因分析、修复方案等

复制相关文件到归档

# 复制修复的代码
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/

提交归档

git add archives/bug_fixes/ docs/fixes/
git commit -m "archive: Bug修复 - path_tracking_error"

功能更新流程

在主代码目录开发新功能

vim src/adaptive_lookahead.cpp
vim include/adaptive_lookahead.h
# 开发新功能...

提交git

git add src/adaptive_lookahead.cpp include/adaptive_lookahead.h
git commit -m "feature: 实现自适应前视距离算法"

创建归档

./scripts/archive_feature.sh adaptive_lookahead "你的名字"

编辑文档

vim archives/updates/20251115_adaptive_lookahead/docs/UPDATE_adaptive_lookahead_20251115.md
# 填写功能说明、设计方案、使用方法等

复制相关文件到归档

# 复制新增的代码
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/

提交归档

git add archives/updates/ docs/updates/
git commit -m "archive: 功能更新 - adaptive_lookahead"

版本发布流程

确保所有变更已提交

git status
# 应该显示 "working tree clean"

运行发布脚本
```
./scripts/create_release.sh 1.2.0
```

编辑Release Notes

vim archives/versions/v1.2.0/release_notes.md
# 填写版本概述、新增功能、bug修复等

提交归档

git add archives/versions/
git commit -m "release: v1.2.0"

推送tag
```
git push origin v1.2.0
```
在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目录?

归档目录 (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 部分，修改路径配置。

维护建议

定期检查归档: 每月检查归档目录，确保文档完整
更新模板: 根据实际需求不断完善文档模板
脚本优化: 根据使用反馈优化脚本功能
配置同步: 团队成员保持配置文件一致

最后更新: 2025-11-15

12 KiB Raw Blame History Unescape Escape

自动归档配置使用指南

配置文件

.claude/file_organization.json

配置加载

文档模板

1. bug_fix_template.md

2. feature_update_template.md

3. release_notes_template.md

辅助脚本

1. Bug修复归档脚本

2. 功能更新归档脚本

3. 版本发布脚本

完整工作流程

Bug修复流程

功能更新流程

版本发布流程

AI辅助使用

自动识别归档类型

示例对话

目录快速参考

常见问题

Q: 为什么要同时保存到归档目录和docs目录?

Q: 脚本在Windows上能用吗?

Q: 如何自定义模板?

Q: AI如何知道要使用这些配置?

Q: 可以修改归档路径吗?

维护建议

12 KiB

Raw Blame History

`.claude/file_organization.json`

1. `bug_fix_template.md`

2. `feature_update_template.md`

3. `release_notes_template.md`