知识库构建工作流

Claude Code 工作流专题 · 用Claude Code建立团队知识库

专题：Claude Code 工作流系统学习

关键词：知识库, MkDocs, Docusaurus, CLAUDE.md, 架构决策, 团队协作, 知识管理

📖 本文目录

一、知识采集体系
二、知识组织方法
三、技术文档系统对比与搭建
四、CLAUDE.md 知识管理
五、知识自动化
六、知识分享与团队协作
七、完整工作流集成
八、总结与最佳实践

一、知识采集体系

知识采集是知识库构建的起点。任何知识库的质量都取决于输入的原始素材。在Claude Code工作流中，知识采集覆盖六个核心场景：代码注释提取、技术决策记录、问题解决方案、最佳实践沉淀、学习笔记整理和会议记录结构化。每个场景都有独特的采集策略和工具配合。

1.1 代码注释提取

代码中的注释是最容易被忽视的知识来源。很多团队在代码 review 时只关注逻辑，却丢失了注释中蕴含的设计意图。使用 Claude Code 可以自动扫描代码库，从注释中提取有价值的架构信息和业务逻辑说明。以下是一个典型的注释提取工作流脚本：

#!/bin/bash
# 代码注释提取工作流 - 配合 Claude Code 执行

function extract_docstrings() {
    local src_dir="$1"
    local output_dir="$2"

    # 扫描所有 Python 文件中的 docstring
    find "$src_dir" -name "*.py" | while read -r file; do
        local rel_path="${file#$src_dir/}"
        local safe_name=$(echo "$rel_path" | tr '/' '_' | tr '.' '_')
        python3 -c "
import ast, sys
with open('$file') as f:
    tree = ast.parse(f.read())
classes = [n.name for n in ast.walk(tree) if isinstance(n, ast.ClassDef)]
funcs = [n.name for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.body and isinstance(n.body[0], ast.Expr)]
print(f'文件: $file')
print(f'类: {classes}')
print(f'函数: {funcs}')
" > "$output_dir/${safe_name}_docs.md"
    done
}
extract_docstrings "./src" "./docs/code-comments"

1.2 技术决策记录（ADR）

架构决策记录（Architecture Decision Record, ADR）是知识库中最高价值的内容之一。每次重大技术选型或架构变更都应该记录为ADR。标准的ADR模板包含标题、状态、背景、决策、后果和备选方案六个部分。使用 Claude Code 可以在决策发生时快速生成ADR文档：

# 架构决策记录: ADR-001 使用 PostgreSQL 作为主数据库
# 状态: [已提议 | 已接受 | 已废弃 | 已替代]

## 背景
项目需要支持高并发读写和复杂事务，当前 SQLite 无法满足
性能要求。需要选择一个生产级别的 OLTP 数据库。

## 决策
采用 PostgreSQL 15+ 作为主数据库，搭配 PgBouncer 连接池。

## 理由
- 支持 MVCC 和复杂事务
- 丰富的扩展生态（PostGIS, pgvector 等）
- 团队已有运维经验
- 相比 MySQL，许可证更友好

## 后果
- 正面: ACID 事务保障，全文搜索能力，JSON 支持
- 负面: 增加运维复杂度，需要专用服务器资源

## 备选方案
- MySQL 8.0: 功能相近但集群方案较复杂
- CockroachDB: 分布式能力强但学习成本高

## 关联
- ADR-003: 数据库迁移策略
- ADR-007: 数据备份与恢复方案

1.3 问题解决方案库

每个团队都会遇到各种技术问题，把解决方案结构化地记录下来可以避免重复踩坑。按照"问题-原因-解决方案-验证"的四段式结构组织，配合搜索标签，可以大幅提升问题排查效率。以下是使用 Claude Code 自动创建故障记录的标准 prompt：

# Claude Code Prompt: 创建故障记录

/prompt
请根据以下对话内容生成故障记录文档，
输出格式为 YAML front matter + Markdown:

---
title: "[问题简述]"
date: 2026-05-08
severity: [P0/P1/P2/P3]
category: [网络/数据库/应用层/部署/安全]
tags: [故障, troubleshooting, 关键词]
affected_services: [受影响的服务列表]
root_cause: "[根因一句话总结]"
resolution_time: "[修复耗时]"
---

## 问题描述
[详细描述现象和影响范围]

## 排查过程
1. [步骤一]
2. [步骤二]
3. [步骤三]

## 根因分析
[深度分析导致问题的根本原因]

