MoAI-ADK (Agentic Development Kit)

MoAI-ADK

모두의AI 에이전틱 코딩 개발 프레임워크

안내: MoAI-ADK는 모두의AI 연구실에서 집필 중인 "(가칭) 에이전틱 코딩" 서적의 별책 부록 오픈 소스 프로젝트 임을 밝혀 둡니다.

"SPEC이 없으면 CODE도 없다."

목차

• Meet Alfred
• Quick Start
• The Problem
• The Solution
• How Alfred Works
• Output Styles
• Language Support
• CLI Reference
• API Reference
• TRUST 5원칙
• 문제 해결
• Support

Meet ▶◀ Alfred - Your AI Development Partner

안녕하세요, 모두의AI SuperAgent AI ▶◀ Alfred입니다!

저는 MoAI-ADK(모두의AI Agentic Development Kit)의 SuperAgent이자 중앙 오케스트레이터(Central Orchestrator) AI, Alfred입니다. MoAI-ADK는 Alfred를 포함하여 총 10개의 AI 에이전트로 구성된 에이전틱 코딩 AI 팀입니다. 저는 9개의 전문 에이전트(spec-builder, code-builder, doc-syncer 등)를 조율하여 여러분의 Claude Code 환경 속에서 공동 개발 작업을 완벽하게 지원합니다.

Alfred라는 이름의 유래: 배트맨 영화에 나오는 충실한 집사 Alfred Pennyworth에서 영감을 받아 지었다고 합니다. 집사 Alfred가 배트맨(Bruce Wayne)을 위해 모든 준비를 완벽하게 갖추고, 위험에 처했을 때 즉각적인 지원을 제공하며, 항상 한 걸음 앞서 생각하듯이, 저 또한 여러분의 개발 과정 속에서 필요한 모든 것을 미리 준비하고, 문제가 발생하면 즉시 해결책을 제시하며, 언제나 여러분이 창의적인 문제 해결에만 집중할 수 있도록 뒷받침합니다. 여러분은 코드의 "왜(Why)"에 집중하시고, "어떻게(How)"는 제가 책임지겠습니다.

🌟 흥미로운 사실: AI가 만든 AI 개발 도구

이 프로젝트의 모든 코드는 100% AI에 의해 작성되었습니다. AI가 직접 설계하고 구현한 AI 개발 프레임워크입니다.

설계 단계부터 AI 협업: 초기 아키텍처 설계 단계부터 GPT-5 Pro와 Claude 4.1 Opus 두 AI 모델이 함께 참여했습니다. 두 AI가 서로 다른 관점에서 설계를 검토하고 토론하며, 더 나은 방향을 제시하고, 최적의 아키텍처를 함께 만들어냈습니다. GPT-5 Pro는 폭넓은 사례 분석을, Claude 4.1 Opus는 깊이 있는 코드 구조 설계를 담당하며 서로 보완했습니다.

Agentic Coding 방법론의 실제 적용: 모두의AI팀이 Claude Code와 Agentic Coding 방법론을 활용하여 개발했습니다. 전통적인 방식처럼 사람이 키보드 앞에 앉아 모든 코드를 직접 타이핑하는 대신, AI 에이전트들이 SPEC을 읽고 이해하고, 테스트를 먼저 작성하고(TDD Red), 구현 코드를 만들고(TDD Green), 리팩토링하고(TDD Refactor), 문서를 동기화하는 전 과정을 자율적으로 수행했습니다. 저 Alfred와 9개 전문 에이전트로 구성된 10개 AI 에이전트 팀이 직접 .moai/specs/ 폴더에 SPEC 문서를 작성하고, tests/ 폴더에 테스트 코드를 만들고, src/ 폴더에 구현 코드를 작성했습니다.

100% AI 생성 코드의 진실: 이 프로젝트는 100% AI로 만들어진 오픈소스이기 때문에, 코드베이스에서 다소 정리되지 않은 부분이나 개선이 필요한 영역이 보일 수 있습니다. 하지만 이것이 이 프로젝트의 핵심 철학입니다.

투명성과 지속적 개선: 완벽하지 않은 코드를 숨기는 대신, AI 개발 도구가 실제로 어떻게 만들어지는지 그대로 보여주고, 커뮤니티와 함께 더 나은 방향으로 발전시켜 나가고자 합니다. 여러분의 사용 경험과 피드백이 이 프로젝트를 더욱 강력하게 만듭니다. GitHub Issues나 Discussions에 피드백을 남겨주시면, 최대한 빠르게 업데이트하고 배포할 것을 약속드립니다. AI가 만든 도구를 함께 더 나은 도구로 만들어가는 여정에 동참해주세요!

▶◀ Alfred가 제공하는 4가지 핵심 가치

1️⃣ 일관성(Consistency): 플랑켄슈타인 코드를 방지하는 3단계 파이프라인

Alfred는 모든 개발 작업을 SPEC → TDD → Sync라는 3단계 파이프라인으로 표준화합니다. 월요일에 ChatGPT로 만든 코드, 수요일에 Claude로 만든 코드, 금요일에 Gemini로 만든 코드가 서로 다른 스타일, 네이밍 규칙, 아키텍처 패턴을 가지는 "플랑켄슈타인 코드"의 문제를 원천적으로 차단합니다.

