bkit Vibecoding Kit for OpenAI Codex - PDCA + Context Engineering for AI-native development
이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.
PDCA 방법론 + 컨텍스트 엔지니어링을 통한 AI 네이티브 개발
bkit-codex는 OpenAI Codex CLI 확장 도구로, AI와 함께 소프트웨어를 구축하는 방식을 혁신합니다. PDCA(Plan-Do-Check-Act) 방법론과 컨텍스트 엔지니어링 아키텍처를 통해 구조화된 개발 워크플로우, 자동 문서화, 지능형 코드 지원을 제공합니다.
컨텍스트 엔지니어링은 최적의 LLM 추론을 위한 컨텍스트 토큰의 체계적인 큐레이션입니다. 단순한 프롬프트 작성 이상으로, AI 동작을 일관되게 안내하는 전체 시스템을 구축합니다.
전통적인 프롬프트 엔지니어링:
"좋은 프롬프트를 작성하는 기술"
컨텍스트 엔지니어링:
"프롬프트, 도구, 상태를 통합하여 LLM에 최적의 컨텍스트를 제공하는
시스템을 설계하는 기술"bkit은 컨텍스트 엔지니어링의 실용적인 구현체로, 여러 AI 코딩 플랫폼에서 체계적인 컨텍스트 관리 시스템을 제공합니다.
bkit-codex는 세 가지 상호 연결된 계층을 통해 컨텍스트 엔지니어링을 구현합니다:
| 계층 | 구성 요소 | 개수 | 목적 | ||
|---|---|---|---|---|---|
| 도메인 지식 | 스킬 | 27 | 점진적 공개를 통해 필요 시 활성화되는 구조화된 전문 지식 | ||
| 동작 규칙 | AGENTS.md | 2개 파일 | MUST/ALWAYS/NEVER 강제를 포함한 전역 + 프로젝트 규칙 | ||
| 상태 관리 | MCP 도구 + 라이브러리 모듈 | 16개 도구 + 80개 함수 | PDCA 상태 추적, 의도 감지, 템플릿 관리, 메모리 지속성, 컨텍스트 복구 |
+------------------------------------------------------------------+
| 계층 1: AGENTS.md |
| (항상 로드됨) |
| |
| 전역 AGENTS.md (~3.8 KB) 프로젝트 AGENTS.md (~2.0 KB) |
| - 세션 초기화 - 레벨별 가이드 |
| - 3가지 핵심 원칙 - 주요 스킬 참조 |
| - PDCA 워크플로 규칙 - 응답 형식 규칙 |
| - MCP 도구 참조 - PDCA 상태 위치 |
| - 코드 품질 표준 |
| |
| 총합: ~5.8 KB / 32 KB 제한 (18% 사용, 82% 사용 가능) |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| 계층 2: SKILL.md |
| (요청 시 로드) |
| |
| 단계 1: 이름 + 설명만 (메타데이터 스캔) |
| 단계 2: 전체 SKILL.md 본문 (스킬이 활성화될 때) |
| 점진적 공개로 컨텍스트 사용 최소화 |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| 계층 3: references/ |
| (요청 시 심층 탐색) |
| |
| ~30개 참조 파일 (템플릿, 패턴, 체크리스트) |
| AI가 명시적으로 참조 파일을 요청할 때만 로드 |
+------------------------------------------------------------------+bkit-claude-code (훅 기반, 100% 자동)
훅 이벤트 --> 스크립트 (stdin/stdout) --> 결정: 허용/차단
= 시스템이 AI를 제어
bkit-codex (명령 기반, ~70% 자동)
AGENTS.md 규칙 --> AI가 읽음 --> AI가 MCP 도구 호출 --> MCP가 가이드 반환
= AI가 자발적으로 규칙을 따름bkit-codex/
|--.agents/skills/ # 27개 Codex 에이전트 스킬
| |-- bkit-rules/ # 핵심 규칙 참조
| |-- pdca/ # PDCA 워크플로 관리
| |-- bkit-templates/ # 템플릿 선택
| |-- starter/ # 초보자 가이드
| |-- dynamic/ # 풀스택 가이드
| |-- enterprise/ # 엔터프라이즈 가이드
| |-- development-pipeline/# 9단계 개요
| |-- phase-1-schema/... phase-9-deployment/
| |-- code-review/ # 코드 품질 분석
| |-- zero-script-qa/ # 로그 기반 테스트
| |-- mobile-app/ # React Native, Flutter, Expo
| |-- desktop-app/ # Electron, Tauri
| |-- codex-learning/ # Codex CLI 가이드
| |-- plan-plus/ # 브레인스토밍 강화 계획
| +-- bkend-*/ # bkend.ai 생태계 (5개 스킬)
|
|-- packages/mcp-server/ # MCP 서버 (외부 의존성 제로)
| |-- index.js # STDIO 전송 (JSON-RPC 2.0)
| |-- src/server.js # 요청 디스패처
| |-- src/tools/ # 16개 MCP 도구 구현
| +-- src/lib/ # 핵심 라이브러리 (~80개 함수)
| |-- core/ # config, cache, file, path
| |-- pdca/ # status, level, phase, automation, template
| |-- intent/ # language, trigger, ambiguity
| +-- task/ # classification, creator
|
|-- AGENTS.md # 프로젝트 AGENTS.md (샘플)
|-- agents.global.md # 전역 AGENTS.md (~/.codex/에 설치)
|-- bkit.config.json # 중앙 집중식 설정
|-- install.sh # Unix/Mac 설치 스크립트
|-- install.ps1 # Windows 설치 스크립트
|-- scripts/sync-deploy.sh # 개발-배포 동기화 유틸리티
|-- docs/ # 문서
+--.github/workflows/ # CI/CD (npm publish)node_modules 없음)docs/.bkit-memory.json을 통한 세션 간 지속적 컨텍스트참고: bkit-codex는 OpenAI Codex CLI용으로 설계되었습니다. Claude Code용은 bkit-claude-code를, Gemini CLI용은 bkit-gemini를 참조하세요.
curl -fsSL https://raw.githubusercontent.com/popup-studio-ai/bkit-codex/main/install.sh | bashirm https://raw.githubusercontent.com/popup-studio-ai/bkit-codex/main/install.ps1 | iex# 1. 프로젝트에 클론
git clone --depth 1 https://github.com/popup-studio-ai/bkit-codex.git.bkit-codex
# 2. 스킬 링크
mkdir -p.agents/skills
for skill in.bkit-codex/.agents/skills/*/; do
ln -sf "../../.bkit-codex/.agents/skills/$(basename $skill)" ".agents/skills/$(basename $skill)"
done
# 3. AGENTS.md 복사
cp.bkit-codex/AGENTS.md./AGENTS.md
# 4. MCP 서버 설정
mkdir -p.codex
cat >.codex/config.toml << 'EOF'
[mcp_servers.bkit]
command = "node"
args = ["./.bkit-codex/packages/mcp-server/index.js"]
startup_timeout_sec = 10
tool_timeout_sec = 60
required = true
EOF
# 5. PDCA 디렉토리 생성
mkdir -p docs/01-plan/features docs/02-design/features docs/03-analysis docs/04-report# 스킬이 링크되었는지 확인
ls.agents/skills/
# MCP 설정 확인
cat.codex/config.toml
# Codex 시작 및 bkit 호출
$pdca status$pdca plan <feature> # 계획 문서 생성
$pdca design <feature> # 설계 문서 생성
$pdca do <feature> # 구현 가이드
$pdca analyze <feature> # 갭 분석 실행
$pdca iterate <feature> # 평가자-최적화자 패턴으로 자동 수정
$pdca report <feature> # 완료 보고서 생성
$pdca status # 현재 PDCA 상태 확인
$pdca next # 다음 PDCA 단계 안내$starter # 정적 웹사이트 (스타터 레벨)
$dynamic # BaaS를 사용한 풀스택 (다이내믹 레벨)
$enterprise # K8s를 사용한 마이크로서비스 (엔터프라이즈 레벨)$development-pipeline # 9단계 파이프라인 개요
$phase-1-schema # 스키마 및 용어 정의
$phase-2-convention # 코딩 규칙
$phase-3-mockup # UI/UX 목업
$phase-4-api # API 설계
$phase-5-design-system # 디자인 시스템
$phase-6-ui-integration # UI 통합
$phase-7-seo-security # SEO 및 보안
$phase-8-review # 코드 리뷰
$phase-9-deployment # 배포$code-review # 코드 품질 분석
$zero-script-qa # 로그 기반 테스트 (Zero Script QA)
$codex-learning # Codex CLI 설정 가이드bkit이 강제하는 핵심 개발 사이클:
Plan ──> Design ──> Do ──> Check ──> Act ──> Report
│ │ │
│ (설계 필수) │ (90% 미만 시)
│ │ │
X──── Do로 건너뛰기 ──X +─────────+
반복 루프
(최대 5회)| 단계 | 동작 | 산출물 | ||
|---|---|---|---|---|
| Plan | 목표, 범위, 성공 기준 정의 | docs/01-plan/features/{feature}.plan.md |
||
| Design | 아키텍처, 데이터 모델, API 명세 | docs/02-design/features/{feature}.design.md |
||
| Do | 사전/사후 쓰기 검사를 포함한 구현 | 설계와 일치하는 소스 코드 | ||
| Check | 갭 분석 (설계 vs 구현) | docs/03-analysis/{feature}.analysis.md |
||
| Act | 일치율 >= 90%가 될 때까지 갭 자동 수정 | 업데이트된 소스 코드 | ||
| Report | 메트릭이 포함된 완료 보고서 | docs/04-report/{feature}.report.md |
mode: "recovery"로 bkitgetstatus를 호출하여 상태 재구성