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으로 버전 관리되는 영구 파일(사양, 발견 사항, 감사 기록, 기록)로 만듭니다.
핵심 개념
| 개념 | 작동 방식 |
|---|---|
| 프로젝트 계획 및 빌드 계획 | 제품 방향과 순서가 지정된 기능 목록을 설명하는 사람이 작성한 마크다운 파일(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)로 노출되는 5가지 주요 단계. 명령은 컨텍스트 파일을 생성하거나 업데이트하고 선택적으로 인간 검토를 위해 일시 중지합니다. |
| 대시보드 | 로드맵, 활성 작업 항목, 발견 사항, Git 상태를 실시간으로 시각화하는 로컬 읽기 전용 웹 UI(blueprint dashboard). |
| 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 마크다운 계약을 읽을 수 있는 기타 "파일 인식" 코딩 에이전트.
주요 기능
- 사양 우선 개발 – 에이전트는 코드를 작성하기 전에 검토된 사양을 생성해야 합니다.
- 파일 기반 상태 – 모든 사양, 발견 사항, 감사 기록, 기록이 리포지토리의 일반 마크다운 파일로 저장됩니다.
- 인간 참여 게이트 – 구성 가능한 검토 정책(
manual,when-sensitive등) 및 병합, 배포, 파괴적 작업에 대한 명시적 승인 단계. - 병렬 작업 지원 – 동시 에이전트를 위해 별도의 Git 워크트리/브랜치를 권장합니다.
- 라이브 로컬 대시보드 – 로드맵, 활성 작업, 감사 상태의 시각적 개요.
- 확장 가능한 CLI –
npx create-ai-blueprint@latest <command>(예:dashboard,status,doctor). - CI 통합 –
ci명령은 로컬에서 사용되는 것과 동일한 Verify 명령을 실행하는 GitHub Actions 워크플로우를 생성할 수 있습니다.
누가 사용해야 하는가
- 이미 LLM 코딩 어시스턴트에 의존하고 재현 가능하고 감사 가능한 개발을 원하는 팀.
- 규제 또는 보안 문제로 문서화된 사양과 독립 검토가 요구되는 프로젝트.
- 기존 스택을 변경하지 않고 규율 있는 "AI 페어 프로그래밍" 워크플로우를 원하는 개인 개발자.
성숙도 및 생태계
- 패키지 – npm에
create-ai-blueprint로 게시됨(README에 최신 버전 배지 표시). - 문서 및 데모 – 공식 사이트(
ai-blueprint.dev), 전체 문서, YouTube 데모 비디오. - CI 상태 – GitHub Actions 배지는 푸시마다 검증 워크플로우가 실행됨을 나타냅니다.
- 라이선스 – MIT, 상업 및 개인 사용 허용.
- 커뮤니티 – 커뮤니티 포럼에 대한 명시적 언급은 없지만, 리포지토리에는 변경 로그, 릴리스 페이지, 피드백을 위한 이슈 트래커가 포함되어 있습니다.
빠른 요점
- AI Blueprint는 새로운 프로그래밍 언어나 AI 모델이 아닙니다. AI가 생성한 코드를 추적 가능하고 검토 가능하게 만드는 워크플로우 레이어입니다.
- 마크다운 파일과 Git만 조작하므로 모든 기술 스택에서 작동합니다.
- 이 접근 방식은 사양 기반, 파일 기반, 인간 중심이며, AI 코딩 에이전트를 활용하면서 제품 의도를 가시적이고 검증 가능하게 유지하는 것을 목표로 합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트