用途
Codedocs 用于为 git 仓库或代码目录生成结构化、分层的文档,这些文档首先面向 AI 智能体消费,其次面向人类开发者。它解决的是扁平 README 容易丢失上下文的问题,通过生成 docs/ 目录树来组织知识。
主要能力
- 生成完整文档:产出 OVERVIEW.md(架构、技术栈、项目结构树、模块地图)、GETTING_STARTED.md(本地开发指南)、INDEX.md(文件到模块的查找表)、modules/ 目录(每个主要代码模块一个 markdown 文件)、patterns/ 目录(跨领域关注点文档)以及 .codedocs.json 清单。
- 文档优先问答:文档存在后,优先从文档回答问题,仅在文档缺失、过时或不足时才回退到源码。
- 增量更新:支持通过 --scope 指定范围更新,或通过 --diff 基于 git diff 检测变更文件进行精准更新。
- 覆盖率检查:通过 codedocs:status 计算源码文件覆盖率、检测过时模块、发现未覆盖目录。
- 语言无关检测:从 package.json、Cargo.toml、go.mod、requirements.txt、pyproject.toml、composer.json、pom.xml、build.gradle、Gemfile、mix.exs 等清单文件检测技术栈。
- 子模块拆分:当模块目录有 15 个以上源文件且存在明显内部分组时,拆分为子模块,父模块文档变为索引。
使用方式
该技能暴露四个子命令:
codedocs:generate [path] [--output docs/]:生成完整或指定范围的文档。流程包括发现阶段(扫描目录树、识别技术栈、映射模块边界、检测跨领域模式)、计划阶段(展示文档计划与覆盖率)、编写 OVERVIEW.md、GETTING_STARTED.md、模块文档、模式文档和清单文件。codedocs:ask "<question>":基于文档回答问题。先检查 .codedocs.json,路由问题到相关文档,优先从文档回答,不足时回退源码并标注,始终引用来源。codedocs:update --scope path/to/module或codedocs:update --diff [base..head]:增量更新文档。读取清单、重新扫描、对比差异、仅重写变更部分、更新清单中的 git SHA 和时间戳。codedocs:status:检查文档覆盖率。读取清单、计算覆盖率、检测过时模块、发现未覆盖目录、输出结构化状态报告。
每次调用开始时需先显示 ASCII 艺术横幅,随后紧跟当前子命令和目标路径。
适用场景
- 为代码库、仓库或目录生成文档
- 回答“这个项目是做什么的”或“解释这个代码库”
- 为新团队成员生成入职文档
- 为仓库生成 AI 智能体可读的文档
- 对已有 codedocs 输出的代码库提问
- 代码变更或新功能后更新现有文档
- 仅记录特定模块或子目录
- 基于最近 git 提交或 diff 刷新文档
限制
- 不适用于编写独立技术文档(RFC、ADR、运行手册),应使用 internal-docs
- 不适用于面向外部消费者的 API 参考文档,应使用 technical-writing
- 不适用于开源打包的 README 创建,应使用 open-source-management
- 输出目录可配置(默认 docs/),但内部结构固定(OVERVIEW.md、INDEX.md、.codedocs.json、modules/、patterns/)
- 覆盖率按源文件计数而非行数,70% 覆盖率可能隐藏未文档化的核心模块
- 清单 SHA 漂移可能导致幻影过时:若生成时仓库有未提交变更,记录的 git SHA 与工作树不匹配,后续更新会视所有文件为过时
- 多语言仓库可能混淆模块边界检测
- GETTING_STARTED.md 若仅从 README 取材可能不完整,需交叉核对 package.json scripts、Makefile 目标和 CI 配置
- 子模块拆分时若父模块文档未更新为索引,会导致信息冲突
核心原则
- 文档优先回答:文档是缓存的结构化知识层
- 语言无关检测:从清单文件和目录约定检测技术栈
- 模块映射代码,模式横切关注点
- 清单驱动增量更新
- 输出可配置,结构不可变
- 覆盖率是一等指标,中型仓库目标 70%+
- 深入而非仅广泛:15 个以上源文件的模块必须分析子模块,大型仓库应生成 30-80 个文档文件