BnAI-ADK (BnAI Agentic Development Kit)

실제 IT 개발팀/유지보수팀을 Claude Code 기반 AI 시스템으로 대체

🎯 목적

• Claude Code를 목적에 적합하게 설정
• 요구사항 인터뷰부터 구현까지 체계적 관리
• 문서화 자동화 및 일관성 확보

📁 프로젝트 구조

📁 BnAI-ADK/
├── 📄 CLAUDE.md              # Claude Code 진입점
├── 📄 README.md              # 이 파일
├── 📁 .claude/               # Claude Code 설정
│   ├── 📁 agents/            # Sub-Agent 정의
│   ├── 📁 skills/            # Skill 정의
│   └── 📁 commands/          # 슬래시 명령어
├── 📁 .bnai/                 # AI 런타임 (휘발성)
└── 📁 docs/                  # 문서 (v1.6 표준)
    ├── 00_overview/          # 시스템 개요
    ├── 10_pmo/               # PMO (계획, 템플릿, RTM)
    ├── 20_interviews/        # 인터뷰 기록
    ├── 30_requirements/      # 요구사항
    ├── 40_flows/             # 업무/시스템 흐름
    ├── 50_specifications/    # 설계 명세
    ├── 60_implementations/   # 구현 계획
    ├── 70_database/          # DB, ERD
    ├── 80_standards/         # 개발/문서 표준
    ├── 90_references/        # 외부 참고자료
    └── 99_analysis/          # 분석/탐색

🚀 시작하기

설치 (NPM 패키지)

# NPM 전역 설치 (향후 지원)
npm install -g bnai-adk

# 또는 로컬 개발용
git clone https://github.com/your-org/bnai-adk
cd bnai-adk
npm install
npm link

프로젝트 초기화

# 새 프로젝트에 BnAI-ADK 적용
cd your-project
bnai init

# 또는 특정 경로에 초기화
bnai init ./new-project

업데이트

# 최신 버전으로 업데이트
cd your-project
bnai update

주요 명령어

bnai version        # 버전 확인
bnai init           # 프로젝트 초기화
bnai update         # 최신 버전으로 업데이트
bnai doctor         # 구성 검증 (향후 지원)
bnai --help         # 도움말

Claude Code에서 사용

1. bnai init으로 프로젝트 초기화
2. Claude Code 앱에서 프로젝트 열기
3. /project status로 상태 확인
4. /알프레드 {요청}으로 작업 시작

📚 핵심 문서

• 문서 인덱스
• 종합 결정 문서
• 폴더 정책
• MoAI-ADK 업데이트 가이드 🆕

🔄 버전

• v2.4.0 (2026-02-02): 기존 프로젝트 CLAUDE.md 자동 보존 (기존 프로젝트에 bnai init 시 컨텍스트 보존)
• v2.3.0 (2026-02-02): Agent LSP 통합 가이드 (architect, backend-dev, frontend-dev, qa-engineer)
• v2.2.0 (2026-02-02): LSP Integration - MoAI-ADK Python 스냅샷 통합 (16+ 언어, Ralph Engine, 스냅샷 방식)
• v2.1.0 (2026-02-02): 크로스 플랫폼 안정화 (WSL 감지, 안전한 JSON 파싱, 경로 정규화)
• v2.0.5 (2026-02-02): Hotfix - Agent 인식 문제 해결 (YAML front matter 추가)
• v2.0.0 (2026-02-01): MoAI-ADK 통합 (Phase 0 병렬탐색, Enhanced SPEC, DDD Workflow, Document Sync)
• v1.8.2 (2026-01-27): NPM 패키지 구현 (bnai init, bnai update 명령어)
• v1.6 (2026-01-21): 10단위 폴더 번호, 90_references 추가, 10_pmo 하위구조 정의

🌐 크로스 플랫폼 지원 (v2.1.0)

BnAI-ADK는 다양한 플랫폼에서 안정적으로 작동합니다:

• ✅ Windows 10/11: 네이티브 지원
• ✅ macOS: 네이티브 지원
• ✅ Linux: 네이티브 지원
• ✅ WSL (Windows Subsystem for Linux): 자동 감지 및 경로 변환

플랫폼 감지

bnai init    # 플랫폼 정보 자동 표시
bnai update  # 플랫폼 정보 자동 표시

WSL 지원

• /proc/version에서 자동 감지
• WSL 경로 자동 변환: /mnt/c/... → C:\...
• 크로스 플랫폼 경로 정규화

안전한 JSON 처리

• JSON 파싱 실패 시 기본값 반환 (크래시 방지)
• 디렉토리 자동 생성
• 상세한 에러 로그

🔍 LSP Integration (v2.2.0)

MoAI-ADK Python 스냅샷 통합 - 16+ 언어 지원, Ralph Engine (LSP + AST-grep)

