harness workspace 详细设计

把主流程里的 workspace 拆成可交接的四类表面：运行时、知识沉淀、issue 闭环和运行工件。

agents-monorepo

运行时、工具调用、服务编排和自动化脚本。

Obsidian

长期知识、reading map、memory 与回桥证据。

Linear

issue 状态、验收条件、阻塞项和人工确认。

memory

跨轮 handoff、失败样本、下一步判断和停止条件。

任务 API / worker

把意图拆成可执行任务单元，并承接服务侧执行。

状态账本 / artifacts

记录 run_id、输入、产物、失败标签、replay hint 和验收证据。

配置与权限边界

区分只读上下文、可逆本地改动、外部副作用和必须确认动作。

输出表面

给 human 的验收报告，给 agent 的结构化状态与下一轮接手包。

Superpowers 工作流全景图

14 个核心 skills · 三层机制 · 主流程 + 旁路技能

🎯 入口

Using Superpowers

调度器：检查每条消息是否有匹配技能

哪怕只有 1% 的可能性，也必须调用技能

方式 A：执行计划

Executing Plans

独立/顺序执行

• 先批判性读计划
• 按任务逐个执行
• 遇 blocker 立即停下
• 保留更多人工检查点

适合：无子代理或想更稳地推进

🔍 系统化调试

Systematic Debugging

4 阶段循环：

1. 观察 — 收集症状和证据
2. 假设 — 基于证据推断根因
3. 验证 — 设计实验验证假设
4. 修复 — TDD 修复 + 回归测试

触发：遇到 bug、测试失败、异常行为

⚡ 并行代理调度

Dispatching Parallel Agents

• 识别独立问题域
• 每个问题派一个代理
• 并行执行，互不干扰
• 汇总结果，检查冲突

触发：2+ 个独立任务/故障 禁用：问题相关、共享状态

✍️ 编写技能

Writing Skills

用 TDD 方法创建新技能：

• 先写技能的验证标准
• 再写技能内容
• 测试技能是否按预期工作

触发：创建/编辑自定义技能

📋 技能使用原则

Using Superpowers

• 不是普通技能，而是总调度器
• 刚性技能（TDD、调试）：严格遵循
• 优先级：流程技能 > 实现技能
• 哪怕 1% 可能适用，也要先查 skill

先查 skill，再行动

2️⃣ 隔离工作区

Git Worktrees

• 检测/创建工作树目录
• 验证 .gitignore
• 安装依赖
• 跑基线测试

原则：不影响主分支

3️⃣ 编写计划

Writing Plans

• 拆成 2-5 分钟小任务
• 每个任务完整 TDD 循环
• 精确文件路径
• 完整代码片段

原则：DRY · YAGNI · TDD

方式 B：子代理驱动

Subagent-Driven Dev

同一会话

• 每任务派独立子代理
• 双重审查：
  • ① 规格合规审查
  • ② 代码质量审查
• 审查不过 → 修复 → 重审

适合：快速迭代

5️⃣ 测试驱动开发

TDD

铁律：没有失败测试就不写代码

🔴 RED → 写失败测试 🟢 GREEN → 最小代码通过 🔵 REFACTOR → 清理

违反？删除代码，重来。

请求审查

Requesting Code Review

• 适合：任务完成、重大功能、merge 前
• 获取 git diff / git range
• 派发 reviewer 检查实现质量
• 按严重度分级： Critical / Important / Minor

接收审查

Receiving Code Review

禁止： ❌ "你说得对！" ❌ "好建议！"

正确做法： ✅ 技术验证后直接修 ✅ 不对就推回（附理由） ✅ 不确定就问

原则：技术正确 > 社交客套

✅ 完成前验证

Verification

铁律：没跑验证就不能说完成

• 跑测试 → 看输出
• 跑构建 → 看退出码
• 逐项核对需求

❌ "应该没问题" ✅ 证据 → 结论

7️⃣ 完成分支

Finishing Branch

4 个选项：

