aiblueprinthq/ai-blueprint

A file-backed, spec-driven AI coding workflow framework for building real software while staying in control.

AI Blueprint – 基于文件的 AI 辅助编码工作流

它是什么 – AI Blueprint 是一个框架，可叠加在任何现有代码库之上，为大型语言模型（LLM）编码助手提供结构化、文件驱动的工作流。它不替代您的应用程序框架；而是记录 AI 代理（例如 OpenAI Codex、Anthropic Claude Code、GitHub Copilot、Google Antigravity、OpenCode）应遵循的规划、规范、验证和审查步骤。

为什么重要 – 当 AI 直接在聊天中生成代码时，意图、正确性证据和审查历史往往会丢失。Blueprint 将这些工件变成永久文件（规范、发现、审计记录、历史），与源代码并存，并通过 Git 进行版本控制。

核心概念

概念	工作原理
项目计划与构建计划	人工编写的 Markdown 文件（`blueprint/project-plan.md`、`blueprint/build-plan.md`），描述产品方向和有序的功能列表。
上下文文件	从计划生成：`project-overview.md`、`current-feature.md`、`findings.md`、`review.md`。所有适配器读取相同的文件，因此您可以在 Codex、Claude 等之间切换。
工作流命令	五个主要步骤，每个步骤作为聊天技能（`/feature`、`/implement`、`/check`、`/audit`、`/complete`）公开。命令创建或更新上下文文件，并可选择暂停以进行人工审查。
仪表板	本地只读 Web UI（`blueprint dashboard`），实时可视化路线图、活动工作项、发现和 Git 状态。
Git 集成	Blueprint 将每个完成的工作项记录为单个提交（或拉取请求分支），并可强制执行门禁，例如在合并前进行独立审查。

典型工作流（快速入门）

搭建应用（例如，npx create-next-app my-app）。

初始化 Git 并安装 Blueprint：

npx create-ai-blueprint@latest   # 或 pnpm dlx …

入门 – 运行 onboard 技能，让 Blueprint 了解您的技术栈、命令和首选适配器。
编写计划 – 编辑 blueprint/project-plan.md 和 blueprint/build-plan.md（或通过可选的 discovery 技能生成）。
概览 – 运行 overview 将计划转换为持久的上下文文件，并获得跟踪的检查清单。
功能周期 – 对于每个项目：
- feature → 创建规范并等待您的批准。
- implement → 以小而可见的步骤构建规范，并提供演练。
- check → 针对规范运行实际应用程序以证明验收。
- audit → 记录任何发现；未解决的 P0/P1 阻止完成。
- complete → 运行最终门禁，归档工作，并请求合并/拉取请求批准。

支持的 AI 适配器

Codex（OpenAI）
Claude Code（Anthropic）
GitHub Copilot
Google Antigravity
OpenCode
任何其他可以读取 Blueprint Markdown 契约的“文件感知”编码代理。

主要功能

规范优先开发 – 代理必须在编写代码之前生成经过审查的规范。
文件支持的状态 – 所有规范、发现、审计记录和历史都以纯 Markdown 文件形式存储在仓库中。
人工参与的门禁 – 可配置的审查策略（manual、when-sensitive 等）以及合并、部署和破坏性操作的明确批准步骤。
并行工作支持 – 鼓励为并发代理使用单独的 Git 工作树/分支。
实时本地仪表板 – 路线图、活动工作和审计状态的视觉概览。
可扩展 CLI – npx create-ai-blueprint@latest <command>（例如，dashboard、status、doctor）。
CI 集成 – ci 命令可以生成 GitHub Actions 工作流，运行与本地相同的 Verify 命令。

适用人群

已经依赖 LLM 编码助手并希望实现可重现、可审计开发的团队。
监管或安全要求需要文档化规范和独立审查的项目。
希望在不更改现有技术栈的情况下采用纪律性“AI 结对编程”工作流的独立开发者。

成熟度与生态系统

包 – 在 npm 上发布为 create-ai-blueprint（README 中显示最新版本徽章）。
文档与演示 – 官方网站（ai-blueprint.dev）、完整文档和 YouTube 演示视频。
CI 状态 – GitHub Actions 徽章表示每次推送时运行验证工作流。
许可证 – MIT，允许商业和私人使用。
社区 – 没有明确提及社区论坛，但仓库包含变更日志、发布页面和问题跟踪器以获取反馈。

快速要点

AI Blueprint 不是新的编程语言或 AI 模型；它是一个工作流层，使 AI 生成的代码可追溯和可审查。
它适用于任何技术栈，因为它只操作 Markdown 文件和 Git。
该方法规范驱动、文件支持且以人为中心，旨在保持产品意图可见和可验证，同时利用 AI 编码代理。