2️⃣ 품질(Quality): TRUST 5원칙으로 자동 보장되는 코드 품질

Alfred는 모든 코드에 TRUST 5원칙(Test First, Readable, Unified, Secured, Trackable)을 자동으로 적용하고 검증합니다. 사람이 일일이 체크리스트를 들고 확인할 필요가 없습니다.

3️⃣ 추적성(Traceability): 6개월 후에도 "왜"를 찾을 수 있는 @TAG 시스템

Alfred의 @TAG 시스템은 모든 코드 조각을 @SPEC:ID → @TEST:ID → @CODE:ID → @DOC:ID로 완벽하게 연결합니다. 6개월 후 누군가 "왜 이 함수는 이렇게 복잡하게 구현했나요?"라고 물어보면, @TAG를 따라가면 답을 찾을 수 있습니다.

4️⃣ 범용성(Universality): 한 번 배우면 어디서나 쓸 수 있는 워크플로우

Alfred는 특정 언어나 프레임워크에 종속되지 않습니다. Python, TypeScript, Java, Go, Rust, Dart, Swift, Kotlin 등 모든 주요 프로그래밍 언어를 지원하며, 각 언어에 최적화된 도구 체인을 자동으로 선택합니다.

🚀 Quick Start (3분 실전)

📋 준비물

• ✅ Bun 또는 npm 설치됨
• ✅ Claude Code 실행 중
• ✅ Git 설치됨 (선택사항)

⚡ 3단계로 시작하기

1️⃣ 설치 (30초)

# Bun 권장 (5배 빠른 성능)
curl -fsSL https://bun.sh/install | bash
bun add -g moai-adk

# 또는 npm 사용
npm install -g moai-adk

# 설치 확인
moai --version
# 출력: v0.x.x

2️⃣ 초기화 (1분)

터미널에서:

# 새 프로젝트 생성
moai init my-project
cd my-project

# 기존 프로젝트에 설치
cd existing-project
moai init .

# Claude Code 실행
claude

Claude Code에서 (필수):

/alfred:0-project

Alfred가 자동으로 수행:

• .moai/project/ 문서 3종 생성 (product/structure/tech.md)
• 언어별 최적 도구 체인 설정
• 프로젝트 컨텍스트 완벽 이해

3️⃣ 첫 기능 개발 (1분 30초)

Claude Code에서 3단계 워크플로우 실행:

# SPEC 작성
/alfred:1-spec "JWT 기반 사용자 로그인 API"

# TDD 구현
/alfred:2-build AUTH-001

# 문서 동기화
/alfred:3-sync

🎉 완료!

생성된 것들:

• ✅ .moai/specs/SPEC-AUTH-001/spec.md (명세)
• ✅ tests/auth/login.test.ts (테스트)
• ✅ src/services/auth.ts (구현)
• ✅ docs/api/auth.md (문서)
• ✅ @SPEC → @TEST → @CODE → @DOC TAG 체인

🚨 The Problem - 바이브 코딩의 한계

AI 도구(Codex, Claude, Gemini)로 빠르게 코딩하는 시대가 열렸습니다. 개발 속도는 확실히 빨라졌지만, 새로운 종류의 문제들이 생겨났습니다.

1. 아름답지만 작동하지 않는 코드

문제 상황: AI가 생성한 코드는 문법적으로 완벽하고 구조도 우아합니다. 하지만 실제로 실행해보면...

• 컴파일은 되지만 런타임에 undefined 에러
• 엣지 케이스 처리 부족 (빈 배열, null 값, 네트워크 타임아웃)
• 성능 문제 (O(n³) 복잡도)
• 의존성 지옥 및 보안 취약점

2. 플랑켄슈타인 코드의 탄생

문제 상황: 여러 AI 도구를 번갈아 사용하거나, 같은 AI라도 다른 세션에서 코드를 생성하다 보면 일관성 없는 코드베이스가 만들어집니다.

• 일관성 없는 코딩 스타일 (함수형, 객체지향, 절차형 혼재)
• 중복 로직 난무 (validateEmail(), checkEmailFormat(), isEmailValid())
• 아키텍처 붕괴 (MVC, Hexagonal, Clean Architecture 혼재)

3. 디버깅 지옥

문제 상황: 프로덕션에서 버그가 발생했을 때, 원인을 찾는 것이 거의 불가능합니다.

• 원인 추적 불가 (AI 채팅 히스토리 삭제됨)
• 사이드 이펙트 파악 불가 (테스트 부재)
• 문서 없음 (outdated 상태)

4. 요구사항 추적성 상실

문제 상황: 시간이 지날수록 "왜 이 코드를 이렇게 만들었는지" 맥락을 잃어버립니다.

• "왜"를 잃어버림 (비즈니스 로직 배경 모름)
• 변경 이력 부재 (Git 커밋 메시지: "fix bug")
• 의사결정 근거 사라짐

5. 팀 협업 붕괴

문제 상황: 여러 개발자가 각자 AI를 사용하면서 협업이 무너집니다.

