Back to Details

codebase-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codebase Onboarding

代码库入门引导

Tier: POWERFUL
Category: Engineering
Domain: Documentation / Developer Experience
Tier: POWERFUL
Category: Engineering
Domain: Documentation / Developer Experience

Overview

概述

Analyze a codebase and generate onboarding documentation for engineers, tech leads, and contractors. This skill is optimized for fast fact-gathering and repeatable onboarding outputs.
分析代码库并为工程师、技术负责人和外包人员生成入门文档。此技能针对快速收集信息和可重复生成入门输出进行了优化。

Core Capabilities

核心能力

  • Architecture and stack discovery from repository signals
  • Key file and config inventory for new contributors
  • Local setup and common-task guidance generation
  • Audience-aware documentation framing
  • Debugging and contribution checklist scaffolding
  • 从仓库信号中发现架构和技术栈
  • 为新贡献者整理关键文件和配置清单
  • 生成本地环境搭建和常见任务指南
  • 针对不同受众调整文档框架
  • 搭建调试和贡献检查清单

When to Use

使用场景

  • Onboarding a new team member or contractor
  • Rebuilding stale project docs after large refactors
  • Preparing internal handoff documentation
  • Creating a standardized onboarding packet for services
  • 为新团队成员或外包人员办理入职
  • 在大型重构后重建过时的项目文档
  • 准备内部交接文档
  • 为服务创建标准化的入门资料包

Quick Start

快速开始

bash
undefined
bash
undefined

1) Gather codebase facts

1) 收集代码库信息

python3 scripts/codebase_analyzer.py /path/to/repo
python3 scripts/codebase_analyzer.py /path/to/repo

2) Export machine-readable output

2) 导出机器可读格式的输出

python3 scripts/codebase_analyzer.py /path/to/repo --json
python3 scripts/codebase_analyzer.py /path/to/repo --json

3) Use the template to draft onboarding docs

3) 使用模板起草入门文档

See references/onboarding-template.md

请查看 references/onboarding-template.md


---

---

Recommended Workflow

推荐工作流程

  1. Run 
    scripts/codebase_analyzer.py
    against the target repository.
  2. Capture key signals: file counts, detected languages, config files, top-level structure.
  3. Fill the onboarding template in 
    references/onboarding-template.md
    .
  4. Tailor output depth by audience:
    • Junior: setup + guardrails
    • Senior: architecture + operational concerns
    • Contractor: scoped ownership + integration boundaries
  1. 针对目标仓库运行 
    scripts/codebase_analyzer.py
    。
  2. 捕获关键信号：文件数量、检测到的编程语言、配置文件、顶层结构。
  3. 填写 
    references/onboarding-template.md
    中的入门模板。
  4. 根据受众调整输出深度：
    • 初级开发者：环境搭建 + 注意事项
    • 资深开发者：架构 + 运维关注点
    • 外包人员：明确职责范围 + 集成边界

Onboarding Document Template

入门文档模板

Detailed template and section examples live in:
  • references/onboarding-template.md
  • references/output-format-templates.md
详细模板和章节示例位于：
  • references/onboarding-template.md
  • references/output-format-templates.md

Common Pitfalls

常见误区

  • Writing docs without validating setup commands on a clean environment
  • Mixing architecture deep-dives into contractor-oriented docs
  • Omitting troubleshooting and verification steps
  • Letting onboarding docs drift from current repo state
  • 在未在干净环境中验证搭建命令的情况下编写文档
  • 在面向外包人员的文档中混入架构深入讲解内容
  • 省略故障排查和验证步骤
  • 让入门文档与当前仓库状态脱节

Best Practices

最佳实践

  1. Keep setup instructions executable and time-bounded.
  2. Document the "why" for key architectural decisions.
  3. Update docs in the same PR as behavior changes.
  4. Treat onboarding docs as living operational assets, not one-time deliverables.
  1. 确保搭建说明可执行且有时间限制。
  2. 记录关键架构决策的“原因”。
  3. 在同一PR中更新文档与行为变更。
  4. 将入门文档视为动态的运维资产，而非一次性交付物。