一个项目最危险的时刻，不是编译失败，而是所有人都说“能跑”。
Agent 交付了一个功能。你打开 README，有文档；你打开代码，结构和文档对不上； 你问“为什么这里要这样设计”，答案只存在于几周前的聊天记录里。
最后验收方式变成了：点一遍按钮，功能没报错，合并。
这不是接手，这是试用。
一、“能跑”和“接得住”是两件事
AI 很擅长让代码跑起来。
它会补类型、加兜底、处理边界、写测试，甚至把看起来不相关的调用方一起改掉。 从“功能可用”的角度看，这很高效。
但“接得住”是另一回事。它至少包括：
- 知道系统由哪些模块组成；
- 知道一个功能对应哪些代码；
- 知道模块之间为什么这样依赖；
- 知道最近的改动为什么发生；
- 知道出问题时从哪里查；
- 知道怎么安全地改，而不把别的地方弄坏。
这些不是运行时的属性，而是理解的属性。
AI 可以在一小时内写出一个能跑的功能，但一个新人可能需要一周才能建立足够的 理解，去安全地修改它。这个差距，就是“接不住”。
二、为什么文档救不了？
很多 AI 项目不是没有文档。问题是文档和代码是两套东西。
1. 文档是“生成”的，不是“校验”的
AI 可以生成很漂亮的 README、架构说明、模块介绍。读起来头头是道，但它不一定 和代码里的真实结构一致。
更危险的是：它看起来很完整，给你一种“我已经懂了”的错觉。
2. 文档解释“做了什么”，不解释“为什么”
一段说明可以告诉你“这个服务负责导出”，但不会告诉你：
- 为什么导出要独立成服务？
- 为什么它依赖权限模块？
- 为什么没有复用已有的下载逻辑？
- 哪些边界是刻意设计的，哪些是临时妥协？
没有“为什么”，文档就只是代码的自然语言复述。代码一变，它立刻过期。
3. 文档没有和代码绑定的位置
“订单模块”到底对应哪个目录？“取消订单”到底是哪个函数？文档里可能只有一个 名字，没有文件、符号和依赖关系。
人和 Agent 都只能靠猜。
4. 文档更新没有触发点
代码改完，测试会跑，CI 会过；文档不会自动报错。于是它慢慢变成历史遗迹。
有文档但对不上，比没有文档更危险。 因为它会让你在错误的地图上做决定。
三、“接不住”通常有三种样子
1. 没有地图
不知道系统分几块，不知道新功能该放哪，只能全局搜索。
2. 地图是错的
文档说有 A、B 两个模块，代码里已经变成 A、C、D；文档说订单依赖领域层，代码里 已经直接调了支付。
3. 没有历史
代码能看出“现在是什么”，看不出“为什么变成这样”。上一个版本为什么被否决， 某个依赖是什么时候加的，没人知道。
这三种情况叠加，最后就只能靠“点按钮”验收：功能对了就合并，结构问题以后再说。
四、接手需要的是“可校验的地图”
Jin 不生成完整文档，也不试图替代 README、ADR 或 runbook。
它维护的是一份可校验的结构地图：
L0：系统、包、模块、分层、外部依赖、约束；L1：每个模块的实体、位置、字段、方法、关系。
这份地图有几个特点：
- 实体有稳定 ID；
- 实体有
location.file和location.symbol； - 模块有路径、职责、依赖和公开实体；
- 提案有版本、目标快照、范围和验收标准；
- 应用有历史，决策有记录；
- 漂移检查会对照真实代码，报告缺失或未登记的符号。
它不能解释所有业务语义，但能回答接手时最常问的几个问题：
- 这个系统有哪些模块？
- 这个功能大概在哪个模块？
- 这个实体在哪个文件、哪个符号？
- 它依赖谁，谁依赖它？
- 最近几次结构改动是什么？
- 架构和代码现在还对得上吗？
五、Jin 在交接里怎么用？
新人接手
打开架构面板，先看 L0 和 L1，不需要一上来读完整仓库。选中实体，看位置、字段、 方法和关系；再看提案历史，知道最近的改动为什么发生。
代码 review
先看架构 diff 和变更文件，再看关键实现。至少知道这次改动在结构上意味着什么。
排查问题
从实体位置定位代码，从依赖关系判断影响范围，从漂移检查判断架构声明和代码有没有 脱节。
Agent 协作
Agent 可以先调用 jin_arch_read 拿到结构，再决定读哪些文件；而不是一上来把
整个仓库塞进上下文。
这些都不能替代人的理解，但能显著降低“从零开始猜”的成本。
六、一份 AI 代码接手清单
如果你不确定一个 AI 项目能不能接手，可以问自己六个问题：
- 我能不能说出它的主要模块和职责？
- 我能不能找到核心公开实体对应的代码位置？
- 架构说明和真实代码对得上吗？上次检查是什么时候？
- 我能不能解释最近三次结构改动的原因？
- 我能不能跑测试，并知道失败时从哪里查？
- 我能不能安全地改一个核心功能，而不担心碰坏别的地方？
如果第 1、2、3 题答不上来，说明你缺的是地图。 如果第 4 题答不上来，说明你缺的是历史。 如果第 5、6 题答不上来，说明你缺的是工程保障。
Jin 主要补第 1–4 题：地图和历史；第 5、6 题仍然要靠测试、CI、监控和团队流程。
七、边界
要说清楚：
- Jin 的架构是声明级的，不是完整语义模型；
- 它不生成完整文档，也不替代 README、ADR、runbook；
- 它不能解释所有业务规则；
- 架构声明可能过时，所以需要漂移检查和持续维护；
- 审批不替代代码 review、测试和 CI；
- 项目还很早期，安装包未签名，自动更新关闭。
但至少，它让“接手”不再只靠聊天记录和口头传承。
验收不是点按钮。接手，是能理解、能修改、能安全地改。
项目地址：
v2.0.32-jin.1 下载：
中文完整指南：
Jin 是 OpenCode 的社区分支，不是 OpenCode 官方产品。
