베스트 프랙티스

베스트 프랙티스

이 문서는 Oh My OpenCode를 사용하기 위한 베스트 프랙티스와 효율적인 패턴을 공유하여 다중 에이전트 협업의 기능을 최대한 활용할 수 있도록 돕습니다.

ultrawork 마법 키워드

ultrawork란 무엇인가요?

ultrawork(약칭 ulw)는 Oh My OpenCode의 마법 키워드입니다. 작업 설명에 이 단어를 추가하면 모든 고급 기능이 자동으로 활성화됩니다.

활성화되는 기능

ultrawork를 사용하면 시스템이 자동으로 다음을 활성화합니다:

• ✅ 모든 구성된 전문 에이전트
• ✅ 백그라운드 작업 병렬 실행
• ✅ 전체 LSP 도구 통합
• ✅ 지능형 컨텍스트 관리
• ✅ AST-Grep 코드 검색
• ✅ 자동 작업 분해 및 조정

사용 예시

# 전체 형식
opencode "ultrawork: 사용자 인증 시스템 리팩토링, OAuth2 지원 추가"

# 약어 형식
opencode "ulw: 전체 프로젝트에 TypeScript 타입 추가"

# 에이전트와 결합
opencode "ultrawork: @oracle 마이크로서비스 아키텍처 설계"

사용 시기

ultrawork 사용 권장 상황:

• 🏗️ 대규모 리팩토링 작업
• 🌐 풀스택 기능 개발
• 📚 복잡한 문제 분석
• 🎯 다단계 구현 작업

ultrawork가 필요 없는 상황:

• 🔍 단순 쿼리
• ✏️ 소규모 수정
• 📖 단일 파일 편집
• ❓ Q&A 유형 요청

팁

복잡한 작업의 경우 항상 ultrawork를 우선순위에 두세요. 리소스를 낭비하지 않고 필요한 기능을 지능적으로 활성화합니다.

다중 에이전트 협업 패턴

패턴 1: 순차적 협업

사용 사례: 명확한 순차적 의존성이 있는 작업

# 1단계: 아키텍처 설계
opencode "@oracle 사용자 권한 시스템 아키텍처 설계"

# 2단계: 문서 조사
opencode "@librarian RBAC 및 ABAC 베스트 프랙티스 조사"

# 3단계: 구현
opencode "@backend-engineer @oracle의 설계를 기반으로 권한 시스템 구현"

장점:

• 책임 분담이 명확함
• 각 단계의 결과를 수동으로 검토 가능
• 이슈 추적이 용이함

패턴 2: 병렬 협업

사용 사례: 하위 작업이 비교적 독립적이며 동시에 진행 가능한 경우

# ultrawork를 사용하여 자동 병렬화
opencode "ulw: 프론트엔드 UI 및 백엔드 API를 포함한 사용자 대시보드 기능 개발"

# Sisyphus가 자동으로 할당:
# - @frontend-engineer: UI 컴포넌트 구현
# - @backend-engineer: API 엔드포인트 구현
# - @librarian: 베스트 프랙티스 조사

장점:

• 효율성 대폭 향상
• 자동 조정 및 통합
• 시간에 민감한 작업에 적합

패턴 3: 계층적 협업

사용 사례: 서로 다른 수준의 의사 결정 및 구현이 필요한 경우

# 1계층: 전략적 결정
opencode "@oracle REST에서 GraphQL로의 마이그레이션 평가"

# 2계층: 기술 조사
opencode "@librarian GraphQL 에코시스템 및 도구 모음 조사"

# 3계층: 프로토타입 개발
opencode "@backend-engineer GraphQL 프로토타입 구현"

# 4계층: 검증 테스트
opencode "@explore 프로토타입 성능 및 유지 관리성 분석"

적합한 에이전트 선택

작업 유형	기본 에이전트	대안	비고
아키텍처 결정	@oracle	-	가장 강력한 시스템적 사고
문서 작성	@document-writer	@librarian	Document Writer는 기술 문서 작성에 집중
문서 조사	@librarian	-	정보 검색 및 정리에 탁월함
UI/UX 디자인	@frontend-ui-ux-engineer	@frontend-engineer	사용자 경험에 집중
프론트엔드 개발	@frontend-engineer	@frontend-ui-ux-engineer	프론트엔드 기술 전문가
API 개발	@backend-engineer	-	백엔드 전문가
버그 디버깅	@explore	@oracle	Explore는 코드 분석에 탁월함
성능 최적화	@oracle	@explore	Oracle은 전략을 제공하고 Explore는 세부 사항 분석
시각적 분석	@multimodal-looker	-	디자인 시안 및 UI 스크린샷 분석

