基于多智能体架构的AI文档生成系统：从原理到工程实践-开发者社区

1. 项目概述：当AI成为你的代码“首席文档官”

在软件开发这个行当里，文档的维护一直是个“老大难”问题。代码在迭代，功能在演进，但文档却常常被遗忘在角落，逐渐“腐烂”——要么过时，要么语焉不详，要么干脆没有。新成员加入项目，面对动辄数万行的代码库，往往需要数周甚至数月才能摸清门道，这其中的时间成本和沟通损耗，每个技术团队都深有体会。我经历过太多这样的场景：为了搞懂一个核心模块，不得不去翻找几年前的提交记录，或者挨个去问已经离职的同事。这种低效和痛苦，催生了我们对自动化、智能化文档工具的渴望。

divar-ir/ai-doc-gen这个项目，正是为了解决这一痛点而生。它不是一个简单的代码注释提取器，而是一个基于多智能体（Multi-Agent）架构的AI文档生成系统。它的核心思想是：让多个具备不同专长的“AI专家”协同工作，像一支训练有素的侦察小队一样，深入你的代码仓库，从结构、数据流、依赖关系、API设计等多个维度进行全面“体检”，然后综合所有发现，生成一份结构清晰、内容详实、可直接用于项目介绍的README文档，甚至还能为你的AI编程助手（如Cursor、Claude Code）生成专属的配置规则。

简单来说，它试图扮演一个“首席文档官”的角色，把开发者从繁琐、重复且容易出错的文档编写工作中解放出来，同时确保文档与代码的实时同步。无论你是个人开发者维护一个开源项目，还是团队负责人需要快速为新项目建立知识库，或是想为遗留系统补全缺失的文档，这个工具都能提供强大的助力。接下来，我将结合自己多年的工程实践，为你深入拆解这个项目的设计思路、实现细节以及那些在官方文档里不会写的“踩坑”经验。

2. 核心设计思路：为什么是多智能体架构？

在深入代码之前，我们必须先理解其灵魂——多智能体架构。这是本项目区别于市面上其他单模型文档工具的关键。为什么不用一个“全能”的大模型直接读取整个代码库然后输出文档呢？原因在于精度、成本和可控性。

2.1 单一模型的局限性

一个大型语言模型（LLM）虽然知识渊博，但让它一次性理解一个复杂项目的全部细节，就像让一个人同时阅读十本书并立刻写出综合书评。这会导致几个问题：

上下文窗口限制：即使是最新的模型，其上下文长度也是有限的。一个中等规模的项目，其代码文件总长度很容易超过这个限制，导致模型无法看到全貌。
注意力分散：模型在生成长文本时，可能会“顾此失彼”，对某些重要模块（如核心业务逻辑）描述不清，而对一些辅助文件（如配置文件）却着墨过多。
专业深度不足：代码分析涉及结构解析、依赖梳理、API归纳、数据流追踪等多个专业领域。一个通用模型很难在所有领域都保持高水平的分析精度。

2.2 多智能体的分工协作策略

ai-doc-gen采用了“分而治之”的策略，设计了多个各司其职的智能体（Agent）：

代码结构分析智能体：它的任务是宏观扫描。它会遍历目录树，识别出项目的整体骨架：哪些是核心源码目录（如src/,app/），哪些是配置文件（如config/,docker/），哪些是测试文件（tests/），以及入口文件（如main.py,app.py）在哪里。它输出的是一张项目的“地图”。
数据流分析智能体：它的任务是微观追踪。它会深入关键的业务逻辑文件，尝试理解数据是如何在函数、类、模块之间流动的。例如，一个用户请求进来，经过了哪些处理函数，数据是如何被转换的，最终存储到了哪里。这有助于理解核心业务流程。
依赖关系分析智能体：它专注于项目对外部世界的依赖。它会解析requirements.txt,pyproject.toml,package.json等文件，列出项目所依赖的第三方库，并尝试判断哪些是核心依赖（如Web框架、数据库驱动），哪些是开发依赖（如测试框架、代码格式化工具）。
请求流分析智能体（针对Web项目）：这是数据流分析的一个特化版本，专门用于理解HTTP请求的生命周期。它会分析路由定义、控制器（Controller）、服务层（Service）和数据访问层，勾勒出从接口到数据库的完整调用链。
API分析智能体：如果项目提供了API（如RESTful接口、GraphQL），这个智能体会负责提取端点（Endpoint）、方法（GET/POST等）、请求/响应格式等信息，为生成API文档做准备。

