senaiverse/reactnative-expo-ai-agent-system-workflow

🌟 SenaiVerse 제작

React Native 모바일 앱을 위한 완전한 AI 기반 개발 툴킷

빠른 시작 • 문서 • 설치 • 제공 사항 • 실제 영향 • [...]

더 적은 버그로 React Native 모바일 앱을 더 빠르게 구축하기 위한 7개의 핵심 AI 에이전트 (20개 에이전트 설계) + 3개의 슬래시 명령어 (slash commands) + 자동화 훅 (automation hooks)으로 구성된 프로덕션 준비 완료 시스템입니다.

📱 React Native/Expo 모바일 개발을 위해 특별히 구축되었습니다. 이 시스템은 다른 프레임워크에도 적용할 수 있지만, 모든 에이전트, 프롬프트 (prompts), 워크플로우 (workflows)는 iOS/Android 모바일 개발에 최적화되어 있습니다.

대상 환경:

• Claude Code CLI v2.0.5

• Windows, macOS, 및 Linux 환경

• Cursor 터미널 사용자

• Expo SDK 50+ / React Native 0.74+

• 이것은 무엇인가?

• 제작 동기

• 기술 스택 (Tech Stack)

• 빠른 시작

• 제공 사항

• 실제 영향

• 설치

• 사용 예시

• 문서

• 커스터마이징 (Customization)

• 문제 해결 (Troubleshooting)

• 시스템 요구 사항

• 포함 사항

• 기여하기 (Contributing)

• 라이선스 (License)

• 저자

프로덕션 수준의 Expo/React Native 앱을 구축하는 개발자로서, 저는 개발 속도를 늦추고 프로덕션 문제를 일으키는 반복적인 문제들에 직면했습니다:

문제점들:

• ❌ 디자인 불일치 (Design inconsistencies) - 코드 리뷰 과정에서 놓치는 하드코딩된 색상 및 간격
• ❌ 접근성 위반 (Accessibility violations) - WCAG 미준수로 인한 앱 스토어 거절
• ❌ 패키지 버전 충돌 (Package version conflicts) - 빌드를 깨뜨리는 "내 컴퓨터에서는 작동함" 문제
• ❌ 성능 저하 (Performance regressions) - 사용자의 불만이 접수된 후 너무 늦게 발견됨
• ❌ 보안 취약점 (Security vulnerabilities) - 개발 단계가 아닌 프로덕션 단계에서 발견됨
• ❌ 수동 코드 리뷰 (Manual code reviews) - 기능당 2~3시간 소요

해결책:
수동 점검과 기억력에 의존하는 대신, Claude Code의 에이전트 시스템을 사용하여 체계적인 AI 기반 접근 방식을 구축했습니다.

이것이 의미하는 바:

100시간 이상의 연구를 통한 Claude Code 에이전트 아키텍처 분석
(2024-2025) React Native 베스트 프랙티스를 활용한 실무 경험
3개의 모바일 앱을 앱 스토어(App Stores)에 출시하며 겪은 실제 페인 포인트 (Real pain points)
버그를 35% 줄이고 개발 시간을 50% 단축한 검증된 패턴 (Proven patterns)

결과:
코드 리뷰 (Code review) 전 문제를 포착하고, **접근성 준수 (Accessibility compliance)**를 보장하며, **버전 충돌 (Version conflicts)**을 방지하고, **성능 예산 (Performance budgets)**을 자동으로 유지하는 완전한 에이전트 시스템입니다.

이것은 이론적인 것이 아닙니다. 1만 명 이상의 사용자가 있는 프로덕션 앱에서 실전 테스트를 거쳤습니다.

핵심 기술:

AI 및 자동화 (AI & Automation):

대상 환경 (Target Environment):

개발 도구 (Development Tools):

입증된 주요 기술:

• AI 에이전트 시스템 아키텍처 (AI Agent System Architecture)
• PowerShell 자동화 및 스크립팅 (PowerShell Automation & Scripting)
• Bash/Shell 스크립팅 및 크로스 플랫폼 개발 (Bash/Shell Scripting & Cross-Platform Development)
• React Native/Expo 모바일 개발 (React Native/Expo Mobile Development)
• WCAG 2.2 접근성 표준 (WCAG 2.2 Accessibility Standards)
• OWASP 모바일 보안 관행 (OWASP Mobile Security Practices)
• 성능 최적화 패턴 (Performance Optimization Patterns)
• 소프트웨어 엔지니어링 베스트 프랙티스 (Software Engineering Best Practices)

👉 START-HERE.md - 5분 빠른 시작 가이드

플랫폼 선택:

macOS/Linux:

cd claude-code-expo-system/scripts
chmod +x ./install-agents.sh
./install-agents.sh

Windows:

cd claude-code-expo-system\scripts
.\install-agents.ps1

다음 질문이 나타납니다:

• 1️⃣ 프로젝트 범위 (팀 동기화) 또는 2️⃣ 글로벌 (개인용)?

또는 파라미터를 사용하여 프롬프트 건너뛰기:

# 프로젝트 범위 강제 (프롬프트 없음)
./install-agents.sh --scope project
# 글로벌 범위 강제 (프롬프트 없음)
...

cd /path/to/your/expo-project
claude
> 내 컴포넌트의 접근성을 확인해줘

파일	용도	읽기 시간
START-HERE.md	빠른 시작 가이드	5분
COMPLETE-GUIDE.md	전체 참조 매뉴얼	30-60분
PLATFORM-SPECIFIC-SETUP.md	OS별 문제 해결	10-15분

이 문서들은 **모바일 개발 일상 업무의 80%**를 커버합니다:

Tier S: 메타 오케스트레이션 (Meta Orchestration)

• ✅
  Grand Architect - 복잡한 기능을 위한 메타 오케스트레이터

Tier 1: 일상 워크플로우 (필수)

• ✅
  Design Token Guardian - 디자인 시스템 강제 적용 - ✅
  A11y Compliance Enforcer - 접근성 검증 (WCAG 2.2) - ✅
  Smart Test Generator - 테스트 자동 생성 - ✅
  Performance Budget Enforcer - 성능 추적

Tier 2: 파워 에이전트 (혁신적 변화)

• ✅
  Performance Prophet - 예측 분석 - ✅
  Security Penetration Specialist - 보안 테스트 (OWASP Mobile Top 10)

완성된 20개 에이전트 시스템 설계에는 필요에 따라 생성할 수 있는 13개의 전문 에이전트가 더 포함되어 있습니다:

• Version Compatibility Shield, User Journey Cartographer, Zero-Breaking Refactor Surgeon
• Cross-Platform Harmony Enforcer, API Contract Guardian, Memory Leak Detective
• Design System Consistency Enforcer, Technical Debt Quantifier, Test Strategy Architect
• Bundle Size Assassin, Migration Strategist, State Management Auditor, Feature Impact Analyzer

생성 템플릿은 ready-to-use/agents/AGENTS-REFERENCE.md를 참조하세요.

/feature

• 멀티 에이전트 기능 구현 워크플로우

/review

• 종합적인 코드 리뷰 (디자인 + 접근성(a11y) + 보안 + 성능)

/test

• 엣지 케이스(edge cases)를 포함한 테스트 스위트 생성

필요에 따라 추가적인 커스텀 명령어를 생성할 수 있습니다.

CLAUDE.md

• 프로젝트 컨텍스트 템플릿

settings.json

• 글로벌/프로젝트 설정
• 자동화를 위한 훅(Hook) 스크립트 (선택 사항)
• 크로스 플랫폼 설치 스크립트 (Windows PowerShell + macOS/Linux Bash)

실제 운영 사용 사례 기반:

시간 절감:

• 기능 개발 시간 50% 감소
• 코드 리뷰 시간 80% 감소
• 테스트 작성 속도 60% 향상
• 디자인 불일치 85% 감소

품질 향상:

• 프로덕션 버그 35% 감소
• 접근성 문제 65% 감소
• 80% 이상의 테스트 커버리지 달성 가능
• 리팩토링 중 Breaking Change(파괴적 변경) 제로

비즈니스 가치:

• 시장 출시 속도(Time to market) 단축
• 고객 지원 티켓 감소
• App Store 거절 방지
• 법적 문제 방지 (접근성 준수)

claude-code-expo-system/
├── README.md ← 현재 위치
├── START-HERE.md ← 이것을 먼저 읽으세요
...

대화형 모드 (Interactive Mode, 권장 - 가장 쉬움!)

설치 프로그램이 프로세스를 안내합니다:

cd claude-code-expo-system/scripts
chmod +x ./install-agents.sh # 실행 권한 부여 (1회 수행)
./install-agents.sh
...

비대화형 모드 (Non-Interactive Mode, 프롬프트 건너뛰기)

프로젝트 범위 지정 (Project-Scoped, 팀 단위 권장)

• 에이전트(Agents)가 프로젝트의 .claude/ 폴더에 설치됩니다. - 버전 관리(Version-controlled)가 가능하며, git을 통해 팀원과 공유할 수 있습니다.

# Expo/React Native 프로젝트로 이동
cd /path/to/your/expo-project
# 프로젝트 범위 강제 지정 (프롬프트 없음)
...

전역 설정 (Global, 개인용)

• 에이전트(Agents)가 ~/.claude/ 폴더에 설치됩니다. - 모든 프로젝트에서 사용 가능합니다.

