AI Blueprint는 파일 기반이며 사양(spec)-주도적인 AI 코딩 워크플로우 프레임워크입니다. 이 도구는 코딩 에이전트에게 계획, 구축, 검증 등 체계적인 공유 워크플로우를 제공하여 실제 소프트웨어 개발을 가능하게 합니다. 모든 작업 기록은 채팅 메모리가 아닌 프로젝트 내 파일로 영구 보존됩니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI Blueprint는 코딩 에이전트에게 계획(planning), 구축(building), 검증(verifying), 그리고 한 번에 하나의 기능을 문서화하기 위한 공유 워크플로우 프레임워크를 제공합니다. 계획(plans), 사양(specs), 발견 사항(findings), 검토 증거(review evidence), 그리고 완료된 이력(completed history)은 이를 생성한 채팅과 함께 사라지는 대신, 프로젝트 내에 읽을 수 있는 파일로 유지됩니다.
모든 애플리케이션 스택에서 작동합니다. 지원되는 어댑터에는 Codex, Claude Code, GitHub Copilot이 포함됩니다. Google Antigravity와 OpenCode도 지원됩니다. 다른 파일 인식 코딩 에이전트(file-aware coding agents)는 읽기 쉬운 워크플로우 파일(workflow files)을 따를 수 있습니다. AI Blueprint는 애플리케이션 프레임워크를 대체하거나 애플리케이션 코드를 추가하지 않습니다.
아래의 스캐폴드 우선 방식(Quick Start)으로 시작하세요.
제품 의도가 채팅에만 존재하고 여러 기능이 혼재되며, "작동한다" 또는 "테스트되었다"와 같은 주장이 관찰 가능한 증거로 뒷받침되지 않을 때 AI 코딩은 신뢰성이 떨어집니다.
Blueprint는 제어된 루프를 추가합니다:
핵심은 판단을 제거하는 것이 아닙니다. AI가 코드를 작성하도록 돕는 동안에도 판단을 보존하는 것입니다.
AI Blueprint는 프로젝트 주변에 AI 코딩 워크플로우 프레임워크를 추가합니다. 이는 애플리케이션 스타터가 아니며, 사용자의 애플리케이션 프레임워크를 대체하지 않습니다. 설치하기 전에 먼저 앱을 스캐폴딩(scaffolding)하고 Git을 초기화하세요.
요구 사항: Node.js 22 이상 버전, 기존 애플리케이션, 그리고 Git 저장소.
먼저 선택한 프레임워크나 언어의 스캐폴딩 CLI를 사용하거나 수동으로 애플리케이션을 생성합니다. 이 예시는 Next.js를 사용하지만, Blueprint는 모든 스택에서 작동합니다. 새 애플리케이션의 루트 디렉토리에서 스캐폴더가 초기화하지 않았다면 Git을 초기화한 다음, Blueprint를 설치하세요:
npx create-next-app@latest my-app
cd my-app
git init
프로젝트의 패키지 관리자에 맞는 명령어를 선택하세요:
# npm
npx create-ai-blueprint@latest
...
devEngines.packageManager를 통해 pnpm을 강제하는 프로젝트는 Blueprint가 시작되기 전에 EBADDEVENGINES 오류와 함께 npx를 거부할 수 있습니다. 해당 프로젝트에서는 pnpm dlx를 사용하세요. 패키지 관리자 요구 사항은 제거하지 마십시오.
나머지 npx create-ai-blueprint@latest 예시들도 동일한 명령어와 옵션을 유지하며 pnpm dlx create-ai-blueprint@latest로 작동합니다.
다음 단계:
onboard를 실행하여 Blueprint가 실제 스택, 명령어, 컨벤션, 어댑터 설정 및 원하는 워크플로우 가시성을 학습하도록 합니다.blueprint/project-plan.md와 blueprint/build-plan.md를 직접 작성하거나, 선택적 디스커버리(discovery) 스킬을 사용하여 대화를 통해 개발할 수 있습니다. 빌드 계획의 경우 단순한 기능 목록만으로 충분합니다.overview를 실행하여 해당 목록을 범위나 순서를 변경하지 않고 추적 가능한 체크리스트로 형식화한 다음, 영구적인 프로젝트 컨텍스트(context)를 생성합니다. 형식화는 추가 승인이 필요 없지만, 불분명한 범위나 순서는 필요합니다. 첫 번째 실행 시에는 Blueprint 설정 및 계획에 대한 검토된 로컬 커밋을 제공합니다.feature를 실행하고, 생성된 사양(spec)을 검토한 후 구현을 시작합니다.터미널에서 위의 npx 명령어를 실행하세요. 도구에 맞는 호출 스타일을 사용하여 AI 코딩 채팅에서 onboard와 같은 워크플로우 스킬(workflow skills)을 실행합니다:
| Tool | Example |
|---|---|
| Codex | $onboard, $overview, $feature |
| ... | |
대화형 설치 프로그램(interactive installer)을 사용하면 하나 이상의 어댑터(adapter)를 선택할 수 있습니다. 이 프로그램은 해당 도구들이 필요로 하는 워크플로우 파일을 추가하며, 애플리케이션의 README.md 파일은 그대로 유지합니다. |
모든 AI 도구에 대한 규칙과 원치 않는 AI 시그니처를 줄이는 선택적 설정은 [Commit and PR attribution]을 참조하세요.
전체 설치 및 온보딩(onboarding) 워크스루는 [Getting Started]에서 확인하세요. 이미 출시된 기능을 가진 프로젝트의 경우, [Adopting an Existing Codebase]부터 시작하세요.
먼저 이 다섯 가지 명령어를 학습하세요:
/feature -> /implement -> /check -> /audit current -> /complete
AI Blueprint fresh-project workflow
각 단계는 명확한 임무를 가지고 있습니다:
이것은 새로운 게이트 정책이 아니라 학습 경로입니다. Audit와 Check는 기본값으로 manual로 설정되며, 독립적인 검토(independent review)는 when-sensitive가 기본값이고, Try It Now는 when-testable이 기본값입니다. 프로젝트에 필요한 검사 및 검토를 실행하세요. 여기서 Audit를 보여준다고 해서 모든 기능에 필수적이라는 의미는 아닙니다.
선택적 명령어인 /explore <주제>는 작업 계획 전에 아이디어를 실제 코드와 비교 평가합니다. 파일 작성이나 계획이 필요하지 않으며, 아무것도 하지 않는 옵션을 포함하여 여러 옵션을 비교합니다. 대신 기존에 계획된 기능을 설명하려면 /brief를 사용하세요.
다른 작업들은 동일한 제어 루프(control loop)를 거칩니다:
fix를 사용합니다.debug를 사용합니다.fix를 사용합니다. 이 기능의 원래 아카이브(archive)는 기록에 남아 있습니다.check guide를 사용합니다.전체 라이프사이클과 명령어별 동작 방식은 Core Workflow를 읽어보세요.
Blueprint는 체크아웃(checkout)당 하나의 활성 작업 항목을 유지합니다. 병렬로 작업하려면 각 개발자나 에이전트에게 별도의 클론(clone) 또는 자체 브랜치(branch)를 가진 Git worktree를 제공해야 합니다. 각 체크아웃 내부에서 일반 워크플로우를 실행하세요. 동일한 작업 디렉터리 내에서 두 개의 활성 작업 항목을 실행하지 마십시오.
Blueprint가 기록할 브랜치에 worktree를 생성합니다. 기본 브랜치 접두사(default branch prefix)를 가진 Export reports라는 계획된 항목의 경우:
git worktree add ../my-app-export-reports -b feature/export-reports main
해당 디렉터리에서 병렬 AI 세션을 열고, 그곳에서 /feature "Export reports"를 실행합니다. worktree 생성은 명시적인 Git 작업으로 남아 있으며, Blueprint가 자동으로 worktree를 생성하거나 제거하지 않습니다.
단독 프로젝트는 설정 변경이 필요 없습니다. 풀 리퀘스트(pull request)를 통해 도착하는 저장소의 경우, blueprint/config.json을 통해 옵트인할 수 있습니다:
"git": {
"landing": "pull-request"
}
이 설정으로 /complete를 사용하면 여전히 동일한 게이트(gate)가 실행되고 동일한 작업 커밋(work commit)이 생성됩니다. 그런 다음 작업 브랜치를 푸시하고 풀 리퀘스트를 열도록 승인을 요청합니다. 이는 결코 해당 요청을 병합하거나 자동 병합(auto-merge)을 활성화하지 않습니다. 하나의 작업 항목이 기본 브랜치 커밋 하나로 남으려면, 반드시 스쿼시 병합(squash-merged)되어야 합니다.
병렬 브랜치도 여전히 blueprint/build-plan.md에서 충돌할 수 있습니다. 이는 일반적인 풀 리퀘스트(pull-request) 통합 흐름을 통해 해결해야 합니다. Blueprint는 항목별 상태 폴더를 추가하거나 에이전트를 자동으로 조정하지 않습니다.
로드맵, 현재 작업, 발견 사항 및 다음 조치를 하나의 로컬 브라우저 뷰에서 확인하세요. 대시보드는 Blueprint 파일과 Git 상태가 변경됨에 따라 새로 고침되며, 프로젝트 진행 상황과 함께 빌드 단계(build steps), 명령어 활동(command activity), 검토 게이트(review gates), 완료된 이력(completed history)을 표시합니다.
Angled AI Blueprint dashboard preview showing Article Reach project health, roadmap progress, and Git state
Blueprint 프로젝트에서 실행하세요:
npx create-ai-blueprint@latest dashboard
선택적 전역 CLI가 설치된 경우, 대신 blueprint dashboard를 사용하세요. 대시보드는 브라우저에서 열리고, 127.0.0.1에 바인딩되며, Ctrl+C를 누르면 중지됩니다. 이는 읽기 전용이며 애플리케이션을 시작하거나 워크플로우 명령을 실행하지 않습니다.
전체 투어 및 명령어 옵션은 Local Dashboard에서 확인하세요.
| 원하는 것 | 시작하기 |
|---|---|
| "대시보드에 캐싱을 적용하는 것이 도움이 될까요?" | /explore would caching help our dashboard? |
| ... |
Explore는 계획을 요구하지 않고 가능성을 조사합니다. Brief는 빌드 플랜에 이미 있는 항목을 설명합니다. 둘 다 파일을 작성하지 않으며, Explore는 프로젝트 코드를 절대 실행하지 않습니다. Verify는 프로젝트의 반복 가능한 자동화 게이트(automated gate)를 실행합니다. Check는 사양(spec)에 따라 동작을 테스트합니다. Guide는 작업이 테스트 가능할 때 작은 '지금 시도해보기 (Try It Now)' 데모를 생성하며, 요청 시 더 깊은 워크스루(walkthrough)를 제공할 수 있습니다. 이는 검사를 실행하거나, 활동 상태를 작성하거나, 승인을 기록하거나, 작업을 검증된 것으로 표시하지 않습니다. Audit은 코드를 검토하고 발견 사항을 기록합니다. 깨끗한 검토가 애플리케이션이 작동한다는 것을 증명하지는 않습니다.
선택된 각 어댑터에는 20가지 스킬이 모두 설치됩니다. 이 그룹들은 명령어를 찾는 데 도움을 주며, 새로운 설치 모드나 구성을 추가하지는 않습니다. 예시에서는 AI 채팅에서 Claude Code 슬래시 명령어(slash commands)를 사용합니다. Codex는 일치하는 $skill 형식을 사용하며, 다른 어댑터들은 일반 언어(plain language)를 통해 이름 지정된 스킬을 실행할 수 있습니다.
| 스킬 | 목적 |
|---|---|
| /feature | 하나의 빌드 계획 항목(build-plan item)을 승인을 위한 명세서(spec)로 변환합니다. |
| ... |
| 스킬 | 목적 |
|---|---|
| /explore | 파일을 작성하거나 계획이 필요하지 않은 상태에서 코드를 기반으로 아이디어를 조사합니다. |
| ... |
| 스킬 | 목적 |
|---|---|
| /onboard | 새로운 Blueprint 설치를 실제 프로젝트에 맞게 조정(tune)합니다. |
| ... |
| 스킬 | 목적 |
|---|---|
| /fix | 작고 계획되지 않은 변경 사항이나 확인된 버그에 대한 명세서를 작성합니다. |
| 스킬 | 목적 |
|---|---|
| /autopilot | 명시적인 명세서(spec)와 구현 패스 하나를 설정된 게이트(gates)를 통해 실행하되, 완료 전에 중지합니다. |
| /continuous | 검토된 빌드 계획 항목들을 로컬 Git 작업을 통해 순차적으로 완료하며, 절대 푸시하거나 배포하지 않습니다. |