每个智能体都像一个领域的专家，只处理自己最擅长的任务。它们的工作成果（即分析报告）会被汇总到一个“文档生成智能体”手中。这个总指挥智能体并不需要重新阅读所有代码，它只需要阅读各位专家提交的报告，然后以这些报告为素材，按照预设的模板（如README的各个章节），撰写最终的综合文档。

这种架构的优势非常明显：

精度高：每个智能体任务单一，可以更专注、更深入地分析特定方面。
可扩展：如果需要增加新的分析维度（比如安全漏洞扫描、性能瓶颈分析），只需增加一个新的智能体即可，无需改动整体架构。
成本可控：每个智能体分析时，只需要传入相关的代码片段，大大减少了每次调用模型时需要处理的令牌（Token）数量，从而降低了API调用成本。
结果结构化：每个智能体的输出都可以被设计成结构化的数据（如JSON），便于后续处理和集成。

实操心得：智能体边界的设计在设计多智能体系统时，最关键的决策是如何划分智能体的职责边界。边界太粗，就失去了分工的意义；边界太细，又会引入过多的协调开销。ai-doc-gen目前的划分（结构、数据流、依赖、API）是一个经过实践检验的、比较合理的平衡点。对于大多数Web应用和后端服务项目，这几个维度足以构建一个全面的项目画像。

3. 从零开始：环境搭建与初次运行详解

理解了架构，我们动手把它跑起来。官方README的“Quick Start”部分给出了最简命令，但作为实际使用者，我会带你走一遍更贴近真实场景的流程，并解释每个步骤背后的意图。

3.1 环境准备与依赖安装

项目要求Python 3.13，这是一个比较新的版本。我建议使用pyenv或conda来管理Python版本，避免污染系统环境。

# 使用 conda 创建并激活虚拟环境（示例） conda create -n ai-doc-gen python=3.13 conda activate ai-doc-gen # 或者使用 pyenv 和 virtualenv pyenv install 3.13.1 pyenv virtualenv 3.13.1 ai-doc-gen pyenv activate ai-doc-gen

接下来是安装。项目推荐使用uv，这是一个用Rust写的、速度极快的Python包管理器和安装器。它的确比传统的pip快很多，特别是在解决依赖关系时。

# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 安装后需要重启终端或 source ~/.bashrc (或对应shell的配置文件) # 克隆项目 git clone https://github.com/divar-ir/ai-doc-gen.git cd ai-doc-gen # 使用 uv 同步依赖（相当于 pip install） uv sync

uv sync命令会读取pyproject.toml文件，安装所有项目依赖，并创建一个可编辑的安装。这一步如果遇到网络问题，可以考虑配置镜像源。

3.2 核心配置：模型API与项目设置

安装完成后，不能直接运行，最关键的一步是配置。你需要一个能够访问大模型API的密钥。

复制环境变量模板：

cp .env.sample .env

打开.env文件，你会看到类似如下的内容：

OPENAI_API_KEY=sk-xxx OPENAI_BASE_URL=https://api.openai.com/v1 LANGFUSE_SECRET_KEY=sk-lf-xxx LANGFUSE_PUBLIC_KEY=pk-lf-xxx LANGFUSE_HOST=https://cloud.langfuse.com