• 스파게티 코드 양산
• 코드 리뷰 불가
• 온보딩 악몽
• 기술 부채 폭발

💔 바이브 코딩의 역설

속도와 품질의 트레이드오프: AI가 코드를 빠르게 생성해주지만, 그 코드는 유지보수할 수 없는 블랙박스가 됩니다. 1주일 만에 만든 프로토타입이 3개월 동안 기술 부채를 만들어냅니다.

해결책의 필요성: 이 문제를 해결하려면, AI의 속도는 유지하면서도 코드의 일관성, 품질, 추적성을 보장하는 체계적인 방법론이 필요합니다. 바로 여기서 Alfred와 MoAI-ADK가 등장합니다.

✨ The Solution - 3단계 워크플로우

Alfred는 Agentic AI 시대의 코드 품질 문제를 체계적인 3단계 워크플로우로 해결합니다.

1️⃣ SPEC - 명세 작성

명령어: /alfred:1-spec "JWT 기반 사용자 로그인 API"

Alfred가 자동으로 수행:

• EARS 형식 명세 자동 생성
• @SPEC:ID TAG 부여
• Git 브랜치 자동 생성
• HISTORY 섹션 자동 추가

2️⃣ BUILD - TDD 구현

명령어: /alfred:2-build AUTH-001

TDD 사이클:

• 🔴 RED: 실패하는 테스트 작성 (@TEST:AUTH-001)
• 🟢 GREEN: 최소 구현으로 테스트 통과 (@CODE:AUTH-001)
• 🔵 REFACTOR: 코드 품질 개선

3️⃣ SYNC - 문서 동기화

명령어: /alfred:3-sync

Alfred가 자동으로 수행:

• TAG 체인 검증: @SPEC → @TEST → @CODE → @DOC
• 고아 TAG 자동 탐지
• Living Document 자동 생성
• PR 상태 전환 (Draft → Ready)

시스템 요구사항

🔴 필수 요구사항

• Node.js: 18.0 이상
• Git: 2.30.0 이상
• npm: 8.0.0 이상 (또는 Bun 1.2.0 이상 강력 추천)
• Claude Code: v1.2.0 이상 (에이전트 시스템 완전 통합용)

🌍 지원 운영체제

• Windows: 10/11 (PowerShell 5.1+)
• macOS: 12 Monterey 이상 (M1/M2 네이티브 지원)
• Linux: Ubuntu 20.04+, CentOS 8+, Debian 11+, Arch Linux

설치

Option A: Bun 설치 (최적 성능, 강력 추천) 🔥

# Bun 설치 (아직 없는 경우)
curl -fsSL https://bun.sh/install | bash  # macOS/Linux
# 또는
powershell -c "iwr bun.sh/install.ps1|iex"  # Windows

# MoAI-ADK 전역 설치
bun add -g moai-adk

Option B: npm 설치 (표준 옵션)

npm install -g moai-adk

Option C: 개발자 설치 (로컬 개발용)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk/moai-adk-ts
bun install  # 또는 npm install
bun run build
npm link

설치 확인

# 버전 확인
moai --version

# 시스템 진단
moai doctor

# 도움말
moai help

🏗️ How Alfred Works - 10개 AI 에이전트 팀

MoAI-ADK는 Alfred (SuperAgent) + 9개 전문 에이전트 = 총 10개 AI 에이전트로 구성된 에이전틱 코딩 팀입니다.

▶◀ Alfred - SuperAgent (1번째 에이전트)

역할: 중앙 오케스트레이터 (Central Orchestrator)

책임:

• 사용자 요청 분석 및 작업 분해
• 적절한 전문 에이전트 선택 및 조율
• 에이전트 간 협업 관리
• 품질 게이트 검증 및 결과 통합

전문가 AI 서브 에이전트

Alfred가 조율하는 전문 AI 에이전트들입니다.

핵심 3단계 에이전트 (자동 호출)

| 에이전트 | 페르소나 | 전문 영역 | 호출 시점 | | ------------------ | --------------- | -------------- | ----------------- | | spec-builder 🏗️ | 시스템 아키텍트 | EARS 명세 작성 | /alfred:1-spec | | code-builder 💎 | 수석 개발자 | TDD 구현 | /alfred:2-build | | doc-syncer 📖 | 테크니컬 라이터 | 문서 동기화 | /alfred:3-sync |

품질 보증 에이전트 (온디맨드)

| 에이전트 | 페르소나 | 전문 영역 | 호출 방법 | | ------------------- | --------------- | -------------- | ---------------------- | | tag-agent 🏷️ | 지식 관리자 | TAG 체인 검증 | @agent-tag-agent | | debug-helper 🔬 | SRE 전문가 | 오류 진단 | @agent-debug-helper | | trust-checker ✅ | QA 리드 | TRUST 검증 | @agent-trust-checker | | git-manager 🚀 | 릴리스 엔지니어 | Git 워크플로우 | @agent-git-manager |

시스템 관리 에이전트

| 에이전트 | 페르소나 | 전문 영역 | 호출 방법 | | --------------------- | ----------------- | ---------------- | ------------------- | | cc-manager 🛠️ | 데브옵스 엔지니어 | Claude Code 설정 | @agent-cc-manager | | project-manager 📋 | 프로젝트 매니저 | 프로젝트 초기화 | /alfred:0-project |

