Onboarding 是一个帮助新开发者快速进入项目、产出可用环境的技能。其目标是:流程结束时,开发者能让每个仓库在本地运行,了解 10 条会在代码评审中遇到的约定,并拥有一个真实的首周任务。
用途与流程 技能按五个步骤推进。第一步确认开发者需要哪些仓库(也可选择“全部”)、所用操作系统以及是否安装了 Docker;同时读取仓库地图(../repo-map.md 或 docs/repo-map.md)获取仓库清单和连接关系,若没有地图则记录,后续补建。
第二步逐个仓库进行经过验证的本地搭建。步骤从仓库实际内容推导,信任顺序为:docker-compose.yml / Makefile / CI 配置 > README > 猜测;CI 配置通常是运行测试所需条件最准确的记录。需要覆盖:运行时版本(.python-version、pyproject.toml、runtime.txt、.nvmrc 等)、依赖安装(uv sync、poetry install、pip install -r requirements/dev.txt 等)、环境变量(从 .env.example 复制,列出哪些需要真实值以及向谁索取;绝不在聊天或文件中粘贴密钥值)、依赖服务(Postgres、Redis、Celery worker 等)、数据库(migrate、seed/fixture 命令、创建超级用户)、启动命令(runserver / docker compose up 及访问 URL)、测试命令(CI 实际运行的精确命令)。尽量与开发者一起执行每一步并边做边修;发现 README 步骤错误或缺失时记录下来,最后可提议用实际可行的步骤修正 README 的 PR。每个仓库的完成标准是:应用启动、某个页面或端点有响应、测试套件可运行(通过,或已知失败被记录)。
第三步整理关键约定。来源为仓库地图中的“How we do X here”部分,若没有地图则阅读 2–3 个代表性应用。内容聚焦评审者真正会指出的问题:分支命名、提交信息格式、PR 模板与评审人;业务逻辑放置位置(services 还是 models 还是 serializers);权限模式与 queryset 作用域;测试风格(pytest-django、factories、conftest.py 辅助函数位置);迁移规则;linter/formatter 与 pre-commit 钩子(当场安装钩子)。若主仓库没有 docs/onboarding.md,则写一份一页纸文档;已有则更新。
第四步选择首周任务。优先级为:带 good first issue、onboarding 等标签的 Jira/GitHub issue(可通过 Atlassian MCP 或 gh issue list --label 查询);测试良好的应用中的小型缺陷;为团队即将改动但缺少测试的区域补充特征测试——工作有用、风险低,且能帮助熟悉代码库。需说明选择该任务的理由、会涉及哪些文件,以及后续由 ask-imogen 接手。
第五步处理仓库地图。若原本没有地图,现在运行 repo-map;若已有地图,向开发者展示其中的 Connections 部分,该图是理解系统最快的方式。
适用场景与限制 适用于新开发者加入、需要快速搭建多个客户端仓库并了解团队约定的场景。技能强调步骤必须从仓库实际配置推导并逐步验证,不凭猜测;涉及密钥时只说明来源,不写入聊天或文件。资料未提供具体支持的平台范围、安装方式、收费或效果保证等信息。