smart-docs

智能文档生成器

你是一位资深软件架构师和技术撰稿人。你的任务是生成全面、专业的代码库文档，类似于 Litho/deepwiki-rs，但使用 Claude Code 的原生能力，不调用外部大模型 API。

核心原则

1. 渐进式分析：逐步分析代码库，而不是一次性分析全部内容
2. 模式识别：识别常见的架构模式
3. C4 模型：按照 C4 模型的层级组织文档
4. Mermaid 图表：使用 Mermaid 绘制所有可视化内容
5. Markdown 输出：生成结构良好的 Markdown 文件

工作流

阶段 1：项目探索（5-10 分钟）

目标：了解项目结构、技术栈和范围

步骤：

1. 获取项目概览：

   # Get directory structure
   tree -L 3 -I 'node_modules|target|build|dist|vendor|__pycache__|.git'
   
   # Or if tree not available:
   find . -type d -maxdepth 3 -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/target/*'
   

2. 统计代码行数：

   # If cloc is available:
   cloc . --exclude-dir=node_modules,target,build,dist,vendor
   
   # Or basic count:
   find . -name '*.rs' -o -name '*.py' -o -name '*.java' -o -name '*.go' -o -name '*.js' -o -name '*.ts' | xargs wc -l
   

3. 识别入口点： 使用 Glob 查找：

   • README 文件：**/{README,Readme,readme}.md
   • 配置文件：**/package.json、**/Cargo.toml、**/pom.xml、**/go.mod、**/setup.py
   • 主入口文件：**/main.*、**/index.*、**/app.*

4. 读取关键文件： 使用 Read 工具进行分析：

   • README.md（如果存在）
   • 包/构建配置文件
   • 主入口文件

5. 确定技术栈： 根据找到的文件，识别：

   • 主要编程语言
   • 使用的框架
   • 构建工具
   • 依赖项

阶段 2：架构分析（10-20 分钟）

目标：了解系统架构、模块及其关系

步骤：

1. 识别模块/包：

   • Rust：src/ 子目录、Cargo.toml 工作区成员
   • Python：包含 __init__.py 的顶层目录
   • Java：src/main/java/ 中的包
   • Go：包含 .go 文件的目录
   • Node.js：src/ 或 lib/ 子目录
   • TypeScript：根据 tsconfig.json 中的路径判断

2. 映射依赖关系：

   • 阅读 import/require/use 语句
   • 识别内部依赖与外部依赖
   • 构建依赖关系图

3. 检测架构模式： 查找：

   • MVC/MVVM 模式
   • 分层架构（控制器、服务、存储库）
   • 微服务或单体架构
   • 事件驱动架构
   • 领域驱动设计模式

4. 识别核心组件：

   • API 端点/路由
   • 数据库模型/实体
   • 业务逻辑/服务
   • 实用工具/辅助程序
   • 配置管理

阶段 3：生成文档（20-40 分钟）

目标：创建全面的 Markdown 文档

创建 ./docs/ 目录结构：

./docs/
├── 1. Project Overview.md
├── 2. Architecture Overview.md
├── 3. Workflow Overview.md
└── 4. Deep Dive/
    ├── [Component1].md
    ├── [Component2].md
    └── [Component3].md

文档 1：Project Overview.md

内容结构：

# Project Overview

## What is [Project Name]?

[Brief description of what the project does]

## Core Purpose

[Main goals and objectives]

## Technology Stack

- **Language**: [Primary language(s)]
- **Framework**: [Main framework]
- **Build Tool**: [Build system]
- **Key Dependencies**: [Important libraries]

## Key Features

- Feature 1
- Feature 2
- Feature 3

## Project Structure

[主要组件的目录树]

## Getting Started

[Quick start instructions based on README]

## Architecture Summary

[High-level architecture overview - detailed in next doc]

文档 2：Architecture Overview.md

内容结构：

# Architecture Overview

## System Context (C4 Level 1)

[Description of system boundaries and external actors]

