← 返回学习中心ARC LAB / LEARNING NOTES

验证与交接

团队协作与项目交接

明确任务、回应审查，让接收者能够独立继续项目。

面向新成员 · 示例与练习
展开本篇目录

一、为什么学习协作与交接？

个人练习可以只关注“我能运行”，团队项目还需要让别人知道你做了什么、如何使用、哪里有风险，以及下一步由谁继续。

在 ArcLab，大一成员可能承担文档、测试、数据整理或简单模块。这些工作只要输入、输出和记录清楚，就能成为真实项目贡献。

协作与交接分别做什么？

内容 主要目标
协作 多人围绕共同任务持续推进
交接 让接收者有能力继续运行、修改和维护

把文件发给别人，只完成了传递，不一定完成交接。接收者能根据材料复现结果，才是更有说服力的证据。

二、理解项目与自己的任务

开始动手前，至少回答三个问题：

  1. 项目解决什么问题，谁会使用？
  2. 输入如何经过各模块变成输出？
  3. 我负责哪一部分，它与别人的接口是什么？

一个小型项目示意

采集数据 → 检查格式 → 计算统计 → 展示结果
              ↑
        本次负责输入校验

如果只知道“整理 CSV”，却不知道字段含义、输出去向和验收人，应先补齐任务上下文。

三、任务需要写清哪些信息

3.1 任务六要素

要素 需要回答
目标 为什么做，解决什么具体问题？
输入 哪个代码版本、数据、设备或接口？
范围 这次负责哪些行为？
输出 代码、数据、文档或演示是什么？
验收 怎样判断完成，由谁检查？
时间与依赖 何时检查，依赖谁提供什么？

3.2 从模糊要求变成小任务

模糊：把项目文档完善一下。

具体：为当前最小 Demo 补齐 README 的环境、启动与结果说明。
输入：队长指定的代码提交和样例数据。
输出：README 修改及一次同伴复现记录。
验收：另一名成员按文档运行，输出非空行数 3，无需作者口头补充。
范围：本次不改变 Demo 功能。
检查点：双方约定的时间；安装阻塞及时反馈。

范围说明用于约束当前任务，不代替必要修复。发现输入或需求有问题时，说明证据再调整约定。

四、拆解任务与安排进度

4.1 按可检查成果拆分

例如“补齐运行文档”可以分成：

  1. 确认版本与样例输入。
  2. 从新目录跑通 Demo，记录命令。
  3. 整理环境、步骤和预期结果。
  4. 请同伴独立复现。
  5. 根据反馈修正并提交。

每一步都能提供结果或证据，不只是“继续学习”。

4.2 标注任务状态

待开始 → 进行中 → 待检查 → 已完成
               ↘ 阻塞

“待检查”不等于已经验收。“阻塞”需要写明缺少什么、已经尝试什么、需要谁协助，不能只换一个状态标签。

4.3 估计投入与风险

把安装、资料阅读和验证也计入工作，不只估计写代码的时间。存在不确定性时先安排小验证，并在发现延期风险时更新计划。

新生阶段可以由队长帮助限定任务大小，不以一开始就能准确估时为前提。

五、用 Issue 记录任务与问题

Issue 可以保存需求、缺陷和待办，使讨论与结果能回查。平台没有启用 Issue 时，也可先用项目任务文档，关键是有明确记录位置。

5.1 任务 Issue 模板

# 补齐 Demo 的环境与启动说明

## 背景

说明当前影响：新成员无法独立按文档运行。

## 输入与版本

填写仓库、实际提交、样例数据和必要设备。

## 目标与范围

列出这次要完成的行为和文档范围。

## 验收条件

- [ ] 环境与依赖明确。
- [ ] 启动命令可复制执行。
- [ ] 输入、输出与预期结果写清楚。
- [ ] 一名同伴完成独立复现。

## 负责人和检查点

填写执行人、验收人、约定检查时间与依赖。

5.2 缺陷报告

问题类 Issue 写明环境、最小复现、预期、实际和错误原文。将定位结论与猜测区分，详细方法见技术检索、文档阅读与问题提问教程。

聊天可以用于及时沟通，但关键决定、变更与解决办法应回到任务记录中。

六、分支、提交与 Pull Request

6.1 基本协作流程

领取任务 → 同步代码 → 创建分支 → 修改并验证
→ 提交 PR → 回应审查 → 合并 → 更新任务记录