협업 원칙

단일 책임 (Single Responsibility):

• 각 에이전트는 자신의 전문 영역만 담당
• 다른 에이전트의 영역을 침범하지 않음

중앙 조율 (Central Orchestration):

• Alfred만이 에이전트 간 작업을 조율
• 에이전트끼리 직접 호출 금지

품질 게이트 (Quality Gates):

• 각 단계 완료 시 TRUST 원칙 자동 검증
• TAG 무결성 자동 확인

🎨 Alfred's Output Styles

Alfred는 개발 상황에 따라 4가지 대화 스타일을 제공합니다. Claude Code에서 /output-style 명령어로 언제든 전환할 수 있습니다.

📋 제공되는 Output Styles

| 스타일 이름 | 설명 | | --------------------------- | ------------------------------------------------------------------------ | | MoAI Professional | SPEC-First TDD 전문가를 위한 간결하고 기술적인 개발 스타일 | | MoAI Beginner Learning | 개발 초보자를 위한 상세하고 친절한 단계별 학습 가이드 (학습 전용) | | MoAI Pair Collaboration | AI와 함께 브레인스토밍, 계획 수립, 실시간 코드 리뷰를 진행하는 협업 모드 | | MoAI Study Deep | 새로운 개념, 도구, 언어, 프레임워크를 체계적으로 학습하는 심화 교육 모드 |

🔄 스타일 전환 방법

Claude Code에서 /output-style 명령어로 전환:

/output-style alfred-pro           # MoAI Professional (기본값)
/output-style beginner-learning    # MoAI Beginner Learning
/output-style pair-collab          # MoAI Pair Collaboration
/output-style study-deep           # MoAI Study Deep

🎯 스타일 선택 가이드

| 상황 | 추천 스타일 | 대상 | 특징 | | ------------------------ | ------------------- | -------------------------- | ---------------------------- | | 실무 프로젝트 빠른 개발 | alfred-pro | 실무 개발자, 프로젝트 리더 | 간결, 기술적, 결과 중심 | | 프로그래밍 처음 배우기 | beginner-learning | 개발 입문자 | 친절, 상세 설명, 단계별 안내 | | 팀 기술 선택 & 설계 논의 | pair-collab | 협업 개발자, 아키텍트 | 질문 기반, 브레인스토밍 | | 새로운 기술 학습 | study-deep | 신기술 학습자 | 개념 → 실습 → 전문가 팁 |

💡 모든 스타일에서 동일하게 작동

• ✅ 10개 AI 에이전트 팀 조율
• ✅ SPEC-First TDD 워크플로우
• ✅ TRUST 5원칙 자동 검증
• ✅ @TAG 추적성 보장

차이점은 오직 설명 방식:

• 📝 간결 vs 상세
• 🎓 빠른 구현 vs 개념 학습
• 💬 기술적 vs 친절 vs 협업적 vs 교육적

SPEC 메타데이터 구조

모든 SPEC 문서는 표준화된 메타데이터 구조를 따릅니다.

필수 필드 (7개)

id: AUTH-001                    # SPEC 고유 ID
version: 0.1.0                  # Semantic Version (v0.1.0 = INITIAL)
status: draft                   # draft|active|completed|deprecated
created: 2025-09-15            # 생성일 (YYYY-MM-DD)
updated: 2025-10-01            # 최종 수정일
author: @Goos                   # 작성자 (GitHub ID)
priority: high                  # low|medium|high|critical

선택 필드 (의존성 그래프 & 범위)

# 분류
category: security              # feature|bugfix|refactor|security|docs|perf
labels: [authentication, jwt]   # 검색 태그

# 관계 (의존성 그래프)
depends_on: [USER-001]          # 의존하는 SPEC
blocks: [AUTH-002]              # 차단하는 SPEC
related_specs: [TOKEN-002]      # 관련 SPEC
related_issue: "github.com/..."  # GitHub Issue

# 범위 (영향 분석)
scope:
  packages: [src/core/auth]     # 영향받는 패키지
  files: [auth-service.ts]      # 핵심 파일

상세 가이드: SPEC 메타데이터 가이드

@TAG 시스템

TAG 체계 철학

@SPEC:ID → @TEST:ID → @CODE:ID → @DOC:ID

핵심 원칙:

1. 단순성: 4개의 핵심 TAG만 사용
2. TDD 완벽 정렬: RED (TEST) → GREEN (CODE) → REFACTOR (DOC)
3. CODE-FIRST: TAG는 코드 자체에만 존재 (정규식 패턴으로 직접 스캔)
4. 무결성: 고아 TAG 자동 탐지, 끊어진 참조 검증

TAG 사용 규칙

TAG ID 형식: <도메인>-<3자리> (예: AUTH-003)

중복 방지:

# 새 TAG 생성 전 기존 TAG 검색
rg "@SPEC:AUTH" -n          # SPEC 문서에서 AUTH 도메인 검색
rg "@CODE:AUTH-001" -n      # 특정 ID 검색

TAG 체인 검증:

# /alfred:3-sync 실행 시 자동 스캔
rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/