配置LLM访问：将OPENAI_API_KEY替换成你的密钥。这里有一个非常重要的点：OPENAI_BASE_URL不一定非得是OpenAI官方地址。因为这个项目使用pydantic-ai，它兼容任何提供OpenAI格式API的终端。这意味着你可以使用：
- OpenAI官方API：https://api.openai.com/v1
- Azure OpenAI：https://your-resource.openai.azure.com/openai/deployments/your-deployment-name
- OpenRouter：https://openrouter.ai/api/v1
- 本地模型（通过Ollama、LM Studio等工具暴露的API）：http://localhost:11434/v1这提供了极大的灵活性，你可以根据成本、速度、模型能力选择最适合的供应商。
（可选）配置可观测性：LANGFUSE_*开头的变量用于集成Langfuse，这是一个LLM应用的可观测性平台。如果你启用它，可以在Langfuse的界面上看到每一次AI智能体调用的详细记录，包括输入、输出、耗时和成本。这对于调试智能体行为和优化提示词（Prompt）至关重要。初期可以不配置，但当你需要深入优化时，强烈建议开启。
创建项目配置：
```
mkdir -p .ai cp config_example.yaml .ai/config.yaml
```
这个config.yaml文件是控制工具行为的核心。我们打开它，看看几个关键配置项：
```
# .ai/config.yaml 示例片段 analysis: exclude_code_structure: false exclude_data_flow: false exclude_dependencies: false exclude_request_flow: false exclude_api_analysis: false readme_generation: excluded_sections: - architecture - c4_model use_existing_readme: true ai_rules_generation: detail_level: comprehensive # 可以是 'brief', 'standard', 'comprehensive' max_claude_lines: 600 max_agents_lines: 150
```
- analysis部分：你可以选择关闭某些你不关心的分析。例如，如果你的项目不是一个Web服务，可以关闭request_flow分析。
- readme_generation部分：你可以控制生成README时包含哪些章节。use_existing_readme: true是一个很贴心的选项，它会让AI在生成新文档时参考项目中已有的README内容，从而保持文档风格的延续性，而不是完全重写。
- ai_rules_generation部分：这里控制为AI助手生成的配置文件的详细程度和长度限制。

注意事项：API成本与速率限制首次运行分析一个大型仓库时，可能会触发数十次甚至上百次对LLM API的调用。请务必：
了解你所使用API的定价，估算成本。使用detail_level: ‘brief’可以显著减少Token消耗。
注意API的速率限制（Rate Limit）。工具内部实现了并发处理，如果短时间内请求太多，可能会被API提供商限制。如果遇到429错误，你需要调整配置或代码中的并发参数。

3.3 运行你的第一次分析

配置妥当后，我们就可以对当前目录（即ai-doc-gen项目自身）进行一次分析，看看效果。

# 第一步：运行分析，收集情报 uv run src/main.py analyze --repo-path . # 第二步：基于分析结果，生成README uv run src/main.py generate readme --repo-path . # 第三步：（可选）为AI助手生成配置 uv run src/main.py generate ai-rules --repo-path .

命令执行后，你会在项目根目录下发现一个.ai/docs/文件夹，里面存放着分析过程的中间结果（各个智能体的报告）以及最终生成的README.md文件。同时，如果你执行了第三步，在项目根目录会看到新生成的CLAUDE.md,AGENTS.md以及.cursor/rules/目录下的文件。

打开新生成的README.md，与项目自带的那个对比一下。你会发现，新生成的文档结构非常标准，包含了项目概述、功能特性、安装步骤、使用指南、配置说明、架构设计等章节，并且内容是基于当前代码实时分析得出的，比如它正确地识别出了这是一个Python项目，使用了uv作为包管理器，核心架构是多智能体等等。

4. 深入核心：多智能体协同的代码解析

现在，让我们深入到src/目录下，看看这些智能体是如何被构建和协作的。这是整个项目最精华的部分。

4.1 智能体的构建基石：pydantic-ai