# 전역 범위 강제 지정 (프롬프트 없음)
cd claude-code-expo-system/scripts
./install-agents.sh --scope global

대화형 모드 (Interactive Mode, 권장 - 가장 쉬움!)

설치 프로그램이 프로세스를 안내합니다:

cd claude-code-expo-system\scripts
.\install-agents.ps1
# 메뉴가 표시됩니다:
...

비대화형 모드 (Non-Interactive Mode, 프롬프트 건너뛰기)

프로젝트 범위 지정 (Project-Scoped, 팀 단위 권장)

• 에이전트(Agents)가 프로젝트의 .claude/ 폴더에 설치됩니다. - 버전 관리(Version-controlled)가 가능하며, git을 통해 팀원과 공유할 수 있습니다.

# Expo/React Native 프로젝트로 이동
cd C:\path\to\your\expo-project
# 프로젝트 범위 강제 지정 (프롬프트 없음)
...

전역 설정 (Global, 개인용)

• 에이전트(Agents)가 ~/.claude/ 폴더에 설치됩니다. - 모든 프로젝트에서 사용 가능합니다.

# 전역 범위 강제 지정 (프롬프트 없음)
cd claude-code-expo-system\scripts
.\install-agents.ps1 -Scope global
...

프로젝트 범위 지정 (Project-Scoped):