## 解决方案
[具体修复步骤和代码变更]

## 预防措施
- [措施一]
- [措施二]

## 关联文档
- [相关链接]

最佳实践：每次故障解决后立即记录，使用 Claude Code 的会话记忆功能自动提取排查过程中的关键命令和输出。建议设置 P0/P1 级故障的强制记录流程，在故障关闭前必须完成文档撰写。

1.4 最佳实践沉淀

最佳实践是团队经验的结晶。通过 Claude Code 的 review 功能，可以在代码审查过程中自动识别可复用的模式，并建议将其沉淀为最佳实践文档。典型的场景包括：代码风格约定、性能优化模式、安全编码规范、测试策略等。关键是从具体的代码示例中抽象出通用原则。

1.5 学习笔记管理

个人和团队的学习笔记是知识库中最活跃的内容类型。使用本文描述的标准化流程，可以将原始的学习材料（讲座录音、技术文章、书籍笔记等）自动转化为结构化的 HTML 学习笔记，并维护目录列表。以下是一个标准化的学习笔记目录结构：

LearningNotes/
├── index.html                 # 学习笔记首页
├── css/
│   └── site-nav.css           # 全站导航样式
├── ShennongBencaoJing/        # 神农本草经专题
│   ├── list.html              # 目录列表
│   ├── template.html          # HTML模板
│   ├── 20260307211105.html    # 学习笔记文件
│   └── ...
├── ClaudeCode工作流/          # Claude Code工作流专题
│   ├── list.html              # 目录列表
│   ├── template.html          # HTML模板
│   └── 20260508120047_25734.html
└── ...

1.6 会议记录结构化

技术会议、架构评审、复盘会议中产生的讨论和决策，如果不加记录就会迅速流失。使用 Claude Code 可以实时辅助记录会议要点，自动生成结构化的会议记录。典型的会议记录模板按"议题-讨论-结论-行动项"的四段式组织，每个行动项标注负责人和截止日期。

工具配合：会议记录完成后，可以通过知识库自动创建关联的任务卡片（如 Linear/Jira issue），实现从"讨论"到"执行"的闭环。Claude Code 的 /remind 功能可用于会议行动的后续追踪。

二、知识组织方法

采集到的原始知识如果不加组织，就是一堆散落的文件。知识组织决定了知识库的可发现性和可维护性。一个优秀的组织体系包含六个维度：标签分类、目录结构、交叉引用、搜索优化、版本管理和权限控制。

2.1 标签分类体系

标签（Tag）是最灵活的知识组织方式。与固定的目录树不同，标签允许一篇文档属于多个分类，实现多维度检索。以下是一个推荐的知识库标签体系：

标签维度	示例标签	说明
技术栈	Python, React, PostgreSQL, Docker, Kubernetes, AWS	标注使用的主要技术
文档类型	ADR, 教程, API文档, 运维手册, 故障记录, RFC	标识文档的性质
领域	前端, 后端, 数据, 架构, 安全, DevOps	按照专业领域分类
成熟度	初稿, 评审中, 已批准, 已废弃, 需更新	标识文档的生命周期状态
团队	平台组, 业务组, SRE, QA, 产品	标识归属团队

2.2 目录结构设计

目录结构是知识库的骨架。推荐使用"专题-类别-文档"三级结构，保持扁平化的同时提供足够的上下文。一个经过实践检验的通用目录结构如下：

docs/
├── index.md                    # 文档站首页
├── guides/                     # 使用指南
│   ├── getting-started.md      # 快速开始
│   ├── setup.md                # 环境搭建
│   └── workflow.md             # 工作流说明
├── architecture/               # 架构文档
│   ├── overview.md             # 架构概览
│   └── decisions/              # ADR 目录
│       ├── index.md            # ADR 目录页
│       ├── ADR-001-db-choice.md
│       └── ADR-002-auth-flow.md
├── api/                        # API 文档
│   ├── rest-api.md             # REST API 规范
│   └── sdk-reference.md        # SDK 参考
├── operations/                 # 运维文档
│   ├── deployment.md           # 部署流程
│   ├── monitoring.md           # 监控手册
│   └── runbooks/               # 故障处理手册
├── standards/                  # 标准规范
│   ├── coding-standards.md     # 编码规范
│   ├── review-checklist.md     # 审查清单
│   └── naming-conventions.md   # 命名规范
└── team/                       # 团队文档
    ├── onboarding.md           # 新人入职
    ├── meeting-notes/          # 会议记录
    └── rfcs/                   # RFC 提案