假设已经克隆练习仓库、拥有写入权限、主分支叫 main，且工作区干净：

git switch main
git pull --ff-only origin main
git switch -c docs-demo-setup

修改并检查 README 后：

git diff
git add README.md
git diff --staged
git commit -m "补充 Demo 环境与运行说明"
git push -u origin docs-demo-setup

平台上创建 PR，核对目标分支与源分支。没有写入权限时可按项目规则使用 Fork，具体命令见 Git 与 GitHub 教程。

6.2 一次提交围绕一件事

只提交与任务相关的代码与资料，不顺便重排全项目格式。提交前检查是否混入数据副本、缓存、环境目录或凭据。

6.3 PR 说明模板

## 问题与结果

说明原来的具体障碍，以及修改后的行为。

## 修改内容

列出帮助理解范围的关键改动。

## 验证

记录实际执行的命令、输入和观察结果。
未执行部分写明原因，不标为通过。

## 关联任务与待确认

链接实际 Issue，说明仍需验证或由接收者处理的内容。

“已自测”缺乏可检查信息。写“在新目录按 README 执行，输出非空行数 3”更具体。

七、代码审查与反馈

7.1 审查什么？

  • 是否满足任务目标和接口约定？
  • 输入、异常和边界情况是否合理？
  • 是否容易理解，文档与实现是否一致？
  • 是否有对应验证，是否混入无关内容？

7.2 怎样给建议？

较模糊：这里写得不好。

较具体：README 使用了作者电脑的绝对路径，其他成员无法直接运行。
建议改为项目内相对路径，并从新目录验证图片和输入可访问。

说明问题、影响和可行方向，区分必须修改的正确性问题与可讨论的风格建议。

7.3 怎样回应？

理解问题后修改并说明验证；有不同判断时给出依据，或请审查者确认需求。收到反馈不等于必须照抄实现，但需要回应实质问题。

审查帮助改进成果，不替作者承担全部正确性责任。是否合并按项目权限和规则处理。

八、接口约定与变更沟通

8.1 接口不只指网络 API

函数参数、CSV 表头、目录结构、文件格式、串口消息都可能成为成员之间的接口。

接口信息 示例
输入字段 sensor,value
数据类型 sensor 为字符串，value 为有限数值
单位 摄氏度或项目指定单位
异常规则 空文件拒绝处理，给出明确提示
输出 JSON 中包含数量与平均值

8.2 改动前确认影响

把 value 改成 temperature 可能影响读取、测试、文档和展示模块。先通知受影响成员，更新约定和对应验证，再统一合并。

不把“代码只改一行”当成“影响一定很小”。需要兼容旧数据时，应明确过渡方案。

九、进展与阻塞怎样汇报

9.1 简短进展格式

已完成：环境说明和启动命令，关联 PR 或提交。
证据：在新目录运行成功，输出非空行数 3。
当前阻塞：缺少团队 Windows 环境验证。
需要协助：请指定一名 Windows 成员复现。
下一步：处理反馈后提交验收。

“看了很多视频”“忙了一周”可以作为过程信息，但不能替代产出和证据。

9.2 及时报告哪些情况？

需求含糊、依赖缺失、重复尝试没有新证据、预计无法达到约定检查点、可能影响公共数据或设备时，应及时沟通。

报告阻塞时同时给出已经确认的事实。只发“不会”不便于帮助，只在最后一刻说“做不完”也不利于调整。

十、项目归档与 README

10.1 最小交接结构

project/
├── README.md
├── environment.yml 或 requirements.txt
├── 主要源码
├── tests/
├── data/sample/
├── docs/
│   ├── decisions.md
│   ├── known-issues.md
│   └── handover.md
└── output/example/

这是参考结构，不要求为小任务制造空目录。原始数据很大或不便公开时，保留合规存放位置、访问方式和可共享样例。

10.2 README 回答什么？

  1. 项目解决什么问题，当前完成到哪里？
  2. 用什么环境和依赖？
  3. 如何取得代码和必要输入？
  4. 怎样启动，预期结果在哪里？
  5. 怎样测试，常见问题如何处理？
  6. 谁维护，哪些功能或环境尚未验证？

核心步骤提供可复制文本，不只提供截图。固定代码提交、数据版本和设备型号，比“用最新版就行”更便于交接。

十一、实验记录、决策与已知问题

11.1 实验记录

记录输入、参数、环境、步骤、结果与结论，区分观察和推测。尝试失败也有价值，可以避免下一届重复无效工作。