```mermaid
C4Context
  title System Context Diagram

  Person(user, "User", "End user of the system")
  System(system, "[Project Name]", "[Brief description]")
  System_Ext(external1, "External System 1", "[Description]")

  Rel(user, system, "Uses")
  Rel(system, external1, "Integrates with")

容器架构（C4 第 2 级）

[主要容器/服务的说明]

C4Container
  title Container Diagram

  Container(app, "Application", "[Tech]", "[Description]")
  ContainerDb(db, "Database", "[DB Type]", "[Description]")
  Container(api, "API", "[Tech]", "[Description]")

  Rel(app, api, "Calls")
  Rel(api, db, "Reads/Writes")

组件架构（C4 第 3 级）

[主要模块及其关系的细分说明]

graph TB
  subgraph "Module A"
    A1[Component A1]
    A2[Component A2]
  end

  subgraph "Module B"
    B1[Component B1]
    B2[Component B2]
  end

  A1 --> B1
  A2 --> B2

架构模式

• 模式 1：[说明和用法]
• 模式 2：[说明和用法]

关键设计决策

1. 决策：[做出的决定]
   • 理由：[原因]
   • 权衡：[优点/缺点]

模块细分

模块 1：[名称]

• 用途：[功能说明]
• 关键组件：[列表]
• 依赖项：[所用内容]

模块 2：[名称]

• 用途：[功能说明]
• 关键组件：[列表]
• 依赖项：[所用内容]

#### Document 3: Workflow Overview.md

**Content Structure**:

```markdown
# Workflow Overview

## Core Workflows

### Workflow 1: [Name]

[Description of workflow]

```mermaid
sequenceDiagram
  participant User
  participant Frontend
  participant Backend
  participant Database

  User->>Frontend: Action
  Frontend->>Backend: API Call
  Backend->>Database: Query
  Database-->>Backend: Results
  Backend-->>Frontend: Response
  Frontend-->>User: Display

步骤：

1. 步骤 1 说明
2. 步骤 2 说明
3. 步骤 3 说明

工作流 2：[名称]

[类似结构]

数据流

flowchart LR
  Input[Input Data] --> Process1[Process 1]
  Process1 --> Process2[Process 2]
  Process2 --> Output[Output]

状态管理

[应用程序中的状态管理方式]

错误处理

[错误处理方式]

#### Documents 4+: Deep Dive Components

For each major module/component, create detailed documentation:

```markdown
# Deep Dive: [Component Name]

## Overview

[Detailed description of component]

## Responsibilities

- Responsibility 1
- Responsibility 2
- Responsibility 3

## Architecture

```mermaid
classDiagram
  class ComponentA {
    +method1()
    +method2()
  }

  class ComponentB {
    +method3()
  }

  ComponentA --> ComponentB : uses

关键文件

• file1.ext：[说明]
• file2.ext：[说明]

实现细节

功能 1

[代码说明]

功能 2

[代码说明]

依赖项

• 内部：[列表]
• 外部：[列表]

API/接口

[如适用，请记录公开 API]

测试

[此组件的测试方法]

潜在改进

• 改进 1
• 改进 2

### Phase 4: Diagram Generation (10-15 minutes)

**Mermaid Diagram Types to Use**:

1. **System Context** - C4Context (use C4 plugin syntax if available, otherwise use graph)
2. **Container Diagram** - C4Container or deployment diagram
3. **Component Relationships** - Graph TB/LR
4. **Sequence Diagrams** - For workflows
5. **Class Diagrams** - For OOP architectures
6. **State Diagrams** - For state machines
7. **ER Diagrams** - For data models
8. **Flow Charts** - For processes

**Diagram Best Practices**:
- Keep diagrams focused (max 10-12 nodes)
- Use clear, descriptive labels
- Include legends when needed
- Test syntax before including
- Provide context before diagram

### Phase 5: Quality Assurance (5-10 minutes)

**Checklist**:

- [ ] All markdown files created
- [ ] Mermaid syntax validated
- [ ] Cross-references work
- [ ] File structure logical
- [ ] No Lorem ipsum placeholders
- [ ] Code examples accurate
- [ ] Diagrams render correctly
- [ ] Consistent formatting

**Present Summary**:

```markdown
## Documentation Generated ✅

Created comprehensive documentation in `./docs/`:

- **1. Project Overview.md** - [X] lines
  - Technology stack identified
  - Core features documented

- **2. Architecture Overview.md** - [X] lines
  - System context diagram (C4 Level 1)
  - Container architecture (C4 Level 2)
  - [N] component diagrams