2.3 交叉引用机制

知识不是孤立的。交叉引用（Cross-Reference）将分散的知识点连接成知识网络。Claude Code 可以自动扫描知识库，识别文档之间的关联关系。例如ADR中可以引用相关的故障记录，API文档可以引用其底层架构设计文档。建议在每篇文档末尾维护一个"关联文档"列表，并在修改时同步更新所有引用。

2.4 搜索优化

知识库的价值与可搜索性成正比。除了文档站自带的全文搜索外，还需要手动优化以下方面：每篇文档提供精确的 meta description 和 keywords 标签；对常见搜索词建立同义词映射；在文档开头使用明确的标题层级确保搜索排名；对核心文档增加摘要字段。使用 Claude Code 可以批量检查和优化文档的 SEO 质量。

2.5 版本管理

知识库的版本管理与代码版本管理同等重要。所有知识文档都应纳入 Git 版本控制，遵循以下规范：每次文档修改独立提交，提交信息格式为 docs(类别): 修改说明；重大修改需要创建 PR 进行 review；文档版本与软件版本保持对应关系，在发布新版本时同步归档知识库快照。使用 Git tag 标记重要的知识库里程碑。

2.6 权限控制

并非所有知识都适合公开。权限控制策略包括：公开文档（项目 README、使用指南）对所有成员可见；内部文档（架构决策、故障记录）对团队内部可见；受限文档（安全策略、客户数据）仅对特定角色可见。建议使用 git submodule 或 monorepo 的目录级权限控制策略来实现分级访问。

三、技术文档系统对比与搭建

选择合适的文档系统是知识库落地的基础。目前主流的文档系统各有特色，适用于不同的团队规模和场景。以下对六种主流方案进行详细对比和配置演示。

系统	语言/框架	托管方式	适合场景	学习成本
MkDocs	Python	静态站点 / GitHub Pages	API文档、开发者文档	低
Docusaurus	React	静态站点 / Vercel	产品文档、开源项目网站	中
ReadTheDocs	Python / Sphinx	托管服务	Python项目文档	中
GitBook	Node.js	托管服务 / 自托管	团队知识库、内部文档	低
语雀	SaaS	云端托管	中文团队协作、企业知识库	极低
Notion / Confluence	SaaS	云端托管	通用团队知识库、项目管理	极低

3.1 MkDocs 完全配置示例

MkDocs 是 Python 生态中最流行的文档生成工具，使用 Markdown 编写，支持丰富的主题和插件。以下是一个生产级别的 MkDocs 配置：

# mkdocs.yml - 生产级配置
site_name: 项目知识库
site_description: 团队技术文档与知识管理平台
site_author: 技术团队
repo_url: https://github.com/org/project
edit_uri: edit/main/docs/

theme:
  name: material
  language: zh
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - search.highlight
    - search.suggest
    - content.code.copy
    - content.tabs.link
  palette:
    primary: indigo
    accent: indigo

plugins:
  - search:
      lang: zh
  - tags:
      tags_file: tags.md
  - git-revision-date-localized:
      enabled: true
  - glightbox:
      auto_caption: true
  - minify:
      minify_html: true

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - attr_list
  - md_in_html

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/org/project
  consent:
    title: Cookie 使用
    description: 本站使用 cookie 分析访问数据

nav:
  - 首页: index.md
  - 快速开始:
    - 环境搭建: guides/setup.md
    - 项目结构: guides/structure.md
  - 架构文档:
    - 架构概览: architecture/overview.md
    - 决策记录: architecture/decisions/
  - API 参考: api/
  - 运维手册: operations/
  - 编码规范: standards/
  - 团队: team/

3.2 Docusaurus 配置示例

Docusaurus 是 Facebook 开源的文档框架，基于 React，功能强大但配置相对复杂。其最大优势是支持自定义 React 组件和版本化文档：

// docusaurus.config.js
module.exports = {
  title: '团队知识库',
  tagline: '用文档驱动开发',
  url: 'https://docs.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
          editUrl: 'https://github.com/org/project/edit/main/',
          lastVersion: 'current',
          versions: {
            current: { label: 'v2.0', path: 'v2' },
          },
        },
        blog: {
          showReadingTime: true,
          postsPerPage: 10,
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: '知识库',
      logo: { alt: 'Logo', src: 'img/logo.svg' },
      items: [
        { type: 'doc', docId: 'intro', label: '文档' },
        { to: '/blog', label: '博客', position: 'left' },
        { type: 'docsVersionDropdown', position: 'right' },
        { href: 'https://github.com/org/project', label: 'GitHub' },
      ],
    },
    prism: {
      theme: 'github',
      darkTheme: 'dracula',
    },
  },
};