사용 예시

// @CODE:AUTH-001 | SPEC: SPEC-AUTH-001/spec.md | TEST: tests/auth/service.test.ts

/**
 * @CODE:AUTH-001: JWT 인증 서비스
 *
 * TDD 이력:
 * - RED: tests/auth/service.test.ts 작성
 * - GREEN: 최소 구현 (bcrypt, JWT)
 * - REFACTOR: 타입 안전성 추가
 */
export class AuthService {
  // @CODE:AUTH-001:API: 인증 API 엔드포인트
  async authenticate(username: string, password: string): Promise<AuthResult> {
    // @CODE:AUTH-001:DOMAIN: 입력 검증
    this.validateInput(username, password);

    // @CODE:AUTH-001:DATA: 사용자 조회
    const user = await this.userRepository.findByUsername(username);

    return this.verifyCredentials(user, password);
  }
}

언어별 TAG 사용 예시

Python

# @CODE:AUTH-001 | SPEC: SPEC-AUTH-001/spec.md | TEST: tests/test_auth.py
"""
@CODE:AUTH-001: JWT 인증 서비스

TDD 이력:
- RED: pytest 테스트 작성
- GREEN: bcrypt + PyJWT 구현
- REFACTOR: 타입 힌트 추가
"""

class AuthService:
    # @CODE:AUTH-001:API: 인증 API 엔드포인트
    async def authenticate(
        self,
        username: str,
        password: str
    ) -> AuthResult:
        # @CODE:AUTH-001:DOMAIN: 입력 검증
        self._validate_input(username, password)

        # @CODE:AUTH-001:DATA: 사용자 조회
        user = await self.user_repo.find_by_username(username)

        return self._verify_credentials(user, password)

Flutter/Dart

// @CODE:AUTH-001 | SPEC: SPEC-AUTH-001/spec.md | TEST: test/auth_test.dart

/// @CODE:AUTH-001: JWT 인증 서비스
///
/// TDD 이력:
/// - RED: widget test 작성
/// - GREEN: dio + flutter_secure_storage 구현
/// - REFACTOR: Riverpod 상태 관리 통합
class AuthService {
  // @CODE:AUTH-001:API: 인증 API 엔드포인트
  Future<AuthResult> authenticate({
    required String username,
    required String password,
  }) async {
    // @CODE:AUTH-001:DOMAIN: 입력 검증
    _validateInput(username, password);

    // @CODE:AUTH-001:DATA: 사용자 조회
    final user = await userRepository.findByUsername(username);

    return _verifyCredentials(user, password);
  }
}

🌍 Universal Language Support

MoAI-ADK는 모든 주요 언어를 지원하며, 언어별 최적 도구 체인을 자동으로 선택합니다.

웹/백엔드

| 언어 | 테스트 | 린터 | 타입 | 상태 | | -------------- | ----------- | ------------ | ---- | ---- | | TypeScript | Vitest/Jest | Biome/ESLint | ✅ | Full | | Python | pytest | ruff/black | mypy | Full | | Java | JUnit 5 | checkstyle | ✅ | Full | | Go | go test | golint | ✅ | Full | | Rust | cargo test | clippy | ✅ | Full |

모바일

| 언어/프레임워크 | 테스트 | 린터 | 상태 | | ------------------ | ---------------- | ------------ | ---- | | Flutter/Dart | flutter test | dart analyze | Full | | Swift/iOS | XCTest | SwiftLint | Full | | Kotlin/Android | JUnit + Espresso | detekt | Full | | React Native | Jest + RNTL | ESLint | Full |

자동 언어 감지

시스템이 프로젝트를 스캔하여 자동으로 감지:

• package.json → TypeScript/JavaScript
• requirements.txt → Python
• go.mod → Go
• Cargo.toml → Rust
• pubspec.yaml → Flutter/Dart

💻 CLI Reference

핵심 명령어

# 프로젝트 초기화
moai init [project] [options]

# 시스템 진단
moai doctor [options]

# 프로젝트 상태 확인
moai status [options]

# 백업 복원
moai restore <backup-path> [options]

Claude Code 전용 명령어

# 프로젝트 초기화
/alfred:0-project

moai init [project]

새 MoAI-ADK 프로젝트를 초기화하거나 기존 프로젝트에 MoAI-ADK를 설치합니다.

옵션:

• --personal: Personal 모드로 초기화 (기본값)
• --team: Team 모드로 초기화 (GitHub 통합)
• -b, --backup: 설치 전 백업 생성
• -f, --force: 기존 파일 강제 덮어쓰기

사용 예시:

# 새 프로젝트 생성 (Personal 모드)
moai init my-project

# 현재 디렉토리에 설치
moai init .

# Team 모드로 초기화
moai init my-project --team

# 백업 생성 후 설치
moai init . -b

# 기존 파일 강제 덮어쓰기
moai init . -f

템플릿 업데이트: 2가지 방법

MoAI-ADK는 템플릿 업데이트를 위해 2가지 방법을 제공합니다. 사용 환경과 목적에 따라 적절한 방법을 선택하세요.

🔧 방법 1: moai init . (CLI 직접 실행)