项目选择pydantic-ai作为智能体框架，而不是更流行的 LangChain 或 LlamaIndex。这是一个非常值得品味的决策。pydantic-ai的特点是与 Pydantic 深度集成，强调类型安全和简洁的声明式编程。

一个典型的智能体定义如下所示（根据项目结构推断）：

# 示例代码，展示 pydantic-ai 智能体的定义风格 from pydantic_ai import Agent, RunContext from pydantic import BaseModel class CodeStructureAnalysisResult(BaseModel): """代码结构分析的结果模型""" project_type: str # e.g., "Python Web Application" core_directories: list[str] entry_points: list[str] build_tools: list[str] # e.g., ["uv", "poetry"] class CodeStructureAnalyzer(Agent): """代码结构分析智能体""" def __init__(self, model: str): super().__init__( model=model, system_prompt="你是一个资深的软件架构师，擅长快速理解代码库的整体结构...", result_type=CodeStructureAnalysisResult ) async def run(self, ctx: RunContext, repo_tree: str) -> CodeStructureAnalysisResult: """分析仓库目录树""" # repo_tree 是一个字符串，包含了类似 `tree` 命令输出的目录结构 result = await self.run_sync( f"请分析以下项目目录结构：\n{repo_tree}\n" "请识别项目类型、核心源码目录、入口文件以及构建工具。" ) return result

关键点在于result_type=CodeStructureAnalysisResult。这强制要求智能体的输出必须符合我们定义的Pydantic模型。这带来了巨大的好处：

类型安全：从AI返回的非结构化文本被自动解析并验证为结构化的数据。
易于集成：下游的文档生成智能体可以直接使用这些结构化的数据对象，无需再手动解析文本。
清晰的接口：每个智能体的输入和输出都被严格定义，降低了系统模块间的耦合度。

4.2 分析流水线：并发执行与结果聚合

在handler层（如analyze_handler.py），我们可以看到智能体是如何被组织和执行的。项目利用了 Python 的asyncio来实现并发，让多个分析智能体同时工作，极大提升了效率。

# 概念性代码，展示并发分析流程 import asyncio from agents.code_structure_agent import CodeStructureAnalyzer from agents.data_flow_agent import DataFlowAnalyzer # ... 导入其他智能体 async def analyze_repository(repo_path: str, config: Config): """并发执行所有分析智能体""" # 1. 准备共享的上下文数据，如读取关键代码文件 context_data = await prepare_analysis_context(repo_path) # 2. 定义要运行的分析任务列表 analysis_tasks = [] if not config.exclude_code_structure: agent = CodeStructureAnalyzer(model=config.model) task = agent.run(context_data.repo_tree) analysis_tasks.append(("code_structure", task)) if not config.exclude_data_flow: agent = DataFlowAnalyzer(model=config.model) # 可能只传入核心业务文件的内容 task = agent.run(context_data.core_files) analysis_tasks.append(("data_flow", task)) # ... 添加其他智能体任务 # 3. 并发执行所有任务 results = {} completed_tasks = await asyncio.gather(*[task for _, task in analysis_tasks], return_exceptions=True) # 4. 收集结果 for (name, _), result in zip(analysis_tasks, completed_tasks): if isinstance(result, Exception): logger.error(f"Analysis {name} failed: {result}") results[name] = None else: results[name] = result # 5. 将结构化的结果保存到 .ai/docs/ 目录下，通常是JSON文件 save_analysis_results(repo_path, results) return results

这种模式非常清晰：主流程负责协调和调度，每个智能体是独立的工人，它们并行工作，互不干扰，最后将产品（分析结果）放到指定的位置。

4.3 文档生成：从数据到叙述

当所有分析结果就绪后，DocumentationAgent（文档生成智能体）开始工作。它不会再去读原始代码，而是读取那些已经结构化的分析结果JSON文件。

它的系统提示词（System Prompt）会非常详细，大致框架如下：

