使用说明

BuildRunner 3.0

Git支持的AI辅助开发治理

BuildRunner 3.0是专为AI驱动的开发工作流程设计的下一代项目管理CLI。它通过确保完整性、保持质量并提供结构化指导的智能系统消除了常见的人工智能编码挫折。

问题

人工智能辅助开发带来了独特的挑战：

🔴 建筑不完整 -AI忘记任务，跳过步骤，留下待办事项
🔴 质量漂移 -会话之间没有一致性，代码质量不同
🔴 建筑混沌 -规格被忽视，模式被违反，标准被遗忘
🔴 上下文丢失 -每一次新的会议都从头开始
🔴 调试地狱 -难以捕捉错误、重现问题、跟踪故障

解决方案

BuildRunner 3.0提供 8智能系统 改变人工智能发展：

1.🎯 完工保证体系

永远不要再运送未完成的项目

自动差距分析检测缺失的功能、不完整的实现
任务依赖性跟踪可确保正确的构建顺序
预推验证阻止不完整的代码
使用可视化STATUS.md进行实时进度跟踪

→ 请参阅差距分析文档

2.⚡ 代码质量体系

自动维护专业标准

多维质量评分（结构、安全、测试、文档）
自动检测、格式化和安全扫描
git钩子中的质量门可以防止坏代码登陆
每个项目的质量阈值

→ 请参阅代码质量文档 | 请参阅行为配置

3.🏗️ 建筑防漂移

使实现与规范保持一致

架构保护程序根据PROJECT_SPEC.md验证代码
自动检测规格违规
Git钩子强制执行架构规则
设计系统一致性验证

→ 请参阅架构保护文档

4.🐛 自动调试系统

自动捕获和管道错误

自动将管道命令输出到上下文
错误模式检测和分析
跨会话的故障分析
智能重试建议

→ 请参阅自动调试文档

5.🎨 工业智能设计系统

根据行业模式生成像素完美的设计

148个行业概况（医疗保健、金融科技、SaaS、电子商务、制造业、教育、政府等）
8种用例模式（仪表板、市场、CRM、分析等）
通过智能冲突解决自动合并配置文件
生成完整的顺风配置
行业合规要求（HIPAA、WCAG等）

→ 请参阅PRD向导文档 | 见设计系统文件

6.📋 规划模式+珠三角一体化

Opus的战略规划，Sonnet的战术执行

交互式项目_SPEC向导
行业和用例的自动检测
Opus预填充规格
用于模型切换的紧凑型切换包
双向同步：规格↔ features.json

→ 见PRD系统文档

7.🔧 自助执行系统

API智能密钥管理和环境设置

自动检测所需服务（Stripe、AWS、Supabase等）
智能提示凭据
.env 带验证的生成
服务不可用时性能下降

→ 查看自助服务文档

8.🎮 全局/本地行为配置

对BuildRunner行为的细粒度控制

~/.buildrunner/config.yaml中的全局默认值
.buildrunner/config.yaml中的项目重写
临时更改的运行时标志
配置层次结构：运行时>项目>全局>默认值

→ 请参阅行为配置文档

快速开始

系统相关性