터미널에서 직접 실행하는 표준 업데이트 방법

특징:

• ✅ 빠른 실행: 터미널에서 단일 명령어로 즉시 실행
• ✅ 스크립트 통합: CI/CD 파이프라인, 자동화 스크립트에 적합
• ✅ 수동 제어: 백업, 강제 덮어쓰기 등 옵션 직접 제어
• ⚠️ 제한적 피드백: 성공/실패만 표시, 상세 분석 없음

사용 시나리오:

# 1. 간단한 템플릿 업데이트
moai init .

# 2. CI/CD 파이프라인
npm install -g moai-adk@latest && moai init . -f

# 3. 배치 스크립트
for project in */; do
  cd "$project"
  moai init .
  cd ..
done

업데이트 절차:

# 1. MoAI-ADK 패키지 최신 버전 설치
npm install -g moai-adk@latest

# 2. 프로젝트 디렉토리로 이동
cd your-project

# 3. 템플릿 업데이트 (백업 자동 생성)
moai init .

# 4. 변경사항 확인
git status

옵션:

# 기본 업데이트 (자동 백업 포함)
moai init .

# 백업 생성 후 업데이트 (명시적)
moai init . -b

# 강제 업데이트 (주의: 기존 파일 덮어쓰기)
moai init . -f

🤖 방법 2: /alfred:9-update (Claude Code 전용)

Claude Code에서 Alfred가 지능형 분석과 함께 수행하는 고급 업데이트

특징:

• ✅ 지능형 분석: 프로젝트 상태 자동 진단 및 위험 평가
• ✅ 맥락 인식: 현재 작업 브랜치, SPEC 상태, Git 상태 고려
• ✅ 대화형 확인: Phase 1(분석) → Phase 2(실행) 2단계 워크플로우
• ✅ 상세 리포트: 업데이트 전후 비교, 영향 분석, 권장사항 제공
• ✅ 충돌 해결: CLAUDE.md, config.json 지능형 병합
• ⚠️ Claude Code 필수: 터미널/스크립트에서 사용 불가

사용 시나리오:

# 1. 인터랙티브 개발 중 업데이트
/alfred:9-update

# 2. 업데이트 가능 여부만 확인 (dry-run)
/alfred:9-update --check

# 3. 강제 업데이트 (백업 없음, 위험)
/alfred:9-update --force

# 4. 품질 검증 포함 업데이트
/alfred:9-update --check-quality

2단계 워크플로우:

Phase 1: 분석 및 계획

Alfred가 자동으로 분석:
1. 현재 MoAI-ADK 버전 확인
2. 업데이트 가능한 최신 버전 확인
3. 프로젝트 상태 진단 (Git, SPEC, 브랜치)
4. 업데이트 영향 분석
5. 사용자에게 계획 보고 및 승인 대기

Phase 2: 실행 (사용자 승인 후)

Alfred가 순차 실행:
1. 백업 생성 (.moai-backup-YYYY-MM-DD)
2. 템플릿 파일 업데이트
3. config.json, CLAUDE.md 지능형 병합
4. SPEC 파일 보호 검증
5. Git 상태 확인 및 커밋 제안
6. 최종 리포트 생성

옵션:

• --check: 업데이트 가능 여부만 확인 (실제 변경 없음)
• --force: 강제 업데이트 (백업 없음, 주의 필요)
• --check-quality: TRUST 5원칙 기반 품질 검증 포함

📊 비교표: moai init . vs /alfred:9-update

| 기능 | moai init . | /alfred:9-update | | ----------------- | ------------------ | ------------------- | | 실행 환경 | 터미널 (어디서나) | Claude Code 전용 | | 실행 속도 | ⚡ 빠름 (1-2초) | 🐢 느림 (10-30초) | | 사전 분석 | ❌ 없음 | ✅ 자동 진단 | | 위험 평가 | ❌ 없음 | ✅ 영향 분석 | | 사용자 확인 | ❌ 없음 (즉시 실행) | ✅ 2단계 승인 | | 백업 생성 | ✅ 자동 | ✅ 자동 | | 충돌 해결 | ⚠️ 수동 | ✅ 지능형 병합 | | Git 통합 | ❌ 없음 | ✅ 커밋 제안 | | 리포트 생성 | ❌ 없음 | ✅ 상세 리포트 | | CI/CD 사용 | ✅ 가능 | ❌ 불가능 | | 스크립트 통합 | ✅ 가능 | ❌ 불가능 | | 품질 검증 | ❌ 없음 | ✅ TRUST 검증 (옵션) |

🎯 권장 사용 케이스

moai init . 사용 추천:

• ✅ 빠른 템플릿 업데이트가 필요할 때
• ✅ CI/CD 파이프라인에 통합할 때
• ✅ 여러 프로젝트를 배치로 업데이트할 때
• ✅ 자동화 스크립트에서 사용할 때
• ✅ Claude Code 없이 작업할 때

/alfred:9-update 사용 추천:

• ✅ Claude Code에서 개발 중일 때
• ✅ 업데이트 영향을 미리 파악하고 싶을 때
• ✅ CLAUDE.md, config.json 충돌이 예상될 때
• ✅ Git 커밋과 함께 업데이트하고 싶을 때
• ✅ 상세한 리포트가 필요할 때
• ✅ TRUST 5원칙 기반 품질 검증이 필요할 때