1. 合并到 main
2. 创建 PR
3. 保持现状
4. 丢弃

清理工作树

1️⃣ 头脑风暴

Brainstorming

• 逐个提问理解需求
• 提出 2-3 种方案
• 获得用户批准
• 写入设计文档

硬门禁：设计未批准前不写代码

新版理解

14 个核心 skills ≠ 只有 7 步流程

更稳的心智模型：

• 启动注入层
• 流程技能层
• 质量兜底层

启动注入层

• SessionStart hook 或原生 skill discovery
• 把 using-superpowers 注入到会话入口
• 先约束 agent，再谈具体技能

流程技能层

brainstorming -> worktree -> writing-plans -> execution -> finish

作用：把开发切成阶段，而不是让 agent 直接写代码

质量兜底层

• TDD
• systematic-debugging
• code review
• verification-before-completion

作用：阻止猜测、跳步和虚假完成

最近关键更新（v5.0.4-v5.0.7）

• inline self-review 替代旧 spec/plan review loop
• 恢复 subagent-driven-development / executing-plans 二选一
• 补齐 Codex / Copilot CLI / OpenCode 适配
• subagent-driven-development 强调两段审查：先 spec，后 quality

Why Your “AI-First” Strategy Is Probably Wrong

这篇文章的真正主张：值得学的不是“99% 代码由 AI 编写”这句口号，而是它背后的系统重构：把 可见性、验证、回滚、分诊、自愈 做成 agent 能稳定运转的交付基础设施。

一句话纠偏

AI-first 不是给旧流程加 Copilot。

它是把 流程、架构、组织 都改写成：AI 是 primary builder，人负责方向、判断和风险。

AI-assisted

• 原有 sprint / Jira / QA / standup 不变
• AI 只在局部提效
• 效率提升通常停在 10% 到 20%

作者真正批评的对象

• vibe coding 到能跑就 commit
• 旧 loop 不变，只把 AI 塞进去
• 提速的是写代码，不是交付系统

Harness engineering 视角

主任务不再是亲手写代码，而是让 agent 能稳定做有用工作。

出问题时别说“再 prompt 一次”，而要追问：

• 缺了什么能力
• 缺了什么约束
• 缺了什么验证 / 反馈

PM 瓶颈

构思和评审还要几周，但 agent 两小时就能做出一版。

当 build time 从月级掉到小时级，长 planning cycle 就变成新的约束。

QA 瓶颈

agent 两小时写完，人工 QA 却要三天补 corner cases。

如果验证速度跟不上实现速度，只是把瓶颈往下游平移。

Headcount 瓶颈

25 人团队不可能靠加人追上 100 倍规模的对手。

作者的结论不是扩编，而是重写系统。

约束公式

设计、实现、测试三段里，只要有任意一段仍是人工长周期，整条 pipeline 就会被它锁死。

Monorepo

把分散在多仓、多服务里的上下文拉回一个 agent 看得见的整体。

目标不是人更方便，而是 AI 能看全局、改全局、测全局。

Structured Signals

CloudWatch、日志、指标、告警都要结构化、可查询。

AI 读不懂运行时信号，就不可能可靠诊断。

Deterministic Pipeline

无手工特批、无模糊 gate。

只有可预测的 CI/CD，agent 才能根据失败形态稳定推理下一步。

Tool Per Phase

每个工具负责一个阶段。

不要期待单个工具包打天下，关键是让它们组成可验证闭环。

统一系统的真正价值

让代码、测试、部署、观测都处于 agent 可 inspect / validate / modify 的视野里。

作者把这叫做从 fragmented 变成 legible。

1. Architect 定义任务

结构化 prompt = 代码上下文 + 目标 + 约束。

人类先定方向与边界。

2. Agent 实施

分解任务、写代码、补测试。

AI 不是只产出 diff，而是先给出 plan 再执行。

3. AI Review

3 路 Claude 并行 gate：

• 代码质量
• 安全
• 依赖风险

它们是 gate，不是可忽略建议。

