# 代码库说明工作流

分析代码库并生成面向开发、维护和使用人员的 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
文档概述
项目简介
技术栈与运行环境
目录结构
总体架构
主要运行流程
模块说明
文件说明
类与数据结构
函数与接口参考
配置参数
构建、运行与测试
常见问题
已知限制
```