语义扫描 静态分析预过滤器需要(ai_code_review 第14阶段）。这是一个系统/开发依赖关系——不要通过安装 requirements-api.txt:

# macOS
brew install semgrep

# Linux (Debian/Ubuntu)
pip install semgrep   # or: sudo snap install semgrep

# Verify
semgrep --version

安装

# Install via pip (recommended)
pip install buildrunner

# Or via Homebrew (macOS)
brew install buildrunner

# Or via Docker
docker pull buildrunner/buildrunner:latest

初始化新项目

# Create new BuildRunner project
br init my-project
cd my-project

# Run the PRD Wizard
br spec wizard

# Start building
br status

5分钟演练

看 docs/QUICKSTART.md 获取完整的教程。

v3.1状态（内部版本4E）

版本： v3.1.0✅ 稳定-生产准备就绪，完成95%，所有MCP测试均通过

BuildRunner v3.1增加了四个主要的系统增强功能：

🔒 安全保障（一级）

✅ 秘密侦查 （13种模式：Anthropic、OpenAI、JWT、AWS、GitHub等）
✅ SQL注入检测 （Python+JavaScript模式）
⚠️ 预提交挂钩 （代码存在，需要生产验证）
✅ 73项测试通过 （覆盖率80%）

→ 见证券.md 详情

🎯 模型路由和成本优化

✅ 基于启发式的复杂度估计 （简单/中等/复杂/关键）
⚠️ 基于人工智能的估算 （可选，需要API密钥，尚未集成）
✅ 模型选择逻辑 （俳句/十四行诗/歌剧）
⚠️ 成本跟踪界面 （SQLite开发中的持久性）

→ 参见ROUTING.md 详情

📊 遥测与监测

✅ 已定义事件模式 （5个类别的16种事件类型）
✅ 度量分析逻辑 （成功率、延迟、成本、错误）
⚠️ 事件收集 （需要编排器集成）
⚠️ 数据持久性 （文件轮换可用，SQLite正在开发中）

→ 参见遥测.md 详情

⚡ 并行编排

✅ 多时段协调 （单元测试，28项测试通过）
✅ 文件锁定与冲突检测 （单元测试）
✅ 工人健康监测 （单元测试）
⚠️ 端到端执行 （尚未在生产中测试）

→ 请参见PARALLEL.md 详情

📚 文件和指南

✅ 快速入门指南 (docs/QUICKSTART.md)
✅ 集成指南 (docs/INTEGRATION-GUIDE.md)
✅ API 参考 (docs/API_REFERENCE.md文件)
✅ E2E测试 （5个综合场景）

⚠️ 集成状态

什么在起作用：

秘密检测模式（13种）
SQL注入检测（Python+JS）
基于启发式的复杂度估计
CLI命令（共25个）
单元测试（101项测试通过）

正在进行什么：

安全挂钩：需要生产验证
人工智能估算：可选，尚未集成
成本跟踪：SQLite在开发中的持久性
遥测数据收集：需要编排器集成
并行执行：需要端到端测试

第1周目标： 集成层、持久层、AI集成、E2E测试

核心功能

基于特征的跟踪

✅ 用清晰的特征跟踪取代令人困惑的阶段/步骤模型 ✅ 从features.json自动生成STATUS.md ✅ 跟踪完成百分比、阻止程序和依赖关系 ✅ 丰富终端UI的视觉进度

Git挂钩和治理

✅ 预提交：验证features.json，执行治理规则 ✅ 提交后：自动生成STATUS.md，更新指标 ✅ 预推：阻止功能不完整或违规的推送 ✅ 使用校验和的代码治理

MCP集成（克劳德代码）

✅ 通过模型上下文协议公开的9个BuildRunner工具 ✅ 直接从Claude Code管理功能 ✅ 运行治理检查，生成状态报告 ✅ 完全基于stdio的通信

→ 请参阅MCP集成文档

可选集成

✅ GitHub：将问题同步到功能，从CLI创建PR ✅ 概念：将STATUS.md和文档推送到Notion工作区 ✅ Slack：构建通知、每日站立、警报 ✅ 速贝：可选的云持久性和事件日志记录

→ 请参阅插件文档

从BuildRunner 2.0迁移

✅ 从.run/到.buildrunner的自动迁移/ ✅ 转换HRPO→ features.json ✅ 转换governance.json→ 治理yaml ✅ 保留git历史和元数据 ✅ 空转模式，安全预览

→ 请参阅迁移指南

多回购仪表板

✅ 自动发现所有BuildRunner项目 ✅ 跨多个存储库聚合状态 ✅ 概述、详细信息、时间线和警报视图 ✅ 健康状态计算（健康/警告/严重） ✅ 带有颜色编码的丰富终端用户界面

→ 请参阅仪表板文档

建筑

┌────────────────────────────────────────────────────────────┐
│                    BuildRunner 3.0                          │
├────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐    ┌──────────────┐   ┌───────────────┐  │
│  │     CLI     │───▶│   FastAPI    │──▶│   Feature     │  │
│  │   (Typer)   │    │   Backend    │   │   Registry    │  │
│  └─────────────┘    └──────────────┘   └───────────────┘  │
│         │                   │                    │          │
│  ┌──────▼─────┐    ┌───────▼────┐   ┌──────────▼──────┐  │
│  │ Git Hooks  │    │MCP Server  │   │   Governance    │  │
│  └────────────┘    └────────────┘   │     Engine      │  │
│                                       └─────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐ │
│  │          Optional Integrations (Graceful Degradation)│ │
│  ├──────────────────────────────────────────────────────┤ │
│  │  GitHub  │  Notion  │  Slack  │  Supabase │ Figma   │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                              │
└────────────────────────────────────────────────────────────┘

→ 参见架构文档

文档

入门指南

快速入门指南 -5分钟入门指南（v3.1）
集成指南 -将BuildRunner集成到您的项目中（v3.1）
安装指南 -详细安装
第一个项目教程 -完整演练

v3.1系统（内部版本4E）

安全指南 -秘密检测、SQL注入检查、预提交挂钩
路线指南 -模型选择和成本优化
遥测指南 -监控、指标和警报
并行编排指南 -多时段协调
API 参考 -完整的API参考（v3.1）

核心系统

CLI 参考 -所有CLI命令
API 参考 -所有API端点
MCP集成 -Claude代码集成
插件 -GitHub、Notion、Slack、Supabase

增强系统

代码质量体系 -质量门和评分
差距分析 -完工保证
建筑警卫 -防漂移
自动调试 -错误捕获
设计系统 -行业情报
PRD向导 -项目_SPEC创建
自助服务执行 -环境设置
行为配置 -全局/本地配置

教程

设计系统指南 -使用行业概况
质量门设置 -制定标准
并行构建 -编排构建
完工保证 -使用间隙分析仪

迁移和工具

从BR 2.0迁移 -升级指南
仪表盘 -多回购管理
模板目录 -行业+用例简介

贡献

贡献.md -如何做出贡献
行为准则 -社区指南

示例项目

医疗保健仪表板

cd examples/healthcare-dashboard/
br spec wizard
# Follow prompts, select Healthcare + Dashboard
br status

使用具有仪表板模式、HIPAA合规性和患者生命体征小部件的医疗保健行业配置文件完成示例。

金融科技API

cd examples/fintech-api/
br spec wizard
# Follow prompts, select Fintech + API Service
br status

API服务，具有安全第一设计、符合PCI和金融交易处理。

电子商务市场

cd examples/ecommerce-marketplace/
br spec wizard
# Follow prompts, select E-commerce + Marketplace
br status

提供产品目录、付款处理和订单管理的多服务项目。

SaaS入职流程

cd examples/saas-onboarding/
br spec wizard
# Follow prompts, select SaaS + Onboarding
br status

展示设计系统，包括入职模式、用户激活和试用流程。

CLI命令

# Initialize project
br init <project-name>

# PRD Wizard
br spec wizard              # Interactive PROJECT_SPEC creation
br spec sync                # Sync spec to features.json
br spec validate            # Validate spec completeness
br spec confirm             # Lock spec

# Feature management
br feature add <name>       # Add new feature
br feature complete <id>    # Mark feature complete
br feature list             # List all features
br status                   # Show project status
br generate                 # Generate STATUS.md

# Security (v3.1) 🔒
br security check           # Check staged files for security issues
br security scan            # Scan entire project
br security hooks install   # Install pre-commit hooks
br security hooks status    # Check hook installation

# Model Routing (v3.1) 🎯
br routing estimate <task>  # Estimate complexity and recommend model
br routing select <task>    # Select model with constraints
br routing costs            # View cost summary
br routing models           # List available models

# Telemetry (v3.1) 📊
br telemetry summary        # View metrics summary
br telemetry events         # List recent events
br telemetry alerts         # Check for threshold alerts
br telemetry performance    # View performance metrics
br telemetry export <file>  # Export data to CSV

# Parallel Orchestration (v3.1) ⚡
br parallel start <name>    # Start parallel session
br parallel status          # View session status
br parallel dashboard       # Show live dashboard
br parallel list            # List all sessions
br parallel workers         # View worker health

# Design system
br design profile <industry> <use-case>  # Preview design profile
br design research           # Research design patterns

# Migration
br migrate from-v2 <path>   # Migrate from BR 2.0
br migrate rollback         # Rollback migration

# Dashboard
br dashboard show           # Multi-repo dashboard
br dashboard show --watch   # Live dashboard

# Quality & Governance
br quality check            # Run quality analysis
br gaps analyze             # Run gap analysis
br validate                 # Run all validations

# Config
br config set <key> <value> # Set config value
br config get <key>         # Get config value
br config list              # List all config

→ 请参阅完整的CLI参考

技术栈

语言：Python 3.11+
CLI框架类型：
API框架：FastAPI
终端用户界面：富有
数据库：Supabase（PostgreSQL）-可选
Git集成：GitPython
测试：pytest+pytest-cov
代码质量：黑色，拉夫，我的，土匪

路线图

v3.1（2025年第一季度）

[]仪表板Web UI
[]实时协作（多人编辑）
[]可视化规范编辑器
[]人工智能驱动的代码审查

v3.2（2025年第二季度）

[]模板市场
[]多项目规格
[]使用分支进行规范版本控制
[]Figma设计导入

v3.3（2025年第三季度）

[]Jira/线性同步
[]GitHub问题集成
[]Slack机器人
[]根据生产指标自动更新

贡献

我们欢迎捐款！请参阅贡献.md 作为指导方针。

开发设置

# Clone repository
git clone https://github.com/buildrunner/buildrunner.git
cd buildrunner

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run quality checks
black .
ruff check .
mypy .

许可证

MIT许可证-请参阅许可证了解详情。

支持

文档: https://buildrunner.dev/docs
问题: GitHub 问题
讨论: GitHub讨论
Discord 的中文翻译是“不和谐”或“纷争”。: 加入我们的社区

致谢

内置于❤️ BuildRunner团队和贡献者。

特别感谢：

Claude Code和MCP协议的拟人化
令人惊叹的工具和库的开源社区
早期采用者和beta测试者提供宝贵的反馈

BuildRunner 3.0 - 因为AI不应该忘记完成它开始的事情 🚀