# Building the harness around our coding agents: eight failure modes, eight pillars
**作者**: Karl Wirth
**日期**: 2026-05-26T13:49:22.000Z
**来源**: [https://x.com/wirthkarl/status/2059270673730580732](https://x.com/wirthkarl/status/2059270673730580732)
---
Teams building with AI usually end up building two products: the thing they ship, and the system around their agents that makes them useful in building the thing they ship.
We built such a system to help us ship Nimbalyst. We call it our team harness. This post is about what we learned from doing it.
## What a harness is
A harness is the durable layer around a model: instructions, tools, permissions, context, and verification.
Claude Code and Codex are harnesses in this sense. Each wraps a model with a system prompt, a tool surface, a permission model, and an execution loop. Anthropic and OpenAI own that layer.
Your team owns the next layer up: the workspace where agents do product work alongside you, with your files, tasks, diagrams, diffs, and decisions. This layer carries the knowledge your team has accumulated: how you build things, what you already decided, what is connected to what, where the agent is allowed to act, and how it checks its own work.
The line between context and harness can blur. A ticket or spec is task-specific context, but the mechanism that makes that ticket searchable, linkable, versioned, and retrievable by any agent is part of the harness.
Almost nothing in a good harness is novel. It is mostly other people’s parts assembled around your project: Claude Code, Codex, MCP, Playwright, a tracker, a diagramming tool, an editor, a test runner, your repository, your docs. The harness is the way those pieces are put together so an agent can pull the right context for a task and verify what it produced.
## 1. Context
Goal: know the project.
Failure mode this answers: the agent doesn’t know your codebase, rules, decisions, or conventions, so it solves every problem like it has never seen this project before.
Context is everything specific to our project: code, specs, design docs, tracker items, data models, past decisions, conventions, examples, and recipes.
In our harness that means:
- Code, specs, plans, and mockups live as local files in formats an agent can read and edit directly.
- Architecture diagrams live as Excalidraw files instead of screenshots trapped in a slide deck.
- Decisions are captured as tracker items, not buried in chat transcripts.
- Bug histories are searchable, so the agent can see symptoms, root cause, and previous fixes.
- Root instruction files like CLAUDE.md and AGENTS.md load at session start and point the agent at the rest.
- Path-scoped rule files load only when the agent touches a relevant directory, so React rules show up for renderer code and Swift rules show up for the iOS package.
- A skill system holds reusable instructions for recurring jobs: how we write tests, add analytics events, release a package, or debug a failing screen.
- Persistent per-user memory captures preferences and validated approaches across sessions.
An agent editing renderer code loads React rules without loading iOS rules. An agent fixing a regression finds the prior bug, the root cause, and the fix before writing code. Each session starts with the team’s accumulated decisions already in scope instead of being re-derived from the prompt.
## 2. Provenance
Goal: trace the why.
Failure mode this answers: the agent can’t traverse the links between artifacts that already exist, so the reasoning behind every change has to be re-explained or rediscovered.
Provenance is how code changes stay linked to the intent that produced them. A persistent, typed record of why each change exists, navigable from any direction: from the file, from the session, from the tracker item, from the commit. The underlying data structure is a typed graph of links between artifacts; the value is being able to ask “why is this the way it is?” and get an answer.
In our harness that means:
- A typed link graph between tracker items, plans, specs, diagrams, mockups, sessions, diffs, files, commits, and decisions.
- First-class editors for those artifacts inside the same workspace, so links resolve to actual working content.
- File-edit history tied to the session that produced it, so any file shows the conversations that wrote it.
- Tracker item types for the different kinds of intent the team carries: bug, feature, decision, plan, incident.
- Decision tracker items that record why an architectural choice was made, so a future session asking “why is this the way it is?” gets an answer instead of guesswork.
- Bug tracker items filed as we find issues, before fix code is written, so the symptom and root cause stay attached to the fix.
- An MCP surface so different agents can traverse the same graph during a session.
A bug can link to the failing screenshot, the fixing session, the diff, and the commit. A feature request can link to the plan, the mockup, the implementation sessions, and the release note. Git captures what changed. Provenance captures why and how we got there.
## 3. Capability
Goal: act and observe.
Failure mode this answers: the agent can’t act on the world or observe what it did, so it stays trapped in the text channel and asks the user to run every command and paste every output.
Capability covers tools that let an agent act on live state and verify what it did: reading logs, querying a running database, driving the UI, taking screenshots, running tests, and looping until the result is correct.
In our harness that means:
- MCP tools that read live application logs and query the running database through the app instead of unsafe direct access.
- Tools to drive the application itself: restart, reload, install extensions, hot-reload code.
- A renderer-eval tool that runs JavaScript inside the running UI to inspect DOM, state, or atoms.
- A screenshot tool that captures the rendered content of any open file.
- A Playwright-driven UI loop so an agent can interact with the running app, take a screenshot, and verify the result.
- MCP tools that wrap third-party systems the agent uses every day: GitHub, the analytics dashboard, the browser, the tracker.
- A sandboxed shell so the agent can run tests, scripts, and safe codemods, and run wrangler tail, curl, and gh instead of asking the user to paste output.
- An extension SDK so teams can write their own MCP tools and ship them inside the workspace.
After changing a React component, the agent can open the screen and check a screenshot. After changing persistence logic, it can verify that the row actually changed. An agent that can act on the world and observe the result can often close its own loop.
## 4. Workflow
Goal: reuse the arcs.
Failure mode this answers: the agent reinvents how to do every task, so the same kind of work takes a different shape every time and the basics have to be re-explained per session.
Workflow is the shape of a coding session: how it starts, how it plans, how it gets help, and how it parallelizes.
In our harness that means:
- Repo-local slash commands in .claude/commands/ for the steps we run over and over: plan, implement, review, release.
- A standard plan-then-execute arc for non-trivial work, so the agent commits to an approach before changing files.
- An investigate, design, implement progression so research and planning happen as their own steps instead of getting interleaved with code.
- Subagents for exploration, planning, and implementation that take broad searches and protect the main session’s context.
- A skill system for reusable habits like writing tests, adding analytics events, or releasing a package.
A /release-alpha command runs the version-bump, changelog, and tag steps the same way every time. A /investigate followed by /design produces a plan document the next session can pick up from, instead of starting over from a blank prompt. A workflow layer keeps each session from reinventing itself.
## 5. Restraint
Goal: stay in bounds.
Failure mode this answers: the agent does something dangerous because nothing stops it, and a capable agent without restraint does it faster than you expected.
Restraint is how we stop an agent from doing the wrong thing quickly. It covers hard rules, approval boundaries, permission scopes, tool allowlists, budget limits, and an audit trail.
In our harness that means:
- Path-scoped rules that block agents from editing specific files or directories.
- Hard rules in instruction files for things the agent must never do, like reading .env files or touching credentials, each with the past incident that taught us why.
- Per-tool permission scopes and allowlists.
- Approval flows for actions that touch shared or costly state: push to main, drop a table, hit a paid API, or run a destructive shell command.
- Workspace trust modes that separate “can edit files” from “can do anything.”
- Durable audit trail of approvals, tool calls, and file changes.
- Review surfaces that make it obvious what the agent actually changed.
In practice, that means letting an agent refactor renderer code but not release scripts, query a development database but not production, and spend tokens on test loops without touching paid third-party APIs unchecked. Restraint is the paired pillar to capability. Every new tool we give the agent needs a matched scope, or it becomes a liability the moment the agent reaches for it in the wrong context. We build the two together.
## 6. Verification
Goal: prove the fix.
Failure mode this answers: the agent hallucinates “fixed” without proof, so a confident announcement and a working change are two different things.
Verification is how an agent proves a change works before handing it back. It covers tests, type checks, fail-first reproduction of bugs, and simulated runs of the agent’s own tool calls.
In our harness that means:
- A failing-test-first discipline: write the failing test before writing the fix, so the bug has a reproduction the next agent can rerun.
- A Vitest unit suite that runs across packages and gives fast feedback on logic-level changes.
- Playwright end-to-end tests for real flows, one spec per run so a failure points at one place.
- An AI tool simulator that lets E2E specs fake AI tool calls and assert on what the agent did, without paying for a real model.
- Fast type checks baked into the loop so the agent catches drift before tests even run.
A fix for a sync bug starts with a Playwright spec that opens the broken document and asserts the body loads, then the agent fixes the code until that spec turns green. A renderer change runs the unit suite and the type check before the agent claims it is done.
If the agent cannot show the change works end-to-end, it is not done.
## 7. Visual interface
Goal: show the work.
Failure mode this answers: the agent can’t show results back to humans in a useful form, so decisions, diffs, and artifacts vanish into a wall of chat text that nobody reviews properly.
A lot of software work is visual. Markdown review, UI mockups, architecture diagrams, data models, diffs, screenshots, and sketches are part of the task input, not presentation garnish, so they belong in the workspace where the agent does the work.
The visual interface is where the agent works and where we review what it did, in the same place. Voice, interactive prompts, and walkthroughs are channels the same workspace orchestrates when text or a static visual is not the right format.
In our harness that means:
- A workspace where the mockup, the diff, and the tracker item sit side by side, so the thing being reviewed and the place the agent works are the same place.
- A markdown editor with red/green diffs for agent edits, plus diff review across every file the agent touched in a session.
- Mockup, diagram, and data-model editors as first-class file types, with image and screenshot inputs the agent can read and produce directly.
- Inline charts and rendered screenshots returned in the conversation, so numeric results and UI changes do not vanish into a text wall.
- Approval gates on risky actions like merges, deploys, and pushes to main, with the diff and linked tickets shown in one view before approval.
- Threaded discussions tied to tracker items, diffs, and decisions, so the reasoning lives next to the artifact instead of vanishing into a chat tool.
- Durable interactive prompt widgets for branching decisions, multi-field input, and approvals, so a blocking question survives navigation and restart instead of getting buried in chat.
- Walkthroughs and tooltips layered over the same UI when the agent needs to guide the user through a flow.
- A voice channel for the same session when the user wants to listen and talk instead of read and type.
- Team handoff posts when a session ends, summarizing what shipped, what is still in flight, and what risks remain.
The agent can edit a mockup, render it, compare the screenshot to the request, and then review a red/green diff before merge in the same workspace. A visual workspace keeps decisions attached to artifacts instead of burying them in chat.
## 8. Coordination
Goal: track every agent.
Failure mode this answers: the human running multiple agents in parallel loses track of who is doing what, where, and why. Work goes into a tab graveyard with no shared memory or hand-off.
One agent on one session is the starting point. Real product work needs many: a planner, an implementer, a reviewer, a researcher, a bug fixer, sometimes a dozen sessions running in parallel on different branches. Coordination is how the human running all of that keeps a single overview: who is doing what, where the hand-offs go, which sessions touched which files, and what’s still open.
In our harness that means:
- Sessions with persistent metadata (name, tags, phase) listed on a kanban board, so the team can see what every agent is working on at a glance.
- Workstreams that group related sessions on the same problem, so a bug that took five sessions to track down stays connected.
- A meta-agent so one session can spawn and supervise others: parallel reviewers across pull requests, a sibling session to verify a fix end-to-end, long-running background work that checks back in.
- Git worktrees and isolated dev instances so multiple agents can edit the same repo without stepping on each other.
- Hand-off briefs when a session ends or spawns a child, so the next session inherits files, links, and constraints instead of starting from a blank prompt.
- File-edit history tied to the session that produced it, so overlapping work is visible before it turns into a merge conflict.
A bug triage session can spawn a sibling to reproduce the issue in an isolated worktree, then a third to write the failing test, then a fourth to implement the fix on a feature branch. Each one inherits the relevant slice of the parent’s context, runs in parallel where it can, and reports back into the same workstream. With this pillar, the harness itself tracks who is doing what, where, and why.
## One bug, all eight pillars
A worked example, drawn from a real workstream we ran. The bug: after a restart, a synced tracker item showed up with an empty body. The body was there in the local database, but the server-side collaborative document had been seeded wrong, so the next session that opened the item saw nothing.
How the eight pillars showed up:
- Context. The session loaded CLAUDE.md, which pointed it at the sync architecture doc and the CollabV3 data-isolation rules. A path-scoped rule about Y.Doc seeding loaded automatically because the session touched the sync directory.
- Provenance. The bug was filed as a tracker item linked to four prior sessions that had announced “fixed” and were not. Opening the tracker showed the chain in chronological order, so the new session inherited what had been tried instead of repeating it. The eventual fix went into the tracker as a closing note linked to the commit and the Playwright spec that proved it.
- Capability. The agent queried the local database through the MCP tool, ran wrangler tail against the sync worker to watch server-side activity in real time, and read the main process log to find a try / catch that had been silently swallowing the seeding error.
- Workflow. The session ran as /investigate first, then /design produced a plan document in nimbalyst-local/plans/, then /implement executed against it.
- Restraint. The session had read access to the production sync worker but not write access. Every commit went through an approval flow, not a direct push. Restart was on the user, not the agent.
- Verification. The first deliverable was a failing Playwright spec that opened a fresh client, seeded a tracker item on the server, restarted, and asserted the body loaded. The spec failed red. The fix turned it green. Only then did the agent announce the bug was fixed.
- Visual interface. The agent posted the red-then-green test output inline, a screenshot of the tracker view showing the body restored, and a structured interactive prompt widget in the same workspace asking whether to merge or hold for further review.
- Coordination. The session was the fifth in a workstream that had spent multiple days on this bug. It read the parent workstream summary and the linked sessions before writing any code. When it finished, it filed a hand-off brief for the next session to confirm the fix held across a multi-day soak.
The bug took one focused session to close because every pillar carried its share. Any one of them missing and the same workstream would have continued.
## What changed once our harness covered all eight pillars
Once we had these pieces in place, a few things changed:
- Sessions resumed from prior context without re-prompting the same background every time.
- A single prompt could pull in the linked plan, prior session, spec, and affected files through one graph traversal.
- We could switch the same task between Claude Code and Codex without rebuilding the workflow above them.
- Permission scopes and the audit trail made it practical to let agents run through multi-step work and review after the fact.
- Agents could verify their own UI and backend changes through screenshots, log queries, and test loops before asking for review.
- The useful parts of a session stopped disappearing with the chat window because the decisions, links, and artifacts remained in the workspace.
- Parallel sessions on the same problem stayed coordinated through workstreams and the meta-agent, instead of each one rediscovering the others’ work.
- Each agent session resulted in better results more quickly
We regularly review transcripts for repeated mistakes and feed the patterns back into rules, linked context, and CLAUDE.md, so the next session does not relearn the same lesson. Decisions made during a session land in the tracker. New skills get written the moment we notice ourselves explaining the same convention twice. The harness gets better every week without anyone setting aside a “harness sprint.”
Here is what the eight pillars look like filled in for a single concrete prompt:
## Recommendations from our experience
If you are building your first harness this week
Do the boring parts first. They compound the fastest.
- Put your specs, plans, diagrams, and checklists in files the agent can read directly.
- Add one root instruction file and a small number of path-scoped rules.
- Give the agent at least three capability tools: logs, tests, and browser or screenshot access.
- Add approval gates for destructive, expensive, or shared-state actions, so capability and restraint grow together.
- Link tickets, docs, files, sessions, and commits so future runs can traverse prior work.
Doing those things already moves you from “chatting with a model” to “operating a system that gets better over time.”
Multi-agent coordination is a second-quarter problem, not a first-week one. Get one agent reliable first, then worry about how many work together.
If you already have a harness, invest in it
Treat the harness as a product your team ships to itself.
A meaningful share of your AI effort should go into improving the system around the model, not just consuming completions from the model. That means writing better rules, wiring up better MCP tools, recording better decisions, adding better examples, tightening the verification loop, and once you have more than one agent running, giving them ways to coordinate.
Pick one shape of multi-agent coordination, even a simple one: a kanban of sessions, a habit of spawning sibling sessions for verification, or a workstream tag that groups related work. Multi-agent ergonomics compound the same way single-agent rules do.
Pick a percentage of your AI effort that goes to the harness instead of feature work, protect it, and make sure every release cycle includes at least one improvement to one of the eight pillars.
Every rule, tool, example, and link makes future sessions cheaper and better.
Own your harness
You should own your harness: instructions, rules, tool definitions, links between work items, audit logs, reusable skills, and the way your sessions hand off to each other.
If you cannot read it, edit it, version it, point a different agent at it, and take it with you, it is not really yours.
This matters more as models get closer to feature parity. As they converge, the advantage moves up a layer, into your accumulated workflow, your verification loops, your linked decisions, your team memory, and the way you organize a team of agents.
Keep your harness portable across coding agents
Model competition is healthy, and you only benefit from it if your harness is portable.
When a new coding agent arrives, your team should be able to point a session at it without rebuilding the workflow above it. Claude Code today, Codex today, something else tomorrow, with the same files, same rules, same tools, same graph, and same multi-agent shape underneath.
If switching the underlying agent means rebuilding your harness, then you do not really have optionality.
Test the framework against your own failures
The eight-pillar framework is one we arrived at by collapsing every recurring failure mode we hit into the smallest set of pillars that named each one exactly once. Yours might differ. The test we use: can you name a recurring failure of your agent that does not map to a pillar? If yes, the framework is missing something. Can you collapse two pillars without bringing a failure mode back? If yes, you have one too many. Use your own incident log as the source of truth.
Nimbalyst can be one starting point for your harness
Nimbalyst is our open source workspace we use to assemble our own harness across these eight pillars. It lets us run multiple coding agents side by side, so we can point a task at Claude Code, Codex, or whatever lands next without rebuilding the layer above them. The visual workspace, the provenance graph, the capability surface, the file-based instructions, the session model, and the multi-agent coordination are all visible and inspectable.
If you want to see our actual implementation in detail, including the specific files, rules, MCP tools, slash commands, and tracker workflows we use day to day, the living catalog lives in our repository at docs/THE_HARNESS.md. The in-repo doc organizes the implementation slightly differently, but the parts are the same.
Use Nimbalyst directly or inspect it and learn from what we have done there.
## 相关链接
- [Karl Wirth](https://x.com/wirthkarl)
- [@wirthkarl](https://x.com/wirthkarl)
- [27K](https://x.com/wirthkarl/status/2059270673730580732/analytics)
- [Claude Code](https://www.anthropic.com/claude-code)
- [Codex](https://openai.com/codex/)
- [docs/THE_HARNESS.md](https://github.com/nimbalyst/nimbalyst/blob/main/docs/THE_HARNESS.md)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [9:49 PM · May 26, 2026](https://x.com/wirthkarl/status/2059270673730580732)
- [27K Views](https://x.com/wirthkarl/status/2059270673730580732/analytics)
---
*导出时间: 2026/5/27 11:09:44*
---
## 中文翻译
# 围绕编码代理构建控制线：八种失败模式与八大支柱
**作者**: Karl Wirth
**日期**: 2026-05-26T13:49:22.000Z
**来源**: [https://x.com/wirthkarl/status/2059270673730580732](https://x.com/wirthkarl/status/2059270673730580732)
---
使用 AI 构建软件的团队最终通常会构建出两个产品：一个是他们发布的产品本身，另一个是围绕在其代理周边的系统，这个系统让代理在构建产品的过程中切实发挥作用。
为了帮助我们要发布 Nimbalyst，我们就构建了这样一个系统。我们称之为团队控制线。这篇文章就是关于我们在构建过程中所学到的经验。
## 什么是控制线
控制线是围绕在模型周边的持久层：它包含指令、工具、权限、上下文以及验证机制。
从这个意义上说，Claude Code 和 Codex 都是控制线。每一个都通过系统提示词、工具接口、权限模型和执行循环包裹着一个模型。Anthropic 和 OpenAI 拥有那一层。
你的团队则拥有再往上一层：即代理与你并肩进行产品工作的“工作区”，这里存放着你们的文件、任务、图表、差异变更和决策。这一层承载了团队积累的知识：你们如何构建事物、你们已经决定了什么、什么与什么相连、代理被允许在何处行动，以及它如何自我检查。
上下文与控制线之间的界限可能会变得模糊。一个工单或规范文档是特定于任务的上下文，但能够让该工单可被搜索、可被链接、可被版本控制以及可被任何代理检索到的机制，则是控制线的一部分。
一个好的控制线中几乎没有任何东西是新颖的。它主要是围绕你的项目组装而成的其他人的现成部件：Claude Code、Codex、MCP、Playwright、追踪器、绘图工具、编辑器、测试运行器、你的代码仓库、你的文档。控制线是这些组件的组装方式，以便代理能够为任务拉取正确的上下文并验证其产出。
## 1. 上下文
**目标**：了解项目。
**所解决的失败模式**：代理不了解你的代码库、规则、决策或约定，因此它在解决每个问题时都像从未见过这个项目一样。
上下文是指特定于我们项目的一切内容：代码、规范、设计文档、追踪条目、数据模型、过去的决策、约定、示例和配方。
在我们的控制线中，这意味着：
- 代码、规范、计划和模型作为本地文件存在，采用代理可以直接读取和编辑的格式。
- 架构图以 Excalidraw 文件的形式存在，而不是被困在幻灯片中的截图。
- 决策被记录为追踪条目，而不是被埋没在聊天记录中。
- 错误历史是可搜索的，因此代理可以看到症状、根本原因和先前的修复方案。
- 像 CLAUDE.md 和 AGENTS.md 这样的根指令文件在会话开始时加载，并指引代理找到其余部分。
- 路径范围的规则文件仅在代理接触相关目录时加载，因此 React 规则会在渲染器代码中出现，而 Swift 规则会出现在 iOS 包中。
- 技能系统持有针对重复性工作的可复用指令：我们如何编写测试、如何添加分析事件、如何发布包或如何调试失效的屏幕。
- 持久的每用户记忆可捕获跨会话的偏好设置和已验证的方法。
一个正在编辑渲染器代码的代理会加载 React 规则而不会加载 iOS 规则。一个正在修复回归问题的代理会先找到先前的错误、根本原因和修复方案，然后再编写代码。每个会话开始时，团队积累的决策都已自动纳入范围，而无需从提示词中重新推导。
## 2. 出处
**目标**：追溯原因。
**所解决的失败模式**：代理无法遍历已存在的产物之间的链接，因此每次变更背后的原因都必须重新解释或重新发现。
出处是指代码变更如何与其产生的意图保持关联。这是一种持久化的、带类型的记录，说明了每次变更存在的原因，并且可以从任何方向导航：从文件、从会话、从追踪条目、从提交。底层数据结构是产物之间的带类型链接图；其价值在于能够问“为什么它是这样的？”并得到答案。
在我们的控制线中，这意味着：
- 追踪条目、计划、规范、图表、模型、会话、差异、文件、提交和决策之间存在带类型的链接图。
- 在同一工作区内针对这些产物的一等编辑器，因此链接会解析到实际的工作内容。
- 与产生它的会话相关联的文件编辑历史，因此任何文件都能显示编写它的对话内容。
- 针对团队承载的不同类型意图的追踪条目类型：错误、功能、决策、计划、事故。
- 决策追踪条目，用于记录做出某种架构选择的原因，因此未来的会话在询问“为什么它是这样的？”时会得到答案而不是猜测。
- 错误追踪条目在发现问题时即被创建，在编写修复代码之前，这样症状和根本原因就能与修复方案保持关联。
- 一个 MCP 接口，以便不同的代理可以在会话期间遍历同一个图。
一个错误可以链接到失效的截图、修复会话、差异和提交。一个功能请求可以链接到计划、模型、实现会话和发布说明。Git 捕获了变更了什么。出处捕获了我们为什么这样做以及是如何做到这一步的。
## 3. 能力
**目标**：行动与观察。
**所解决的失败模式**：代理无法对外部世界采取行动或观察它做了什么，因此它被困在文本通道中，要求用户运行每一条命令并粘贴每一次输出。
能力涵盖了允许代理对实时状态采取行动并验证其所做工作的工具：读取日志、查询正在运行的数据库、驱动 UI、截图、运行测试以及循环运行直到结果正确。
在我们的控制线中，这意味着：
- MCP 工具，它们读取实时应用日志并通过应用查询正在运行的数据库，而不是进行不安全的直接访问。
- 驱动应用本身的工具：重启、重新加载、安装扩展、热重载代码。
- 渲染器求值工具，它在正在运行的 UI 内部运行 JavaScript 以检查 DOM、状态或原子。
- 截图工具，用于捕获任何打开文件的渲染内容。
- 由 Playwright 驱动的 UI 循环，以便代理可以与正在运行的应用交互、截图并验证结果。
- 封装了代理每天使用的第三方系统的 MCP 工具：GitHub、分析仪表板、浏览器、追踪器。
- 一个沙箱化的 Shell，以便代理可以运行测试、脚本和安全的代码修改，以及运行 wrangler tail、curl 和 gh，而无需用户粘贴输出。
- 一个扩展 SDK，以便团队可以编写自己的 MCP 工具并将其部署在工作区内。
在更改 React 组件后，代理可以打开屏幕并检查截图。在更改持久化逻辑后，它可以验证行确实发生了变化。一个能够对外部世界采取行动并观察结果的代理通常可以自我闭环。
## 4. 工作流
**目标**：复用流程。
**所解决的失败模式**：代理每次都会重新发明如何执行任务，因此相同类型的工作每次都呈现不同的形态，并且基本常识必须在每次会话中重新解释。
工作流是编码会话的形态：它如何开始、如何规划、如何获取帮助以及如何并行化。
在我们的控制线中，这意味着：
- 位于 .claude/commands/ 中的代码库本地斜杠命令，用于我们要反复运行的步骤：计划、实施、审查、发布。
- 针对非平凡工作的标准“先计划后执行”流程，以便代理在更改文件之前先确定方法。
- 调查、设计、实施的递进过程，因此研究和规划作为独立的步骤进行，而不会与代码交织在一起。
- 用于探索、规划和实施的子代理，它们执行广泛搜索并保护主会话的上下文。
- 针对可复用习惯的技能系统，例如编写测试、添加分析事件或发布包。
一个 /release-alpha 命令每次都以相同的方式运行版本升级、变更日志和打标签步骤。先执行 /investigate 再执行 /design 会生成一个计划文档，下一个会话可以从中接手，而不是从空白提示词重新开始。工作流层让每个会话都不会重复造轮子。
## 5. 约束
**目标**：保持在界限内。
**所解决的失败模式**：代理做了危险的事情，因为没有东西阻止它，而一个没有约束的有能力的代理做事的速度会超出你的预期。
约束是我们阻止代理快速做错事的方法。它涵盖了硬规则、审批边界、权限范围、工具白名单、预算限制和审计跟踪。
在我们的控制线中，这意味着：
- 阻止代理编辑特定文件或目录的路径范围规则。
- 指令文件中的硬规则，规定代理绝对不能做的事情，例如读取 .env 文件或触碰凭据，每条规则都附有教会我们为什么要这样做的过往事故。
- 针对每个工具的权限范围和白名单。
- 针对触及共享或昂贵状态的操作的审批流程：推送到主分支、删除表、访问付费 API 或运行破坏性的 Shell 命令。
- 区分“可以编辑文件”和“可以做任何事”的工作区信任模式。
- 审批、工具调用和文件变更的持久审计跟踪。
- 让代理实际更改的内容一目了然的审查界面。
实际上，这意味着允许代理重构渲染器代码但不能动发布脚本，允许查询开发数据库但不能查询生产数据库，允许在测试循环上花费 Token，但不能不受限制地触碰付费的第三方 API。约束是与能力配对的支柱。我们给代理的每一个新工具都需要匹配的范围，否则当代理在错误的上下文中伸手去拿它时，它就会变成一种负债。我们是将两者一起构建的。
## 6. 验证
**目标**：证明修复有效。
**所解决的失败模式**：代理在没有证据的情况下臆造“已修复”，因此自信的声明和实际有效的变更是两回事。
验证是指代理在交回工作之前证明变更有效的方法。它涵盖了测试、类型检查、错误的“先失败”复现，以及代理对自己工具调用的模拟运行。
在我们的控制线中，这意味着：
- “先失败测试”的纪律：在编写修复代码之前先编写失败的测试，这样该错误就有一个下一个代理可以重新运行的复现方法。
- 跨包运行的 Vitest 单元测试套件，为逻辑级别的变更提供快速反馈。
- 针对真实流程的 Playwright 端到端测试，每次运行一个规范，因此失败会指向一个地方。
- AI 工具模拟器，允许端到端规范伪造 AI 工具调用并断言代理做了什么，而无需为真实模型付费。
- 集成到循环中的快速类型检查，以便代理在测试运行之前就能发现偏离。
针对同步错误的修复以一个 Playwright 规范开始，该规范打开损坏的文档并断言主体已加载，然后代理修复代码直到该规范变绿。渲染器的变更会在代理声称完成之前运行单元套件和类型检查。
如果代理不能端到端地证明变更有效，那就没有完成。
## 7. 可视化界面
**目标**：展示工作。
**所解决的失败模式**：代理无法以有用的形式向人类展示结果，因此决策、差异和产物消失在没有人会正确审查的聊天文本墙中。
许多软件工作是可视化的。Markdown 审查、UI 模型、架构图、数据模型、差异、截图和草图是任务输入的一部分，而不是展示性的点缀，所以它们属于代理进行工作的那个工作区。
可视化界面是代理工作的地方，也是我们在同一个地方审查它所做工作的场所。语音、交互式提示和演练是由同一个工作区编排的通道，适用于文本或静态视觉形式不是正确格式的场景。
在我们的控制线中，这意味着：
- 一个工作区，其中模型、差异和追踪条目并排显示，因此被审查的内容和代理工作的场所是同一个地方。
- 带有针对代理编辑的红/绿差异的 Markdown 编辑器，以及会话中代理接触过的每个文件的差异审查。
- 模型、图表和数据模型编辑器作为一等文件类型，代理可以直接读取和生成图像和截图输入。
- 在对话中返回的内联图表和渲染截图，因此数值结果和 UI 变更不会消失在文本墙中。
- 针对合并、部署和推送到主分支等风险操作的审批门，在审批前在一个视图中显示差异和关联的工单。
- 与追踪条目、差异和决策相关联的线程讨论，因此推理逻辑与产物生活在一起，而不是消失在聊天工具中。
- 用于分支决策、多字段输入和审批的持久交互式提示小部件，因此阻塞性问题可以在导航和重启后继续存在，而不会被埋没在聊天中。
- 当代理需要引导用户完成流程时，叠加在同一个 UI 上的演练和工具提示。
- 当用户想要听和说而不是读和打字时，同一会话的语音通道。
- 当会话结束时发布的团队交接帖子，总结已发布的内容、仍在进行的工作以及剩余的风险。
代理可以编辑模型、渲染它、将截图与请求进行比较，然后在同一工作区中在合并之前审查红/绿差异。可视化工作区使决策依附于产物，而不是将它们埋在聊天中。
## 8. 协调
**目标**：跟踪每一个代理。
**所解决的失败模式**：并行运行多个代理的人类失去了对谁在做什么、在哪里以及为什么的跟踪。工作进入了标签页坟场，没有共享记忆或交接。
单次会话中的一个代理是起点。真实的产品工作需要许多代理：规划者、实施者、审查者、研究者、错误修复者，有时是十几个会话在不同分支上并行运行。协调是运行所有这一切的人类如何保持单一概览的方法：谁在做什么、交接发生在哪里、哪些会话接触了哪些文件，以及什么仍然是开放的。
在我们的控制线中，这意味着：
- 具有持久元数据（名称、标签、阶段）的会话列在看板上，因此团队可以一眼看出每个代理正在做什么。
- 将同一问题上的相关会话分组的工作流，因此花费了五个会话才追踪到的错误可以保持连接。
- 一个元代理，因此一个会话可以生成并监督其他会话：跨拉取请求的并行审查者、一个验证修复端到端效果的兄弟会话、以及会定期汇报的长时间运行的后台工作。
- Git 工作树和隔离的开发实例，以便多个代理可以编辑同一个代码库而不会相互踩脚。
- 当会话结束或生成子会话时的交接简报，因此下一个会话继承文件、链接和约束，而不是从空白提示词开始。
- 与产生它的会话相关联的文件编辑历史，因此重叠的工作在变成合并冲突之前就是可见的。
一个错误分类会话可以生成一个兄弟会话，在隔离的工作树中复现问题，然后生成第三个会话来编写失败的测试，再生成第四个会话在功能分支上实施修复。每个会话都继承父上下文的相关切片，在可能的地方并行运行，并向同一个工作流汇报。有了这根支柱，控制线本身就会跟踪谁在做什么、在哪里以及为什么。
## 一个错误，八大支柱
一个取自我们运行的真实工作流的实战示例。这个错误：重启后，一个同步的追踪条目显示为空白主体。主体存在于本地数据库中，但服务器端的协作文档播种错误，因此接下来打开该条目的会话什么也没看到。
八大支柱是如何体现的：
- **上下文**。会话加载了 CLAUDE.md，它指向同步架构文档和 CollabV3 数据隔离规则。关于 Y.Doc 播种的路径范围规则自动加载，因为会话触碰了同步目录。
- **出处**。该错误被记录为一个追踪条目，链接到四个先前曾宣布“已修复”但并未修复的会话。