11.2 决策记录

# 决策：固定样例相对脚本目录定位

## 背景

从上级目录运行时，原程序找不到样例。

## 选择与理由

样例随脚本交付，因此相对脚本定位。

## 影响

从不同工作目录启动均读取同一份样例。

## 限制

用户自选输入仍应通过命令行参数传入。

11.3 已知问题清单

写明触发条件、影响、临时处理、负责人或下一步。不要用“有些 bug”代替具体记录，也不要把未实现功能包装成已完成。

十二、交接验收：由接收者实际操作

12.1 交接前准备

  • 代码已进入指定仓库或约定位置，有明确版本。
  • 样例输入、依赖、运行与测试说明齐全。
  • 已知问题和必要资源说明清楚。
  • 账号或设备权限通过团队指定方式转交，不写进公开 README。

12.2 接收者操作

  1. 在新目录取得代码，不借用作者现成的运行目录。
  2. 按说明创建或选择环境。
  3. 运行最小 Demo，核对预期结果。
  4. 执行相关测试或手工检查。
  5. 完成一处小修改，证明理解入口和输出。
  6. 把卡点和缺失步骤反馈回文档。

12.3 完成标准

接收者能说明项目目标、关键入口、输入输出、验证方式和未解决问题。作者只靠现场口头补充才能跑通时，应补文档并重试相应步骤。

小任务可以只用一条复现记录，不必建立复杂签字流程。

十三、一个综合示例：交接非空行统计 Demo

13.1 明确任务

采用开发环境与文件路径教程中的 path-demo。任务是补齐文档并交给同伴，不要求加入额外框架。

输入为三行样例，预期输出 非空行数：3；固定样例按脚本目录定位。

13.2 完成与验证

  1. 为本次任务建立记录，写清范围与验收人。
  2. 在自己的分支修改 README。
  3. 从项目目录和上级目录分别运行，保存命令和结果。
  4. 给样例插入一个空行，确认统计仍为 3，再恢复输入。
  5. 提交 PR，附修改目的与实际验证。

13.3 同伴复现

接收者在新目录获取对应版本，按 README 运行，核对输出文件。发现缺少“需要先创建输入文件”等说明时，回到 PR 补充。

13.4 交接记录示例

# Demo 交接记录

## 对应版本

填写实际仓库与提交标识。

## 验证环境

填写接收者实际系统与 Python 版本。

## 复现结果

- 项目目录启动：填写实际结果。
- 上级目录启动：填写实际结果。
- output/report.txt：填写实际内容。

## 问题与处理

填写缺失步骤、修改位置和重新验证结果。

## 仍未验证

例如未覆盖的系统、编码或大文件情形。

此模板需要填写实际事实，不直接把示例勾选为已完成。

十四、常见问题排查

情况 改进方式
多人重复做同一项 明确任务记录和当前执行人
做完却不符合预期 开始前补齐输入、范围与验收条件
合并困难或冲突很多 小批量提交、及时同步并明确修改边界
PR 看不懂 写清问题、改后行为与验证，去掉无关改动
队长不知道成员卡住 按约定检查点汇报，发现阻塞及时说明
同伴无法运行 补环境、目录、样例和完整命令
作者离开后无人会维护 让接收者实际运行与修改，不只听讲
结果看似完成却没有证据 链接提交、日志、测试或复现记录

十五、练习

  • 用三句话解释所在项目与自己的任务。
  • 把一个模糊任务改写为输入、输出和验收条件明确的任务。
  • 为任务建立 Issue 或文档记录，约定检查点。
  • 创建分支并完成一次小提交与 PR。
  • 给同伴一个包含影响和理由的审查建议，并回应自己的反馈。
  • 写一条结构清楚的进展或阻塞报告。
  • 为一次技术选择写简短决策记录。
  • 完成 Demo 交接，记录接收者实际复现过程。

验收：别人可以从任务记录找到代码、文档、验证和下一步，而不必遍历大量聊天记录。

十六、协作速查表

阶段 关键产物
领取任务 目标、输入、范围、输出、验收人和检查点
开始实现 明确版本、独立分支与依赖
提交检查 小范围改动、有效说明与验证结果
审查反馈 问题、影响、依据与处理结果
状态汇报 完成、证据、阻塞、协助与下一步
归档 README、环境、样例、已知问题
交接 接收者实际复现与一次小修改

十七、相关学习资料

← 继续探索学习路径反馈问题 ↗