🌊 Vibe Engineering Playbook

AI-Native 全栈开发工作流系统 - 通过 GitHub Actions 和 AI Agent 实现从 Issue 到代码的自动化闭环

Vibe Engineering Playbook 是一个完整的 AI 驱动开发工作流系统，通过 12 个 GitHub Actions 工作流和 2 个可复用 Actions，实现从需求分析、代码生成、错误修复到部署监控的全自动化流程。系统支持前后端分离开发，自动管理功能分支，并提供完善的错误处理和监控机制。

✨ 核心特性

🤖 AI Agent 工作流

统一 Agent 入口: 通过 /agent ui|spec|be|fe 命令，自动生成 UI 规格、技术规格、后端代码、前端代码
代码生成: 支持前端（Next.js + TypeScript）和后端（Go + Gin）自动代码生成
规格文档生成: 从产品需求自动生成 UI 设计规格和完整技术规格文档
错误自动修复: CI/CD 失败时自动分析并修复构建错误

🔄 自动化工作流

前后端联动: 后端 PR 合并后自动触发前端开发
功能分支管理: 自动创建、同步和合并功能分支
部署监控: 监控 Vercel 部署状态，自动更新 Issue 和 PR
任务监控: 每小时自动检查任务状态，清理超时任务

📊 智能管理

Issue 管理: 自动标签、欢迎消息、父子 Issue 关系管理
错误分析: AI 分析 workflow 失败原因，提供修复建议
状态同步: 自动同步 Issue 状态和实现进度
每日维护: 每天凌晨 3:00 自动检查依赖、安全漏洞和待处理任务

🏗️ 技术栈

前端

框架: Next.js 15 (App Router)
语言: TypeScript 5
UI 库: React 19 + shadcn/ui
样式: Tailwind CSS 4 + Base.org 设计系统
状态管理: React Hook Form + Zod
部署: Vercel

后端

语言: Go 1.24+
框架: Gin + GORM
数据库: PostgreSQL
缓存: Redis
日志: Zap
部署: Railway

AI & 自动化

AI 服务: OpenRouter (Claude Sonnet 4.5)
自动化: GitHub Actions (14 workflows + 4 reusable actions)
代码生成: Claude Code Action

🚀 快速开始

1. 克隆项目

git clone https://github.com/your-org/vibe-engineering-playbook.git
cd vibe-engineering-playbook

2. 配置 GitHub Secrets

在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加：

OPENROUTER_API_KEY: OpenRouter API Key（用于 AI 调用）
RAILWAY_BACKEND_URL: Railway 后端 URL（用于 Smoke Test，可选）

3. 本地开发

后端

cd backend
go mod download
go run cmd/server/main.go

前端

cd frontend
npm install
npm run dev

详细配置请参考本地开发指南

4. 创建第一个 Issue

在 GitHub 上创建一个新 Issue，描述你的需求
Vibe Router 会自动分析复杂度并触发对应的 Agent
AI 会自动生成代码并创建 PR
审查 PR 后合并即可

📖 工作流系统

本项目包含 12 个 GitHub Actions 工作流和 2 个可复用 Composite Actions，实现完整的自动化开发流程。

工作流分类

🤖 核心 Agent 工作流（1个）

工作流	功能	触发方式
Vibe Agent	统一 Agent 入口，处理 UI/Spec/后端/前端代码生成	`/agent ui

🔄 Issue 管理工作流（3个）

工作流	功能	触发方式
Issue Manager	自动标签和欢迎消息	Issue 创建时自动触发
Parent-Child Issue Guard	管理父子 Issue 关系，防止父 Issue 在子 Issue 未完成时被关闭	Issue 关闭时自动触发
Update PRD Status	自动更新 PRD Issue 状态表格	Issue 关闭/重新打开时自动触发

⚡ 自动化工作流（3个）

工作流	功能	触发方式
Auto Trigger Frontend	后端 PR 合并后触发前端	PR 合并时自动触发
Feature Branch Manager	管理功能分支	`feature:xxx` 标签或命令
Dependency Chain Trigger	依赖链自动触发下一个任务	子 Issue 关闭时自动触发

🔍 监控和错误处理（4个）

工作流	功能	触发方式
Vibe Continuous	任务监控与自动迭代	每24小时自动运行
Fix PR	修复 PR 构建错误	`/fix` 命令
Vercel Status Monitor	监控 Vercel 部署状态	部署状态变化时触发
Check API Error Handling	检查 API 错误处理规范	PR 包含后端代码变更时触发

📋 其他工作流（1个）

工作流	功能	触发方式
Daily Maintenance	每日仓库维护	每天凌晨 3:00（北京时间）自动运行，也可手动触发

常用命令

命令	说明	适用场景
`/agent ui`	生成 UI 设计规格	需要先设计 UI
`/agent spec`	生成完整技术规格	需要技术方案设计
`/agent be`	生成后端代码	已有规格文档
`/agent fe`	生成前端代码	已有规格文档或后端 API
`/agent be --spec #123`	基于指定 Issue 的规格生成后端	指定规格来源
`/fix`	修复构建错误	PR 构建失败
`/sync`	同步 main 到功能分支	功能分支需要更新
`/merge-to-main`	创建合并 PR	功能完成后合并

