我以前比较容易把“AI Coding 经验沉淀”理解成一件偏轻的事：把 Prompt 写清楚，把目录放整齐，把自己的工作流跑顺，剩下的无非是再补几条规则。
这次重新看 Maglev 仓库时，我被几个很具体的对象重新提醒了一遍：init、update --dry-run、项目里的 .agents/ 和 .maglev/，还有分发脚本。这些对象放在一起时，我才更明确地意识到，个人用得顺的 AI Coding 经验，离团队能稳定复用的组织规则，中间隔着一整层以前很容易被我忽略的东西。
因为一旦目标变成“让别人也能接住这套经验”，我关注的重点就会落到另一层：它有没有公共入口、目录约定、更新方式、版本同步、文档和最小安装路径，能不能以一种不同项目都能低摩擦接入的形式存在。
这也是为什么我现在更愿意把“组织规则”理解成一种可分发资产，而不是几段值得转发的经验。
系列导航
- 你现在在哪：这篇是 AI 研发治理主线里更具体的一篇，重点不是“为什么需要治理”，而是“个人经验为什么难以直接升级成组织规则”。
- 建议先读：为什么 AI Coding 越强，越需要治理、写给技术负责人：怎么理解 AI 研发治理的接入与落地。
- 继续往后读：写给企业：为什么要把 AI Coding 变成组织能力、Maglev 解决什么问题。
我为什么会被 Maglev 仓库重新提醒这件事
如果只在内部讨论“AI Coding 经验怎么沉淀”，人很容易停留在抽象层：
- 要不要统一规则
- 要不要沉淀宪章
- 要不要做覆盖率检查
- 要不要给不同 Agent 共用一套约束
这些判断本身没错，但很容易停在判断层。
直到我回头看 Maglev 仓库，才发现很多以前说得抽象的东西，其实都已经以具体对象的形式摆在那里了。
对这篇文章来说，真正必要的支点其实只有三类：
- 用户入口：README 和
packages/maglev-cli/暴露出来的init/update --dry-run - 项目落点：初始化后会进入项目的
.agents/、.maglev/、specs/、docs/、issues/ - 分发链路：
scripts/maglev_release.py和release.version.json
光是这三类对象，就已经足够让我重新校准一个判断：
当一套经验想从“我自己会用”升级到“别人也能装、也能看、也能更”，它就得从脑中的方法，变成仓库里的对象。
我这里故意不再展开更多目录、更多提交，因为那些内容本身并不改变这篇文章的论证。真正改变论证的，是这套经验已经开始回答“别人怎么接入、怎么落地、怎么更新”。
只看一个命令，就能看出“个人经验”和“组织规则”的差别
Maglev README 里最短的用户入口非常直接：
npx @idea-maglev/maglev-cli init如果已经接入过，还可以先预览更新：
npx @idea-maglev/maglev-cli update --dry-run这两个入口看上去很普通，但它们会逼人面对一个很具体的问题：
个人经验只需要“我知道怎么做”；而一旦要做成团队可接入的规则，就得回答“别人怎么装进去”。
因为一旦你把它做成一个真正要给别人用的入口，你马上就得面对很多个人实践里不会遇到的问题：
- 第一次安装到底在项目里落什么目录
- 已有项目怎么更新，而不是每次全量重装
- 哪些文件是运行资产，哪些是构建产物
- 出问题时用户应该去看哪份文档，而不是来问经验持有者
quickstart 里已经把这些事情讲得很明确了。它不是只说“先装一下”，而是直接把安装后的结果列出来：
.agents/.maglev/specs/docs/issues/tests/
这件事对我触动很大。因为它说明，团队规则一旦要进入项目，就不能只停留在“有一份约束文档”。它还得知道自己会在项目里留下什么痕迹。
真正难的不是规则写出来，而是它怎么进入项目
个人经验最舒服的地方，在于你不必处理“接入”这件事。
你可以默认：
- 你的目录已经这样放了
- 你的工具就认这种结构
- 你的上下文你自己知道
- 你的规则只需要你自己遵守
但组织规则不行。
只要它要进入别人的项目，接入就会立刻变成第一道门槛。
Maglev 的初始化手册里，其实已经把这层问题写得很实在：init 不只是“开始使用”，而是要做几件明确的事情：
- 获取发行清单
manifest.json - 把运行资产落到当前项目
- 创建基础目录骨架
- 写入
.maglev/config.json - 写入
.maglev/sync_state.json
这比“请参考这份最佳实践”重很多，但也更接近真实落地时会遇到的问题。
因为团队复用要解决的不是理解问题，而是落地问题：
这套规则到底怎么进项目，怎么被记录，怎么被后续更新识别出来。
如果这些没有做，经验再好，也很容易停留在“那个人懂”。
仓库里最能说明问题的，不是理论，而是分发链路
这次我感受最深的一点，其实来自 scripts/maglev_release.py 这类分发相关文件。
如果只是个人工作流，你根本不需要想“分发”这件事。你自己会用就够了。
但一旦要变成组织规则，分发链路就会暴露出另一种难度：
- 哪些资产可以公开带出去
- 哪些内部对象不能跟着发行物一起下发
- catalog 里哪些条目是
user_visible，哪些不该公开 - 发布给用户的 npm 包，应该只包含哪些文件
这些问题听起来不像“AI Coding 经验”，但它们恰恰决定了一套经验能不能被团队接住。
比如 CLI README 已经把目录分得很明确：
runtime-src/是源文件，应该改这里dist/是构建产物，不应该手工直改
再往下看发布脚本，又会看到更具体的一层：
- 它会从
.agents/private-catalog.yaml投影出一份 public catalog - 只保留
user_visible的对象 - 会把运行资产构建到
.maglev_build/ - 再同步到
packages/maglev-cli/dist/给 npm 包使用
这就不是“写几条规则”了，而是在处理另一件更组织化的事：
一套规则怎样从仓库内部事实，被整理成别人可以安全安装的公共发行物。
个人实践常常可以绕过这个问题，但团队规则通常绕不过去。
所以我现在会先把组织规则当成“公共资产”来看
如果只把这件事理解成经验沉淀，很容易写出很多“应该怎样”的内容，但这些内容并不会自动进入项目。
对我来说，仓库里这些对象最大的作用，就是把这个判断落成了四个可检查的问题。
1. 有没有公共入口
如果别人还得先来问你“现在该看哪份规则”，那它大概率还不是一个可复用的团队规则。README、CLI、目录约定这类入口，至少要让别人能自己找到开始的位置。
2. 有没有项目内落点
规则不能只活在说明文档里，它还得能进入项目，并留下稳定落点。像 .agents/、.maglev/、specs/ 这些目录，就是我现在会优先去找的痕迹。
3. 有没有更新机制
update --dry-run 这种入口之所以重要，不是因为命令本身高级，而是因为它在回答：旧项目怎么同步到新规则。
4. 有没有分发边界
从 public catalog 投影，到 npm 包只带公开文件，这些都在说明：一套规则如果真要被分发，就得先知道哪些东西该带出去，哪些不该带出去。
这也是为什么“再写几段 Prompt”解决不了这个问题
Prompt 当然重要。
但我现在更倾向于把它看成个人效率资产，它主要解决的是：
- 我怎样和这个 Agent 配合更顺
- 我怎样把这次任务说清楚
- 我怎样减少来回沟通成本
而团队规则要处理的是另一层问题：
- 不同人能不能读同一份规则
- 不同项目能不能接同一份最小约束
- 不同工具能不能尽量共享同一层公共资产
- 规则更新以后，存量项目怎么知道该跟进
这些问题并不是靠多写几段 Prompt 就会自然解决的。它们更接近资产治理。
也正因为如此，我现在会更谨慎地说“这套个人经验已经可以推广给团队了”。
如果没有公共入口、项目落点、更新机制和分发边界，再好的经验也很容易变成一份大家都说有价值、但没人真正接进去的文档。
总结
这篇文章写到最后，我给自己的结论其实很简单：下次再看到一套“个人用起来很顺”的 AI Coding 方法时，我不会急着判断它能不能推广给团队，而会先看四件更具体的事：
- 别人能不能自己找到入口
- 它会不会在项目里留下稳定落点
- 旧项目有没有更新路径
- 分发出去的边界是不是清楚
如果这四件事还答不清，我现在更愿意把它当成一套成熟的个人方法，而不是一套已经成形的团队规则。
这也是 Maglev 仓库这次重新提醒我的地方：个人经验和组织规则之间，并不是“一键复制”的关系。前者更像方法，后者更像资产；方法只要你自己会用就能成立，资产则必须能被别人找到、装进去、同步起来，并在不同项目里持续活下去。