“你是一名技术文档工程师。以下是一个软件项目的多项分析报告，包括项目结构、数据流、依赖关系等。请根据这些材料，撰写一份专业的README.md文档。文档需包含以下章节：项目简介、核心功能、技术栈、快速开始、详细配置、架构说明、常见问题等。请使用清晰、客观的技术语言，避免营销口吻。”

然后，将各个智能体的结果作为用户提示（User Prompt）的一部分传入。由于输入已经是结构化的摘要，文档生成智能体需要处理的Token数量大大减少，任务也从复杂的“代码理解”简化为相对简单的“报告综合与润色”，从而提高了生成质量和速度。

生成AI助手配置文件（如CLAUDE.md）的逻辑也类似，但提示词会更具体：

“你正在为Claude Code这个AI编程助手编写项目上下文文档。请基于以下项目分析，总结出最关键的信息，帮助Claude更好地理解这个项目，以便在编程时提供准确的建议。请重点说明：项目的主要目的、核心模块的职责、代码风格约定、重要的配置项、以及需要避免的常见错误。”

5. 高级用法与集成：GitLab CI与生产部署

对于团队而言，单次运行工具生成文档是不够的。理想的状态是文档能随着代码自动更新。ai-doc-gen提供了cronjob命令和GitLab集成，正是为了这个自动化场景。

5.1 GitLab集成与自动合并请求

项目的cronjob analyze命令设计为在CI/CD流水线中定期运行（例如，每天凌晨）。它的工作流程是：

扫描项目：连接到配置的GitLab实例，获取指定组（Group）或命名空间（Namespace）下的所有项目列表。
过滤项目：根据配置（如commit_recency_days）过滤出最近活跃的项目。
克隆并分析：为每个目标项目创建临时工作目录，克隆代码，运行analyze和generate readme。
对比与提交：将新生成的README与仓库现有的README进行对比。如果发现显著差异（而不仅仅是格式调整），工具会自动：
- 创建一个新的分支（如docs/ai-update-20240527）。
- 提交更改。
- 创建一个合并请求（Merge Request），标题类似 “docs: AI-generated documentation update”。
- 在MR描述中，可能会包含AI生成的更改摘要。

这个功能非常强大，它使得文档维护变成了一个持续的、自动化的后台进程。团队开发者只需要像评审代码一样评审这些AI提交的文档MR即可。

5.2 配置Cronjob

要使能这个功能，你需要在.ai/config.yaml中提供GitLab的访问凭证和配置：

cronjob: enabled: true gitlab_url: "https://gitlab.your-company.com" gitlab_access_token: "${GITLAB_ACCESS_TOKEN}" # 建议从环境变量读取 target_group: "your-engineering-group" # 要扫描的GitLab群组 working_path: "/tmp/ai-doc-gen-workspace" # 临时工作目录 commit_recency_days: 7 # 只分析最近7天有提交的项目 branch_prefix: "docs/ai-update"

然后，你可以设置一个系统的Cron任务，或者更方便地，在GitLab CI的.gitlab-ci.yml中配置一个定时流水线（Pipeline Schedule）：

# .gitlab-ci.yml 示例 update-docs: image: python:3.13-slim variables: UV_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/uv" cache: key: "uv-cache" paths: - .cache/uv before_script: - curl -LsSf https://astral.sh/uv/install.sh | sh - uv sync script: - uv run src/main.py cronjob analyze only: - schedules # 这个任务只在定时触发器下运行 rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # 可选：只对默认分支做定时任务

5.3 生产环境考量

如果你计划在团队内部署这个工具，需要考虑以下几点：

安全性：GITLAB_ACCESS_TOKEN需要具有读取仓库和创建分支、MR的权限。务必使用项目访问令牌（Project Access Token）或部署密钥，并严格控制其权限范围。
资源隔离：Cronjob会在临时目录克隆和操作代码。确保该目录有足够的磁盘空间，并且不同项目的分析不会相互干扰。
错误处理与重试：网络问题、API限流、个别项目分析失败等情况需要妥善处理。工具应该有完善的日志记录和失败重试机制。
成本监控：自动化运行意味着持续的API调用。你需要密切监控LLM API的使用量和成本，设置预算警报。可以考虑为分析任务设置更严格的Token上限，或者使用更经济的模型。

