Skip to content

快速上手

SpexCode 围绕你已经在使用的 Agent 工作流展开。安装一个命令，在已有 Git 仓库中引入，然后继续用自然语言和 Agent 交流。Agent 会读取仓库里自动发现的契约，替你执行具体的 spex 操作。

安装 CLI

SpexCode 需要 Node 22 与 Git。全局安装一次：

npm install -g spexcode

在仓库中引入

在仓库内显式选择哪些 harness 接收工作流契约：

spex init --harness claude,codex

填入你实际使用的 ID；--harness 接受一个或多个逗号分隔的 harness ID，已有的 harnesses 设置也能满足这个要求。init 是追加式的：它播种初始 .spec/ 数据、写入 spexcode.json、安装每份 clone 自己的 Git hook，并 materialize 生成的 harness 产物，不会覆盖你已有的文字。

让 Agent 工作前，先确认引入结果：

spex doctor
spex spec lint

doctor 检查契约是否真正抵达所选 harness；spec lint 报告图谱的结构健康和引入待办，既应本地运行，也应放进 CI。

启动普通 Agent

像平时一样在仓库里启动 claude 或 codex。materialize 出来的 CLAUDE.md 或 AGENTS.md 会告诉它去哪里找治理 spec、手册和必要的审阅流程。现在你可以直接这样说：

  • 「在这里引入 SpexCode，并为 src/auth 抽取 spec。」
  • 「修改会话过期策略，让 spec 和实现一起更新。」
  • 「运行 spex spec lint，解决阻断错误并解释剩余警告。」
  • 「通过真实产品复现这个 bug，先归档 fail eval，修好后再归档同一场景的 pass。」

你审阅的是结果里的 diff 和合并提议，而不是一串 shell 命令。

这些文件分别是什么

被跟踪的数据刻意保持很小：

  • .spec/保存 spec 节点。节点的 spec.md 描述当前意图，并指向它治理的代码。
  • spexcode.json保存可移植的项目策略，例如 harness 选择、图谱根目录和会话设置。

materialize 出来的 CLAUDE.md、AGENTS.md、.claude/、.codex/ 和 Git hook 都是每份 clone 的派生产物。它们可见、可撤销，但不会被悄悄加入项目的已跟踪文件。spex uninstall 会移除生成的足迹，同时保留你的 spec 数据和文字。

只在需要时加入共享工作台

只有一个 Agent 时，上述直接路径就是完整工作流。当多个项目或多个 worker 需要一个共同视图时，再启动项目后端和宿主仪表盘：

spex serve
spex dashboard

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