4. CI Validate

类型检查、lint、单测、集成测试、Playwright E2E、环境一致性检查。

没有可选项。

5. Merge Queue

Graphite 负责 rebase、重跑 CI、只在 green 时合并。

高吞吐下也尽量避免分支漂移。

6. Six-Phase Deploy

Verify CI -> Build & Deploy Dev -> Test Dev -> Deploy Prod -> Test Prod -> Release

dev / prod 都有测试。

7. Flag Rollout

Statsig 先 team 内开启，再按比例灰度，必要时同步做 A/B test。

8. Observe / Kill / Rollback

指标劣化就 kill switch 关特性；严重问题由基础设施 circuit breaker 自动回滚。

坏功能当日上线，当日也能死。

这条线真正变化了什么

人类把关 strategic risk，不再逐行承担 correctness。

系统把大量重复判断前移到 gate 与回路里。

1. Detect

CloudWatch + Sentry 持续发现异常。

2. Daily Health Report

每天 09:00 UTC，Claude Sonnet 查询 CloudWatch，自动生成健康摘要并发到 Microsoft Teams。

3. Triage Engine

1 小时后聚类错误，按 9 个 severity 维度评分，自动在 Linear 建 investigation ticket。

4. Dedup / Reopen

同类错误已存在就更新；已关闭但复发就 reopen。

减少噪音，保留历史。

5. Fix Through Same Pipeline

工程师核实诊断、提交修复；后续仍走同一套 review + CI + deploy。

6. Re-verify

部署后再查 CloudWatch。

原问题消失则自动 close；未解决则继续循环。

自愈 loop 的核心

错误检测、分诊、修复、验证不是四支队伍的交接，而是一个可以天天自动跑的闭环。

观测层

AWS / CloudWatch / structured logs / alarms / custom metrics

交付层

GitHub Actions + Graphite

负责 gate、merge queue、部署推进。

评审与诊断层

Claude Opus / Sonnet

负责 review、health summary、triage。

控制层

Statsig + kill switch + circuit breaker rollback

人类协作层

Linear tickets + human reviewer + Teams summary

作者的选型原则

Each tool handles one phase.

关键不是单点最强，而是阶段清晰、接口清晰、反馈清晰。

新组织分工

Architect：设计 SOP、边界、测试基础设施、triage 系统。

Operator：调查 bug、微调 UI、验证 PR、处理执行层任务。

价值迁移

工程师价值从“代码产量”转向“决策质量”。

关键能力是批判 AI、发现漏洞、看见 failure mode。

适应差异

作者观察：junior 往往比 senior 更快适应，因为包袱更少、习惯更少。

管理变化

作者的管理时间从约 60% 掉到 10% 以下。

更多时间花在搭 harness，而不是对齐与开会。

不止 engineering

如果工程按小时交付，但产品、市场、增长仍按周 / 月节奏运作，它们就会成为新瓶颈。

所以 release note、视频、社媒、health report 也被 AI-native 化。

结果

• 14 天里平均每天 3 到 8 次 production deploy
• 新功能当天提出、当天上线
• 差功能当天 kill
• engagement 和 payment conversion 上升

代价

• 员工不确定感和角色焦虑
• senior 工程师价值感被冲击
• CTO 长时间高压亲自搭系统
• 旧系统拆掉到新系统跑稳之间有过渡风险

给 CTO / Founder 的行动建议

1. 先找出 cycle time 长于 build time 的环节。
2. 在放大 agent 前先补 testing harness。
3. 先用 1 个 architect 把系统跑通，再扩 operator。
4. 把 AI-native 推到工程之外。

文章真正想让你记住的事

竞争优势不在于“手上有这些工具”，而在于：

• 有没有重设计流程的决心
• 能不能承受重构期间的成本
• 能不能把 judgment 变成系统约束

关联阅读

这篇 clipping 更适合作为“AI-native 交付系统”的总览图。

往下可以接到本库已有的 harness engineering / AI adoption / 最大化 AI 杠杆语境。