选型建议：Python 技术栈团队优先选择 MkDocs + Material 主题；前端团队优先选择 Docusaurus；追求零运维团队选择 GitBook 或语雀。无论选择哪个系统，核心原则是内容与展示分离——使用 Markdown 编写内容，通过 CI/CD 自动构建部署。

3.3 静态站点生成与 CI/CD 集成

知识库的持续部署是保证内容新鲜度的关键。以下是一个完整的 GitHub Actions 工作流，实现 MkDocs 文档站的自动构建和部署：

# .github/workflows/docs.yml
name: Deploy Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs-material
          pip install mkdocs-git-revision-date-localized-plugin
          pip install mkdocs-glightbox

      - name: Build docs
        run: mkdocs build --strict

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

四、CLAUDE.md 知识管理

CLAUDE.md 是 Claude Code 的项目记忆文件，存储在仓库根目录，是 AI 辅助开发的核心知识载体。它记录了项目的关键上下文、编码规范、架构决策和开发工作流。一个精心维护的 CLAUDE.md 文件可以让 Claude Code 在每次会话中都拥有完整的项目认知。

核心理念：CLAUDE.md 不是普通的项目文档，而是 Claude Code 的"系统提示"。它直接决定了 AI 在项目中行为的准确性和效率。高质量 CLAUDE.md 应兼顾机器可读性和人类可读性。

4.1 CLAUDE.md 标准结构

以下是一个经过实践优化的团队级 CLAUDE.md 模板，覆盖了七个关键领域：

# 项目名称

## 项目概述
[一句话描述项目定位、技术栈和核心功能]

## 编码规范
- 语言: TypeScript 5.x, strict 模式
- 框架: React 18 + Next.js 14 (App Router)
- 样式: Tailwind CSS + CSS Modules
- 测试: Vitest + Playwright
- 格式化: Biome（禁止 prettier）
- 命名: 组件 PascalCase, 函数 camelCase, 常量 UPPER_SNAKE_CASE

## 架构决策
- ADR-001: 采用 PostgreSQL 作为主数据库
- ADR-002: 使用 tRPC 替代 REST 进行 API 通信
- ADR-003: 认证方案采用 NextAuth.js + OAuth 2.0
- ADR-004: 部署使用 Docker + Cloud Run

## API 规范
- 所有 API 端点使用 tRPC Router 组织
- 错误响应统一格式: { code, message, details? }
- 输入校验使用 Zod Schema
- 所有公共 API 必须有 JSDoc 注释

## 配置说明
- 环境变量: 见 .env.example，使用 zod 校验
- 数据库迁移: 使用 Prisma Migrate
- CI/CD: GitHub Actions，见 .github/workflows/
- 日志: pino + Google Cloud Logging

## 常见问题
- 本地开发: pnpm dev (需启动 PostgreSQL)
- 测试: pnpm test (单元), pnpm test:e2e (E2E)
- 构建: pnpm build (静态检查 + 编译)

## 工作流规则
- 每次提交前: 运行 lint + type-check + 单元测试
- 修改 API: 必须同时更新 Zod schema 和类型定义
- 数据库变更: 必须创建新的迁移文件
- 新功能: 必须包含单元测试和 E2E 测试

4.2 项目记忆持久化

每次 Claude Code 会话都是独立的。为了让 AI 记住跨会话的经验和教训，可以使用 revise-claude-md 技能自动更新 CLAUDE.md。这个工作流的触发时机包括：完成重大架构变更后、发现并修复复杂 bug 后、建立新的开发规范后、完成技术评审后。更新 CLAUDE.md 时应遵循"增量写入"原则，保留历史决策而不要覆盖删除。

# 使用 revise-claude-md 更新 CLAUDE.md 的最佳实践

/revise-claude-md

Claude Code 会根据当前会话中的关键决策和发现，
自动生成更新摘要并追加到 CLAUDE.md 中。

典型更新内容:
- 新增的架构决策理由
- 发现的坑和解决方案
- 建立的编码约定
- 配置参数的关键说明

4.3 多级记忆体系

