Skip to content

与 Agent 协作

SpexCode 为编码 Agent 提供一份持久工作流，但不会替换你和 Agent 交流的方式。日常路径是在仓库里启动普通 harness；当工作确实需要隔离、并行或共享审阅面时，托管会话与仪表盘使用同一份契约。

先直接使用，管理能力按需加入

直接启动的 Agent 是默认路径。 运行 spex init --harness claude,codex 后，在仓库中启动你选择的 harness。它自动发现的普通文件会带来契约：改代码前读治理 spec，将代码和它所证明的意图一起提交，度量重要行为，并把合并提议交给人。

托管会话用于并行工作。 spex serve 为一个仓库运行后端；spex dashboard 打开一个宿主级工作台，发现当前机器上运行的后端，把 Agent 派发到隔离 worktree，并展示会话、diff、eval、issue 与实时终端。仪表盘消费的仍是同一份文件和 CLI 状态；它不是另一套工作流，也不是另一个数据库。

让 Agent 在需要时拉取细节

materialize 出来的契约会把 Agent 指向 spex guide，而不是把所有 schema 塞进每一次 prompt：

  • spex guide 说明安装和引入工作流。
  • spex guide spec 说明 spec.md 以及它拥有的意图。
  • spex guide eval 说明场景、证据和归档的读数。
  • spex guide settings 说明可移植与机器本地的配置。

这样普通 prompt 保持简短，而任务需要时完整手册随手可读。参考逐字投影 SpexCode 自己的 spec 树；指南则面向读者解释如何使用这些契约。

分清可移植和本地配置

  • spexcode.json是提交进仓库的项目策略：harness、图谱根目录、源头分支布局、会话上限和仪表盘身份。
  • spexcode.local.json是被忽略的机器配置，例如本地 launcher 命令路径或 TLS 文件路径。它覆盖可移植文件，却不会把本地细节变成项目历史。

这份分离让团队共享一套工作流，而不共享凭证、绝对路径或运行残留。

审阅是一次真实交接

托管工作中，每个 Agent 都有自己的 worktree 和分支。它读取相关 spec，完成经过验证的改动，提交代码和更新后的意图，再声明可审阅的提议。人或监督 Agent 审阅这个已提交的 head，并执行合并。worker 不会自行合并。

直接使用 Agent 时，即使没有仪表盘，形状也相同：提出变更，检查 diff 与证明，再决定是否落地。SpexCode 让证据与所有权可见；它不取代人的决定。

SpexCode 会留下什么

SpexCode 是仓库里的客人。.spec/ 与 spexcode.json 是你选择提交的、可读的数据。生成的发现文件、hook shim 和每份 clone 的 Git hook 都有来源标记、可见且可撤销。spex uninstall 只移除 SpexCode 生成的内容，保留你自己的文字与已跟踪意图。