BLOG

项目说明入口维护规范

2026/04/25 7 min read BLOG 编程规范 项目说明入口维护规范

项目说明入口维护规范：为什么 README 和 project.json 必须一起改

先说结论

很多工程不是坏在代码，而是坏在“说明入口分裂”。

最常见的场景就是：

  • README.md 改了，project.json 没改
  • project.json 改了，README.md 没改
  • runtime 已经换了，但文档还停留在旧结构
  • 部署链已经换了，但机器可读入口还指向旧脚本

结果就是：

人看 README 以为系统是这样
机器读 project.json 以为系统是那样
后续 agent 再接手时，又按过期事实继续改

所以这条规则必须硬下来：

只要项目运行真相、部署契约、结构边界、入口地址、服务名、
workflow、runner、脚本路径、健康检查合同发生变化，
README 和 project.json 必须同任务同步更新。

一、两者分别负责什么

很多人会把 README.md 和 project.json 看成“差不多的两个说明文件”。

这其实是错误理解。

它们应该是一个配对系统：

1. README.md

负责给人看。

它应该回答这些问题：

  • 这个项目现在真实跑在哪里
  • 对外入口是什么
  • 内部 target 是什么
  • 当前 deploy 链路是什么
  • 什么是 canonical path
  • 什么不能改
  • 排障时先看什么、后看什么

也就是说：

README = 面向人类的当前事实层 + 约束层 + 操作层

2. project.json

负责给机器看。

它应该承载的是稳定、可解析、可对齐的项目事实，例如：

  • 本机源码根
  • 服务器 runtime 根
  • public base URL
  • console URL
  • health/debug 路径
  • deploy mode
  • deploy script 路径
  • workflow 路径
  • service name
  • runner name

也就是说：

project.json = 面向机器的当前事实索引

3. 这两个文件不是替代关系

不是：

有 README 就够了

也不是：

有 project.json 就不用写 README

而是：

README 讲清楚
project.json 定准点

一个负责解释，一个负责定位。

二、哪些变更必须双改

下面这些变更，一旦发生，就不能只改一边。

1. 运行时真相变化

例如：

  • runtime 根目录换了
  • systemd service 名字换了
  • Nginx canonical 入口换了
  • health/debug 路径改了

这类变更如果只改代码或只改服务器，不同步说明入口，后面几乎必然出错。

2. 部署契约变化

例如：

  • 从 GitHub-hosted runner 切到 self-hosted runner
  • deploy script 从 SSH 模式改成本机 deploy
  • workflow 名字或触发范围变了
  • secret / variable 合同变了

这类信息如果只写在 YAML 里，人会看不懂；如果只写在 README 里，机器又拿不到。

3. 项目结构变化

例如：

  • 新增 frontend/
  • static/ 迁移到新壳层
  • deploy/ 下新增 runner 模板
  • 原有路径变为 legacy / deprecated

这类变化如果不同时写进目录树和机器入口，后续 agent 最容易在错误位置开改。

4. canonical 入口变化

例如：

  • API public base URL
  • console domain
  • internal management URL
  • workflow / deploy script canonical path

入口一变，README 和 project.json 都必须一起更新。

三、什么时候最容易漏改

1. 修线上 bug 时

这时人最容易专注在：

  • 代码修好没
  • 服务起来没
  • 请求通了没

然后忘了：

  • 这次是不是已经改了部署契约
  • 这次是不是已经换了 canonical path
  • 这次是不是已经把历史路径降级了

2. 做“看起来只是文档”的任务时

比如：

  • 改 README
  • 补部署说明
  • 画结构图

如果这次文档改动实际上反映的是已经落地的 runtime 真相，那就不能只改文档，不改机器元数据。

3. 做“看起来只是机器配置”的任务时

比如：

  • 改 project.json
  • 改 workflow
  • 改 deploy script 路径

这类任务也不能只改机器入口，不改 README。

因为后续真正出错时，先看文档的人会被旧事实带偏。

四、最小执行规则

以后只要任务命中以下任意一类，就默认触发双改检查：

runtime
deploy
structure
entrypoint
domain
service
runner
workflow
health/debug contract
machine-readable project metadata

命中后必须检查两件事：

A. README.md 是否同步了

至少要确认：

  • 当前运行事实是否已经写清
  • 历史路径是否已降级或删除
  • 新的 canonical path 是否已明确

B. project.json 是否同步了

至少要确认：

  • 路径
  • URL
  • deploy mode
  • workflow
  • service
  • runner
  • scripts

是否反映当前 landed state。

五、最短检查清单

以后每次改完下面这些内容，可以直接过这张表。

项目说明入口同步检查清单

  • 是否改了 public entry / internal target / health/debug contract
  • 是否改了 runtime root / service name / deploy mode
  • 是否改了 workflow / runner / deploy script 路径
  • 是否新增了正式目录或正式文件类别
  • 是否把旧路径降级成了 legacy / emergency / deprecated
  • README.md 是否已同步这些变化
  • project.json 是否已同步这些变化
  • 两边是否仍然指向同一套当前事实

如果有一项答“是”，但最后两项没完成，那任务就不该算结束。

六、错误示范

错误示范 1

workflow 改了
README 没改

结果：

  • 自动部署确实能跑
  • 但后续人还以为旧 SSH 流程是默认路径

错误示范 2

README 改了
project.json 没改

结果：

  • 人知道当前结构
  • 机器和 agent 还按旧路径继续操作

错误示范 3

新路径写上了
旧路径没降级

结果：

  • 文档里出现多个“看起来都能用”的入口
  • 后续 agent 会自己脑补哪个才是真的

七、正确示范

正确做法应该是：

改 runtime / deploy / structure
↓
同步 README
↓
同步 project.json
↓
标记或删除旧路径
↓
推送
↓
验证真实运行

注意这里不是：

代码改完
以后再补文档

而是：

说明入口同步本身就是交付的一部分

八、一句话规则

把这条记住就够了：

README 负责让人不走错路，
project.json 负责让机器不走错路。
只要项目真相变了，这两边就必须一起变。

这不是“文档洁癖”，而是工程防错。