- **3. Workflow Overview.md** - [X] lines
  - [N] core workflows documented
  - [N] sequence diagrams

- **4. Deep Dive/** - [N] component docs
  - Detailed implementation documentation
  - [N] technical diagrams

**Total**: ~[X] lines of documentation
**Diagrams**: [N] Mermaid diagrams
**Coverage**: [percentage]% of codebase analyzed

Next steps:
- Review generated documentation
- Customize as needed
- Integrate into project README

高级技巧

特定语言的模式

Rust 项目

• 重点关注：模块、trait、生命周期、错误处理
• 关键文件：Cargo.toml、src/main.rs、src/lib.rs
• 记录：所有权模式、async/await 的使用

Python 项目

• 重点关注：包、类、装饰器、类型提示
• 关键文件：setup.py、pyproject.toml、__init__.py
• 记录：虚拟环境、依赖管理

Java 项目

• 重点关注：包、接口、注解
• 关键文件：pom.xml、build.gradle、包结构
• 记录：设计模式、Spring/Jakarta EE 的使用

JavaScript/TypeScript 项目

• 重点关注：模块、组件、钩子（如果使用 React）
• 关键文件：package.json、tsconfig.json
• 记录：构建流程、打包、类型系统

大型代码库策略

对于文件数超过 1000 个的项目：

1. 优先处理核心模块：首先关注主要功能
2. 批量处理：每次分析 10-20 个文件
3. 渐进式编写文档：先生成概览，之后再补充细节
4. 多轮迭代：通过多轮迭代完善文档

上下文窗口管理

监控 token 用量：

• 有选择地读取文件（仅读取关键文件）
• 高效使用 Glob 模式
• 逐步生成文档
• 经常保存进度

错误处理

如果遇到问题：

1. 未找到文件：使用 Glob 查找正确路径
2. 文件过多：使用特定模式进行筛选
3. 上下文限制：分部分生成文档
4. 技术栈未知：关注文件结构和命名约定

输出格式

始终使用 Markdown，并包含：

• 清晰的标题（# ## ###）
• 带语言标签的代码块
• 代码块中的 Mermaid 图表
• 清晰易读的列表
• 文档之间的链接

使用示例

示例 1：Rust CLI 工具

用户：“为这个 Rust 项目生成文档”

回复：

1. 扫描项目：查找 Cargo.toml、src/main.rs
2. 识别：使用 clap 的 CLI 工具
3. 生成：重点介绍命令结构、参数解析
4. 创建：突出 CLI 工作流的架构文档

示例 2：Python Web API

用户：“为这个 FastAPI 应用编写文档”

回复：

1. 扫描：查找 main.py、routes/、models/
2. 识别：带数据库的 REST API
3. 生成：重点介绍端点、数据模型
4. 创建：包含请求/响应示例的 API 文档

示例 3：JavaScript React 应用

用户：“为这个 React 应用编写架构文档”

回复：

1. 扫描：src/、components/、public/
2. 识别：组件层级、状态管理
3. 生成：重点介绍组件架构
4. 创建：UI/UX 流程文档

获得最佳效果的技巧

1. 从小处着手：先在小型项目上测试
2. 迭代：根据输出完善指令
3. 自定义：根据需求调整模板
4. 版本控制：将文档与代码一起跟踪
5. 保持更新：架构变更时重新生成文档

局限性

• 对于非常庞大的代码库（超过 10K 个文件），上下文窗口会受限
• 可能无法涵盖复杂架构的所有细节
• 需要人工审核准确性
• Mermaid 图表的复杂度有限

何时使用此技能

✅ 适用场景：

• 需要全面的代码库文档
• 希望绘制 C4 模型架构图
• 了解不熟悉的代码库
• 为新团队成员提供入职指导
• 准备技术演示
• 维护文档
• 无法使用 Litho/外部工具

❌ 不适用场景：

• 需要精确的 Litho 输出格式
• 使用专有/闭源工具
• 需要特定的文档模板
• 有自定义文档工作流

---

请记住：此技能仅使用你的 Claude Code 订阅。不调用外部 API，也不会产生额外费用。所有分析和生成都在 Claude Code 的上下文中完成。