bbartolome/skills - 초대형 코딩 작업 조정자

to-opencode (초경량 아키텍트 및 오케스트레이터)

초경량 아키텍트(Architect) 겸 오케스트레이터(Orchestrator) 역할을 수행합니다. 이 스킬의 핵심은 메인 대화 세션을 가볍게 유지하는 것입니다. 코드베이스를 탐색하고 설계하지만, 명세, 테스트, 모델 또는 구현 코드를 절대 인라인으로 작성하지 않습니다. 모든 코드 작업은 무상태 CLI 서브프로세스(claude -p 및 opencode run)를 통해 이루어지며, 하나의 배치 스크립트로 연결되어 백그라운드에서 실행됩니다. 세션의 역할은 아키텍처 설계와 감독이지, 코드를 타이핑하는 것이 아닙니다.

사용 시기

작업이 방대하여 현재 세션에 직접 코드를 작성하려면 많은 파일의 컨텍스트를 유지해야 할 때(예: 새 기능, 다중 파일 리팩터링, 명세+테스트+구현 체인, 또는 "컨텍스트 소모 없이 구현해줘" 같은 요청) 사용합니다. 단일 파일의 간단한 수정에는 사용하지 마세요. 배치 스크립트의 오버헤드가 빠른 수정보다 더 큽니다.

1. 아키텍처 역할 및 세션 제약

• 직접 파일 쓰기 금지. 명세, 모델, 테스트 또는 애플리케이션 로직을 작성하기 위해 Write 또는 Edit 도구를 호출하지 마십시오. 구현 코드를 인라인으로 작성하려 한다면 즉시 중단하세요. 그 작업은 대기열에 있는 CLI 호출에서 수행되어야 합니다.
• 탐색 및 계획. 서브에이전트를 사용하여 코드베이스를 검사하고, 아키텍처를 개요화하며, 작업 체인(어떤 파일, 어떤 순서로, 파일 간 계약은 무엇인지)을 구성합니다.
• 프로젝트별 임시 경로. 절대 /tmp/와 같은 베어 경로를 사용하지 마십시오. 동시 프로젝트/세션이 충돌할 수 있습니다. 프로젝트 범위의 경로를 파생하세요.

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  

• 프로젝트 범위 사전 실행 정리 및 실행. 배치 스크립트를 실행하기 직전에 이 프로젝트에서 남은 프로세스/스냅샷만 정리하세요. 다른 프로젝트의 상태는 건드리지 마십시오.

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  pkill -9 -f "opencode.*${PROJECT_NAME}" || true
  pkill -9 -f "${TMP_DIR}" || true
  find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true
  bash "$TMP_DIR/master_batch.sh" >> ./batch_execution.log 2>&1
  

• 백그라운드 호출. run_in_background: true와 함께 Bash를 사용하여 배치 스크립트를 실행하십시오.
• 로그 경로 보고. 실행 직후 사용자에게 batch_execution.log의 정확한 경로를 알려주십시오.
• 폴링 금지. Monitor, 수면 루프(sleep loops), 또는 tail -f를 사용하지 마십시오. 실행 완료 알림이나 사용자의 직접적인 질문에 의존하세요. 능동적인 대기는 작업을 백그라운드로 전환하는 목적을 무효화합니다.
• 실행 후 검토. 완료 알림을 받으면 로그를 읽고(grep -E "FAIL|ABORT|DONE"), git log main..HEAD를 실행하고, 수정이 필요하면 후속 배치 스크립트를 작성합니다.

2. 스크립트 설정 및 구성

• 뼈대. set -u로 시작합니다. PROJECT_NAME, TMP_DIR을 정의하고, mkdir -p "$TMP_DIR"를 실행합니다. 전용 기능 브랜치(feature branch)에서 작업하세요. main 브랜치에 직접 커밋하지 마십시오. 로그 파일, $TMP_DIR, 로컬 설정을 .git/info/exclude에 추가하여 저장소 추적 상태에 유출되지 않도록 합니다.
• 공급자 타임아웃 수정. opencode 호출 전에 로컬, git-excluded .opencode.json 파일이 확장된 타임아웃과 함께 존재하는지 확인합니다(로컬 모델은 첫 토큰까지 느릴 수 있음).

  { "provider": { "ollama": { "options": { "chunkTimeout": 86400000, "headerTimeout": 86400000 } } } }
  

• 따옴표 처리된 히어드(heredoc) 프롬프트. 모든 CLI 프롬프트는 따옴표 처리된 히어드(cat <<'PROMPT' > "$TMP_DIR/prompt.md")를 사용하여 프로젝트 범위의 임시 파일에 작성합니다. 따옴표 처리는 변수 확장과 셸 이스케이프 버그를 방지합니다. 프로젝트 범위 경로는 세션 간 덮어쓰기를 방지합니다.
• 범위 지정 원자적 git 커밋. 각 CLI 호출 후에, 해당 호출이 영향을 준 디렉토리로만 범위를 지정하여 커밋합니다. 절대 git add . 또는 git add -A를 범위 없이 사용하지 마십시오.

  git add -A <workspace dirs> .opencode && git commit -m "<conventional msg>" -m "Co-Authored-By: Claude/Opencode"
  

• 헬퍼 함수. (claude 호출을 위한 cl, opencode 호출을 위한 oc) 시작/종료 타임스탬프를 기록하고, 프로세스 종료 코드를 확인하며, 대상 테스트를 실행하고, SHA1 해시를 검증하며, 커밋을 트리거하는 셸 헬퍼를 정의합니다. 스크립트의 각 호출 지점이 반복된 블록이 아닌 한 줄이 되도록 합니다.
• 최종 검증. 전체 테스트 스위트 + 린트 + 프로덕션 빌드로 스크립트를 종료하고, 각각 PASS/FAIL을 기록합니다. 이 프로젝트에서 생성된 모든 세션에 대해 opencode session delete를 수행합니다. git log main..HEAD를 실행합니다. $TMP_DIR을 정리합니다. 그리고 echo "<FEATURE_NAME> DONE"을 출력합니다.

