快速上手¶

有两条路。atlas 插件跑在你正在用的 agent 里，机器上什么都不用装。CLI 则把整个仓库接入完整的工作流：钩子、agent 契约、session 和 dashboard。很多人先用插件，之后再加上 CLI。

从你的 agent 开始：atlas 插件¶

atlas 插件会读整个仓库，写出第一版 spec 树，为值得配图的节点画出架构图，每张图都检查到通过，最后交回一个可以直接浏览的页面。它通过 npx 运行 SpexCode，不用安装，也不用配置。

# Claude Code
claude plugin marketplace add shuxueshuxue/spexcode-plugins
claude plugin install atlas@spexcode
# Codex
codex plugin marketplace add shuxueshuxue/spexcode-plugins
codex plugin add atlas@spexcode

然后在任意仓库里运行 /atlas。

第一次接入用的是 spex init --pure：只有 git 里的 .spec/ 纯文件，不装钩子，不改 agent 配置。它写出来的树，就是 CLI 使用的那份资产，所以之后再用 spex init --harness … 接入这个仓库时，会原样沿用。

Tencent/vConsole 的 atlas：「VConsole 核心」节点和它的生命周期图。

用这种方式画出来的开源仓库见 Flatcode。图由 archify（MIT）渲染。

PenguinHarness¶

PenguinHarness 在 agent 设置里安装同一个 skill。进入 Agents，选中 agent，点 Settings，进 Skills 标签，选 Import skill。填入下面这个来源，把准备好的对话发出去；agent 会先读完、审查，再安装：

https://github.com/shuxueshuxue/spexcode-plugins/tree/main/penguin/use-spexcode/skills/atlas

同一个对话框也可以上传 skill 的 zip。装好以后，在对话里让 agent 画出某个仓库的 spec atlas 即可。

ZCode 和 gugu 用各自的机制安装 atlas，具体见分发说明。

安装 CLI¶

SpexCode 需要 Node 22 和 git。装一次 CLI：

npm install -g spexcode

接入一个仓库¶

在仓库里，选择要接收工作流契约的 harness：

spex init --harness claude,codex,opencode,pi,zcode,claude-headless,opencode-headless,pi-headless,codex-headless

示例列出了全部内建 harness，留下你用的就行（任意一个 id 或逗号分隔的子集）。init 是增量的：它种下初始的 .spec/ 树，写入 .spec/spexcode.json，安装每个 clone 自己的 git 钩子，并把工作流说明写进你的 agent 本来就会读的文件，不会覆盖你自己写的内容。spex init --pure 只种下 spec 树和它的配置，不装钩子。

让 agent 开工前，先检查一下接入结果：

spex doctor
spex spec lint

doctor 诊断项目的健康状况。spec lint 检查 spec 和代码之间的图；本地要跑，CI 里也要跑。

启动一个普通的 agent¶

照常在仓库里启动 claude 或 codex。物化出来的 CLAUDE.md 或 AGENTS.md 会告诉它去哪找管辖代码的 spec、手册和 review 流程。现在可以这样说：

「为 src/auth 写 spec，给它们描述的函数加上锚点。」
「修改 session 过期策略，spec 和实现一起改。」
「跑 spex spec lint，解决阻断性的错误，解释剩下的提醒。」
「对这棵树运行 /atlas。」

你 review 的是最终的 diff 和合并提议，而不是一串 shell 命令的记录。

这些文件是什么¶

受 git 跟踪的数据刻意保持很少：

.spec/ 存放 spec 节点。节点的 spec.md 描述当前的意图，并写明它管辖的代码。
.spec/spexcode.json 存放可移植的项目策略，比如 harness 选择、受管辖的根目录和 session 设置。机器相关的设置放在被忽略的 .spec/spexcode.local.json 里。

物化出来的 CLAUDE.md、AGENTS.md、.claude/、.codex/ 和 git 钩子，都是每个 clone 自己派生的文件。它们看得见、删得掉，也绝不会被悄悄加进项目的受跟踪文件。spex uninstall 会删掉生成的这些东西，保留你的 spec 数据和自己写的内容。

需要时再加上共享工作台¶

只有一个 agent 时，上面这条直接的路就是完整的工作流。多个项目或多个 worker 需要一个共同的视图时，先装一次 dashboard，再启动项目后端和本机的 dashboard：

npm install -g @spexcode/spec-dashboard
spex serve
spex dashboard

后端服务当前仓库；一个 dashboard 会发现并路由这台机器上运行的每个后端。派发托管 session 前，先读与 Agent 协作。