查看工作流运行状态

可以通过以下方式查看工作流的运行情况：

方式一：GitHub 网页

直接访问 Actions 页面查看所有工作流运行记录。

方式二：GitHub CLI

# 查看特定工作流的运行记录
gh run list --workflow=weekly-maintenance.yml

# 查看最近 5 次运行
gh run list --workflow=weekly-maintenance.yml --limit=5

# 查看某次运行的详情
gh run view <run-id>

完整工作流文档

📚 详细的工作流文档请查看: .github/workflows/README.md

最新更新：

✅ Prompt 模板化：所有 workflow 中的 prompt 已提取为独立模板文件
✅ 统一 Agent 入口：/agent ui|be|fe 命令格式，支持 --spec 参数
✅ 每日维护工作流：每天凌晨 3:00（北京时间）自动执行
✅ 父子 Issue 关系管理：防止父 Issue 在子 Issue 未完成时被关闭
✅ PRD 状态自动更新：自动同步子 Issue 完成状态到父 Issue

📁 项目结构

vibe-engineering-playbook/
├── .github/
│   ├── workflows/          # 12 个 GitHub Actions 工作流
│   │   ├── README.md      # 工作流详细文档
│   │   ├── vibe-agent.yml  # 统一 Agent 入口
│   │   ├── vibe-continuous.yml  # 任务监控与自动迭代
│   │   └── ...
│   ├── actions/            # 2 个可复用 Composite Actions
│   │   ├── load-prompt/          # Prompt 模板加载器
│   │   └── context-discovery/    # 项目上下文发现
│   ├── prompts/           # AI Prompt 模板
│   │   ├── agents/        # Agent Prompt 模板
│   │   └── router/         # 路由 Prompt 模板
│
├── backend/               # Go 后端
│   ├── cmd/server/        # 入口文件
│   ├── internal/
│   │   ├── handlers/      # HTTP 处理器
│   │   ├── models/         # 数据模型
│   │   ├── repository/    # 数据访问层
│   │   ├── services/      # 业务逻辑层
│   │   └── router/        # 路由配置
│   ├── migrations/        # 数据库迁移
│   ├── CLAUDE.md          # 后端开发规范
│   └── go.mod
│
├── frontend/              # Next.js 前端
│   ├── app/               # App Router 页面
│   ├── components/        # React 组件
│   ├── lib/               # 工具函数和 API 客户端
│   ├── STYLE_GUIDE.md     # 前端设计规范
│   └── package.json
│
├── api/                   # API 契约
│   ├── openapi.yaml       # OpenAPI 规范
│   └── contract.json      # API 契约 JSON
│
├── docs/                  # 项目文档
│   ├── development/       # 开发指南
│   ├── workflow/          # 工作流程文档
│   ├── templates/         # 模板文件
│   └── examples/          # 示例文档
│
├── scripts/               # 工具脚本
├── docker-compose.yml     # Docker 编排配置
├── DEPLOYMENT.md          # 部署指南
└── README.md              # 本文件

🎯 使用流程

典型开发流程

graph LR
    A[创建 Issue] --> B[描述需求]
    B --> C[/agent spec]
    C --> D[生成技术规格]
    D --> E[/agent be]
    E --> F[生成后端代码 PR]
    F --> G[代码审查]
    G --> H[合并 PR]
    H --> I[/agent fe]
    I --> J[生成前端代码 PR]
    J --> K[代码审查]
    K --> L[合并 PR]
    L --> M[自动部署]

1. 创建需求 Issue

在 GitHub 上创建 Issue，描述你的需求：

## 需求描述

实现用户登录功能

## 验收标准

- [ ] 用户可以使用邮箱和密码登录
- [ ] 登录成功后跳转到首页
- [ ] 显示错误提示信息

## 技术约束

- 使用 JWT 认证
- 前端使用 shadcn/ui 组件

2. 使用 Agent 命令

在 Issue 评论中使用命令触发 AI Agent：

/agent spec  # 先生成技术规格
/agent be    # 生成后端代码
/agent fe    # 生成前端代码

3. 代码生成和 PR

