跳转至

与 Agent 协作

SpexCode 是一件由你的 Agent 来驱动的工具。本页解释 Agent 从哪些入口抵达它、它如何在你不必事无巨细交代的情况下学会使用它，以及你会用来引导它的各种配置、artifact(产物) 和模式。

两个入口

1. 你自己在仓库里启动的 Agent。 你自己启动一个普通的 claude 或 codex——这次启动里并没有任何 SpexCode 进程。它之所以能工作，是因为 spex init / spex materialize 把契约折叠进了 CLAUDE.md（Claude）和 AGENTS.md（Codex），而 harness(载体) 在启动时会自动发现这些文件。于是那些规则——先提交再声明、spec 驱动的流程、去哪里找文件格式——都作为普通上下文抵达，不需要任何额外参数。这是日常路径。

2. 仪表盘。 spex serve 加上看板，给你一个地方去针对 spec 节点派发（dispatch） worker Agent、观察它们的生命周期、审阅它们的 diff、并合并。底层的投递方式是一样的：仪表盘把契约 materialize 到每个 worktree 里，然后平平常常地启动 Agent。当你想要并行的多个 worker 和一个鸟瞰视角时用它；只需要身边一个 Agent 时用入口 1。

无论哪条路，人主要负责说话和审阅，由 Agent 去运行 spex 命令。

Agent 如何学会这件工具：guide

你不必把文件格式说明粘贴进每一次 prompt。契约会把 Agent 指向 spex guide——一份它在需要细节时才去读的按需手册：

  • spex guide —— 搭建工作流（安装 → 引入 → serve → 仪表盘）以及配置。
  • spex guide spec —— spec.md 的格式：frontmatter、处于契约高度的正文、以及 lint 强制执行的规则。
  • spex guide yatsu —— yatsu.md 的格式：一个节点的行为如何被度量、结果如何归档。
  • spex guide config —— spexcode.json / spexcode.local.json 的每一个键，以及下面的投递模式。

这个设计是刻意的：prompt 保持精简，而手册承载 schema，于是 Agent 在需要时恰好拉取它需要的那点细节。本站的参考一节，就是这同一份契约，从 SpexCode 自己的 spec 树逐字投影而来。

配置：两个文件

  • spexcode.json（提交进仓库）—— 可移植的、与项目相关的策略：lint 的预算与 governedRoots、布局（mainBranch、branchPrefix）、dashboard 身份、sessions.maxActive、defaultLauncher 的名字、以及 harness 选择。任何一个队友该共享的东西。
  • spexcode.local.json（被 gitignore）—— 绝不能提交的、与机器相关的取值：launcher 命令的绝对路径，以及 private 模式开关。它会逐字段地叠加在 spexcode.json 之上。

每个键见 config，或 spex guide config。

Artifact：SpexCode 会种下什么

SpexCode 始终是一位客人，它种下的每一件产物都是有戳记的、可见的、可撤销的（footprint）：

  • .spec/ —— spec 树本身；唯一属于数据、会被提交的那一样。
  • CLAUDE.md / AGENTS.md —— harness 读取的、被 materialize 出来的契约块（生成物，被 gitignore）。
  • .claude/ · .codex/ —— 钩子 shim 以及任何技能和子 Agent（生成物，被 gitignore）。
  • git 钩子 —— 一个 pre-commit 的 lint 检查和一个提交信息戳（每个 clone 各自安装，不提交）。

spex uninstall 会按戳记移除每一件生成的产物，而你的 .spec 数据和你自己的文字原封不动。

你会引导的模式

  • Harness 选择（spexcode.json 里的 harnesses）—— materialize 投递给哪些 Agent：Claude、Codex，或一个自包含的插件包。默认：全部原生 harness。见 harness-select。
  • Launcher 配置档（sessions.launchers）—— 一个具名的 { harness, cmd }，会话在创建时挑选它，并持久化在记录上，这样 resume 会复用同一条命令和同一套鉴权（一个登录包装脚本、一个 API-key launcher、一个定制脚本）。见 launcher-select。
  • Private overlay（私有覆盖）（private: true）—— 在一个你共享、但并不拥有的仓库上运行 SpexCode，且在它被跟踪的文件里不留一丝痕迹：忽略清单移到 .git/info/exclude，任何已被跟踪的 CLAUDE.md / AGENTS.md 会被标记为 skip-worktree，于是 git status 保持干净，也没有任何东西进入共享历史。它是可逆的，并且与默认模式能干净地相互抵消。见 private-overlay。

以上任何一项，你都可以通过编辑配置、让 Agent 重新 materialize 来切换——或者干脆对它说，比如：“把这个仓库设为私有，别让我的团队看到 SpexCode”，或者 “加一个叫 gpt5 的 Codex launcher，并设为默认。”