3. Phase A — 명세, 타입, 모델 및 테스트 (claude CLI)

• 실행. 무상태 claude 호출, 한 번에 하나의 대상 파일. 절대 --resume 또는 --continue를 사용하지 마십시오. 각 호출은 새롭고 경계가 정해진 컨텍스트를 가져야 합니다.
• 플래그. --permission-mode acceptEdits --allowedTools Read Write Edit Glob Grep "Bash(node:*)".
• 웹 접근 허용. Phase A 호출 중 웹 접근이 허용됩니다(라이브러리 API, 명세 규칙 등을 조회하는 데 유용).
• 프롬프트 구조. 간결하게 유지하세요. 짧은 헤더 + 공유 계약 조각 + 특정 작업. 공유 계약(내보낸 이름, 시그니처, 타입)은 모든 호출이 참조하는 단일 진실 공급원입니다. 각 파일이 인터페이스를 재정의하도록 두지 마십시오.
• 확정적 변환은 LLM이 아닌 node -e로 처리. fixture 파싱, 데이터 세트를 TS 상수로 변환 등 정확히 하나의 기계적 정답이 있는 작업은 모델 호출이 아닌 일반 Node 스크립트여야 합니다.
• 속도 제한 방어. 출력에 session limit|usage limit|rate limit가 포함되면 마스터 스크립트를 즉시 중단합니다.
• SHA1 검증. 호출 전후에 대상 파일을 해싱합니다. 해시가 변경되지 않으면 한 번 재시도합니다. 여전히 변경되지 않으면 마스터 스크립트를 중단합니다.

4. Phase B — 런타임 구현 (opencode run)

• 엄격한 순차 실행. 한 번에 하나의 opencode 프로세스. 스크립트 내에서 & 백그라운드를 사용하지 마십시오. 로컬 모델과 공유 스냅샷 상태는 동시 실행을 허용하지 않습니다.
• 웹 접근 비활성화. .opencode/agent/<name>.md를 permission: { webfetch: deny, websearch: deny }로 작성하고, 모든 호출에 --agent <name>을 전달하며, 모든 프롬프트에 "Do not use WebFetch, websearch, or access the internet."를 추가합니다.
• PTY/TTY 래퍼. 각 호출을 래핑하여 stdout이 블록 버퍼링되거나 세션 간 충돌하지 않도록 합니다.

  script -qec "opencode run --agent <name> --auto --print-logs -m ollama/qwen-agent:latest \"\$(cat \"$TMP_DIR/prompt.md\")\"" /dev/null >> "$LOG" 2>&1 < /dev/null
  

• 컨텍스트 축소 및 프롬프트. 프롬프트를 1-2KB로 유지합니다. 정확한 파일 경로를 명시하고, 큰 파일의 경우 grep -n 오프셋을 통해 라인 범위나 describe( 블록을 가리킵니다. 특정 작업과 관련된 계약 조각만 포함합니다. "탐색을 짧게 유지: 파일을 일찍 작성하고, 그 다음 다듬으세요."를 추가합니다.
• 테스트 실행 및 실패 처리, 모든 프롬프트에 명시적으로:
  • 정확한 테스트 명령어 제공: "Run tests to verify your implementation using: npx ng test <proj> --watch=false --include='**/<file>.spec.ts'"
  • 테스트 또는 테스트 설정 편집 금지: "NEVER modify *.spec.ts files and NEVER create or modify test configuration files (e.g., jest.config.js, karma.conf.js, vitest.config.ts, tsconfig.spec.json). Test configs are static and handled externally."
  • 도구 자가 복구 금지: "If test execution fails, or if you encounter test config/runner errors, DO NOT attempt to fix or generate test configuration files. Immediately stop execution, print the failure details, and exit with an error code."
  • 아직 구축되지 않은 다른 모듈의 관련 없는 컴파일 오류는 무시하도록 지시합니다.
• 세분성. 한 번에 하나의 파일. 큰 파일은 증분적이고 추가 전용 호출로 분할합니다("APPEND X; 기존 함수를 변경하지 마십시오").
• 대상 검증 및 중단 방어. 각 단계 후에 oc 헬퍼를 통해 대상 테스트를 실행합니다. 0이 아닌 종료 코드 또는 설정/러너 오류로 인한 테스트 실패는 마스터 스크립트를 즉시 중단합니다.
• SHA1 검증. Phase A와 동일: 대상 파일이 변경되지 않으면 최대 3회 재시도 후 중단.

5. 스톨 워치독 (30분 임계값)

각 opencode 호출을 백그라운드에서 실행하고, PID를 캡처한 후($OC_PID), 60초마다 로그를 폴링합니다.

• 종료 조건 — 두 조건이 동시에 충족되어야 함:
  1. 가장 최근의 비어 있지 않은 로그 라인이 cleanup prune을 포함합니다.
  2. 로그가 1800초 동안 (크기/내용) 변경되지 않았습니다.
• cleanup prune만으로는 절대 종료하지 마십시오. 시작 시와 매시간 정기적으로 기록됩니다. 로그가 활발하게 증가하는 동안에는 절대 종료하지 마십시오.
• 종료 절차 (프로젝트 범위로만):
  1. kill -9 $OC_PID 2>/dev/null || pkill -9 -f "opencode.*${PROJECT_NAME}", 래핑 script PID도 종료합니다.
  2. 이 프로젝트의 스냅샷만 정리: find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true.
  3. 최대 2회 재시도까지 단계를 다시 시도합니다.