codebase-onboarding

代码库入门指南

分析任意代码库，并生成适合目标受众、达到生产级质量的入门文档。可生成架构概览及系统图、带注释的关键文件索引、本地环境逐步设置指南、常见开发任务操作手册、包含实际错误解决方案的调试指南，以及贡献指南。支持 Markdown、Notion 和 Confluence 输出格式。

核心功能

• 架构分析 — 从清单文件／锁定文件识别技术栈、映射系统边界、生成 Mermaid 数据流图和依赖关系图，并标注模块归属。
• 关键文件注释 — 列出最重要的 20 个文件并说明其重要性；标记入口点、配置中心、共享工具，以及未经协调不宜修改的文件。
• 设置指南生成 — 列出带精确版本号的前置条件、从 git clone 到测试的步骤、环境变量文档、基础设施设置（Docker／DB／缓存），以及验证检查清单。
• 任务操作手册 — 添加 API 端点、运行／编写测试、创建并应用迁移、部署到预发布／生产环境，以及安全地添加依赖项。
• 调试指南 — 列出常见错误及其准确消息和修复方法、各环境的日志位置、诊断用 SQL／CLI 查询，以及在本地复现生产问题的方法。
• 适配受众的输出 — 面向初级开发者、高级工程师和承包商定制内容；支持 Markdown／Notion／Confluence 格式。

关键词： 代码库入门、开发者体验、文档、架构概览、设置指南、调试指南、贡献指南、代码导览、新员工入职

适用场景

• 帮助新团队成员（初级开发者、高级工程师或承包商）熟悉项目
• 大规模重构后，现有文档已过时
• 项目开源之前
• 为自己负责的服务创建团队 Wiki 页面
• 长假或团队交接前整理文档
• 准备需要文档的合规审计

先确认信息

生成文档前，请确认以下信息。如果任何一项未知或含糊，请先提问，不要擅自假设：

• 目标代码库路径 — 要分析哪个项目（三个脚本都会扫描此输入）
• 受众 — 初级开发者、高级工程师或承包商（决定显示哪些章节及其详略程度）
• 输出格式 — Markdown、Notion 或 Confluence（决定生成的文档格式）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“直接起草”，则继续，并在文档开头列出假设。

工具

工具	用途	命令
architecture_mapper.py	分析项目结构并生成高层架构图	python scripts/architecture_mapper.py /path/to/project --json
onboarding_generator.py	扫描项目目录并生成入门指南	python scripts/onboarding_generator.py /path/to/project --json
setup_validator.py	验证项目开发环境设置是否完整	python scripts/setup_validator.py /path/to/project --json

所有工具均接受可选的 directory 参数（默认值为当前目录），以及用于生成机器可读输出的 --json 参数。

参考资料

加载与任务匹配的参考资料——保持此文件精简，按需查阅详细内容：

• references/fact-gathering-and-patterns.md — 第 1 阶段的信息收集 shell 命令，以及第 2 阶段的架构模式分类表。编写文档前分析代码库时请阅读。
• references/documentation-templates.md — 架构概览、关键文件映射、本地设置和调试指南模板，以及面向不同受众（初级／高级／承包商）的补充内容。生成实际的入职文档时请阅读。
• references/quality-and-best-practices.md — 质量验证清单、常见问题、最佳实践、故障排查矩阵和成功标准。交付入职文档前请阅读。

范围与限制

此技能涵盖：

• 根据代码库分析生成架构概览、关键文件映射、设置指南、任务操作手册和调试指南
• 面向不同受众，为初级开发者、高级工程师和承包商定制文档
• 输出为 Markdown、Notion 和 Confluence 格式
• 质量验证清单和内容时效性审查流程

此技能不涵盖：

• 根据代码注解自动生成 API 参考文档——发布相关文档请参阅 engineering/changelog-generator，API 质量请参阅 engineering/api-design-reviewer
• 持续文档流水线或由 CI 触发的文档构建——流水线自动化请参阅 engineering/ci-cd-pipeline-builder
• 威胁模型或访问控制矩阵等以安全为重点的文档——安全审计请参阅 engineering/skill-security-auditor
• 事件响应和生产运维操作手册的生成——运维操作手册请参阅 engineering/runbook-generator

集成点

技能	集成方式	数据流
engineering/runbook-generator	入职任务操作手册可作为生产事件响应运维操作手册的基础	入职操作手册模板 → Runbook Generator，用于扩展为运维级内容
engineering/api-design-reviewer	第 1 阶段的 API 路由分析可为 API 设计质量审查提供依据	发现的 API 端点 → API Design Reviewer，用于一致性检查
engineering/database-schema-designer	关键文件映射过程中识别出的数据库架构文件可为架构设计审查提供信息	架构文件路径和 ORM 类型 → Schema Designer，用于迁移规划
engineering/tech-debt-tracker	架构分析中发现的技术债务项应记录下来以便跟踪	架构分析结果 → Tech Debt Tracker 待办事项
engineering/ci-cd-pipeline-builder	第 1 阶段发现的 CI/CD 配置可由流水线构建器验证和改进	CI 配置路径和工作流列表 → Pipeline Builder，用于优化
engineering/dependency-auditor	第 1 阶段收集的依赖数量和锁文件可直接用于安全与许可证审计	软件包清单和锁文件 → Dependency Auditor，用于漏洞扫描