6. 实战经验：提示词优化与结果调校

工具开箱即用能提供不错的结果，但要想获得“惊艳”的、高度符合你团队口味的文档，离不开对智能体提示词的精细调校。这是将AI工具从“能用”提升到“好用”的关键。

6.1 理解并修改提示词

ai-doc-gen的提示词很可能定义在各个智能体类的system_prompt属性中，或者集中在一个配置文件中。你需要找到它们并进行调整。

例如，文档生成智能体的默认提示词可能比较通用。你可以根据你的需求强化它：

强调特定章节：如果你希望README必须包含“部署指南”或“性能指标”，就在提示词里明确要求。
定义写作风格：“请使用简洁、直接的工程师语言，避免任何夸张的形容词。优先使用列表和代码块来展示信息。”
注入团队规范：“在我们的文档中，请始终将‘Docker’写作‘Docker（容器）’，并在第一次出现时给出简要说明。”
控制详略程度：“对于安装步骤，请假设用户是中级开发者，省略诸如‘如何安装Python’这样的基础步骤。专注于项目特有的依赖和配置。”

6.2 处理复杂或特殊的项目结构

工具默认的分析逻辑可能对某些特殊项目结构不友好。例如：

Monorepo（单体仓库）：一个仓库里包含多个独立服务或包。默认分析可能会把它们混为一谈。你可以在config.yaml中通过exclude选项关闭某些分析，或者更高级地，修改智能体的上下文准备逻辑，让它分别分析不同的子目录。
配置文件驱动型项目：有些项目的核心逻辑不在代码里，而在复杂的YAML或JSON配置文件中。你可能需要定制一个“配置分析智能体”，或者调整数据流分析智能体，让它也读取并理解这些配置文件。
文档代码分离：有些项目习惯把文档放在docs/目录，而README.md只是一个入口。你可以在生成README时，通过use_existing_readme: true来利用已有的docs/内容，或者提示生成智能体：“本项目的主要文档在docs/目录下，README只需提供最简概述和导航。”

6.3 评估与迭代

生成了文档，如何判断其质量？不要只看一眼了事。建议建立一个简单的评估流程：

准确性检查：随机抽查几个生成文档中提到的技术点（如“核心模块X负责Y功能”），去代码里验证是否正确。
完整性检查：对比你心目中一份完整README应有的章节，看生成文档是否遗漏了关键部分（如“环境变量列表”、“错误处理”）。
实用性检查：让一个新加入团队的同事（或扮演这个角色）只阅读生成的文档，尝试完成“搭建本地环境”、“运行项目”、“实现一个小功能”等任务。记录下他卡住的地方，这些就是需要优化提示词或补充分析维度的地方。

基于这些反馈，回头调整智能体的提示词、分析范围或生成模板。这是一个迭代的过程。ai-doc-gen的价值在于它提供了一个自动化的框架，而你可以通过调校，让它越来越贴合你团队的具体需求。

7. 常见问题与排查技巧实录

在实际使用中，你肯定会遇到各种问题。下面是我在测试和使用过程中遇到的一些典型情况及其解决方法。