Claude Code 支持四级记忆体系，从全局到局部逐级细化：全局记忆（用户级别的 MEMORY.md）、项目记忆（仓库级别的 CLAUDE.md）、会话记忆（单次会话的上下文）和工具记忆（MCP 工具提供的持久化状态）。合理分配不同级别的记忆内容可以最大化 AI 辅助效果。全局记忆存个人偏好，项目记忆存团队规范，会话记忆专注当前任务。

记忆分配原则：全局 MEMORY.md 记录"我是谁"（个人习惯、常用配置、跨项目经验）；CLAUDE.md 记录"项目是什么"（技术栈、架构、规范、FAQ）；会话上下文记录"正在做什么"（当前任务、临时变量）。将全局偏好在 MEMORY.md 中登记可以避免每次初始化项目时的重复配置。

4.4 自动化规则注册

对于需要 Claude Code 自动响应的行为（如"每次修改数据库 schema 后运行迁移"），不写入 CLAUDE.md 而是注册为 settings.json 中的 hooks。这样可以在不修改项目文件的情况下实现自动化行为。hooks 支持 before_task, after_task, on_error 三种触发时机。

// .claude/settings.json
{
  "hooks": {
    "before_task": [
      {
        "match": "修改了 .prisma 文件",
        "command": "npx prisma generate"
      }
    ],
    "on_error": [
      {
        "match": "TypeScript 编译错误",
        "command": "npx tsc --noEmit 2>&1 | head -20"
      }
    ]
  }
}

五、知识自动化

知识库的维护成本随着内容增长而线性上升。知识自动化通过脚本和工具链将维护工作从手动变为自动，确保知识库始终保持高质量和新鲜度。自动化覆盖六个核心场景：自动更新、过时检测、一致性检查、知识图谱构建、链接检查和术语维护。

5.1 自动更新流水线

代码变更自动触发文档更新是最基础的知识自动化。在 CI/CD 中集成文档生成步骤，当检测到 API 接口变更时自动更新对应的 API 文档、当数据库 Schema 变更时自动更新数据字典、当依赖升级时自动更新环境要求文档。以下是一个使用 Claude Code 实现自动文档生成的 CI 脚本：

#!/bin/bash
# scripts/auto-docs.sh - 自动化文档生成流水线

set -euo pipefail

echo "=== 开始自动化文档生成 ==="

# 1. 从 OpenAPI 规范生成 API 文档
if [ -f "openapi.yaml" ]; then
    npx @redocly/cli build-docs openapi.yaml \
        -o docs/api/reference.html
    echo "  ✓ API 参考文档已更新"
fi

# 2. 从 Prisma Schema 生成数据字典
if [ -f "prisma/schema.prisma" ]; then
    npx prisma-docs-generator \
        --schema prisma/schema.prisma \
        --output docs/database/schema.md
    echo "  ✓ 数据字典已更新"
fi

# 3. 生成 CHANGELOG
if git describe --abbrev=0 >/dev/null 2>&1; then
    conventional-changelog -p angular -i CHANGELOG.md -s
    echo "  ✓ CHANGELOG 已更新"
fi

echo "=== 文档生成完成 ==="

5.2 过时检测机制

知识库中最危险的不是没有文档，而是有错误的过期文档。过时检测通过以下方法实现：在每篇文档头部标注"最后验证日期"，超过设定阈值（建议 90 天）自动标记为"需验证"；在 CI 中集成 diff 检测，当代码与文档描述不一致时发出告警；使用 Claude Code 定期扫描知识库，对比代码实现和文档描述的一致性。以下是一个文档新鲜度检查脚本：

#!/bin/bash
# scripts/stale-check.sh - 检查过期文档

echo "=== 检查过期文档 ==="
threshold_days=90
stale_files=()

while read -r file; do
    local last_verified=$(grep -oP 'last_verified:\s*\K.*' "$file")
    if [ -n "$last_verified" ]; then
        local last_ts=$(date -d "$last_verified" +%s)
        local now_ts=$(date +%s)
        local age=$(( (now_ts - last_ts) / 86400 ))
        if [ "$age" -gt "$threshold_days" ]; then
            stale_files+=("$file (已 $age 天未验证)")
        fi
    fi
done < <(find docs/ -name "*.md")