🔒 공통 안전 기능

두 방법 모두 다음 사항을 보장합니다:

• 🔒 .moai/specs/ - 사용자 SPEC 파일 절대 건드리지 않음
• 🔒 .moai/reports/ - 동기화 리포트 보존
• 🔄 백업 자동 생성 (.moai-backup-YYYY-MM-DD)
• ✅ 시스템 파일만 안전하게 업데이트
• ✅ 지능형 병합 (config.json, CLAUDE.md)

moai doctor

시스템 진단을 실행하여 MoAI-ADK가 올바르게 설치되었는지 확인합니다.

옵션:

• -l, --list-backups: 사용 가능한 백업 목록 표시

사용 예시:

# 시스템 진단 실행
moai doctor

# 백업 목록 확인
moai doctor -l

moai status

MoAI-ADK 프로젝트 상태를 표시합니다.

옵션:

• -v, --verbose: 상세 상태 정보 표시
• -p, --project-path <path>: 프로젝트 디렉토리 경로 지정 (경로 필수)

사용 예시:

# 현재 디렉토리 상태 확인
moai status

# 상세 정보 포함
moai status -v

# 특정 경로 프로젝트 상태 확인
moai status -p /path/to/project

# 상세 정보 + 특정 경로
moai status -v -p /path/to/project

moai restore

백업 디렉토리에서 MoAI-ADK를 복원합니다.

인자:

• <backup-path>: 복원할 백업 디렉토리 경로 (필수)

옵션:

• --dry-run: 변경 없이 복원할 내용 미리보기
• --force: 기존 파일 강제 덮어쓰기

사용 예시:

# 백업에서 복원 (미리보기)
moai restore .moai-backup-2025-10-02 --dry-run

# 실제 복원 실행
moai restore .moai-backup-2025-10-02

# 강제 복원 (기존 파일 덮어쓰기)
moai restore .moai-backup-2025-10-02 --force

참고: MoAI-ADK 템플릿 업데이트는 터미널에서 moai init . 명령어를 사용하세요.

프로그래매틱 API

기본 사용

import { CLIApp, SystemChecker, TemplateManager } from 'moai-adk';

// CLI 앱 초기화
const app = new CLIApp();
await app.run();

// 시스템 체크
const checker = new SystemChecker();
const result = await checker.checkSystem();

// 템플릿 관리
const templateManager = new TemplateManager();
await templateManager.copyTemplates(projectPath);

설정 파일 (.moai/config.json)

{
  "project": {
    "name": "my-project",
    "mode": "personal",
    "language": "typescript"
  },
  "workflow": {
    "enableAutoSync": true,
    "gitIntegration": true
  }
}

TRUST 5원칙

모든 개발 과정에서 TRUST 원칙을 준수합니다:

T - Test First (테스트 우선)

SPEC → Test → Code 사이클:

• @SPEC: EARS 형식 명세서 우선 작성
• RED: @TEST TAG - 실패하는 테스트 작성
• GREEN: @CODE TAG - 최소 구현으로 테스트 통과
• REFACTOR: @CODE TAG - 코드 품질 개선

R - Readable (가독성)

코드 제약:

• 파일당 ≤300 LOC
• 함수당 ≤50 LOC
• 매개변수 ≤5개
• 복잡도 ≤10

U - Unified (통합성)

SPEC 기반 아키텍처:

• 모듈 간 명확한 책임 분리
• 타입 안전성 보장
• 언어별 경계를 SPEC이 정의

S - Secured (보안성)

입력 검증:

• 모든 사용자 입력 검증 (정규식, 화이트리스트)
• 파일 업로드 제한 (확장자, 크기, MIME 타입)

주요 취약점 방어:

• SQL Injection: Prepared Statement, ORM 사용
• XSS: HTML 이스케이핑, CSP 헤더
• CSRF: CSRF 토큰, SameSite 쿠키
• 비밀번호: bcrypt/argon2 해싱 (최소 10 라운드)

보안 스캐닝:

• 정적 분석 도구 (Snyk, OWASP Dependency-Check)
• 환경 변수 보안 (.env Git 제외)

T - Trackable (추적성)

@TAG 시스템으로 완전한 추적성:

• @SPEC → @TEST → @CODE → @DOC 체인
• 코드 직접 스캔으로 무결성 검증
• 고아 TAG 자동 탐지

문제 해결

자주 발생하는 문제

1. /alfred:2-build 실행 시 "SPEC not found" 에러

증상: TDD 구현 중 SPEC 파일을 찾을 수 없다는 에러 발생

원인: /alfred:1-spec 단계를 건너뛰었거나, SPEC 파일 경로가 잘못됨

해결 방법:

# 1. SPEC 파일 존재 여부 확인
ls .moai/specs/SPEC-*.md

# 2. SPEC이 없다면 먼저 작성
/alfred:1-spec "기능 설명"

# 3. SPEC ID 확인 후 재실행
/alfred:2-build SPEC-ID

2. 테스트 실패 시 복구

