buildwright

核心定位

Buildwright 是一款面向 AI 智能体（Agent）的轻量级工程纪律层框架，由软件工程师 raunakkathuria 开发并开源。它将传统软件工程中的 TDD（测试驱动开发）、文档纪律、安全审查、代码审查和质量门禁等最佳实践封装为可复用的工作流命令，旨在解决 AI 辅助开发中常见的"快速但混乱"问题。

核心用法

框架通过五个主要命令构建完整交付闭环：

• `/bw-plan`：纯研究模式，输出书面交付物而不触碰代码，适用于技术调研和方案设计
• `/bw-work`：核心开发命令，遵循 理解→研究→规划→Red→Green→重构→文档→验证→安全审查→代码审查→提交 的严格流程
• `/bw-verify`：执行质量门禁（类型检查、Lint、测试、构建），支持从配置文件自动发现命令
• `/bw-ship`：完整发布流水线，整合验证、安全审查、Staff Engineer 审查后自动提交、推送并创建 PR
• `/bw-analyse`：遗留代码分析工具，自动生成架构文档和技术栈配置

显著优点

1. 工程纪律自动化：将 TDD 循环、文档更新义务、安全审查等容易遗漏的环节固化为强制流程
2. 智能体原生设计：针对 Claude Code、OpenCode、Cursor、Codex CLI 等 AI 编程工具优化，理解 AI 的上下文限制
3. 可配置的指导原则：通过 .buildwright/steering/ 目录支持项目级自定义，同时预置 KISS、YAGNI、DRY 等工程哲学
4. 角色化审查机制：内置 Staff Engineer 和 Security Engineer 提示词角色，模拟人工代码审查
5. 安全意识内建：显式禁止编辑 .env 文件、强制推送、合并 PR 等危险操作

潜在局限

• 生态依赖：必须配合 Git 和 GitHub CLI 使用，安全扫描需额外安装 Semgrep、Gitleaks、TruffleHog 等工具
• 认知开销：严格的流程可能对原型开发或探索性编程造成摩擦
• 版本较新：当前 v0.0.16 处于早期阶段，API 和配置格式可能不稳定
• AI 特定假设：流程设计基于当前大模型能力假设，可能随模型演进需要调整

适合人群

• 使用 AI 编程助手但希望保持代码质量的开发者
• 需要为团队建立 AI 辅助开发规范的 Tech Lead
• 在现有项目中引入工程纪律的 brownfield 场景
• 对安全合规和代码审查有要求的严肃项目

常规风险

1. 流程僵化风险：过度依赖框架可能导致开发者忽视上下文判断，在简单变更上消耗不必要的流程成本
2. AI 幻觉传导：框架本身不验证 AI 生成的审查意见质量，可能将模型的错误自信转化为"正式"审查结果
3. 工具链脆弱性：质量门禁依赖外部工具的正确配置，错误配置可能导致"假阳性通过"或不必要的阻塞
4. 开源维护风险：单一作者维护的早期项目，长期支持和社区生态存疑

核心用法

Buildwright 是一套面向 Agent 的工程纪律工作流框架，通过 5 个核心命令规范开发流程：

• `/bw-work`：执行功能开发、Bug 修复或重构。遵循 TDD 流程（Red-Green-Refactor），自动生成技术文档，并在完成后触发安全审查和代码审查。
• `/bw-plan`：纯研究模式，调研技术问题并输出文档，不修改代码。
• `/bw-verify`：运行质量门禁，包括类型检查、Lint、测试和构建。支持从配置文件读取或自动检测项目类型。
• `/bw-ship`：完整的发布流程——验证通过后执行 Staff Engineer 审查、安全审查，最后提交、推送并创建 PR。
• `/bw-analyse`：面向遗留代码库的分析工具，自动生成架构文档、技术栈说明和代码规范。

工作流内置「驾驶舱」机制（Steering），递归读取 .buildwright/steering/ 下的 Markdown 文件，确保所有工作遵循项目约定的哲学（KISS、YAGNI、DRY）和技术规范。

显著优点

1. 工程化思维注入：将行业最佳实践（TDD、文档驱动、安全左移）转化为 Agent 可执行的提示词流程，弥补 AI 编程缺乏纪律性的短板。
2. 零侵入设计：纯 Markdown 实现，无可执行代码，不改变用户环境，不触碰敏感文件（明确声明不编辑 .env、不强制推送、不合并 PR）。
3. 多 IDE 兼容：支持 Claude Code、OpenCode、Cursor、Codex CLI 等主流 AI 编程工具。
4. 可扩展的审查人格：通过提示词定义 Staff Engineer 和安全工程师角色，实现类人工的代码审查体验。
5. 遗留代码友好：/bw-analyse 命令特别适合快速理解 Brownfield 项目，生成标准化架构文档。

潜在缺点与局限性

1. 外部工具依赖：完整功能需要本地安装 git、gh CLI，安全扫描可选依赖 semgrep、gitleaks、trufflehog，配置成本较高。
2. 文档负担：强制要求每个用户可见变更更新文档，小型迭代或原型开发阶段可能显得繁琐。
3. 提示词黑盒：审查人格的具体行为取决于提示词质量，不同 Agent 模型的执行一致性可能存在差异。
4. T3 来源限制：作为个人开源项目，长期维护承诺不及企业级产品，社区生态尚在早期（7 Stars、3 Forks）。

适合的目标群体

• 技术团队 Lead/Staff Engineer：希望为团队建立统一的 AI 辅助开发规范。
• 追求代码质量的独立开发者：个人项目希望保持专业级工程纪律。
• 遗留代码维护者：需要快速理解和文档化历史项目。
• AI 编程工具重度用户：希望弥补 Cursor/Copilot 等工具在流程规范上的不足。

使用风险

1. 执行权限风险：虽然 Skill 本身安全，但 /bw-ship 等命令会实际调用 git commit/push 和 gh pr create，建议配合 --dry-run 或人工最终确认。
2. 模型能力差异：复杂的安全审查和代码审查依赖底层 LLM 的代码理解能力，弱模型可能流于形式。
3. 配置漂移：自动检测的技术栈配置（tech.md）可能随项目演进过时，需定期人工校验。
4. 性能开销：完整的 /bw-work 流程包含多次 LLM 调用（研究→计划→实现→审查），对 token 消耗敏感场景需权衡。