핵심 특징

• ✅ 16+ 언어 지원: Python, TypeScript, JavaScript, Go, Rust, C, C++, Java, C#, Ruby, PHP, Kotlin, Swift, Scala, Lua, Zig
• ✅ Ralph Engine: LSP + AST-grep 병렬 진단 (3-5배 빠름)
• ✅ 스냅샷 방식: 패키지 의존성 없음, MoAI-ADK 소스를 직접 복사
• ✅ Node.js 브리지: Python 코드를 subprocess로 호출

사용법

Python 환경 확인

const { checkEnvironment } = require('./scripts/lsp-moai/wrapper');

const env = await checkEnvironment();
console.log(env.python.version);  // Python 3.14.2
console.log(env.moaiAdk.exists);  // true

LSP 기본 진단

const { getDiagnostics, checkProject } = require('./scripts/lsp-moai/wrapper');

// 파일 진단
const result = await getDiagnostics(__dirname, 'src/main.py');
console.log(result.summary);  // ✅ 0개 에러, 0개 경고

// 프로젝트 진단
const project = await checkProject(__dirname, {
  filePatterns: ['src/**/*.py'],
  timeout: 30000
});
console.log(project.summary);  // ✅ 타입 에러 없음

Ralph Engine 진단 (LSP + AST-grep)

const { ralphDiagnoseFile, ralphDiagnoseProject } = require('./scripts/lsp-moai/wrapper');

// 파일 진단 (LSP + AST-grep 병렬)
const file = await ralphDiagnoseFile(__dirname, 'src/main.py');
console.log(`Errors: ${file.errorCount}, Warnings: ${file.warningCount}`);

// 프로젝트 진단 (전체)
const project = await ralphDiagnoseProject(__dirname);
console.log(project.summary);

지원 언어

| 언어 | LSP 서버 | 확장자 | |------|----------|--------| | Python | pyright-langserver | .py, .pyi | | TypeScript | typescript-language-server | .ts, .tsx | | JavaScript | typescript-language-server | .js, .jsx | | Go | gopls | .go | | Rust | rust-analyzer | .rs | | C/C++ | clangd | .c, .cpp, .h | | Java | jdtls | .java | | C# | omnisharp | .cs | | Ruby | solargraph | .rb | | PHP | intelephense | .php | | Kotlin | kotlin-language-server | .kt | | Swift | sourcekit-lsp | .swift | | Scala | metals | .scala | | Lua | lua-language-server | .lua | | Zig | zls | .zig | | Bash | bash-language-server | .sh |

MoAI-ADK 스냅샷 구조

scripts/lsp-moai/
├── lsp-bridge.py          # Python CLI 인터페이스
├── wrapper.js             # Node.js 브리지
└── python/
    └── moai_adk/          # MoAI-ADK Python 스냅샷
        ├── lsp/           # LSP 클라이언트
        ├── ralph/         # Ralph Engine
        ├── astgrep/       # AST-grep 통합
        └── loop/          # 반복 개선

Agent 통합 (v2.3.0)

개발 프로세스 전체에 LSP 타입 체크가 자동으로 통합됩니다.

통합 워크플로우

architect (설계)
   ↓ LSP 품질 게이트
   ↓ errorCount === 0, warningCount <= 10
   ↓
backend-dev / frontend-dev (구현)
   ↓ LSP 실시간 검증
   ↓ 파일별 자동 타입 체크
   ↓
qa-engineer (테스트)
   ↓ LSP Strict 모드
   ↓ errorCount === 0, warningCount === 0
   ↓
✅ 배포

Agent별 LSP 기능

| Agent | 기능 | 통과 조건 | |-------|------|----------| | architect | LSP 품질 게이트 | errorCount === 0, warningCount <= 10 | | backend-dev | LSP 실시간 검증 | errorCount === 0, warningCount <= 5 | | frontend-dev | LSP 실시간 검증 | errorCount === 0, warningCount <= 3 | | qa-engineer | LSP Strict 모드 | errorCount === 0, warningCount === 0 |

자동 수정 패턴

각 Agent는 타입 에러 발견 시 자동 수정을 시도합니다:

• 타입 불일치 → 타입 수정
• 누락된 import → import 자동 추가
• 미사용 변수 → 제거 또는 @SuppressWarnings
• any 타입 → 명시적 타입 추론

효과

• ✅ 16+ 언어 타입 에러 사전 감지
• ✅ AST 패턴 매칭으로 구조적 문제 탐지
• ✅ 병렬 스캔으로 3-5배 빠른 진단
• ✅ 패키지 의존성 없음 (스냅샷 방식)
• ✅ MoAI-ADK 업데이트 시 소스만 복사하면 됨
• ✅ 전체 개발 프로세스에서 타입 안전성 보장 (v2.3.0)