증상: /alfred:2-build 실행 후 테스트가 계속 실패

원인: 엣지 케이스 누락, 의존성 문제, 환경 변수 미설정

해결 방법:

# 1. 테스트 수동 실행으로 정확한 에러 확인
npm test  # 또는 bun test, pytest 등

# 2. debug-helper 에이전트 호출
@agent-debug-helper "테스트 실패 에러 메시지"

# 3. 환경 변수 확인
cat .env.example  # 필요한 환경 변수 확인
cp .env.example .env  # 환경 변수 파일 생성

# 4. 의존성 재설치
rm -rf node_modules && npm install

3. TAG 체인 끊어짐 경고

증상: /alfred:3-sync 실행 시 "고아 TAG 발견" 경고

원인: SPEC 없이 CODE만 작성했거나, TAG ID 불일치

해결 방법:

# 1. 고아 TAG 찾기
rg '@CODE:' -n src/  # CODE TAG 목록
rg '@SPEC:' -n .moai/specs/  # SPEC TAG 목록

# 2. 누락된 SPEC 작성
/alfred:1-spec "해당 기능 설명"

# 3. TAG ID 일치시키기
# CODE와 SPEC의 ID가 동일한지 확인 (예: AUTH-001)

# 4. 재검증
/alfred:3-sync

4. Git 브랜치 충돌

증상: SPEC 생성 시 브랜치 생성 실패

원인: 동일한 이름의 브랜치가 이미 존재

해결 방법:

# 1. 기존 브랜치 확인
git branch -a

# 2. 기존 브랜치로 전환 (계속 작업하려면)
git checkout feature/SPEC-XXX-YYY

# 3. 또는 새 브랜치 강제 생성 (처음부터 다시 시작)
git branch -D feature/SPEC-XXX-YYY
/alfred:1-spec "기능 설명"

5. 권한 에러 (Permission Denied)

증상: moai init 실행 시 권한 에러

원인: 파일 실행 권한 부족

해결 방법:

# 1. .moai/ 디렉토리 권한 확인
ls -la .moai/

# 2. 실행 권한 추가
chmod -R 755 .moai/

# 3. 재시도
moai init .

6. 테스트 커버리지 85% 미만

증상: TRUST 검증 실패 - 테스트 커버리지 부족

원인: 엣지 케이스 테스트 누락

해결 방법:

# 1. 커버리지 리포트 확인
npm test -- --coverage  # 또는 bun test --coverage

# 2. 누락된 브랜치 확인
# 커버리지 리포트에서 빨간색(미테스트) 라인 확인

# 3. 엣지 케이스 테스트 추가
# - null/undefined 입력
# - 빈 배열/객체
# - 경계값 (0, -1, 최대값)
# - 에러 케이스

# 4. 재실행
/alfred:2-build SPEC-ID

7. 설치 실패

권한 문제:

sudo npm install -g moai-adk

캐시 문제:

npm cache clean --force
npm install -g moai-adk

8. 명령어 인식 안 됨

PATH 확인:

echo $PATH
npm list -g --depth=0

셸 재시작:

source ~/.bashrc  # bash
source ~/.zshrc   # zsh

9. Claude Code 연동 문제

• .claude/settings.json 파일 확인
• Claude Code 최신 버전 사용 확인
• 에이전트 파일 권한 확인

로그 확인

문제 원인 파악을 위한 로그 위치:

# MoAI-ADK 시스템 로그
~/.moai/logs/moai.log

# 에러 로그
~/.moai/logs/error.log

# 프로젝트별 로그
.moai/logs/

# Claude Code 로그
~/.claude/logs/

긴급 복구

심각한 문제 발생 시 백업에서 복원:

# 1. 백업 목록 확인
moai doctor -l

# 2. 최신 백업으로 복원 (미리보기)
moai restore .moai-backup-YYYY-MM-DD --dry-run

# 3. 실제 복원
moai restore .moai-backup-YYYY-MM-DD

개발 참여

기여 방법

1. Repository Fork
2. 기능 브랜치 생성 (git checkout -b feature/new-feature)
3. 변경사항 커밋 (git commit -am 'Add new feature')
4. 브랜치 푸시 (git push origin feature/new-feature)
5. Pull Request 생성

개발 환경 설정

# 저장소 클론
git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk/moai-adk-ts

# 의존성 설치 (Bun 권장)
bun install

# 개발 모드 실행
bun run dev

# 빌드
bun run build

# 테스트
bun test

# 코드 품질 검사
bun run check

코딩 규칙

• TRUST 5원칙 준수
• @TAG 시스템 적용
• TypeScript strict 모드 사용
• ≤50 LOC per function
• Test coverage ≥85%

🙏 Contributors

MoAI-ADK 프로젝트에 기여해주신 분들께 감사드립니다:

• @Workuul - 심볼릭 링크 실행 문제 수정 (PR #1)
  • realpathSync() 적용으로 글로벌 설치 이슈 해결
  • REPL/eval 환경 방어 로직 추가
  • JSDoc 문서화 개선

문서 및 지원

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📦 npm Package: moai-adk

Made with MoAI's 🪿

라이선스

이 프로젝트는 MIT License를 따릅니다.