nerviz

↑ ↓ 移动 · Enter 打开 · Esc 关闭点按一个结果

← 从哪里开始
已有项目 · Spring Boot 4.0 及以上 · /arch-adopt

在别处诞生的项目，也能装上 harness。

在项目内的会话中，/arch-adopt 把这套 .claude/ 安装进从未由 Nerviz 生成的项目，或为落后的项目带来新版本。它拒绝不干净的工作区，为写入的每个文件记录哈希，并把 diff 留给你审阅。

§ 它做什么

一个操作，两种起点

这不是两条命令。区分两者的是溯源标记；其余流程相同。skill 负责决定：用哪个来源、哪个蓝图、是否可以安全写入。几乎每一个字节随后都由确定性的 export 模式根据数据清单写入。

起点发生什么skill 如何判断
从未由 /init-project 生成、没有这种形态 .claude/ 的项目安装没有 .claude/.arch-provenance.json
已有这套 .claude/ 但版本落后的项目升级标记存在，且指向更早的 ref
# the example in docs/en/10-arch-adopt.md; the ref, counts and file names are illustrative
› /arch-adopt --ref latest-tag --blueprint hexagonal

✅ updated — blueprint hexagonal, ref v0.9.3 (a1b2c3d)

Source ....... codeload.github.com, fetched at 14:22
Files ........ 136 written · 118 unchanged · 4 overwritten
Warnings ..... none
Schema ....... exit 0
Provenance ... ⚠️ 2 files edited locally since the stamp:
               .claude/rules/persistence.md
               .claude/settings.json
Bounded ctx .. already declared
Migrations ... 1 below, to paste when you choose

Review: git diff · Undo: git checkout -- .claude
Next: /arch-doctor for the full diagnosis

输出取自 nerviz 文档中的示例。ref、数量和文件名仅作示意。

§ 三项保证

这套流程承诺什么

  • 拒绝不干净的工作区。不是 git 仓库，或 git status --porcelain 非空：就停止。升级会覆盖文件，所以 git diff 是你审阅的方式，git checkout 是你撤销的方式。它会说明该运行什么，并且不会替你提交。
  • source 的四个值，没有一个是凭记忆写的。base_url、git_url、auth_env 和 default_ref 是 extensions.json 中的数据。auth_env 只写环境变量的名字，从不携带它的值；公开仓库不需要凭据。
  • 溯源是写下来的，不是承诺出来的。标记记录 ref、sha、蓝图，以及写入的每个文件的哈希。/arch-doctor 把这些哈希与磁盘对比，在下次升级覆盖之前点名你手工修改过的文件。
§ 带走什么

哪些进入项目，哪些留在外面

这一切都是 extensions.json 的 export 块：数据，而不是文字说明。ArchHook.java schema 会对照磁盘检查清单，所以既不在 include 也不在 exclude 里的 skill 或智能体，会按名字报错。

分组内容
Hook 与数据ArchHook.java、ArchHook.jar（按字节复制）和 extensions.json
settings.json按 project-bootstrap 的模板整体覆盖：项目自己的 hook 和 permissions 会消失，并出现在 git diff 中
规则每条规范，其 paths 按当前蓝图的包重写
Skill 与智能体开发用的 skill 和执行器智能体。init-project、project-bootstrap 和 project-initializer 留在外面：它们只在项目存在之前有用
蓝图只带当前蓝图，绝不带目录；没有它，下次升级就无法解析标记中记录的 id
审计轨迹.claude/audit-usage/ 被创建（这会打开轨迹），并随项目纳入版本管理；docs/lessons-learned/ 是本地的，不纳入版本管理

已有自己 .claude/ 的项目，路径与清单不同的内容会保留。请先运行 --dry-run：它列出将被覆盖的内容，并且不写入任何东西。

§ 什么会让它停止

四种情形，下限是其中之一

/arch-adopt 不评判项目的代码。它只决定写入 .claude/ 是否安全。

情形步骤结果
不是 git 仓库，或 git status --porcelain 非空1停止；不写入任何内容
没有凭据的抓取，或 HTTP 错误3停止；--fail 把 404 变成错误，而不是一个损坏的 tarball
Spring Boot 低于 doctor.platform.min_line（目前是 4.0）5export 在写入任何字节之前以 2 退出；没有 --force。向上的路是 /platform-upgrade
export 之后 schema 没有以 0 退出6文件已经写入；报告先显示失败，步骤 7 到 9 不再运行

下限只是下限：没有上限。Spring Boot 5.x 可以通过，而为 4 线编写的规范可能与它产生偏差，且不会有任何警告。隐藏版本号的构建（例如企业级 parent 或外部 BOM）也能通过。

低于下限？/platform-upgrade 指南 →

§ 当约定发生变化

一段可粘贴的提示词，绝不是一次编辑

当规范的变化会让此前生成的代码落后时，这个变化以 extensions.json 的 migrations 块中的一条记录发布。升级时，skill 会显示项目尚未见过、且适用于其蓝图的每一条记录：一段说明，加一段可粘贴到项目里 Claude Code 中的提示词。它绝不会执行。项目自己那份 extensions.json 就是它已看过什么的记录，所以在某条记录之后生成的项目永远不会看到它。

§ 运行之后

审阅、撤销、诊断

它让工作树带着可供审阅的 diff，并说明如何撤销。之后由 /arch-doctor 给出完整诊断。它发现的内容会变成报告中的一行；只有 doctor.gate.labels 中的行才会让 CI 失败。

  • 生成项目。没有 pom.xml 或 build.gradle 时，你要的是 /init-project。
  • 编写业务代码，或触碰 src/。
  • 提交。
  • 标记已记录蓝图时再次询问蓝图：升级时，蓝图是项目的既定事实。
# review
git diff
# undo
git checkout -- .claude && git clean -fd .claude
# then the full diagnosis
› /arch-doctor