컨텍스트 관리 베스트 프랙티스

AGENTS.md 계층 시스템

계층적 컨텍스트 규칙을 적절히 사용하세요:

전역 규칙 (프로젝트 루트)

<!-- project/AGENTS.md -->
# 전역 개발 표준

## 일반 규칙
- TypeScript 엄격 모드 사용
- 모든 함수에 타입 주석 필수
- ESLint 및 Prettier 사용

## 커밋 표준
- Conventional Commits 준수
- 모든 커밋은 모든 테스트를 통과해야 함

모듈 규칙 (src 디렉토리)

<!-- project/src/AGENTS.md -->
# 소스 코드 표준

## 코드 구성
- 유형별이 아닌 기능 모듈별로 구성
- 각 모듈은 index.ts 내보내기 포함

## 테스트 요구 사항
- 핵심 비즈니스 로직은 유닛 테스트 필수
- 커버리지 80% 이상

컴포넌트 규칙 (components 디렉토리)

<!-- project/src/components/AGENTS.md -->
# React 컴포넌트 표준

## when: file.ext == "*.tsx"
- 함수형 컴포넌트 및 Hook 사용
- Props는 TypeScript 인터페이스 정의 필수
- 스타일 관리에 CSS Modules 사용

## when: agent == "@frontend-engineer"
- 회사의 UI 디자인 시스템 준수
- Storybook을 사용하여 컴포넌트 문서화

조건부 규칙 사용

파일 유형별 활성화

## when: file.ext == "*.test.ts"
Jest 및 React Testing Library 사용
AAA 패턴 준수 (Arrange, Act, Assert)

## when: file.ext == "*.spec.ts"
E2E 테스트에 Cypress 사용

에이전트 유형별 활성화

## when: agent == "@oracle"
자세한 기술적 결정 근거 제공
장기적 유지 관리성 고려

## when: agent == "@frontend-engineer"
사용자 경험 최우선 고려
웹 접근성(a11y) 표준 준수

작업 단계별 활성화

## when: phase == "design"
아키텍처 다이어그램 및 기술 선택 문서 출력

## when: phase == "implementation"
테스트 가능한 코드 작성
필요한 주석 추가

백그라운드 작업 사용 팁

동시성 적절히 설정

구독 플랜에 따라 조정하세요:

Claude Max20 구성:

{
  "sisyphus": {
    "max_concurrent_tasks": 3
  }
}

ChatGPT Plus / Gemini 구성:

{
  "sisyphus": {
    "max_concurrent_tasks": 2
  }
}

무료 또는 제한적 플랜:

{
  "sisyphus": {
    "max_concurrent_tasks": 1
  }
}

백그라운드 작업 사용 사례

백그라운드 실행에 적합함:

• 📖 문서 조사
• 🔍 코드베이스 분석
• 📊 성능 벤치마킹
• 🧪 테스트 실행
• 📝 보조 문서 생성

백그라운드 실행에 부적합함:

• ✏️ 코드 직접 수정
• 🚀 중요 경로 작업
• 👤 사용자 확인이 필요한 작업

백그라운드 작업 모니터링

# 현재 실행 중인 백그라운드 작업 상태 보기
opencode "모든 백그라운드 작업 상태 보여줘"

# 특정 백그라운드 작업 취소
opencode "작업 ID 취소: abc123"

# 모든 백그라운드 작업 완료 대기
opencode "계속하기 전에 모든 백그라운드 작업이 완료될 때까지 기다려줘"

코드 품질 제어 전략

자동 주석 확인

에이전트가 필요한 주석을 자동으로 추가하도록 구성하세요:

{
  "code_quality": {
    "enforce_comments": true,
    "comment_rules": {
      "functions": "복잡도 > 10인 경우 주석 필수",
      "classes": "공개 클래스 주석 필수",
      "exports": "내보낸 함수/클래스 주석 필수"
    }
  }
}

코드 리뷰 통합

에이전트가 코드 리뷰를 돕도록 하세요:

# 특정 파일 리뷰
opencode "@oracle src/auth/login.ts의 코드 품질 리뷰해줘"

# 전체 PR 리뷰
opencode "ulw: 현재 브런치의 모든 변경 사항 리뷰해줘"

