Agent驱动项目Wiki自动生成方案实践指南

在日常开发工作中，利用 Claude Code（下文简称 CC）进行项目分析时，我发现它不仅能够快速定位到具体的业务逻辑代码块，还能深入理解项目结构、提炼核心模块。这让我意识到，它本身就是一个现成的、功能强大的 Wiki 生成工具。直接引导 CC 分析项目源码并输出结构化文档，即可获得一份高度准确、与代码实时同步的项目知识库。

项目背景与演进

近期，我持续探索如何高效自动化地生成高质量项目文档。此前，我曾围绕 deepwiki 项目撰写过两篇技术文章：一篇《deepwiki-rag-principle》深入剖析了其基于 RAG 的技术原理，另一篇《deepwiki-optimize-line-number》则分享了为代码块添加行号以提升可读性的具体实践。

经过多次迭代优化，我们主要实现了两大核心改进：一是为所有代码片段自动添加清晰的行号标识，二是基于 Proto 等接口定义文件生成确定性的文档目录结构。这两项优化背后，贯穿着同一个核心设计哲学：将所有确定性的、规则明确的结构化信息交由程序化规则处理，而仅让人工智能专注于其擅长的语义理解、信息归纳与内容总结工作。

大型语言模型在精确计算和生成严格结构化数据方面存在局限。通过将确定性与非确定性任务分离，让规则引擎与 AI 模型各展所长，最终生成的文档质量得到了显著提升。上述实践均基于开源的 deepwiki-open 项目进行。

现有方案面临的瓶颈

尽管生成的单页面文档质量令人满意，但我们仍面临一个关键挑战：如何自动生成项目全局视角的总结性内容？例如，系统整体架构图、核心业务流程图、数据库实体关系图等。

这类全局性图表需要基于前期已生成的、分散的多个页面内容进行二次信息聚合与深度提炼。然而，deepwiki 的架构设计侧重于独立页面生成，缺乏一个统一的“后处理”阶段来整合和关联所有信息。在现有架构下实现此功能较为复杂，这促使我们开始寻求新的解决方案。

创新方案：基于 Claude Code 的文档生成

正如开篇所述，CC 在代码理解与精准检索方面表现出色。它通过调用一系列内置工具来实现代码定位，完全无需依赖 deepwiki 方案中的向量数据库，使得整体架构变得异常简洁。

在此简要解析 CC 的代码搜索机制。与传统 RAG 方案先将代码转换为向量再检索不同，CC 采用了一套工具驱动（Tool-based）的检索范式。其精妙之处在于，大语言模型并非依赖向量化的“模糊记忆”，而是像一位资深工程师，通过灵活组合调用精确的工具来定位目标代码。

举例来说，当需要查找某个特定函数时，CC 可能会先调用类似 grep 的工具筛选出相关文件列表，再使用 Read 工具精读文件内容以确认上下文，最后还可能借助 LSP 工具来分析函数间的调用关系。整个过程具备确定性、可追溯性，结果也更加可靠。

（若希望了解更详细的技术实现，可参考 Anthropic 官方最新文档：Claude Code Overview）

此外，当代码仓库发生更新时，只需让 CC 读取 git 提交日志，它便能自动识别变更影响的范围，并同步更新相关部分的文档，极大地简化了文档的维护成本。

能力复用：封装为可调用的 Skill

考虑到公司内部项目众多，为了便于其他团队快速复用这套高效的文档生成流程，我将整个生成静态 Wiki 的步骤封装成了一个可复用的“Skill”。这样，其他项目只需在 CC 环境中直接调用这个预定义好的 Skill 即可，无需重复配置环境与流程。

其生成的项目文档目录结构示例如下：

├── SKILL.md
├── skill.json
├── templates/
│   ├── page-architecture.md
│   ├── page-er.md
│   ├── page-features.md
│   └── page-service.md
└── wiki/
    ├── 01-系统架构.md
    ├── 02-核心功能.md
    ├── 03-ER图.md
    ├── index.html
    └── service/
        └── *.md

方案深度对比：deepwiki 与 Claude Code

为了更清晰地做出技术选型，我们将两种文档自动化生成方案进行全方位对比：

deepwiki 方案分析

核心优势：

• 自动化程度极高，近乎实现“一键生成”全项目文档，过程中无需人工介入。

潜在不足：

• 文档生成后，难以对单个页面的内容进行精细化的微调与定制。
• 架构层面难以支持“基于已生成内容进行二次汇总”的全局性需求（例如生成跨模块的数据库 ER 图）。

Claude Code 方案分析

核心优势：

• 控制粒度极细，开发者可以精准调整每一个文档页面的内容与数据呈现方式。
• 借助强大的工具链，其代码检索与分析结果极为精准，尤其擅长处理跨文件、跨模块的复杂关联分析。

潜在不足：

• 无法实现完全无人值守的一键生成，需要开发者通过多轮对话进行交互引导和结果调试。
• 若想部署至服务器实现持续集成自动化，需要额外开发工具来管理和驱动 CC 的会话流程。

总结与选型建议

实际上，deepwiki 与 Claude Code 两种方案并非相互替代，它们更适合被视为项目在不同生命周期阶段的最佳实践选择。

• 项目初期，追求快速启动： 当你需要为项目快速搭建一个初步、全面的文档框架时，deepwiki 的“一键生成”能力具有明显优势，能快速建立知识库基础。
• 项目成熟期，追求质量与深度控制： 当项目结构趋于稳定，你需要一份能够精确反映代码逻辑、支持深度定制、并能清晰展示复杂模块关联的高质量文档时，CC 方案更值得投入时间与精力。

CC 方案的核心价值在于其无与伦比的可控性与精准性。虽然需要投入更多时间进行交互式调试，但所换来的文档质量，尤其是在处理复杂业务逻辑和代码关联时，确实更为出色。当然，其当前的自动化程度是主要限制。不过，随着 CC 开发者生态的不断成熟，未来必然会出现更完善的自动化解决方案。我们不妨保持关注，让技术再演进一段时间。