用途:为代码库生成并维护 docs/ 目录下的结构化 Markdown 文档,让 AI 智能体(和人类)无需翻阅源码即可快速准确理解项目。适用于用户要求记录代码库、更新已有文档、生成 AI 友好文档、维护 docs/ 目录或编写架构/结构文档的场景。
主要能力:先评估代码库(读取根目录 README、package.json/Cargo.toml/pyproject.toml、配置文件与已有 docs/,梳理目录结构、技术栈、入口点与架构模式),再生成文档集。始终生成 docs/OVERVIEW.md(项目目的、技术栈、架构风格、关键概念,作为入口)、docs/STRUCTURE.md(带注释的目录树)、docs/ARCHITECTURE.md(组件连接、数据流、请求生命周期、关键抽象、模块依赖),最后生成 docs/INDEX.md 作为目录索引。按需生成 DATA_MODEL.md、API.md、CONFIGURATION.md、PATTERNS.md、DEPLOYMENT.md、DEVELOPMENT.md、GLOSSARY.md。
写作原则:每文件以 2-3 句摘要开头,用标题分段、段落简短、代码块标注路径与命令、表格做结构化对比;明确关系与数据流向,引用真实文件路径,说明假设与约束;每文件顶部含 Last updated 日期,底部含 Changes Log;不重复 README、不逐函数记录、不复制代码、不记录生成文件或 node_modules。
更新与校验:更新时先读全部现有文件,重新扫描代码库检测变更,仅更新受影响文件并更新日期与变更日志,增删文件时同步更新 INDEX.md;完成后校验文档中路径真实存在、目录树与实际一致、索引链接完整、交叉引用正确。
限制:文档是地图而非全貌,侧重可导航性与准确性;业务逻辑描述与不明显架构决策可能需人工复核;具体模板见 references/doc-templates.md,资料未提供其内容。