buildwright

核心用法

Buildwright 是一个规范驱动的自主开发工作流工具，支持两种运行模式：单代理模式适用于简单功能开发，多代理模式（Claw Architecture）则将跨领域工作分解为专业子代理（UI、API、DB）并行执行。核心命令包括 /bw-new-feature 用于完整功能开发流程，/bw-claw 处理跨领域复杂特性，/bw-quick 提供快速修复通道，/bw-ship 为现有代码提供质量流水线，/bw-verify 执行快速检查，/bw-analyse 分析遗留代码库并生成结构化文档。

使用流程遵循严格阶段：代码库分析 → 撰写规格文档（docs/specs/[feature]/spec.md）→ 人工审批（除非启用 BUILDWRIGHT_AUTO_APPROVE）→ TDD 实现 → 质量关卡（类型检查、代码风格、测试、构建）→ 可选安全扫描（semgrep、gitleaks、trufflehog）→ 模拟 Staff Engineer 的代码审查 → 自动提交、推送并创建 PR。

显著优点

1. 架构解耦：Claw Architecture 将复杂功能按领域垂直拆分，各子代理专注单一技术栈，通过接口契约协作，避免单代理上下文溢出
2. 质量保证体系：内置五层质量关卡，结合安全扫描与模拟资深工程师的代码审查，降低缺陷流入生产环境的风险
3. 透明审计：所有规格文档、研究笔记、执行报告均提交至 Git 历史，形成完整决策链条
4. 失败容错：任一扇门失败后，工具会提交已完成工作并附带结构化失败报告，避免静默失败或孤立分支
5. 多 IDE 兼容：支持 Claude Code、OpenCode、OpenClaw、Cursor 等主流 AI 编程环境

潜在缺点与局限性

• 外部依赖较重：必须配置 git、gh CLI 及 GITHUB_TOKEN，安全扫描功能依赖额外二进制工具
• 人工审批瓶颈：默认交互模式下，规格审批环节会阻塞流程，团队需建立明确的响应机制
• 令牌权限风险：repo 范围令牌具备读写权限，虽支持细粒度令牌，但配置复杂度上升
• 多代理协调开销：Claw 模式对简单功能可能产生过度设计，增加不必要的协调成本
• 代码审查为提示工程实现：Staff Engineer 审查基于本地提示文件，非真实人工审查，对复杂架构决策的把关能力有限

适合人群

• 追求标准化开发流程的中大型开发团队
• 需要并行处理前端/后端/数据库联调的全栈开发者
• 希望将代码规范、安全扫描、审查流程自动嵌入 CI 前阶段的 Tech Lead
• 已在 Claude Code、Cursor 等环境中深度使用 AI 辅助编程的开发者

常规风险

• 令牌泄露：GITHUB_TOKEN 若配置为环境变量，可能在子进程或日志中暴露
• 自动代码提交：启用 BUILDWRIGHT_AUTO_APPROVE 后，AI 生成的代码将自动推送至远程仓库，存在逻辑缺陷或安全漏洞被提交的风险
• 安全扫描盲区：semgrep、gitleaks 等工具的规则集可能产生误报或漏报，不能替代专业安全审计
• 分支污染风险：虽禁止强制推送和重置操作，但频繁的功能分支可能增加仓库管理复杂度