工程化与团队协作
从“一个人能跑”到“一群人能维护”，差的就是这一章。
你将学会
- 用清晰的目录与约定降低协作成本；
- 用分支与评审管理多人改动；
- 配一条最小的 CI/CD 流水线；
- 设置质量门禁，让烂改动进不来；
- 用 ADR / DEVLOG 记录决策；
- 让团队共享同一套 AI 协作规范。
前置知识
一、项目结构与约定
一份好的 README + 一份项目指令文件（AGENTS.md）就能省下大量口头沟通：
- README：这是什么、怎么跑、数据存哪、已知限制；
- 目录约定：源码/测试/文档/产物各放哪，生成目录不进仓库；
- 命名一致：文件、变量、接口命名统一风格；
- 命令固化：安装、开发、测试、构建各一条命令，写进文档。
二、分支策略与协作
最小可用的流程：
text
main（永远可发布）
└── feature/xxx（一个功能一条分支）
└── Pull Request（评审 + 自动检查）→ 合并回 main- 一条分支只做一件事，避免巨型 PR；
- PR 里写清：做了什么、怎么验、影响范围；
- 评审看正确性、边界、安全，而不是格式（格式交给工具）。
三、CI/CD 入门
CI（持续集成）：每次提交自动跑检查； CD（持续部署）：检查通过后自动部署。
最小流水线三步：装依赖 → 跑检查（lint/测试/构建）→ 部署或产出可下载产物。 好处：不依赖“我记得本地跑过”，也能让 AI 的改动必须过同一道门槛。
四、质量门禁
把“靠自觉”变成“靠机制”：
- 提交前：格式化 + lint（能用 pre-commit 钩子自动跑）；
- PR 时：类型检查 + 测试 + 构建必须通过；
- 合并前：至少一次人工评审（可以是换会话的 AI 独立审查，见代码质量与审查）。
五、技术决策记录（ADR / DEVLOG）
- ADR（架构决策记录）：记录“为什么这么选”，一条一件事，带背景、备选、理由、影响；
- DEVLOG（开发日志）：记录“这次改了什么、怎么验的、有什么遗留”。
作用：半年后（或下一个人、下一个 AI）能看懂当时的取舍，而不是靠猜。
六、多人用 AI 协作
- 共享规范：把团队约定写进仓库的
AGENTS.md，所有人和所有工具都读同一份； - 统一口径：提交信息格式、目录结构、命令一致，减少互相踩踏；
- 审查不变：AI 参与的改动，评审标准不降低；
- 知识留痕：重要结论写进 ADR/DEVLOG，而不是留在某个人的会话里。
动手练习
- 为你的项目补齐 README（运行方式、数据位置、已知限制）。
- 给仓库配一条最小 CI：提交后自动跑 lint + 测试 + 构建。
- 为一个重要取舍写一条 ADR（背景 / 备选 / 决策 / 影响）。
检查点
- 新人（或新 AI）只看仓库，能不能跑起来并改对地方；
- 一次改动从提交到合并，是否都过了同一套自动检查；
- 关键决策是否都有记录。
常见问题
Q：一个人也要搞 CI 吗？ 一个人更需要——它替你记住“提交前该跑什么”。起步用平台的免费额度即可。
Q：ADR 会不会太重？ 轻量到一条 Markdown 就够了。重点不是格式，而是留下“为什么”。