项目级闭环要求

目的

这份文档给技术负责人、项目负责人和小组长用。组织级文档只能说明原则，真正交付时必须落到每个具体项目：仓库是什么、owner 是谁、怎么跑、怎么测、依赖谁、怎么发、怎么回滚。

一个项目如果回答不了这些问题，就不算可维护项目。

项目必须有一个入口页

每个项目必须在仓库内放一个项目入口页，推荐路径：

docs/PROJECT.md

使用模板：templates/项目入口-project-index.md。

入口页不是长文档，它只回答新人和技术负责人最先要看的问题：

  1. 项目解决什么问题。
  2. 当前生产负责人是谁。
  3. 代码仓库、环境、监控、发布入口在哪里。
  4. 本地怎么跑起来。
  5. 改完要跑什么检查。
  6. 上游是谁，下游是谁。
  7. 哪些地方不能随便改。
  8. 出问题怎么回滚或找谁。

项目级 P0 文档

草台团队不要一开始写十几个文档。每个项目先保证 P0 文档存在。

文件 作用 不合格表现
docs/PROJECT.md 项目入口和负责人 新人不知道从哪里开始
docs/ARCHITECTURE.md 系统边界、模块、数据流 只能靠资深工程师口头解释
docs/TECH_STACK.md 技术选型、版本、命令 pnpm check 这类命令没人知道做什么
docs/DEPENDENCIES.md 上下游、第三方、基础设施依赖 下游故障时没人知道影响范围
docs/RUNBOOK.md 发布、回滚、排障入口 上线或事故靠个人记忆

P0 文档不要求完整，但必须真实、可执行、能被新人验证。

项目级 Owner

每个项目至少明确 4 个 owner：

Owner 负责什么 可以由谁兼任
Product Owner 业务目标、优先级、用户验收 产品、业务负责人、创始人
Tech Owner 架构、代码质量、技术风险 技术负责人、模块 owner
Ops Owner 发布、回滚、监控、事故响应 工程师、运维、平台负责人
Doc Driver 推动项目文档不过期 Tech Owner 或项目成员

小团队可以一人多职，但 docs/PROJECT.md 里必须写清楚。不要写“后端组”“平台组”这种无法直接找到人的 owner。

三角色项目评审

技术负责人评审项目是否可维护，产品负责人评审项目是否服务正确用户，平台 / 资深工程师评审项目是否能被新人跑起和接手。

角色 项目评审必须通过
产品负责人 一句话说明、用户 / 调用方、核心路径、业务验收入口
技术负责人 架构边界、数据状态、风险路径、review owner
平台 / 资深工程师 本地启动、检查命令、依赖服务、监控日志、发布回滚

项目级启动检查

一个新人或临时接手的人，应该能在半天内完成：

拉代码
-> 安装依赖
-> 启动依赖服务
-> 启动应用
-> 跑最小检查
-> 找到监控和日志入口
-> 知道如何提 PR

如果做不到，说明项目开发环境或文档不合格。不要把问题归因于新人不熟。

项目级变更检查

任何项目内 PR 都要判断是否触发这些文档更新：

改动 必须检查
新增接口、事件、webhook ARCHITECTURE.md、DEPENDENCIES.md、契约测试
新增表、字段、状态机 ARCHITECTURE.md、migration、回滚或 forward-fix
新增第三方服务 DEPENDENCIES.md、密钥、降级策略、成本
新增环境变量 .env.example、PROJECT.md、部署配置
改部署方式 RUNBOOK.md、release checklist、rollback
改核心技术栈 TECH_STACK.md、升级策略、替代方案
改权限、支付、客户数据 安全 review、业务验收、回滚计划

Reviewer 如果发现项目级文档没有同步更新，应要求补齐，不要只看代码能不能跑。

技术负责人评审项目时问什么

评审一个项目，不要只问“代码写得怎么样”。按这个顺序问：

  1. 这个项目的生产 owner 是谁？
  2. 新人能不能按文档跑起来？
  3. 主路径 smoke 是什么？
  4. 核心数据在哪里，状态机是什么？
  5. 上游调用方和下游依赖是否写清楚？
  6. 下游失败时用户会看到什么？
  7. 发布失败后怎么回滚？
  8. 哪些改动必须人工 approval？
  9. 最近 30 天架构文档有没有跟代码冲突？
  10. 这个项目如果负责人离职，下一位能不能接手？

答不出来的项，不一定马上阻塞业务，但必须形成技术债任务，并指定 Driver 和截止时间。

项目成熟度分级

等级 状态 技术负责人处理
L0 只有代码，没有可靠项目入口 先补 PROJECT.md、启动命令、owner
L1 能跑起来，但依赖和回滚不清 补 DEPENDENCIES.md、RUNBOOK.md
L2 能开发、测试、发布、回滚 开始补模块契约、服务契约、监控
L3 可交接、可审计、可复盘 允许更多自动化参与

大多数草台项目先做到 L1 就已经能显著降低沟通成本。不要为了追求 L3，反而让 P0 文档没人维护。

下一步阅读

读完或填完这份文档后，通常继续看：