108 lines
2.3 KiB
Markdown
108 lines
2.3 KiB
Markdown
|
||
# 代码库说明工作流
|
||
|
||
分析代码库并生成面向开发、维护和使用人员的 LaTeX 代码参考文档。
|
||
|
||
## 定位代码库
|
||
|
||
如果用户指定了项目路径，优先使用该路径。
|
||
|
||
否则从当前目录识别 Git 仓库根目录。
|
||
|
||
如果当前目录不是 Git 仓库：
|
||
|
||
1. 在工作区内浅层查找 Git 仓库；
|
||
2. 只有一个仓库时使用该仓库；
|
||
3. 存在多个仓库时让用户选择；
|
||
4. 没有仓库时，将当前项目目录作为目标。
|
||
|
||
读取项目适用的 `AGENTS.md`、README 和主要设计文档。
|
||
|
||
## 确定分析范围
|
||
|
||
支持两种范围：
|
||
|
||
### `scope=core`
|
||
|
||
默认模式，只整理：
|
||
|
||
- 项目入口；
|
||
- 核心模块；
|
||
- 公共接口；
|
||
- 主要类；
|
||
- 关键算法；
|
||
- 外部可调用函数；
|
||
- 重要配置和数据结构。
|
||
|
||
不详细记录普通私有辅助函数、生成代码和测试辅助代码。
|
||
|
||
### `scope=all`
|
||
|
||
只有用户明确要求时使用，尽量整理全部可识别的代码文件、类和函数。
|
||
|
||
如果项目规模很大，应先统计文件和符号数量，并让用户选择模块或分批生成，不要一次读取整个大型代码库。
|
||
|
||
## 调研代码库
|
||
|
||
优先检查：
|
||
|
||
- README 和主要文档；
|
||
- 项目清单和依赖配置；
|
||
- 项目入口；
|
||
- 源码目录；
|
||
- 核心模块；
|
||
- 公共头文件和接口；
|
||
- 配置文件和配置类；
|
||
- 测试中体现的实际行为；
|
||
- Git 当前状态和最近相关提交。
|
||
|
||
使用 `rg --files` 和针对性符号搜索。
|
||
|
||
默认排除：
|
||
|
||
- `.git`；
|
||
- `bin`、`obj`、`build`、`dist`；
|
||
- 第三方依赖目录；
|
||
- 日志、缓存和编译产物；
|
||
- 自动生成代码；
|
||
- 大型数据文件；
|
||
- 与目标模块无关的参考项目。
|
||
|
||
## 识别项目结构
|
||
|
||
根据实际代码识别：
|
||
|
||
- 编程语言和技术栈；
|
||
- 项目入口；
|
||
- 目录职责；
|
||
- 模块边界；
|
||
- 核心数据结构；
|
||
- 模块依赖；
|
||
- 主要调用流程；
|
||
- 外部接口；
|
||
- 配置方式；
|
||
- 构建、运行和测试方法。
|
||
|
||
不要根据目录名或常见框架习惯编造系统行为。
|
||
|
||
## 组织代码文档
|
||
|
||
建议采用以下结构：
|
||
|
||
```text
|
||
文档概述
|
||
项目简介
|
||
技术栈与运行环境
|
||
目录结构
|
||
总体架构
|
||
主要运行流程
|
||
模块说明
|
||
文件说明
|
||
类与数据结构
|
||
函数与接口参考
|
||
配置参数
|
||
构建、运行与测试
|
||
常见问题
|
||
已知限制
|
||
```
|