if [ ${#stale_files[@]} -eq 0 ]; then
    echo "  ✓ 所有文档均新鲜"
else
    echo "  ⚠ 发现 ${#stale_files[@]} 篇过期文档:"
    for f in "${stale_files[@]}"; do
        echo "    - $f"
    done
fi

5.3 一致性检查

知识库中的术语、代码示例、配置参数需要保持一致性。不一致的知识比没有知识更有害。推荐使用以下工具进行自动化一致性检查：vale（文本风格检查）、markdownlint（Markdown 格式检查）、lychee（链接有效性检查）。在 CI 中集成这些检查，确保每次文档变更都通过质量门禁。

# .github/workflows/docs-lint.yml
name: Documentation Lint
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check Markdown format
        uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          globs: 'docs/**/*.md'

      - name: Check broken links
        uses: lycheeverse/lychee-action@v1
        with:
          args: 'docs/ --verbose --no-progress'

      - name: Check terminology consistency
        uses: errata-ai/vale-action@v2
        with:
          files: docs/
          styles: |
            https://github.com/errata-ai/write-good/releases/latest
            https://github.com/errata-ai/Google/releases/latest

5.4 知识图谱构建

知识图谱将离散的文档通过实体关联构建成网络结构。每个文档、术语、代码模块、团队角色都作为一个节点，它们之间的引用关系形成边。使用 Claude Code 可以自动分析知识库内容，提取实体关系并生成可视化的知识图谱。图谱可用于发现知识孤岛（没有引用的文档）、知识热点（被引用最多的文档）和知识缺口（缺失关联的领域）。

5.5 链接检查与术语维护

知识库中常见的问题包括死链接（指向已删除的文件）、重定向链接（未更新到新地址）、术语不一致（同一概念在不同文档中使用不同名称）。建议每周运行一次全局链接检查，每月进行一次术语一致性审计。术语维护可以借助 Claude Code 的搜索替换能力，批量更新整个知识库中的术语。

# .claude/terminology.yaml - 术语表
# 用于一致性检查和自动更正

terms:
  - preferred: 知识库
    aliases: [知识库系统, 知识管理系统, 文档库]

  - preferred: 架构决策记录
    aliases: [架构决策, ADR, Architecture Decision Record]
    patterns:
      - '架构(上的)?决定'
      - '技术选型记录'

  - preferred: CLAUDE.md
    aliases: [claude.md, Claude.md, project memory]
    patterns:
      - '项目记忆文件'
      - 'AI 配置文件'

patterns:
  - preferred: CI/CD
    not: [CI, CD, 'CICD', 'ci/cd']

  - preferred: 前端
    not: [前台, 客户端侧]

六、知识分享与团队协作

知识库的最终价值体现在知识的高效流动和复用。再完善的知识库如果团队成员不使用，就是数字废墟。知识分享与协作需要从流程、工具和文化三个维度同步建设。

6.1 团队协作流程

建议采用"写者-审者-发布者"的三级协作模型：写者负责起草文档内容，使用 PR 提交；审者负责技术准确性审查和格式规范检查；发布者负责合并发布和通知同步。每次文档变更通过 PR 流程流转，确保质量。以下是使用 Claude Code 创建的标准化文档 PR 模板：

## 文档变更摘要

**变更类型**: [新建 | 更新 | 废弃 | 删除]
**涉及文档**: [文件路径列表]
**关联 PR/Issue**: #[编号]

**变更说明**:
[简要描述变更的内容和原因]

**审查重点**:
- [ ] 技术准确性
- [ ] 术语一致性
- [ ] 代码示例可运行
- [ ] 链接有效性
- [ ] 格式规范

**受影响团队**:
[列出需要知悉此变更的团队或成员]

**是否需要培训**: [是/否]
**培训材料**: [链接]

6.2 评论与反馈机制

文档不是刻在石碑上的，它应该是动态的、可讨论的。推荐为每篇文档提供以下反馈渠道：文档末尾的"改善建议"按钮，指向 GitHub Issue 创建链接；文档每段旁的可评论锚点（类似 Google Docs）；定期的文档质量问卷调查；使用 Claude Code 自动收集用户对文档的模糊查询，识别需要改进的章节。

6.3 版本历史与变更通知

每次文档更新都应有清晰的版本记录和变更通知。在文档底部自动生成修改历史表格，包含修改日期、修改人、修改摘要和关联 PR。重大变更通过即时通讯工具（如飞书、Slack）推送通知，使用 webhook 在文档 CI 流程中自动发送变更摘要。

## 修改历史

| 日期 | 修改人 | 变更摘要 | 关联 PR |
|------|--------|----------|---------|
| 2026-05-08 | 张三 | 新增 MkDocs 配置示例 | PR #142 |
| 2026-04-20 | 李四 | 更新 API 认证流程 | PR #138 |
| 2026-03-15 | 王五 | 初始版本创建 | PR #101 |

6.4 知识审核机制

知识审核是保证知识库质量的守门人。建议建立"月度知识审核"制度，由各技术负责人轮流担任审核官。审核内容涵盖：新文档的质量评估、过期文档的清理建议、知识图谱中孤岛文档的重新关联、用户反馈中反映的文档问题。审核结果形成月度报告，纳入团队的技术债务管理。

审核清单示例：文档是否有明确的写作日期和作者信息？代码示例是否可运行且使用最新语法？术语是否与团队术语表一致？交叉引用是否完整有效？文档的元信息（description, keywords）是否完善？是否有明确的读者定位（入门/进阶/专家）？

6.5 新人入职文档

新人入职文档是知识库价值的试金石。如果新人能通过阅读知识库独立完成开发环境搭建、第一个 PR 提交、熟悉项目架构，说明知识库是健康有效的。新人入职文档建议包含：团队介绍和沟通方式、开发环境搭建步骤（可自动化）、项目结构和代码库导航、CI/CD 流程说明、编码规范和代码审查流程、常用术语表、常见问题 FAQ 和新手任务列表。

实践经验：每季度让一位新人（或轮岗成员）按流程走一遍新人入职文档，记录所有卡点和疑问，然后更新文档。这种"吃自己的狗粮"的方式是检验知识库质量的最有效方法。

6.6 RFC 流程

RFC（Request for Comments）是技术团队中最重要的知识共创流程。当需要引入重大变更时，先写 RFC 文档征求团队意见，经过充分的讨论和修改后再进入实施阶段。以下是一个轻量级 RFC 模板：

# RFC-NNN: [提案标题]

## 元信息
- **作者**: [姓名]
- **创建日期**: 2026-05-08
- **状态**: [草稿 | 讨论中 | 已批准 | 已实施 | 已拒绝]
- **优先级**: [P0/P1/P2]

## 摘要
[200 字以内的提案核心内容]

## 动机
[为什么要做这个变更？当前方案有什么问题？]

## 设计提案
[详细描述方案设计，可包含架构图、API 设计、数据流等]

## 备选方案
[列出至少 2 个备选方案，说明为什么最终选择当前方案]

## 影响评估
- 正面影响: [性能、可维护性、开发者体验的提升]
- 负面影响: [迁移成本、学习成本、兼容性问题]
- 风险评估: [潜在风险和应对措施]

## 实施计划
- 阶段一: [MVP 范围和时间预估]
- 阶段二: [扩展功能]
- 阶段三: [收尾和文档更新]

## 开放问题
[尚未确定的决策点，需要团队讨论解决]

---

## 讨论记录

### 2026-05-08 架构评审
- [某人]: [观点]
- [结论]: [达成的共识或需要进一步讨论的问题]

工具实践：所有 RFC 文档放在 docs/team/rfcs/ 目录下，按编号命名（RFC-001.md, RFC-002.md）。每个 RFC 获得批准后，自动创建对应的实施任务卡片，并通知相关干系人。使用 Claude Code 可以辅助生成 RFC 的初稿，根据会议录音或讨论记录自动提炼要点。

七、完整工作流集成

上述六大模块不是孤立的，它们共同构成一个完整的知识生命周期。以下是一个端到端的工作流集成示意图，展示了从知识采集到分享的完整闭环：

# 知识库构建工作流 - 端到端流程

# 阶段一: 知识采集 (每日)
# 触发条件: 代码合并、故障解决、技术评审、会议结束
├── Claude Code 自动提取代码注释 → docs/code-comments/
├── 工程师手动创建 ADR → docs/architecture/decisions/
├── 故障记录模板 → docs/operations/runbooks/
└── 会议记录模板 → docs/team/meeting-notes/

# 阶段二: 知识组织 (每周)
# 触发条件: 定时任务或手动触发
├── 标签审核: 检查标签一致性和覆盖面
├── 交叉引用: Claude Code 扫描引用关系自动补全
├── 搜索优化: 检查 meta 信息完整性
└── 权限审计: 检查目录权限配置

# 阶段三: 知识构建 (CI/CD)
# 触发条件: 推送 docs/ 目录变更
├── Markdown lint 检查
├── 链接有效性检查
├── 术语一致性检查
├── 静态站点构建 (MkDocs/Docusaurus)
└── 部署到 GitHub Pages / Vercel

# 阶段四: 知识自动化 (每月)
# 触发条件: 定时任务 + 代码变更
├── 过时文档检测: 标记 90 天未验证的文档
├── CLAUDE.md 更新回顾: revise-claude-md
├── 知识图谱重新生成
└── 文档质量报告自动生成

# 阶段五: 知识分享 (持续)
# 触发条件: PR 合并、文档发布
├── 文档变更通知 → 团队即时通讯
├── RFC 讨论 → 团队评审会议
├── 新人文档引导 → 入职培训
└── 月度知识审核 → 技术债务管理

7.1 Claude Code 工作流集成

Claude Code 在整个工作流中充当"智能枢纽"的角色，在各个阶段提供 AI 辅助：采集阶段自动提取注释和生成文档初稿；组织阶段扫描交叉引用和检查一致性；自动化阶段执行过时检测和术语更新；分享阶段辅助 RFC 撰写和会议记录。以下是一个典型的 Claude Code 会话工作流：

# Claude Code 日常会话工作流

# 步骤 1: 启动会话
cd project
claude

# 步骤 2: Claude 自动加载 CLAUDE.md 获取项目上下文
# - 了解技术栈、编码规范、架构决策
# - 加载常用命令和配置

# 步骤 3: 执行任务并自动记录知识
/revise-claude-md
# 会话结束后更新 CLAUDE.md，记录本次会话的关键决策

# 步骤 4: 提交知识变更
git add docs/
git commit -m "docs: 添加数据库迁移策略ADR"
git push

八、总结与最佳实践

知识库构建的七个黄金法则：

写文档要像写代码：遵循 DRY 原则，使用版本控制，经过 code review
先有流程，再有工具：工具只是辅助，核心是团队的知识管理文化和流程
自动化一切可自动化的：文档生成、链接检查、过时检测全部 CI/CD 化
持续维护而非一次性建设：每天 10 分钟的知识维护胜过每月 4 小时的大扫除
以读者为中心：写文档时思考"读者需要什么"而不是"我想写什么"
拥抱结构化：模板是知识库的骨架，避免自由格式的文档泛滥
度量驱动改进：跟踪文档覆盖率、新鲜度、搜索命中率等指标

立即行动的三个步骤：

今日：在项目仓库中创建 CLAUDE.md，记录当前的技术栈、编码规范和三个最重要的架构决策。执行一次 /revise-claude-md 让 AI 自动优化内容结构。
本周：搭建 MkDocs 或 Docusaurus 文档站，配置 CI/CD 自动构建部署。迁移至少 5 篇散落的文档到结构化知识库中。建立 ADR 目录并起草第一份架构决策记录。
本月：建立知识审核机制，配置自动化过时检测和链接检查。组织团队 RFC 流程的首次试点。运行新人文档测试流程，邀请一位新同事按照知识库搭建环境并记录卡点。

"知识管理的终极目标不是建立最大的知识库，而是最小化团队获取正确知识所需的时间。最好的知识库是让团队感觉不到其存在的知识库——当需要时它就在那里，准确、及时、易于理解。"

常见陷阱与避免方法：

陷阱一：文档过度膨胀。避免方法：定期清理合并重复文档，保持每篇文档聚焦一个主题。
陷阱二：只写不读。避免方法：将文档阅读纳入开发流程（如 PR review 时参考关联文档）。
陷阱三：格式崇拜。避免方法：先关注内容质量，再优化格式美观，不要为了美观牺牲内容。
陷阱四：一次性工程。避免方法：将知识维护纳入 sprint 的 Definition of Done，每次迭代必须更新相关文档。

阶段	关键活动	工具	频率
采集	注释提取、ADR创建、故障记录	Claude Code, 模板脚本	每日
组织	标签审核、交叉引用、权限管理	标签系统, CI脚本	每周
构建	文档编译、站点部署	MkDocs/Docusaurus, GitHub Actions	PR合并时
自动化	过时检测、图谱构建、术语维护	Claude Code, 定时任务	每月
分享	通知推送、RFC流程、新人引导	即时通讯, Wiki系统	持续

知识库构建不是一次性项目，而是一种持续的组织实践。它需要工具的支持、流程的保障和文化的滋养。使用 Claude Code 作为智能助手，可以将知识管理的效率提升一个数量级——让 AI 处理机械的采集和维护工作，让人类专注于创造性的知识组织和应用。随着团队持续实践，知识库将从一个被动的内容仓库进化为主动的"团队大脑"，在每个技术决策的关键时刻提供准确的参考信息。