工程师入职和开发闭环
目的
这份文档站在刚入职工程师视角：我怎么了解项目、怎么和团队协作、怎么开始开发、怎么交付第一个 PR。
目标不是让新人一次性读完所有文档，而是让新人能在 1-3 天内完成一个低风险真实改动，并知道遇到问题该找谁。
第 0 步：先确认入口
加入一个项目后，先找当前项目的：
docs/PROJECT.md
如果没有这个文件，先问 Tech Owner 或小组长：
- 项目入口文档在哪里？
- 本地怎么跑？
- 任务在哪里领？
- PR 找谁 review？
- 出问题找谁？
如果这些问题没人能回答，这不是新人问题，是项目交接不合格。应补一个 docs/PROJECT.md。
第 1 天：了解项目
新人第一天不要追求读懂全部代码。先建立地图。
按这个顺序看：
docs/PROJECT.md：项目解决什么问题、owner、常用链接、启动方式。docs/ARCHITECTURE.md：系统边界、核心模块、数据流。docs/TECH_STACK.md：语言、框架、测试和构建命令。docs/DEPENDENCIES.md：上下游、第三方、基础设施。- 最近 3-5 个已合并 PR：团队怎么写代码、怎么测、怎么描述风险。
看完后，应该能用 5 句话说明：
这个项目服务谁。
最核心的 1-3 条路径是什么。
代码大概分哪几层。
本地怎么跑，PR 要跑什么检查。
哪些地方不能随便改。
如果说不出来，先不要接复杂任务。
第 2 步：确认协作方式
开始做任务前，确认团队怎么协作：
| 问题 | 应该从哪里找到 |
|---|---|
| 任务在哪里领？ | docs/PROJECT.md 的任务看板 |
| 日常问题在哪里问？ | 项目沟通群 |
| 技术问题问谁？ | Tech Owner / 模块 Owner |
| 产品问题问谁？ | Product Owner / Business Approver |
| PR 找谁 review？ | CODEOWNERS、项目入口、任务卡 |
| 发布找谁？ | Ops Owner / release checklist |
| 卡住多久要同步？ | 团队约定，默认半天内同步 Driver |
新人不要把问题藏到最后。默认规则：
- 环境跑不起来，卡住 30-60 分钟就同步。
- 需求或 scope 不清，不开工。
- 改动超过任务 scope，先问 Driver。
- 发现文档和代码不一致，先按代码和运行事实做，再创建文档修复任务。
三角色怎么帮新人
| 角色 | 新人应该找他解决什么 |
|---|---|
| 产品负责人 | 任务为什么做、用户是谁、验收标准是什么 |
| 技术负责人 | 代码怎么改才不破坏架构、风险路径在哪里 |
| 平台 / 资深工程师 | 本地怎么跑、测试怎么跑、CI / 发布 / 监控怎么看 |
第 3 步：跑起项目
按 docs/PROJECT.md 执行：
安装依赖
-> 启动依赖服务
-> 配置环境变量
-> 启动应用
-> 跑本地快速检查
-> 跑一个核心路径 smoke
完成后，在任务或入职 checklist 里留下结果：
本地启动：成功 / 失败
检查命令：通过 / 失败
核心路径 smoke：通过 / 失败
遇到的问题：
需要修正文档的地方：
如果文档缺步骤，不要只在群里问完就结束。补到 docs/PROJECT.md 或创建文档修复任务。
第 4 步：接第一个任务
第一个任务应满足：
- Scope 小。
- 不涉及支付、权限、客户数据、生产密钥、破坏性 migration。
- 有明确验收标准。
- 有明确 Reviewer。
- 可以在本地或 staging 验证。
不适合作为第一个任务：
- 跨多个仓库的大改动。
- 线上紧急事故主责。
- 架构重构。
- 没有 owner 的历史问题。
- 需求还在争论的功能。
开发流程
推荐按这个节奏：
读任务
-> 确认 scope 和验收
-> 找相关代码
-> 做最小改动
-> 跑相关检查
-> 自己 review 一遍 diff
-> 提 PR
-> 根据 review 修改
-> 合并 / 发布 / 关闭任务
找代码时优先看：
- 任务关联的页面、API、模块。
- 最近改过同类逻辑的 PR。
- 模块契约或 service contract。
- 测试文件。
- 日志、错误码、监控名称。
不要一上来全局重构。新人第一目标是理解局部并安全交付。
提 PR 前自查
提 PR 前自己回答：
- 我解决的是任务里的问题吗？
- 有没有改出 scope？
- 我跑了哪些检查？结果是什么？
- UI/API 变化有没有截图、请求响应或录屏？
- 如果这次改动出问题，怎么回滚？
- 是否需要产品验收或发布记录？
- 是否需要更新
docs/PROJECT.md、架构、技术栈或依赖文档？
答不出来的项，先补齐再提 PR。
协作礼仪
好的协作不是少问问题，而是让别人容易帮你。
提问时带上：
我在做哪个任务：
我想达成什么：
我已经看过哪些文件 / 文档：
我试过什么命令：
现在卡在哪里：
我倾向的下一步：
不要只发“这个怎么弄”“跑不起来”。这样别人无法判断上下文。
新人可以反向修文档
新人最容易发现文档缺口。遇到这些情况，应直接提文档修复：
docs/PROJECT.md的命令跑不通。- 环境变量缺解释。
- 常用链接失效。
- PR 检查命令和文档不一致。
- 架构文档和代码明显冲突。
- 任务卡缺 owner、验收或 scope。
文档修复也是交付，不是额外负担。
前 7 天完成标准
新人前 7 天至少完成：
| 项 | 标准 |
|---|---|
| 跑起项目 | 本地应用和核心依赖能启动 |
| 读懂入口 | 能说明项目目标、owner、核心路径 |
| 完成第一个 PR | 小 scope、带验证证据、被 review |
| 参与一次协作 | 能在任务、PR 或群里清楚同步状态 |
| 修正一个缺口 | 修文档、补命令说明或创建技术债任务 |
如果做不到，负责人应检查项目文档、开发环境和任务拆分，而不是只评价新人能力。
下一步阅读
读完或填完这份文档后，通常继续看：
- 43-本地开发-local-development.md：新人理解协作方式后，继续按本地开发手册跑项目。