问题现象	可能原因	排查与解决思路
运行`uv sync`或安装时超时/失败	1. 网络连接问题。 2. PyPI镜像源问题。 3. 系统依赖缺失（如某些Python包需要C编译器）。	1. 检查网络，尝试使用手机热点。 2. 为`uv`或`pip`配置国内镜像源（如清华、阿里云镜像）。对于`uv`，可以设置环境变量`UV_INDEX_URL`。 3. 在Ubuntu/Debian上，尝试安装`build-essentialpython3-dev`等包。
运行分析命令时报`OpenAIError`或`APIError`	1. API密钥错误或未设置。 2.`OPENAI_BASE_URL`配置错误。 3. API额度不足或速率受限。 4. 本地模型服务（如Ollama）未启动。	1. 检查`.env`文件中的`OPENAI_API_KEY`是否正确，是否有空格。 2. 确认`OPENAI_BASE_URL`的末尾是否有多余的`/`，格式是否正确。 3. 登录API提供商后台查看额度和使用情况。在配置中增加请求间隔（如果工具支持）或使用更小模型。 4. 运行`ollama serve`并确保服务在`http://localhost:11434`可用。
生成的文档内容空洞、重复或错误很多	1. 使用的LLM模型能力太弱（如某些小参数本地模型）。 2. 提示词不够精确，导致AI理解偏差。 3. 代码库本身非常混乱或包含大量非英文注释/命名。	1. 切换到更强大的模型，如GPT-4 Turbo、Claude 3.5 Sonnet。这是提升质量最直接有效的方法。 2. 按照第6节的方法，仔细审查和优化各个智能体的系统提示词。 3. 尝试先对代码库进行预处理，或者让智能体专注于分析核心的、结构清晰的目录。
分析过程特别慢	1. 代码仓库非常大，文件众多。 2. LLM API响应慢。 3. 网络延迟高。	1. 在`config.yaml`中通过`exclude`选项关闭一些非必需的分析。 2. 检查是否所有智能体都在并发运行。查看日志确认。 3. 如果使用海外API，考虑使用代理或选择地理位置上更近的端点。对于本地模型，确保硬件资源（CPU/内存）充足。
GitLab Cronjob 创建了太多无意义的MR	1. 工具检测文档变化的逻辑过于敏感（如格式调整也被视为变更）。 2. 定时任务运行太频繁。	1. 查看工具源码中对比文档差异的逻辑，看是否可以调整阈值，例如只当内容变更超过一定行数或比例时才创建MR。 2. 调整Cronjob的运行频率，比如从每天改为每周。在`config.yaml`中增大`commit_recency_days`，只分析真正活跃的项目。
生成的`CLAUDE.md`对AI助手帮助不大	1. 生成规则时使用的提示词不适合你的AI助手。 2. 信息过于冗长或不够关键。	1. Cursor和Claude Code对上下文文件的偏好可能不同。你需要实验哪种格式和内容它们“消化”得更好。可以手动编辑一个理想的`CLAUDE.md`，然后反推提示词该如何修改。 2. 调整`ai_rules_generation`下的`detail_level`和`max_*_lines`参数，在信息量和上下文长度之间找到平衡。

一个关键的调试技巧：启用Langfuse如果你在提示词调优或分析逻辑上遇到困难，强烈建议配置并启用Langfuse。它会记录每一次AI调用的详细数据：
输入的系统提示词和用户消息：你可以直观地看到发给模型的是什么。
模型的完整输出：你可以看到模型“原始”的回答，对比工具最终解析后的结果。
耗时与Token使用：帮你定位性能瓶颈和成本消耗点。通过分析这些Trace（追踪记录），你可以精准地发现是哪个智能体在什么情况下给出了不满意的回答，从而进行针对性的优化。这比盲目猜测要高效得多。

最后，我想分享一点个人体会。像ai-doc-gen这样的工具，它代表的是一种范式转变：从“人工编写并维护文档”到“构建系统来自动生成并同步文档”。它不会完全取代技术写作者，但会极大地放大开发者的能力，让保持文档更新从一项艰巨的、容易被遗忘的“课外作业”，变成一个轻量的、可自动化的“持续集成”步骤。初期投入时间进行配置和调校是值得的，一旦流程跑通，它就能为整个团队持续地节省时间、减少困惑，并提升项目的可维护性。最理想的状态是，你几乎感觉不到它的存在，但项目的文档却总是清晰和最新的。