# 보안 이슈 확인
opencode "@explore 코드의 보안 취약점 확인해줘"

할 일(Todo) 연속 실행기

Todo 시스템을 사용하여 장기 작업을 추적하세요:

# Todo 생성
opencode "할 일 생성: 사용자 인증 모듈 리팩토링"

# Todo 보기
opencode "완료되지 않은 모든 할 일 목록 보여줘"

# Todo 연속 실행
opencode "할 일 연속 실행: 사용자 인증 모듈 리팩토링"

팁

할 일 연속 실행기는 컨텍스트를 유지하며 세션 간에도 이전 작업을 계속할 수 있습니다.

성능 최적화 권장 사항

모델 선택 최적화

작업마다 다른 모델 사용:

{
  "agents": {
    "oracle": {
      "model": "claude-sonnet-4",  // 복잡한 결정에는 가장 강력한 모델 사용
      "temperature": 0.7
    },
    "explore": {
      "model": "claude-sonnet-3.5",  // 코드 분석에는 중간급 모델 사용
      "temperature": 0.3
    },
    "librarian": {
      "model": "gpt-4-turbo",  // 문서 조사에는 다른 모델 사용 가능
      "temperature": 0.5
    }
  }
}

토큰 사용량 제어

{
  "token_management": {
    "max_context_tokens": 4096,
    "summarize_long_context": true,
    "cache_common_queries": true
  }
}

작업 설명 최적화

❌ 모호한 설명:

opencode "코드 개선해줘"

✅ 명확한 설명:

opencode "@explore UserService.ts의 성능 병목 지점을 분석하고, @backend-engineer가 데이터베이스 쿼리를 최적화해줘"

캐싱 사용

{
  "caching": {
    "enabled": true,
    "cache_lsp_results": true,
    "cache_duration": 3600,  // 1시간
    "cache_directory": ".opencode/cache"
  }
}

흔한 실수 및 해결책

실수 1: ultrawork 과다 사용

문제: 단순 작업에 ultrawork를 사용하여 리소스 낭비

해결:

# ❌ 과다 사용
opencode "ulw: package.json 내용 보여줘"

# ✅ 단순 작업 직접 실행
opencode "package.json 보여줘"

실수 2: 부적절한 에이전트 선택

문제: 작업에 적합하지 않은 에이전트가 실행하도록 함

해결:

# ❌ 잘못된 선택
opencode "@librarian React 컴포넌트 구현해줘"

# ✅ 올바른 선택
opencode "@frontend-engineer React 컴포넌트 구현해줘"

실수 3: 컨텍스트 관리 소홀

문제: 프로젝트에 AGENTS.md를 구성하지 않음

해결: 계층적 AGENTS.md 파일을 생성하여 필요한 컨텍스트 제공

실수 4: 너무 많은 동시 작업

문제: max_concurrent_tasks를 너무 높게 설정하여 API 속도 제한 발생

해결: 실제 구독 플랜에 기반하여 동시성 조정

실제 팁 요약

빠른 시작 템플릿

# 신규 기능 개발
opencode "ulw: @oracle이 [기능 이름]의 아키텍처를 설계하고, @librarian이 관련 기술을 조사하고, @frontend-engineer와 @backend-engineer가 병렬로 구현해줘"

# 버그 수정
opencode "@explore [버그 설명]의 근본 원인을 분석하고 수정해줘"

# 코드 리뷰
opencode "@oracle 현재 PR의 아키텍처 타당성 리뷰하고, @explore가 잠재적 이슈를 확인해줘"

# 문서 작성
opencode "@librarian 프로젝트 구조를 조사하고 완전한 README.md 작성해줘"

효율성 향상 체크리스트

• ✅ 프로젝트에 AGENTS.md 계층 규칙 구성함
• ✅ 구독 플랜에 따라 동시성 조정함
• ✅ 복잡한 작업에 ultrawork 사용함
• ✅ 작업에 적합한 에이전트 선택함
• ✅ 백그라운드 작업을 활용하여 효율성 높임
• ✅ Todo 시스템을 사용하여 장기 작업 추적함
• ✅ 정기적으로 캐시 및 세션 정리함

다음 단계

베스트 프랙티스를 마스터한 후 다음 항목을 권장합니다:

1. ⚙️ 고급 설정에서 심층 사용자 정의 탐색
2. 💡 사용 사례에서 더 많은 영감 얻기
3. 🔧 팀의 요구 사항에 맞게 워크플로우를 사용자 정의하세요