Buildwright

Buildwright 是一个轻量级的工程实践层：理解、测试、实现、文档化、验证、评审、交付。

命令

/bw-work

用于实现缺陷修复、重构和功能开发。

流程：理解 → 研究 → （如需）规划 → Red（失败测试）→ Green（通过测试）→ Refactor（重构）→ 文档 → 验证 → 安全评审 → 代码评审 → 提交/交付。

对于较大规模的功能，/bw-work 会生成 docs/specs/[feature]/research.md 和 docs/specs/[feature]/spec.md；对于小型任务，则保持研究过程轻量化。所有面向用户的功能变更，都必须更新相关文档，或明确说明为何无需更新文档。

/bw-plan

针对某个问题或主题开展研究，并产出一份书面交付成果。不修改源码、不提交、不推送、不创建 PR。

/bw-verify

运行项目的质量门禁检查：类型检查（typecheck）、代码规范检查（lint）、测试（test）和构建（build）。所执行的命令优先从 .buildwright/steering/tech.md 中读取（若该文件存在）；否则由 Buildwright 自动检测并生成相应命令。

/bw-ship

依次执行 verify、安全评审、Staff Engineer 评审，然后完成提交、推送并打开 PR。交付操作将确认文档已更新，或已明确声明文档不适用。

/bw-analyse

分析现有代码库（brownfield codebase），生成以下文件：.buildwright/codebase/STACK.md、ARCHITECTURE.md、CONVENTIONS.md 和 CONCERNS.md；同时创建或更新 .buildwright/steering/tech.md，填入识别出的技术栈与对应命令。

引导机制（Steering）

Buildwright 在会话启动时，递归读取 .buildwright/framework/ 和 .buildwright/steering/ 目录下的所有 .md 文件。

框架行为（.buildwright/framework/）由 Buildwright 所有并固化——在所有安装实例中完全一致，随版本更新自动刷新，不可定制：

• .buildwright/framework/autonomy.md —— 唯一的自主性行为定义（无模式标志位），支持在就绪任务上自动连续执行，并基于上下文推断处理失败情形。
• .buildwright/framework/capability.md —— 优先使用各宿主工具原生能力（如 plan/file-write/task-tracking/sub-agents/parallelism/worktrees/hooks），仅限用于 执行机制 层面，并附有明确定义的备选方案；这些能力绝不会替代 Buildwright 的引导逻辑或流程控制。
• .buildwright/framework/findings.md —— 记录需上报上游（report-upstream）及上线前暂缓项（before-production deferrals）的约定格式。

引导配置（.buildwright/steering/）由项目方所有并可定制，且在 Buildwright 更新过程中保持不变。默认随产品发布的配置如下：

• .buildwright/steering/philosophy.md —— 包含 KISS、YAGNI、DRY、采用“无聊技术”（boring technology）、快速失败（fail fast）、Red → Green → Refactor、文档纪律（documentation discipline）以及财务代码规范（financial code rules）等核心原则。

更进一步的项目专属引导配置按需懒创建：

• 在完成技术栈与命令识别后，生成 tech.md；
• 仅在 greenfield 工作或显式提供产品上下文时，生成 product.md。

角色（Personas）

Buildwright 使用基于提示词（prompt-based）的评审角色：

• Staff Engineer：负责规格（spec）与代码评审；
• Security Engineer：负责安全评审。

安全性（Safety）

Buildwright 不会编辑 .env 文件，不执行具有破坏性的 Git 操作（例如强制推送 force push 或合并 PR），仅暂存当前工作涉及的变更文件。