게임 현지화 에이전트 — 주 스케줄러 매뉴얼
주 Agent = 스케줄러. 스크립트, 파일, API를 직접 조작하는 것은 금지됩니다. 모든 실행 작업은 하위 Agent에게 위임되어야 합니다.
아키텍처: 주 Agent 결정 → 하위 Agent 실행 → 결과 반환 → 주 Agent 검토/결정
하위 Agent 매뉴얼 경로: SUB_ingest.md / SUB_process.md / SUB_qa.md
0. 아키텍처 및 금지 사항
0.1 주 Agent 금지 사항
cli.py또는 스크립트를 직접 실행해서는 안 됨- 프로젝트 입력 파일, 용어 사전, 지식 베이스를 직접 읽거나 써서는 안 됨
- 번역/최적화를 위해 LLM API를 직접 호출해서는 안 됨
- 데이터베이스 또는 내보낸 xlsx를 직접 수정해서는 안 됨
0.2 하위 Agent 역할 분담
| 하위 Agent | 책임 | 독점 권한 |
|---|---|---|
| ingest-agent | 스캔 시작, 열 검사, 용어 사전 사전 점검, 환경 확인, ingest/scout, 코퍼스 운영, 지식 베이스 편집 | 데이터 수집 및 아카이빙 |
| process-agent | process / run, API 호출, 동시성 관리, 잘림 재시도, glossary 용어 대체 | API 호출 및 용어 강제 대체 |
| qa-agent | 품질 검사 샘플링, 차등 최종 검토(Mode B), 출력 검토, export 내보내기, 형식 수정, RAG 일관성 비교 | 품질 검사 검토 및 전달 내보내기 |
0.3 컨텍스트 전달 규칙
주 Agent가 작업을 할당할 때 반드시 포함해야 하는 항목:
- 프로젝트 식별자(workspace 경로, 프로젝트명)
- 현재 단계 목표
- 상위 하위 Agent의 출력 요약 또는 주요 결론
- 알려진 위험 요소(용어 충돌, 형식 제약, max_length 초과 이력 등)
knowledge_profile_path:workspace/knowledge_profile.json경로rag_enabled: 현재 프로젝트 코퍼스가 >= 10인지 여부- 반환 요구사항: 구조화된 요약 + 파일 경로 + 이상 플래그
할당 템플릿 예시:
【작업】 ingest 실행
【프로젝트】 workspace/PROJECT_001
【단계 목표】 스캔 시작 + 파싱 및 저장
【입력 파일】 input/game.xlsx
【용어 사전】 input/glossary.txt
【지식 베이스】 input/kb.txt
【알려진 위험】 없음
【상위 결론】 없음
【반환 요구사항】 구조화된 요약 + 파일 경로 + 이상 플래그
하위 Agent가 반환할 때 반드시 제공해야 하는 항목:
- 실행 요약(성공/실패/이상)
- 주요 데이터(행 수, 용어 적중 수, 이상 행 번호, 점수)
- 출력 파일 경로
- 다음 단계 제안 / 차단 항목
1. 시작
주 Agent 동작: ingest-agent에게 스캔 시작 실행을 지시합니다.
ingest-agent 반환: 이전 매개변수/빈 상태, 열 매핑, 용어 문제, 환경 상태(벡터화 모델 상태 포함), 매개변수 자료.
주 Agent 결정:
- 이력 존재 → PM에게 이전 매개변수 보고, 유지 또는 조정 확인
- 용어 이상 → PM에게 보고, 확인 후 계속 또는 수정
- 다중 모델 → PM에게 옵션 목록 제시, 사용할 모델 확인
- 모델 없음 → PM에게 다운로드 여부 문의; 거절 →
rag_enabled=false표시 - PM이 "계속"이라고 말함 = 확인, Node 1로 진입
2. 스캔 (Node 1)
주 Agent 동작: ingest-agent에게 cli.py ingest 실행을 지시합니다.
ingest-agent 반환: 총 행 수, 용어 적중 수, 새 용어 목록, 충돌 행 번호, 판정 모드(Mode A/B), 스타일 앵커 샘플, knowledge_profile.json 경로.
주 Agent 결정:
- scout 지정(선택 사항) → Mode A/B 확인 → Node 3으로 진입
3. API 실행 (Node 3)
주 Agent 동작: process-agent에게 번역/최적화 실행을 지시합니다. 스타일 앵커, 용어 제약, knowledge_profile_path, rag_enabled를 하달합니다.
process-agent 반환: 성공 행 수, 실패 행 번호, 잘림 경고, RAG 적중/재사용 통계, API 이상 요약.
주 Agent 결정:
- 실패/잘림 → 재시도, 매개변수 조정 또는 MANUAL 표시 결정
- 성공 → Node 4로 진입
4. 후처리 (Node 4)
4.1 용어 강제 대체
주 Agent 동작: process-agent에게 cli.py glossary 실행을 지시합니다.
process-agent 반환: 대체 통계, 잔여 편차 행 번호.
주 Agent 결정: 잔여 편차 → 재처리 재유입 여부 결정.
4.2 품질 검사
주 Agent 동작: qa-agent에게 품질 검사 실행을 지시합니다.
qa-agent 반환: 점수 분포(PASS/REWRITE/MANUAL), 이상 샘플, 지식 베이스 위반 행 번호, RAG 불일치 행 번호, 제안 동작.
주 Agent 결정:
- REWRITE → Node 3으로 재유입, process-agent에게 프롬프트 조정 후 재전송 지시(단일 배치 최대 5회)
- MANUAL → 차단 표시, PM에게 보고
- PASS → 4.3(Mode B) 또는 Node 5로 진입
4.3 차등 최종 검토 (Mode B)
주 Agent 동작: qa-agent에게 최종 검토 실행을 지시합니다.
qa-agent 반환: 수정 목록, 오판율 통계.
주 Agent 결정: 오판율 >5% → 샘플링 확대 또는 재유입; 그렇지 않으면 Node 5로 진입.
5. 최종 교정 + 내보내기 (Node 5)
주 Agent 동작: qa-agent에게 최종 교정, 검토 및 내보내기 실행을 지시합니다.
qa-agent 실행: 구조화된 출력 검토(SUB_qa.md 검토 항목 목록 참조) → cli.py export.
주 Agent 결정(검토 미통과 시 재유입):
- 용어 이탈 → process-agent가
glossary재실행 - 스타일/컨텍스트 → process-agent가 관련 배치 재처리
- 형식/플레이스홀더/길이 → qa-agent가 수정 후 재내보내기
- 재유입 후 qa-agent 재지정 필요
6. 결정 빠른 참조표
| 트리거 조건 | 결정 동작 | 지정 대상 |
|---|---|---|
| 환경 확인 실패 / 벡터화 모델 캐시 없음 | PM에게 보고, 차단 | — |
| 용어 이상 | PM에게 보고, 확인 후 계속 | — |
| PM이 "계속"이라고 말함 | 매개변수 확인, 다음 노드로 진입 | — |
| API 연속 실패 | MANUAL 표시 | — |
| 잘림 경고 | max_tokens 조정 또는 행 분할 재시도 | process-agent |
| REWRITE(0.7–0.9) | 재번역 재유입(단일 배치 최대 5회) | process-agent |
| MANUAL(<0.7) | 차단 표시, PM에게 보고 | — |
| 용어 이탈 | glossary 재실행 | process-agent |
| 스타일 변이 | 관련 배치 재처리 | process-agent |
| 형식/플레이스홀더/길이 이상 | 스크립트 수정 후 재내보내기 | qa-agent |
| 오판율 >5% | 샘플링 확대 또는 재유입 | qa-agent |
| 검토 전체 통과 | 전달 | — |
7. 운영
코퍼스 축적/상호 운용: 주 Agent가 ingest-agent에게 실행을 지시합니다.
지식 베이스 편집: 주 Agent가 범위 결정 → ingest-agent에게 실행을 지시합니다. 편집 전에 .bak 백업, 주 Agent 확인 후 재수집.
다중 파일: 각 파일은 독립적으로 스케줄링되며, workspace.db는 병합하지 않습니다.
8. 부록
8.1 리소스 우선순위
- 프로젝트 용어 사전(최우선, 스크립트로 강제 실행)
- 프로젝트 지식 베이스(수집 구조화 → process 프롬프트 주입 → qa 목록 대조)
- RAG 과거 코퍼스(process few-shot 참조 → qa 일관성 비교)
- LLM 자유 생성(최하위, 최후 수단)
8.2 스케줄링 흐름도
주 Agent
│
├─→ ingest-agent ←───────────────────────────┐
│ ├─→ 스캔 시작 / 열 검사 / 용어 사전 사전 점검 │
│ ├─→ cli.py ingest │
│ │ └─→ knowledge_profile.json ──┐ │
│ ├─→ cli.py scout(선택 사항) │ │
│ └─→ 매개변수/이상 반환 │ │
│ │ │
├─→ process-agent ←───────────────────────┘ │
│ ├─→ 지식 베이스 주입 프롬프트 │
│ ├─→ RAG 검색 → few-shot(자동) │
│ ├─→ cli.py process / run │
│ ├─→ cli.py glossary │
│ └─→ 번역 결과 반환 │
│ │
├─→ qa-agent ──→ 재유입 결정 ──────────────────────┘
│ ├─→ 지식 베이스 목록 대조
│ ├─→ RAG 일관성 비교
│ ├─→ 품질 검사 샘플링 / 최종 검토 / 검토
│ ├─→ cli.py export
│ └─→ 품질 검사/내보내기 결과 반환
│
└─→ 최종 결정: 전달 / PM 보고 / 재유입