AI Agent 读取项目上下文和规格文档
生成符合规范的代码
自动创建分支和 PR
在 Issue 中发布进度追踪

4. 审查和合并

审查 AI 生成的代码
运行测试验证功能
合并 PR 触发自动部署

5. 部署和监控

Vercel 自动部署前端
Railway 自动部署后端
Vercel Monitor 更新 Issue 状态
部署成功后自动关闭 Issue

🛠️ 开发指南

后端开发

技术栈: Go 1.24+ / Gin / GORM / PostgreSQL / Redis

目录结构:

backend/
├── cmd/server/main.go       # 入口文件（不要修改）
└── internal/
    ├── handlers/            # HTTP 处理器
    ├── models/              # GORM 模型
    ├── repository/          # 数据访问层
    ├── services/            # 业务逻辑层
    └── router/              # 路由注册

添加新 API:

在 internal/models/ 创建模型
在 internal/repository/ 创建数据访问层
在 internal/handlers/ 创建处理器
在 internal/router/router.go 注册路由

详细规范请参考: backend/CLAUDE.md

前端开发

技术栈: Next.js 15 / React 19 / TypeScript / Tailwind CSS / shadcn/ui

设计系统: 严格遵循 Base.org 设计规范

90% 灰度/白色空间
10% Base Blue (#0000ff) 强调色
无阴影、无边框设计
12-24px 圆角

组件使用: 优先使用 shadcn/ui 组件库

详细规范请参考: frontend/STYLE_GUIDE.md

🚢 部署

后端部署（Railway）

连接 GitHub 仓库
Railway 自动检测 railway.toml
添加 PostgreSQL 和 Redis 数据库
配置环境变量
自动部署

前端部署（Vercel）

连接 GitHub 仓库
Vercel 自动检测 Next.js
配置环境变量
自动部署

详细步骤请参考: DEPLOYMENT.md

📚 文档

核心文档

工作流文档 - 14 个工作流和 4 个 Actions 详细说明
本地开发指南 - 本地环境配置
项目设计文档 - 项目架构和设计原则
部署指南 - 生产环境部署步骤
Agent 协议 - AI Agent 使用规范

开发规范

后端开发规范 - Go 后端开发指南
前端设计规范 - Base.org 设计系统
代码审查清单 - PR 审查标准

模板和示例

🔧 配置说明

环境变量

后端（Railway）

PORT=8080
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
LOG_LEVEL=info
CORS_ORIGIN=https://your-frontend.vercel.app

前端（Vercel）

NEXT_PUBLIC_API_URL=https://your-backend.railway.app

GitHub Secrets

OPENROUTER_API_KEY: OpenRouter API Key（必需）
RAILWAY_BACKEND_URL: Railway 后端 URL（可选，用于 Smoke Test）

工作流配置

各工作流的环境变量配置请参考: .github/workflows/README.md

🎨 设计系统

本项目严格遵循 Base.org 设计系统：

核心原则

极致克制: 90% 灰度/白色空间
精准爆发: 10% Base Blue (#0000ff) 强调色
无阴影无边框: 通过背景色差异表达层次
大圆角: 12-24px 圆角系统

颜色系统

主色: Base Blue #0000ff
灰度: #000000 → #ffffff 渐变
语义色: 错误、警告、成功（谨慎使用）

详细规范请参考: frontend/STYLE_GUIDE.md

🤝 贡献指南

提交 Issue

使用 Issue 模板创建 Issue
提供清晰的需求描述和验收标准
Vibe Router 会自动分析并路由

提交 PR

AI Agent 会自动创建 PR
或手动创建 PR 时使用 PR 模板
确保代码通过测试和 lint
添加必要的文档更新

代码规范

后端: 遵循 backend/CLAUDE.md
前端: 遵循 frontend/STYLE_GUIDE.md
提交信息: 使用清晰的 commit message

🐛 故障排查

Agent 失败

查看 Actions 日志了解详细错误
在 Issue 中重新评论对应的 Agent 命令重试
如果持续失败，可能需要优化需求描述或规格文档

构建错误

在 PR 中评论 /fix 命令
AI 会自动分析并修复
如果自动修复失败，查看错误日志手动修复

任务超时

vibe-continuous.yml 会每24小时自动检查并清理超时任务
查看 Actions 日志确认状态
使用对应的 Agent 命令重试

部署失败

查看 Vercel/Railway 日志
在 PR 中评论 /fix 修复构建错误
修复后平台会自动重新部署

更多故障排查请参考: .github/workflows/README.md

📊 项目统计

工作流数量: 12 个
可复用 Actions: 2 个
AI Agent: 1 个统一入口（支持 UI/Spec/BE/FE 四种模式）
自动化流程: 10+
支持平台: GitHub, Vercel, Railway
技术栈: Go, Next.js, TypeScript, PostgreSQL, Redis

📝 更新日志

2026-01-17

✅ Prompt 模板化完成：所有 workflow 中的 prompt 已提取为独立模板文件
- vibe-agent.yml 使用 load-prompt Action 加载模板
- 支持变量替换，便于维护和版本控制
- 模板位置：.github/prompts/agents/vibe/
✅ 统一 Agent 入口优化：
- vibe-agent.yml 重构，支持 /agent ui|be|fe 统一命令格式
- 兼容旧命令：/agent-ui, /agent-be, /agent-fe
- 支持 --spec #123 参数指定 UI Spec 来源
- UI Spec 输出到 docs/specs/issue-{number}-ui.md，避免评论折叠
✅ 工作流和前端路由系统重构：优化任务路由逻辑和前端代码生成流程
✅ 每日维护工作流调整：改为每天凌晨 3:00（北京时间）执行，支持手动触发

2026-01-17

✅ 工作流简化：
- 禁用复杂度路由系统：vibe-router.yml, agent-simple.yml, agent-medium.yml, agent-complex.yml
- 统一使用 vibe-agent.yml 作为唯一 Agent 入口
- 当前保留 12 个活跃 workflow、2 个 Actions
✅ 目录结构优化：
- 整合前端 prompt：合并 fe/system-prompt.md 到 fe-codegen.md
- 清理冗余文件：删除未使用的 scripts、prompts 和 actions
✅ 工作流优化：
- 新增可复用 Composite Actions：load-prompt, context-discovery
- 重构多个工作流：从配置文件读取配置，添加重试机制

2026-01

✅ 创建 vibe-agent.yml：统一 Agent 入口，支持 UI/Spec/BE/FE 四种模式
✅ 创建 update-prd-status.yml：实现 Issue 状态自动同步
✅ 创建 parent-child-issue-guard.yml：管理父子 Issue 关系
✅ 创建 vibe-continuous.yml：任务监控与自动迭代引擎
✅ 实现 AI 对话面板 (Chat Console) 前端功能
✅ 重写项目文档，包含完整的工作流系统说明

2024-2025

✅ 初始版本，包含所有核心工作流
✅ 支持 OpenRouter 集成
✅ 支持功能分支管理
✅ 支持自动错误分析和修复
✅ 完整的文档和示例

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🙏 致谢

OpenRouter - AI API 服务
Claude Code Action - 代码生成工具
Base.org - 设计系统灵感
shadcn/ui - UI 组件库

📮 联系方式

Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ using AI-Native Development Workflow

快速开始 • 工作流文档 • 部署指南

Name		Name	Last commit message	Last commit date
Latest commit History 485 Commits
.claude		.claude
.github		.github
api		api
backend		backend
docs		docs
frontend		frontend
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
README.md		README.md
TEST_AUTH_FLOW.md		TEST_AUTH_FLOW.md
Untitled		Untitled
delete_issues.html		delete_issues.html
delete_issues.sh		delete_issues.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
railway.toml		railway.toml
render.yaml		render.yaml

Folders and files

Latest commit

History

Repository files navigation

🌊 Vibe Engineering Playbook

✨ 核心特性

🤖 AI Agent 工作流

🔄 自动化工作流

📊 智能管理

🏗️ 技术栈

前端

后端

AI & 自动化

🚀 快速开始

1. 克隆项目

2. 配置 GitHub Secrets

3. 本地开发

后端

前端

4. 创建第一个 Issue

📖 工作流系统

工作流分类

🤖 核心 Agent 工作流（1个）

🔄 Issue 管理工作流（3个）

⚡ 自动化工作流（3个）

🔍 监控和错误处理（4个）

📋 其他工作流（1个）

常用命令

查看工作流运行状态

完整工作流文档

📁 项目结构

🎯 使用流程

典型开发流程

1. 创建需求 Issue

2. 使用 Agent 命令

3. 代码生成和 PR

4. 审查和合并

5. 部署和监控

🛠️ 开发指南

后端开发

前端开发

🚢 部署

后端部署（Railway）

前端部署（Vercel）

📚 文档

核心文档

开发规范

模板和示例

🔧 配置说明

环境变量

后端（Railway）

前端（Vercel）

GitHub Secrets

工作流配置

🎨 设计系统

核心原则

颜色系统

🤝 贡献指南

提交 Issue

提交 PR

代码规范

🐛 故障排查

Agent 失败

构建错误

任务超时

部署失败

📊 项目统计

📝 更新日志

2026-01-17

2026-01-17

2026-01

2024-2025

📄 许可证

🙏 致谢

📮 联系方式

About

Resources

Uh oh!

Stars

Watchers

Packages