# Expo 프로젝트 루트에서 실행
cp -r /path/to/ready-to-use/agents/* ./.claude/agents/
cp -r /path/to/ready-to-use/commands/* ./.claude/commands/
...

전역 설정 (Global):

# 사용자 디렉토리에 설치
cp -r ready-to-use/agents/* ~/.claude/agents/
cp -r ready-to-use/commands/* ~/.claude/commands/
...

Claude Code는 다음 순서로 에이전트(Agents)를 확인합니다:

프로젝트 에이전트 (Project agents) (프로젝트 내의 .claude/agents/) - 가장 높은 우선순위
전역 에이전트 (Global agents) (홈 디렉토리 내의 ~/.claude/agents/) - 낮은 우선순위

하이브리드 접근 방식 (Hybrid Approach): 둘 다 사용할 수 있습니다! 프로젝트 에이전트 (Project agents)는 동일한 이름을 가진 전역 에이전트 (Global agents)를 덮어씁니다.

프로젝트 범위 지정 (Project-Scoped) (팀 단위 권장):

• ✅ 팀 프로젝트 (git을 통해 공유되는 에이전트)
• ✅ 프로젝트별 맞춤 설정 (Project-specific customizations)
• ✅ 프로젝트마다 다른 에이전트 버전 사용
• ✅ 팀원들을 위한 자동 동기화

전역 (Global) (개인용):

• ✅ 개인 프로젝트
• ✅ 모든 프로젝트에서 일관된 에이전트 사용
• ✅ 빠른 설정
• ✅ 모든 것에 대한 단일 설치

사용자: "내 컴포넌트에 하드코딩된 색상이 있는지 확인해줘"
→ Design Token Guardian 자동 호출

사용자: "@security-specialist 결제 흐름을 감사해줘"
→ Security Specialist가 OWASP Mobile Top 10 감사를 실행

사용자: "/review src/screens/LoginScreen.tsx"
→ 멀티 에이전트 리뷰 (디자인, 접근성 (a11y), 보안, 성능)

사용자: "오프라인 모드 구현을 돕도록 @grand-architect가 필요해"
→ Grand Architect가 계획을 수립하고 전문 에이전트들에게 위임

• 시스템 설치

• 3~5개의 기본 에이전트 사용

• /review 명령어를 시도해 보세요
  목표: 에이전트 호출에 익숙해지기

• 강제 적용을 위한 훅 (hooks) 활성화

• /feature 명령어를 사용하세요

• 복잡한 작업에는 Grand Architect를 시도해 보세요
  목표: 반복적인 체크 자동화

• 멀티 에이전트 워크플로우 (Multi-agent workflows)

• 커스텀 슬래시 명령어 (Custom slash commands)

• 성능 최적화 워크플로우
  목표: 오케스트레이션 (Orchestration) 숙달

• 커스텀 에이전트 생성

• 팀 협업 설정

• 메트릭 (Metrics) 추적
  목표: 시스템 전체 숙련도 확보

• 파일 생성:
  ~/.claude/agents/my-agent.md

• YAML 프론트매터 (frontmatter) 추가:

---

name: my-agent
description: 이 에이전트가 하는 일
tools: Read, Grep, Edit
model: sonnet

• 시스템 프롬프트 (system prompt) 작성
• 테스트:
  @my-agent [task]

상세한 맞춤 설정 지침은 COMPLETE-GUIDE.md를 참조하세요.

# 설치 확인
ls ~/.claude/agents/
# 에이전트 이름이 파일과 일치하는지 확인
...

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 스크립트를 실행 가능하게 만들기
chmod +x scripts/*.sh

• 에이전트 YAML에서 설명을 더 구체적으로 작성하세요

• 수동 호출: @agent-name

• COMPLETE-GUIDE.md의 트러블슈팅 (troubleshooting) 섹션을 확인하세요

플랫폼별 트러블슈팅 (troubleshooting)에 대해서는 PLATFORM-SPECIFIC-SETUP.md를 참조하세요.

핵심 요구사항 (Core):

Claude Code: v2.0.5+
Node.js: 18.x 이상
IDE: Cursor (또는 모든 터미널)
Project: Expo SDK 50+ 또는 React Native 0.74+

플랫폼별 요구사항 (Platform-Specific):

Windows: PowerShell 5.1+ (또는 WSL/Git Bash를 통한 Bash)
macOS: Bash 4.0+ (또는 bash shebang을 통한 Zsh, macOS 10.15+)
Linux: Bash 4.0+ (Ubuntu, Debian, Fedora, CentOS 등)

빠른 시작 (Quick Start): START-HERE.md
전체 가이드 (Full Guide): COMPLETE-GUIDE.md
플랫폼 설정 (Platform Setup): PLATFORM-SPECIFIC-SETUP.md
Claude Code 문서 (Claude Code Docs): https://docs.claude.com/en/docs/claude-code
Expo 문서 (Expo Docs): https://docs.expo.dev
React Native 문서 (React Native Docs): https://reactnative.dev

✅ 7개의 핵심 프로덕션 준비 완료 에이전트 (80% 커버리지)
✅ 생성 템플릿을 포함한 20개 에이전트 시스템 설계
✅ 3개의 커스텀 슬래시 명령어 (확장 가능)
✅ 프로젝트 템플릿 (CLAUDE.md)
✅ 글로벌 설정 (settings.json)
✅ 크로스 플랫폼 설치 스크립트 (Windows PowerShell + macOS/Linux Bash)
✅ 사전 점검 (Pre-flight) 검증 및 테스트 스크립트
✅ 포괄적인 문서 (11개의 마크다운 파일)
✅ 실제 사례 및 워크플로우 (workflows)
✅ 베스트 프랙티스 (Best practices) 가이드
✅ 트러블슈팅 (Troubleshooting) 가이드 (40개 이상의 솔루션)
✅ 커스터마이징 지침

• ✅
  현재 위치 - README 읽기
• 📖 START-HERE.md 읽기 (5분 소요)
• ⚡ install-agents.ps1 (Windows) 또는 install-agents.sh (macOS/Linux) 실행
• 📋 CLAUDE.md를 프로젝트에 복사
• 🚀 Claude Code를 시작하고 에이전트 테스트
• 📘 심층 분석을 위해 COMPLETE-GUIDE.md 읽기

이 시스템은 다음 분야에 대한 100시간 이상의 연구를 나타냅니다:

• Anthropic 공식 문서
• 프로덕션 React Native 베스트 프랙티스
• 실제 모바일 개발의 페인 포인트 (pain points)
• 검증된 에이전트 오케스트레이션 (orchestration) 패턴

귀하의 스택에 맞춰 특별히 구축되었습니다:

• ✅ Claude Code CLI v2.0.5+
• ✅ Windows, macOS, 및 Linux 환경
• ✅ Cursor 터미널
• ✅ Expo/React Native 모바일 앱

더 나은 앱을 더 빠르게 만들기 시작하세요. 즐거운 코딩 되세요! 🚀

기여(Contributions), 이슈(issues), 그리고 기능 요청(feature requests)은 언제나 환영합니다!

기여 방법 (How to Contribute):

저장소 포크 (Fork the repository)

기능 브랜치 생성 (Create a feature branch):
git checkout -b feature/amazing-feature

변경 사항 적용 (Make your changes)
(에이전트 (agents), 명령어 (commands), 문서 (documentation))

철저한 테스트 (Test thoroughly)

• 설치 스크립트 및 에이전트 (agent) 기능 검증

변경 사항 커밋 (Commit your changes):
git commit -m 'Add amazing feature'

브랜치로 푸시 (Push to the branch):
git push origin feature/amazing-feature

풀 리퀘스트 (Pull Request) 생성

가이드라인 (Guidelines):

• 기존 에이전트 (agent) 파일 패턴 준수 (YAML frontmatter + markdown)
• 모든 플랫폼 (Windows PowerShell, macOS Bash, Linux Bash)에서 테스트
• 새로운 기능에 대한 문서 업데이트
• 사용 예시 포함

자세한 가이드라인은 CONTRIBUTING.md를 참조하세요.

기여 아이디어 (Ideas for Contributions):