나만의 팀 하네스 구축 — 통합 실습 가이드
2026.10.15
# 나만의 팀 하네스 구축 — 통합 실습 가이드
> **CYS Terminal(JARVIS) × Ouroboros Interview·Seed·Run × Research Survey v2**
> 교육생 배포용 · 2026-10-13 통합판 · 타임스탬프 없음
이 가이드는 다섯 가지 교육 자료와 세미나 내용을 연결해, 교육생이 **하나의 실무 과제를 정의하고, 구현하고, 검수하고, 다시 개선**할 수 있도록 만든 통합 지침이다. 서비스·CLI의 설치 버전과 UI가 다를 수 있으므로 명령 실행 전에 현재 설치의 도움말과 연결 상태를 확인한다.
**가장 중요한 원칙:** Ouroboros는 무엇을 만들지 명확하게 하는 요구사항 정리·구현 흐름이고, CYS는 누가 일을 맡고 누가 검수할지 정하는 조직 운영 구조이며, Research Survey는 그 구조로 수행하거나 개선할 수 있는 구체적인 도메인 하네스다. 세 가지를 모두 사용해야만 하는 것은 아니다.
---
## 0. 처음 읽는 사람을 위한 한 페이지 요약
### 학습 목표
수업이 끝나면 교육생은 다음을 수행할 수 있어야 한다.
- 업무 목표·입력·출력·금지사항·성공 조건을 PLAN.md로 문서화한다.
- Ouroboros 인터뷰에 요구사항의 빈틈을 질문하게 하고, 확정된 **Seed YAML**을 확보한다.
- 구현에 사용할 **프로젝트 루트**와 Seed 위치를 구분하고, 실제 코드/파일이 어디에 작성되는지 확인한다.
- CYS Terminal에서 master, cso, worker, reviewer의 권한과 인계 형식을 정의한다.
- Research Survey의 **후보 추천 → 사용자 선택 → 계획 → 검색 → 원문 검증 → 비교 서베이**를 실행하거나, 이 업무를 더 잘하는 하네스를 개선한다.
- 결과물에 대해 증거 기반 ACCEPT/REVISE/REJECT 판정을 내리고 다음 실행으로 연결한다.
### 통합 전체 흐름
```text
[운영자] 해결할 문제 선택, PLAN.md 작성
│
▼
[Ouroboros Interview] 목표·범위·제약·수용기준을 질문으로 정제
│
▼
[Ouroboros Seed] 합의된 요구사항을 YAML 명세로 고정
│ └─ interview/seed 원본 식별 · 복사 · 출처/해시 기록
▼
[프로젝트와 실행 위치 확정] Seed 파일 ≠ 코드 작업 루트 ≠ 결과 저장 폴더
│
├─ (경로 A) 기존 Research Survey v2로 곧바로 업무 수행
│
└─ (경로 B) Ouroboros Run으로 하네스 구현·개선
│
▼
[CYS 팀 운영: 필요할 때만]
master(결정·인수) → worker(실행·증거 보고)
↘ cso(환경·비용·장애)
↘ reviewer(독립 품질 판정)
│
▼
테스트·평가 → 피드백 → 스킬/지침 업데이트 → 재평가
```
**두 가지 사용 경로를 먼저 선택한다.**
| 경로 | 언제 적합한가 | 권장 구성 | 목표 산출물 |
|---|---|---|---|
| **A. 지금 논문을 조사한다** | 이미 Research Survey가 있고 리서치 결과를 얻고 싶은 경우 | Research Survey v2 단독, 필요하면 1명의 검수 | 후보·검색 기록·논문별 리뷰·서베이 |
| **B. 논문 조사 하네스를 만든다/고친다** | 반복할 리서치 업무의 검색·필터·평가 방식을 개선하는 경우 | PLAN → Ouroboros → CYS 1~4역할 | 재사용 가능한 워크스페이스·스킬·평가셋·테스트 |
**피해야 할 혼동 ①** Research Survey에서 말하는 reference/seed 논문은 연구 방향을 고르는 출발 논문이다. **Ouroboros Seed YAML**은 구현 요구사항 명세다. 이름이 비슷하지만 목적과 파일 형식이 다르다.
**피해야 할 혼동 ②** CYS의 역할 분담과 Ouroboros 자체의 실행·평가 에이전트는 별개의 오케스트레이션이다. 같은 검사를 양쪽에서 무한히 중복 실행하지 말고, **Ouroboros 내부 QA**와 **CYS의 사용자 업무 기준 최종 인수**를 구분한다.
---
## 1. 세 도구의 관계와 용어
| 개념 | 의미 | 무엇을 결정하는가 | 대표 산출물 |
|---|---|---|---|
| **Workspace** | 코드·지침·예제·문서가 있는 프로젝트 작업 공간 | AI가 참조할 맥락 | AGENTS.md, CLAUDE.md, skills/, docs/ |
| **Harness** | 업무를 일관되게 수행하도록 구성한 지침·도구·상태·평가·피드백의 집합 | 수행 방식과 품질 관리 | 스킬, 템플릿, 테스트, 평가 규칙 |
| **CYS Department** | 하나의 업무 영역 또는 프로젝트를 관리하는 부서 | 업무 담당과 세션의 분리 | 부서별 설정·맥락·산출물 |
| **Role** | 부서 안의 책임 단위 | 누가 결정·실행·검수하는가 | briefs, reports, reviews, logs |
| **Ouroboros Interview** | 모호한 요구를 구조화하는 질문 절차 | 목적, 범위, 미결정 사항 | 인터뷰 기록 JSON |
| **Ouroboros Seed** | 인터뷰 결과를 고정한 구현 계약 | 수행 목표, 제약, 수용 기준 | seed_*.yaml |
| **Ouroboros Run** | Seed를 받아 구현/실행하는 과정 | 어떤 프로젝트에 어떤 변경을 할지 | 코드·작업 세션·실행/평가 기록 |
| **Research Survey v2** | 검색·선정·원문 검증·종합 비교를 위한 업무별 워크플로 | 어떤 논문을 왜 포함할지 | candidates/selection/plan/reviews/survey |
### 도구를 선택하는 기준
- **단순한 1회 작업:** Codex/Claude 단일 세션 또는 기존 Research Survey 도구를 먼저 사용한다.
- **요구사항이 모호한 신규 과제:** PLAN.md → Ouroboros Interview → Seed로 명확히 한다.
- **수정과 검증이 여러 번 필요한 구현:** Ouroboros Run과 Git 기반 테스트를 활용한다.
- **장기·병렬·고위험 작업:** CYS에서 Master 중심으로 역할별 계약과 인계 문서를 만든다.
- **매일 같은 작업:** 처음 하네스를 안정화한 뒤, 필요한 스크립트/스케줄러로 정기 실행한다. 매번 무거운 멀티 에이전트 전체를 돌릴 필요는 없다.
### 세미나에서 나온 도구 사용 원칙
1. **결과물 한 건을 먼저 만들어본다.** 성공과 실패가 드러난 뒤에 수행 과정을 스킬/하네스로 추출한다.
2. **도메인 지식은 생략할 수 없다.** AI가 아는 일반 상식과 실제 전문가의 포함·제외 기준은 다르다.
3. **일반 가이드보다 결과물 피드백이 중요하다.** 좋은 결과/나쁜 결과를 근거와 함께 알려주고 지침에 반영한다.
4. **긴 세션을 하나로 유지하는 것이 항상 유리하지는 않다.** 경로와 문서로 인계하고 작업 단위를 분리한다.
5. **좋아졌다고 주장하기 전에 같은 입력으로 비교한다.** 품질뿐 아니라 실패율, 지연, 토큰도 기록한다.
---
## 2. 시작 전에 확인할 것: 환경·권한·폴더
### 2.1 입문 준비 점검
| 항목 | 확인 사항 | 검증 방법 |
|---|---|---|
| Codex 또는 Claude Code | 현재 접속할 수 있는 환경과 실제 로그인 상태 | CLI를 열어 버전·연결 확인 |
| Ouroboros | 현재 환경에 설치됐는지, MCP가 실제로 연결됐는지 | 대화창 ooo setup 또는 CLI 도움말/상태 확인 |
| CYS Terminal | 설치본 버전, 부서 추가 UI, 역할 변경 방법 | 실제 앱에서 확인. 버전별 UI 차이 인정 |
| Research Survey v2 | research-survey-v2/ 폴더와 AGENTS.md / 스킬 | 폴더와 README 확인 |
| 네트워크·검색 | PubMed/OpenAlex/학회 원문 접근 | 시험 검색 및 오류 기록 |
| 데이터·안전 | 민감정보·API 키·유료 호출·외부 발행 승인 조건 | 별도 권한 체크리스트 |
| Git | 소스 백업과 변경 추적 | git status와 변경 내용 확인 |
명령의 **입력 위치**를 반드시 구분한다.
- **PowerShell/터미널:** Set-Location, git status, python ..., ouroboros run ...처럼 실제 프로그램을 실행하는 명령.
- **Codex·Claude 대화창:** ooo interview ..., ooo seed, ooo run ... 등 플러그인 스킬 호출 및 자연어 요청. 플러그인 미설치 시 동일하게 동작하지 않는다.
- **CYS 채팅/Control Center:** 부서·역할 구성, 경로 기반 업무 지시, 승인·거부. CYS의 정확한 UI 명칭은 설치 버전에 따라 달라질 수 있다.
### 2.2 파일 구성 권장안 — **교육용 제안 구조**
아래 구조는 여러 자료를 통합하기 위한 **교육용 제안**이며 CYS, Ouroboros, Research Survey가 자동으로 만들거나 강제하는 단일 공식 표준이 아니다. Research Survey 실행 시 생성되는 경로는 실제 도구 계약을 우선한다.
```text
harness-workspace/
├─ AGENTS.md # Codex가 읽을 프로젝트 시작 안내 (권장)
├─ CLAUDE.md # Claude Code를 쓸 때 (선택)
├─ PLAN.md # 사람이 쓴 초기 업무 맥락
├─ requirements/
│ └─ import-v1/
│ ├─ interview-original.json
│ ├─ seed-original.yaml
│ └─ provenance.json
├─ contracts/
│ ├─ role-contracts.md
│ └─ quality-gates.md
├─ briefs/ # master → worker 작업 지시
├─ reports/ # worker 수행·자체 점검 기록
├─ reviews/ # reviewer 독립 판정
├─ logs/ # CSO 환경/오류/비용 기록
├─ research/ # 업무별 원문·결과 (예시)
│ ├─ artifacts/discovery/<session>/
│ └─ 40-drafts/<session>/
├─ evaluations/ # 비교평가·회귀 테스트
├─ handoffs/ # 세션 재개 문서
└─ README.md # 열기·실행·중단·복구 안내
```
**분리 기준:** requirements/는 합의한 요구, briefs/는 구체적 작업, reports/는 실제 수행 근거, reviews/는 독립 판정, evaluations/는 기준 대비 성능 변화다.
---
## 3. PLAN.md 작성: 인터뷰 전에 사람이 알아야 하는 것
Ouroboros가 질문을 잘하려면 출발점을 줘야 한다. 세미나에서는 최소 20줄 안팎이라도 문제와 판단 기준을 먼저 써 놓고 인터뷰하는 접근을 권했다. 중요한 것은 길이가 아니라 **최종 결과물과 포함·제외 기준의 구체성**이다.
### 3.1 복사해서 채우는 템플릿
```markdown
# PLAN — [프로젝트명]
## 사용자와 해결할 문제
- 실제 사용자는:
- 기존 방식의 실패/반복 작업:
- 이 프로젝트를 하는 이유:
## 원하는 결과물과 완료 기준
- 입력:
- 출력 및 저장할 파일:
- 성공으로 볼 객관적 조건 3~5개:
## 업무 프로세스 / 도메인 규칙
- 실제 사람이 하던 순서:
- 신뢰하는 1차 자료/레퍼런스:
- 반드시 포함할 것:
- 반드시 제외할 것:
- 중요도를 판단하는 기준:
## 기술적/운영 제약
- 실행 환경/프로젝트 루트:
- 사용 가능한 모델·도구·예산:
- 허용된 변경 범위:
- 외부 전송/유료 API/발행 승인 정책:
## 실패와 미결정 사항
- 이미 겪었던 오류/불만:
- 판단하지 못한 문제:
- Ouroboros가 확인해야 할 질문:
```
### 3.2 Research Survey 하네스를 만들 때의 좋은 입력
> **교육용 예시:** “Medical LLM의 RL post-training 논문을 조사한다. 보상 설계, 사용 데이터, base model, 독립 평가, 의료적 한계를 비교한다. Radiology report 생성·수정은 포함하고, 비의료 RL은 방법론 배경으로만 다룬다. DOI/공식 URL, 게재 상태, 원문 확인 수준을 기록한다. 내가 논문 후보를 선택하기 전에는 집중 검색을 하지 않는다. 결과는 프로젝트 폴더에 저장하며, 원문을 안 읽은 논문은 미정독으로 표시한다.”
### 3.3 인터뷰 전에 기존 자산을 연결하는 방법
기존 Codex 워크스페이스, 직접 만든 리서치 필터, 과거 성공·실패 예시가 있으면 새 세션에 **참조 경로**를 제공한다. 학습 실험으로 신규 도구를 공정 비교할 때만 의도적으로 제로베이스를 유지한다.
```text
PLAN.md와 아래 기존 자료를 참고해서 새 요구사항을 정리해줘.
- 이전 성공 사례: examples/good/
- 이전 실패 사례: examples/bad/
- 기존 평가 기준: evaluations/baseline.md
- 금지: 과거 답을 무비판적으로 정답으로 채택하지 말 것.
먼저 참조할 수 있는 정보와 불확실한 정보를 구분해줘.
```
---
## 4. Ouroboros Interview: 질문으로 요구사항을 수렴하기
### 4.1 무엇을 하며 어떤 입력을 받는가
인터뷰는 “앱을 만들어줘” 같은 막연한 요구를 **목표·대상·입출력·필수 기능·금지사항·수용기준**으로 바꾸는 단계다. 사용자 인터뷰를 통한 의도 구체화가 핵심이며, 그 자체가 코드 구현은 아니다.
수업 자료의 핵심 사용법은 **프로젝트를 연 Codex/Claude 대화창에 ooo interview ...**를 입력하고 후속 질문에 답하는 것이다. 현재 설치 방식에 따라 ooo 스킬과 터미널 CLI는 별도 인터페이스이므로, 단독 CLI에서는 ouroboros init start ... 등의 해당 버전 명령을 확인한다.
**대화창 입력 예시 — Research Survey 개선:**
```text
ooo interview 다음 프로젝트의 PLAN.md를 먼저 읽어줘.
프로젝트 목적은 반복 가능한 Medical LLM 논문 서베이 하네스를 만드는 거야.
반드시 주제 제안 → 실제 출처 검증된 reference 추천 → 사용자 선택/코멘트
→ 집중 검색 → 원문 리뷰 → RQ별 비교까지 포함해.
검색 실패와 논문 없음, 초록 확인과 원문 정독을 구분해야 해.
결과물은 별도 프로젝트 폴더에 저장하고 싶어.
먼저 성공 기준, 데이터 출처, 검수 방식, 예산, 승인 경계를 질문해줘.
```
### 4.2 인터뷰에 답할 때의 원칙
1. **선택지만 선택하지 않는다.** 1번의 일부 + 3번의 제한사항처럼 복합 답과 이유를 설명한다.
2. **권장·금지·미정**을 구분한다. 모르는 항목은 질문으로 남기고 AI의 임의 확정을 막는다.
3. **실제 예시를 제시한다.** “좋은 리서치”보다는 좋은 포함 사례 3개/제외 사례 3개가 유용하다.
4. **미래의 테스트로 바꿀 수 있게 답한다.** “논문 출처가 반드시 있어야 한다”는 검증 가능하지만 “품질 좋게”는 검증할 수 없다.
5. **인터뷰의 길이를 성능 지표로 삼지 않는다.** 10문항으로 충분할 수도 있고 복잡한 과제는 훨씬 오래 걸릴 수 있다.
**교육용 답변 예시:**
```text
1번의 '의료 LLM' 범위를 사용하되, 3번의 '영상의학 보고서 생성·수정'을
별도 하위 그룹으로 추가해줘. 임상적 정확성은 단일 점수로 판단하지 말고,
평가의 독립성, 데이터셋 분할, 사람 평가가 있었는지를 각각 기록해.
논문 2~3개를 선택하면 검색을 확장하고, 선택 전에는 확장하지 마.
```
### 4.3 인터뷰를 종료해도 되는 조건
- 요구사항과 제외사항이 모순되지 않는다.
- 산출물의 **파일 형식과 위치**, 성공/실패의 판정 방법이 적혀 있다.
- 접근권한·외부 공유·유료 사용의 승인 주체가 명확하다.
- 미정 항목은 “미정”으로 명시되고, 치명적 미정은 실행 전에 해결한다.
- 인터뷰 최종 요약을 운영자가 승인했다.
**PM 모드:** 발표에서 제품 PRD 작성에는 별도 PM 지향 인터뷰 모드가 도움이 될 수 있다는 의견이 나왔다. 버전마다 명령과 지원 범위가 다르므로 현재 도구의 PM 인터뷰 기능을 확인하고 사용한다. 이것은 일반 인터뷰보다 항상 우월하다는 의미가 아니다.
---
## 5. Ouroboros Seed: 인터뷰를 실행 계약으로 바꾸기
### 5.1 Seed 생성
**대화창 예시:**
```text
인터뷰 최종 요약이 합의된 요구사항과 일치해.
목표·비목표·제약·수용기준·의존성·작업 위치를 확인한 뒤
확정된 Seed를 생성하고 파일 경로와 식별자를 알려줘.
```
수업용 플러그인 경로에서 **같은 대화 세션**에 다음처럼 요청한다.
```text
ooo seed
```
인터뷰 세션을 지정해야 한다면 자료의 예시처럼 ooo seed <인터뷰 세션 ID>를 사용할 수 있다. 다만 Ouroboros 버전에 따라 인터뷰 종료 시 Seed가 이미 생성되거나 ooo run으로 이어질 수 있으므로 **이미 있는 Seed를 무의미하게 중복 생성하지 않는다.**
### 5.2 Seed 검토 항목
| Seed 영역 | 교육생이 반드시 확인할 질문 |
|---|---|
| Goal / Scope | 원하는 결과가 한 문장으로 명확한가? |
| Non-goals | 로그인·결제·배포 등 범위 밖 작업이 배제됐는가? |
| Inputs / Outputs | 파일 형식과 경로가 구체적인가? |
| Constraints | 비용, 개인정보, 접근권한, 수정 금지 경로가 있는가? |
| Acceptance criteria | 명령·파일·데이터로 합격을 입증할 수 있는가? |
| Dependencies | 검색 API·CLI·네트워크 등 선행 조건이 표현됐는가? |
| Open issues | 의도적으로 보류한 결정이 남아 있는가? |
**주의:** 아래는 **의미를 보여주는 교육용 의사 YAML**이다. 설치된 Ouroboros의 정식 Seed 스키마를 재현한 것으로 간주하거나 그대로 CLI에 입력해서는 안 된다.
```yaml
# 교육용 개념 예시 — 실제 실행용 Seed 아님
goal: "Evidence-grounded Medical LLM survey workflow"
constraints:
- "공식 출처 확인"
- "원문 미확인 논문은 미정독으로 표시"
non_goals:
- "임상적 유효성 보장"
acceptance_criteria:
- "후보 논문마다 출처와 게재 상태를 기록"
- "사용자 선택 전 집중 검색 금지"
- "서베이 주장에 원문 페이지/표 근거 연결"
```
### 5.3 Seed 원본을 왜 보관하나
인터뷰 질문에 대한 결정 사항은 나중에 맥락 압축이나 모델 교체로 사라질 수 있다. Seed를 요구사항 기준점으로 고정하면, 테스트 실패·운영자 피드백을 해당 버전에 연결할 수 있다.
---
## 6. Seed/인터뷰 원본을 프로젝트로 가져오기
첨부된 **`OUROBOROS_INTERVIEW_SEED_IMPORT.md`**의 핵심은 **“파일을 프로젝트에 복사하는 것”과 “해당 프로젝트에서 구현 실행하는 것”을 분리**하는 데 있다. 스킬 등록 없이도 프로젝트별 가져오기를 수행할 수 있다.
### 6.1 로컬 파일 위치 — 해당 자료에서 확인한 한 설치 환경의 예
| 파일 | 로컬 위치 예시 |
|---|---|
| 인터뷰 JSON | %USERPROFILE%\.ouroboros\data\interview_*.json |
| Seed YAML | %USERPROFILE%\.ouroboros\seeds\seed_*.yaml |
| 실행 상태 DB | %USERPROFILE%\.ouroboros\ouroboros.db |
이는 한 로컬 설치에서 확인한 위치로, 모든 OS·버전에서 같은 경로라는 뜻이 아니다. 원본을 옮기거나 지우지 말고 복사본을 프로젝트에 둔다.
### 6.2 가져오기 6단계
1. **대응되는 인터뷰·Seed를 식별:** 파일이 최신이라는 이유만으로 선택하지 않는다. ID와 내용·목적을 확인한다.
2. **원본 보존:** 원래 .ouroboros 파일과 DB를 수정하지 않는다.
3. **프로젝트에 버전별 복사:** requirements/import-v1/에 interview-original.json, seed-original.yaml을 넣는다.
4. **출처와 무결성 기록:** 원본/복사본 경로, ID, 복사 시각, SHA256, 대응 확인 근거를 provenance.json에 남긴다.
5. **읽기용 문서 별도 생성:** interview-readable.md는 편집본이 아니라 원본의 설명용 요약이다. 기록에 없는 답/승인을 만들지 않는다.
6. **실행에 사용할 명세 경로 고정:** CYS Master·Ouroboros Run이 **어느 버전의** seed-original.yaml을 읽어야 하는지 지정한다.
**마스터에게 복사해 보낼 요청문:**
```text
현재 프로젝트와 실제로 대응하는 Ouroboros 인터뷰와 Seed를 찾아줘.
최신 파일이라는 이유만으로 선택하지 말고 interview_id와 목표를 대조해.
내부 원본은 보존하고 requirements/import-v1/로 그대로 복사해줘.
원본/복사본 경로, 식별자, 시각, SHA256, 대응 관계 근거를 기록하고
복사본 해시가 원본과 같은지 확인해.
읽기용 Markdown은 별도로 만들되 원본에 없는 답변이나 승인은 작성하지 마.
후보가 복수거나 관계를 특정할 수 없으면 결정 전에 보고해.
이후 Run과 작업 브리프가 참조할 Seed 경로까지 명확히 표시해.
```
### 6.3 언제 재사용 스킬로 만들까
한 프로젝트를 한 번 가져오려면 **복사·검증**으로 충분하다. 여러 프로젝트에서 같은 식별·복사·해시·인계 과정을 반복한다면 그 절차를 스킬로 만들 수 있다. 프로젝트별 Seed 자체를 전역 스킬로 등록할 필요는 없다. 또한 원본 복사만으로 Ouroboros의 실행 상태나 세션이 자동으로 이전되지는 않는다.
---
## 7. Run 실행 전에 반드시 지정할 세 가지 경로
| 이름 | 뜻 | 예시 |
|---|---|---|
| **Seed 파일 경로** | 무엇을 구현할지 결정하는 YAML | requirements/import-v1/seed-original.yaml |
| **프로젝트 루트** | 실제 코드를 읽고 수정할 기준 디렉터리 | C:\harness-workspace\medical-survey-harness |
| **결과물 폴더** | 리포트·표·문서 등을 저장할 하위 폴더 | ...\medical-survey-harness\output |
cd로 셸을 이동했다고 MCP 서버의 cwd 또는 실행 세션이 자동으로 바뀌지 않는다. --project-dir는 **기존 로컬 가이드가 2026-10-12 설치 코드에서 확인한 옵션**이므로, 현재 버전의 ooo run --help / ouroboros run --help에 실제로 있는지 확인한다. 실행이 별도 Git worktree에서 이루어질 수 있으므로 반환된 **실제 수정 경로**까지 검증한다.
### 7.1 현재 설치에 --project-dir 옵션이 있는 경우
**PowerShell / CLI 예시 — 버전 확인 후에만 사용:**
```powershell
# 실행 전 실제 지원 옵션과 상태부터 확인
ouroboros --version
ouroboros run --help
# 아래 옵션은 로컬 설치에서 지원될 때만 사용
ouroboros run "C:\harness-workspace\medical-survey-harness\requirements\import-v1\seed-original.yaml" `
--project-dir "C:\harness-workspace\medical-survey-harness"
```
**중요한 버전 차이:** 첨부된 2026-10-12 로컬 가이드는 --dry-run을 Seed 검증 용도로 안내한다. 반면 확인한 **공식 Ouroboros CLI Reference(2026-10-13 조회)**에는 기본 orchestrator 모드에서 --dry-run이 **실제 실행을 막지 않을 수 있으며**, --no-orchestrator와 함께 쓸 때만 검증 전용으로 동작한다고 명시되어 있다. **`--dry-run` 하나만 붙여서 안전한 미실행이라고 믿지 않는다.** --no-orchestrator 지원 여부와 해당 버전 도움말을 확인한 뒤 테스트하거나, 별도의 읽기 전용 스키마 검증을 수행한다.
```powershell
# 공식 문서가 설명하는 조합 — 설치된 버전에서 반드시 도움말 확인
ouroboros run "C:\harness-workspace\medical-survey-harness\requirements\import-v1\seed-original.yaml" `
--no-orchestrator --dry-run
```
공식 문서의 현재 CLI 목록과 특정 로컬 설치의 옵션 집합은 다를 수 있다. **실제로 지원하지 않는 옵션은 삭제해서 ‘비슷하게’ 실행하지 말고, 안전한 경로 지정 방법을 먼저 확인**한다. 플러그인·MCP 경로에서는 도구 호출이 전달받은 cwd와 결과의 실제 작업 폴더를 확인한다.
### 7.2 Run 전에 Master가 읽어야 할 승인표
```text
[ ] Seed: 정확한 ID / 절대경로 / 해시
[ ] 작업 종류: 새 프로젝트 / 기존 코드 개선 / 결과물 제작
[ ] 프로젝트 루트: 실제 cwd 또는 지원되는 CLI 경로 옵션
[ ] 실수정 위치: 원본 폴더 또는 작업 worktree
[ ] 수정 허용 범위 / 삭제 금지 파일
[ ] 산출물 경로와 파일 이름
[ ] 유료 호출·커밋·설치·배포·외부 발행의 승인 범위
[ ] 실행/평가 후 어떤 파일로 증거를 남길지
```
### 7.3 다른 프로젝트 유형을 혼동하지 않는다
- **새 연구 하네스 개발:** --project-dir/`cwd`는 새 하네스 소스 프로젝트.
- **기존 영상 하네스 reviewer 수정:** --project-dir/`cwd`는 설치된 스킬 복사본이 아닌 원본 소스 저장소. 운영본/설치본 반영은 따로 검증한다.
- **이미 설치된 영상 하네스로 영상 제작:** 하네스 실행 파일은 도구로 사용하고, 영상 콘텐츠 작업 폴더는 별도로 지정한다. 해당 스킬의 --root는 Ouroboros의 --project-dir와 서로 다른 옵션이다.
---
## 8. CYS Terminal: 부서와 네 역할을 설정하기
### 8.1 CYS에서 **부서**와 **역할**은 다르다
부서는 리서치, 영상, 마케팅 같은 **업무 범위**이고, 역할은 그 안에서 결정을 내리거나 실행·검수하는 **책임**이다. 영상 부서와 리서치 부서 각각에 Master·Worker 등이 있을 수 있다. 전체 조직 운영이 필요할 때만 총괄 Master와 부서별 Sub-master 계층을 둔다.
**UI는 버전마다 다르다.** 세미나에서 어떤 교육생은 + 부서 추가, 다른 교육생은 전문가용 → 팀 만들기가 보여 혼란이 있었다. 따라서 교재는 한 화면의 버튼 위치를 확정하지 않는다. 해당 설치에서 부서 생성 기능을 확인하고, 채팅 지시를 사용했다면 생성된 설정과 파일을 실제로 검증한다.
### 8.2 네 역할의 표준 계약 — 첨부 **「네 역할 팀 구조」** 우선
> **원본 간 차이:** 세미나 구두 설명에서는 CSO를 중간 관리자/PM에 가까운 역할로 표현했다. 반면 이번에 받은 실제 운영 설계 문서에서는 **CSO가 환경·비용·장애 담당**이고, **Master가 작업 배정과 최종 인수**를 맡는다. 두 정의를 혼합하면 책임이 겹치므로 **이 통합 가이드에서는 첨부 운영 설계 문서의 계약을 표준**으로 채택한다. 팀별 기존 CSO 설정이 다르면 바꾸기 전에 현재 계약을 확인한다.
| 역할 | 해야 할 일 | 하지 말아야 할 일 | 산출물·결정권 |
|---|---|---|---|
| **Master** | 목표·Seed 해석, 작업 분해·브리프, 이견 조정, 증거 확인, 최종 인수/보고 | 대량 구현, 승인 없는 유료 호출·외부 발행 | briefs/, 인수 기록·보고 |
| **CSO** | 도구·인증·디스크·GPU·환경, 비용 장부, 장애 원인 분석 | 콘텐츠 품질 판정, 직접 구현, 승인 없는 재기동 | logs/ENV_*.md, COST_LEDGER.md |
| **Worker** | 지시서 안에서 조사·구현·실행, 결과물과 자체 검사 보고 | 범위 확대, 자기 검수만으로 최종 완료 선언 | reports/, 코드·파일·테스트 로그 |
| **Reviewer** | 독립적으로 사실·증거·기준 대조, 재현 가능한 결함 보고 | 직접 수정, Worker에게 우회 지시, 요청 없는 과잉 검수 | reviews/의 ACCEPT/REVISE/REJECT |
**운영 모델 이름은 예시 구성이지 필수값이 아니다.** 첨부 운영 문서의 config/roles.json은 Master/Worker에 낮은 추론 강도 모델을, CSO/Reviewer에 강한 검토 모델을 배치했다. 현재 계정·런타임에서 사용 가능한 모델명과 비용을 검증하고 역할·역량 기준으로 선택한다. 이 배분의 성능·비용 우위가 정량 검증됐다는 근거는 자료에 없다.
### 8.3 핵심 조직 설계: 실패를 발견할 지점을 만든다
네 역할의 목적은 “많은 에이전트를 쓰는 것”이 아니라 다음을 분리하는 것이다.
- **작성자 ≠ 최종 품질 판정자** — Worker가 보고한 완료를 Master와 Reviewer가 증거로 확인한다.
- **운영 정상 ≠ 콘텐츠 정상** — CSO가 API와 GPU가 정상이라고 해도 내용의 사실성이 확보된 것은 아니다.
- **주장 ≠ 확정 사실** — Master는 CSO와 Reviewer의 결론도 증거 범위만큼만 인수한다.
- **기억 ≠ 인계 자료** — 세션/도구 변경에도 파일·경로·미결 사항을 통해 재개한다.
### 8.4 얼마나 많은 역할이 필요한가
| 규모 | 추천 | 적합한 작업 | 주의점 |
|---|---|---|---|
| **1역할** | Master 또는 단일 에이전트 | 짧은 리서치·작은 실습·원샷 템플릿 | 최종 검수를 운영자가 직접 |
| **3역할** | Master + CSO + Worker | 반복 실행·환경 의존 업무 | 품질 최종 확인은 Master |
| **4역할** | Master + CSO + Worker + Reviewer | 외부 공개, 근거 정확성, 다단계 개선 | 조율/토큰 비용과 중복 검수 감수 |
Reviewer는 상시 켜둘 필요가 없다. **독립 검수가 필요한 시점에만 투입**하는 것이 교육 자료의 기본 설계다. 단, 의료·대외 공개 등 결과 오류의 영향이 큰 작업에서는 실제 독립 검수 생략 여부를 보수적으로 판단한다.
### 8.5 CYS에서 부서를 세팅하도록 요청하는 교육용 지시문
```text
이 프로젝트를 Research Survey 부서로 설정해줘.
최초에는 Master/Worker/CSO를 구성하고,
최종 서베이의 사실성 검증 단계에서만 Reviewer를 추가해.
역할은 다음 계약으로 제한해.
- Master: Seed와 평가 기준을 읽고 작업 배정, 최종 인수·보고
- CSO: 검색 API 연결·권한·요금·장애/비용 보고, 콘텐츠 판정 금지
- Worker: 검증 가능한 리서치 산출물 생성, 보고서와 증거 경로 첨부
- Reviewer: 독립 논문·인용·실험 조건 검토, 수정 없이 판정만
Seed: requirements/import-v1/seed-original.yaml
프로젝트 루트: [실제 경로]
작업 범위 밖 수정과 유료 호출·외부 게시에는 승인 게이트를 둬.
생성 후 실제 부서와 역할 설정 파일 경로를 보고해.
배경 자동 작업과 무한 재시도를 기본 활성화하지 마.
```
이 문장은 CYS 버전별 전용 명령이 아니라 **채팅에 전달할 교육용 요청문**이다. 실제 설정 파일과 UI에 반영됐는지 점검한다.
---
## 9. 파일 기반 작업 인계: 팀이 서로 무엇을 주고받나
### 9.1 단일 업무 실행 프로토콜
```text
운영자 → Master: 목표, 승인 범위, Seed 경로
Master → CSO: 필요한 경우 환경/비용/접근성 점검
CSO → Master: ENV 보고, 확인한 범위/미확인 영역
Master → Worker: 작업 브리프 파일 경로
Worker → Master: 결과물 + 검사 기록이 포함된 보고서 경로
Master: 산출물이 실제 존재하는지 독립 확인
Master → Reviewer: 정확한 결과물/브리프/Seed 경로로 검수 요청
Reviewer → Master: ACCEPT / REVISE / REJECT + 증거
Master → 운영자: 결과·확인한 것·미확인·결정 필요 사항
운영자: 필요한 유료 호출·외부 배포/발행 승인
```
**리뷰에서 REVISE:** Reviewer가 Worker에게 직접 지시하지 않고 **Master가 결함을 작업 지시서로 재정리**해 보낸다. 이 루프는 횟수·종료 조건·비용 한도를 둔다.
### 9.2 Master 작업 지시서 템플릿
```markdown
# BRIEF-001 | [작업 이름]
- 근거 Seed: requirements/import-v1/seed-original.yaml
- 목표: [한 문장]
- 입력 자료 및 출처: [...]
- 실행 폴더: [...]
- 허용 작업: [...]
- 금지/승인 필요 작업: [...]
- 출력 파일: [...]
- 성공 기준/검사 방법: [...]
- 종료 조건 및 재시도 한도: [...]
- 보고: reports/BRIEF-001.md에 실행/검사 근거를 남길 것
```
### 9.3 Worker 보고서 템플릿
```markdown
# WORK REPORT | BRIEF-001
- 실제 수정/생성 파일:
- 실제 실행 명령과 종료 상태:
- 자체 테스트(명령/결과/로그):
- 원문·문헌 출처/접근 수준:
- 실패·차단·미완료:
- 브리프와 다른 결정 및 이유:
- 비용/소요 시간(측정했다면):
- Master에게 확인이 필요한 사항:
```
### 9.4 Reviewer 판정 양식
```markdown
# REVIEW | BRIEF-001
Verdict: ACCEPT | REVISE | REJECT
- 검토 대상 및 버전/해시:
- 합격 기준과 판정 근거:
- 결함 1: 파일·줄/문단/표/페이지, 재현 방법, 예상·실제 결과
- 결함 2: ...
- 미검증 영역(권한·원문 미확인·접근 차단):
- 추천 수정 방향(직접 수정하지 않음):
- Master가 인수할 때 추가 확인할 내용:
```
### 9.5 흔한 팀 운영 실패와 예방
- **메시지는 보냈지만 받지 못함:** 송신 사실뿐 아니라 수신 세션의 실제 화면/기록을 확인한다.
- **승인 대기 중 장시간 정지:** Worker가 실행하지 않는 이유가 승인 창인지 로그/상태로 구분한다.
- **환경 장애를 품질 문제로 오해:** CSO 진단과 Reviewer 판정을 분리한다.
- **한 역할 지침이 너무 김:** 짧은 역할 계약 + 필요한 파일 경로만 주입한다. 첨부 운영 사례는 범용 지침 약 41KB를 역할별 약 5KB로 줄인 기록을 제시한다.
- **Master가 Reviewer 결론을 뒤집음:** 가능하지만 반드시 이유와 증거를 기록하고 운영자에게 알린다.
---
## 10. Research Survey v2 — 기존 하네스를 실제로 사용하는 방법
이 장은 **첨부 lecture.html의 실제 교육 흐름**을 유지한다. Research Survey v2는 “논문 검색어를 크게 던지고 아무거나 요약하는 도구”가 아니라 **연구자가 후보와 기준을 결정하고, 그 결정을 재현 가능한 검색과 원문 비교로 연결**하는 워크플로다.
### 10.1 시작: 도구 폴더와 연구 결과 폴더를 나눈다
```text
workspace/
├─ research-survey-v2/ # 배포 받은 도구/스킬/강의 자료
└─ medical-rl-workspace/ # 논문 후보, 기록, 리뷰, 최종 서베이
```
- **Codex 경로:** research-survey-v2 폴더를 열고 AGENTS.md와 discover 스킬을 읽도록 한다.
- **Claude Code 경로:** 저장소에서 claude --plugin-dir .로 로컬 플러그인을 로드하고, 세션 내부에서 예시 /research-survey-v2:research-survey discover Medical LLM 강화학습 방식 호출. 플러그인 버전·설치 상태 확인.
- **Python 보조 CLI:** 자료 기준 Python 3.10+, 본문 PDF 추출은 선택적 pypdf. 키가 필요한 서비스(OpenAlex 등)는 환경 변수로 관리하고 프롬프트에 API 키를 노출하지 않는다.
- **주의:** survey.py의 검색·상태 관리 명령만 실행한다고 LLM이 자동 원문 정독하여 최종 서베이를 써주는 것은 아니다.
### 10.2 6단계 리서치 수행 흐름
| 단계 | 교육생이 하는 일 | 반드시 남길 기록 | 완료 조건 |
|---|---|---|---|
| **① Discover** | 주제·RQ·참조 논문을 입력 | 후보 6~8편, 출처/추천 이유 | 방향이 서로 다른 후보를 실제 근거와 함께 추천 |
| **② Select** | 후보 2~3편 선택, 추가 코멘트 | selection.json | 선택 ID와 포함·제외 이유 저장 |
| **③ Plan** | 질문과 검색 범위 확정 | plan.json | RQ, 연도, 소스, 제외 규칙, 빈 영역 정리 |
| **④ Search** | 학회/저널/API 검색 확장 | search-log.jsonl, candidates | 실패/결과 없음/미확인 구분 |
| **⑤ Read** | 실제 원문 확인·논문별 리뷰 | paper review, 페이지/표 근거 | 초록과 원문을 구별, 데이터/평가 기록 |
| **⑥ Synthesize** | RQ별 종합·반론·한계 | survey.md | 근거 연결된 비교와 미해결 사항 제시 |
### 10.3 Discover 프롬프트 — Codex 대화창
```text
research-survey discover 워크플로로 진행해줘.
주제: Medical LLM 강화학습 방식.
목적: 보상 설계와 임상적 정확성 평가 방법을 비교하고 싶어.
Radiology report 생성·수정 연구도 후보에 포함해줘.
결과는 ../medical-rl-workspace 에 저장해줘.
우선 방향이 다른 reference 논문 6~8편을 추천하고,
각 논문의 공식 출처, 게재 상태, 추천 이유, 미확인 사항을 알려줘.
내가 논문과 방향을 선택하기 전에는 집중 검색하지 마.
```
가능하면 제목 외에 DOI·공식 URL·PDF와 **왜 그 논문을 참고하는지**도 제공한다.
### 10.4 Select/Plan 프롬프트
```text
추천 결과에서 [실제 논문 ID 1], [실제 논문 ID 2]를 선택할게.
보상 설계와 독립적인 임상 정확성 평가를 중심으로 조사해줘.
Radiology report 생성·수정는 포함하고,
의료 적용이 없는 일반 RL은 방법론 배경으로만 다뤄줘.
DPO 같은 선호 최적화는 별도 비교축으로 두고,
이 선택과 내 코멘트를 저장한 뒤 RQ, 포함·제외 조건, 검색 계획으로 바꿔줘.
```
대괄호는 **실제 검색으로 반환된 ID**로 바꾼다. 이 문서는 현재 논문 검색을 수행하지 않았으므로 실제 후보 논문명이나 인용 수를 만들어 쓰지 않는다.
### 10.5 검색 범위와 신뢰성 기준
- 첨부 강의의 기본 학회/분야 목록: **NeurIPS, MICCAI, ICML, ICLR, CVPR, ECCV, ICCV, AAAI, ACL**. 의료 주제는 PubMed/PMC와 관련 저널을 함께 본다.
- 강의의 기본 최신 기간: **실행 연도의 2년 전 1월 1일 ~ 검색 실행일**. 예: 2026년이면 2024-01-01부터. 이후 실행에서는 실제 당일로 계산한다.
- **최근 논문**과 **영향력 큰 기반 연구**를 구분한다. 인용 수에는 출처와 조회일을 붙이고, 확인 안 된 값은 unknown.
- 공식 proceedings/저널·DOI·preprint/워크숍·초록만 있는 기록을 구분한다.
- 검색 서비스 요청 실패, 결과가 0개, 원문 접근 제한, 포함 기준 미달은 서로 다른 상태다.
- HTTP 200이나 PDF 파일 존재만으로 본문 확보·정독을 주장하지 않는다.
**핵심 비교축 예시 — Medical LLM RL:**
| 축 | 최소 확인값 |
|---|---|
| 연구 과제 | 질의응답 / 임상추론 / 영상 판독 / report 생성·수정 |
| Base model | 정확한 공개 모델 버전/크기, 공개 여부 |
| 데이터 | 사용 원천데이터, 분할, 규모, 공개성, 환자 단위 누수 위험 |
| 학습 | SFT/RL/DPO/GRPO 등 구분, 보상·비교 선택·학습 단계 |
| 평가 | benchmark·환자 수준·전문의 판단·독립 평가 여부 |
| 수치 | 사용 지표, baseline, CI/통계, 평가 조건 |
| 증거 수준 | 초록/전문/표/코드 확인 정도, 페이지/표 번호 |
| 한계 | 데이터 접근, 재현성, 안전성, 실패 사례 |
같은 점수 이름이라도 테스트 데이터·분할·baseline이 다르면 **직접 성능 순위를 매기지 않는다.**
### 10.6 원문 리뷰·최종 서베이 프롬프트
```text
선별한 논문은 가능한 경우 실제 원문을 확인하고 논문별 리뷰를 작성해줘.
방법 / 데이터 / 학습 방식 / 보상 설계 / 비교 방법 / 독립 평가 / 한계를 추출하고,
주장과 수치에는 원문의 페이지·섹션·표 근거를 붙여줘.
초록만 확인한 논문과 본문까지 확인한 논문을 구분해.
비교 데이터/분할이 다르면 정량 우열을 단정하지 마.
반대 결과, 제외 근거, 원문 접근 실패, 검수 미실시를 명확히 표시해.
마지막으로 RQ별 비교·공백·후속 실험 제안을 포함한 서베이를 작성해줘.
```
### 10.7 Research Survey의 저장 상태를 올바르게 해석하기
첨부 강의에 소개된 구조:
```text
<결과 폴더>/
├─ artifacts/discovery/<세션>/
│ ├─ candidates.json
│ ├─ selection.json
│ ├─ plan.json
│ ├─ search-log.jsonl
│ └─ reports/
└─ 40-drafts/
├─ papers/ # 개별 논문 상세 리뷰
└─ <세션>/survey.md # 최종 서베이 초안
```
**`prepared_not_summarized`·`incomplete`는 완료 아님.** draft_ready와 verified_full_text도 실제 근거/검수 기록을 살펴야 한다. report CLI 성공은 후보·검색 보고서 작성이지 논문 정독이나 최종 서베이 완성 선언이 아니다.
### 10.8 선택 실습: Python CLI로 상태와 검색 확인
**PowerShell — research-survey-v2/ 폴더에서 실행할 예시:**
```powershell
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl init --topic "Medical LLM 강화학습 방식"
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl search --provider pubmed --query "(large language model) AND (reinforcement learning)" --lane recent --limit 6
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl report
# 실제 반환된 ID로 아래를 교체
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl select --ids 실제ID --comment "보상 설계 중심, radiology report 포함"
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl plan --rq "임상적 정확성을 어떤 보상으로 학습하고 별도로 평가하는가?" --query "radiology report reinforcement learning reward" --providers openalex pubmed --limit 6
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl expand
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl status
python .\survey.py --workspace ..\medical-rl-workspace --session medical-rl report
```
이 CLI는 프로젝트 폴더에 실제 survey.py가 있을 때만 실행한다. --workspace·`--session`은 하위 명령 **앞**에 둔다. 각 API 사용 조건/키/호출 제한을 확인한다. 위 명령은 문서 작성 중 실행하지 않았다.
---
## 11. 통합 사례: Research Survey 하네스를 개선하는 팀 실행
Research Survey 도구를 **사용**하는 것과 Research Survey **도구 자체를 개발·개선**하는 것은 다르다. 여기서는 **후자**를 가정한다.
### 과제 예시
> “Medical LLM 리서치의 논문 후보에 비관련 연구가 자주 포함된다. 기존 Research Survey v2의 검색/스크리닝 가이드를 개선해, 연구자 선택 전 집중 검색을 하지 않고, 인용·게재 상태·원문 접근 수준을 빠짐없이 추적한다. 동일한 평가셋으로 기존 버전과 비교한다.”
### 11.1 역할별 업무 분장
| 단계 | 담당 | 구체 작업 | 산출물/검증 |
|---|---|---|---|
| 문제 정의 | 운영자 + Master | 오류 예시, 포함·제외 기준, 평가셋 설정 | PLAN.md, eval-set-v1.jsonl |
| 인터뷰·명세 | Ouroboros | 요구사항 질문 → 승인된 Seed | requirements/import-v1/ |
| 환경 확인 | CSO | 검색 API, 토큰 예산, PDF 접근/권한 점검 | logs/ENV_001.md |
| 작업 지시 | Master | Seed에서 검색/선택/원문 단계별 작업 분해 | briefs/BRIEF_001.md |
| 구현 | Ouroboros Run 또는 Worker | 코드·프롬프트·스킬 개선, 테스트 | 소스 변경, reports/WORK_001.md |
| 기술 QA | Run/테스트 | 단위 테스트, 수용 기준 충족 여부 | 실행 로그·테스트 결과 |
| 업무 검수 | Reviewer | 의도한 포함·제외/인용/근거 연결 독립 확인 | reviews/REVIEW_001.md |
| 인수·반영 | Master + 운영자 | 개선 효과·비용·미해결 문제 판단 | evaluations/AB_001.md, 승인 |
**중첩 실행을 조심한다.** Ouroboros Run이 이미 내부 작업 분해·자동 평가를 수행한다면 CYS Worker가 **똑같은 Seed를 새로 Run**할 필요는 없다. CYS Master는 작업 범위·입출력 계약을 관리하고, 실제 구현 실행은 한 경로로 정한다. Reviewer는 기계적 단위 테스트의 중복이 아니라 **독립 업무 적합성**을 검사한다.
### 11.2 실행 전 Master 프롬프트
```text
다음 Seed를 기준으로 Research Survey 개선 작업을 관리해줘.
Seed: requirements/import-v1/seed-original.yaml
작업 종류: 기존 하네스 개선
프로젝트 루트: [실제 research-survey 소스 디렉터리]
먼저 현재 git status와 사용자 변경 파일을 확인하고 보존해.
Research Survey의 discover→select→plan→search→read→synthesize 계약을 요약해.
변경 범위와 기존 실패 사례를 보고 1개 브리프를 만들어줘.
실제 구현은 Ouroboros Run 또는 Worker 중 하나만 담당하게 해.
CSO는 검색 접근·비용·환경, Reviewer는 원문 출처와 선정 품질만 검토해.
테스트·검수·성능 비교 뒤에 내가 승인할 때만 운영본/설치본에 반영해.
```
### 11.3 개선 사이클
```text
Baseline 측정 → 실패 사례 수집 → 원인 분류 → Seed/지침/스킬 수정
→ 동일 평가셋 실행 → 독립 검수 → 채택/보류 → 변경 이력 기록
```
예를 들어 후보 6편 중 2편만 관련 있다면 “더 잘 찾아줘”보다 **왜 나머지 4편이 제외 대상인지** 기록하고, 스크리닝 기준을 수정한 후 재실행한다. 단, 한 사례를 보고 기준을 과도하게 고정하지 않도록 다른 주제 평가셋도 확인한다.
---
## 12. 검수 체계: 자동 테스트와 독립 Reviewer를 나누기
### 12.1 세 수준으로 나눈다
| 수준 | 질문 | 담당/증거 |
|---|---|---|
| **Level 1 — 산출 확인** | 파일이 생겼나? 형식과 경로는 맞나? | Worker, Master / 파일·명령 로그 |
| **Level 2 — 수용 기준** | Seed 기준을 충족하나? 테스트를 통과했나? | Run·테스트 / test logs, CI |
| **Level 3 — 업무 정합성** | 내용·출처·의학적 주장·누락에 문제가 없나? | Reviewer + 운영자 / 출처 대조·반례 |
Reviewer 판정은 ACCEPT, REVISE, REJECT이며, 실제로 확인하지 못한 항목은 UNKNOWN/NOT_CHECKED처럼 **별도 미검증 상태를 기록**한다. 이 미검증 상태는 첨부 4역할 파일의 공식 verdict 종류를 늘리자는 주장이 아니라 평가표의 보조 필드로 사용하는 **교육용 제안**이다.
### 12.2 Research Survey 전용 품질 Gate
**치명 Gate 예시 — 하나라도 실패하면 인수하지 않는다.**
- 존재하지 않는 논문·DOI·학회 게재 상태를 만들어냈다.
- 원문을 확인하지 않았는데 “원문으로 확인함”이라고 기재했다.
- 사용자 선택 전 대규모 집중 검색을 진행했다(요구된 승인 게이트 위반).
- 다른 데이터셋·평가 조건을 같은 benchmark 순위처럼 표기했다.
- 출처·원문·검색 실패를 숨기거나 미확인을 임의로 채웠다.
- 개인정보/계정 키를 공유하거나 미승인 외부 발행을 실행했다.
**정성 Rubric 예시 — 각 항목 0~3점, 조건 정의 후 운영:**
| 항목 | 0 | 1 | 2 | 3 |
|---|---|---|---|---|
| 관련성 | 대부분 부적합 | 관련 방향 약함 | 다수 관련 | RQ별 의도에 정확히 일치 |
| 출처 추적 | 없음 | 일부 링크 | 출처/시점 대체로 | DOI·공식 게재·접근 수준 명확 |
| 원문 근거 | 주장 무근거 | 초록 중심 | 다수 원문 근거 | 핵심 주장이 페이지·표와 연결 |
| 비교 공정성 | 조건 무시 | 비교 근거 부족 | 일부 조건 구분 | 데이터·분할·baseline 차이를 분명히 |
| 불확실성 | 숨김 | 일부 언급 | 실패/제한 기록 | 빈 영역·반례·미정독을 체계적으로 기록 |
합계만으로 Gate 실패를 상쇄하지 않는다. 점수 기준은 **교육용 제안**이며 논문 자체의 과학적 우수성을 확정하는 공식 지표가 아니다.
### 12.3 A/B 평가 템플릿
**A=기존 도구**, **B=개선 도구**로 두고, 가능한 범위에서 동일 입력·동일 검색 시점·검색 API·예산·완료 조건을 유지한다. 비교 자료가 부족하면 “우월”이 아니라 “관찰 결과”로 보고한다.
```markdown
# A/B 실험 기록
- 테스트 ID/버전/날짜:
- A 해시/모델/프롬프트:
- B 해시/모델/프롬프트:
- 고정 데이터셋: 선정 주제·RQ·정답 판정 근거:
- 검색 조건: 시점·제공자·한도:
- 실행 횟수 / 랜덤성 설정:
- 주요 지표: 관련 후보 Precision/Recall, DOI 정확성, 원문 근거 충족률
- 부차 지표: token, 지연, 비용, reviewer 수정 횟수
- Gate 위반 건수:
- 개선/퇴화 및 실패 사례:
- Reviewer 확인 범위:
- 결론: 채택 / 보류 / 재실험
```
**주요 제안 지표:**
- **Candidate Precision** = 관련 후보 수 / 추천 후보 수 (정답 판정 기준 선행)
- **Candidate Recall** = 찾은 정답 후보 수 / 평가셋의 정답 후보 전체 (정답 집합이 있는 경우에만 산출)
- **Citation validity** = 실제로 맞는 논문·게재 출처를 지목한 인용 / 검사한 인용
- **Evidence coverage** = 페이지·표 근거가 확인된 핵심 주장 / 검사한 핵심 주장
- **Hallucination count** = 없는 출처·수치·근거를 사실처럼 단정한 건수
- **Runtime cost** = 실제 과금 또는 사용량 기록에 근거한 지표 (추정치와 분리)
Research Survey의 “논문 후보 보고서”와 “원문 근거를 담은 최종 서베이”를 서로 다른 평가 대상으로 본다.
---
## 13. 컨텍스트·토큰·세션 관리
### 13.1 언제 길어진 세션을 나누나
세미나에서는 CYS가 자체 핸드오프·요약 지침으로 맥락을 축적한다는 장점을 설명했지만, **자동 압축이 의도한 사실을 모두 보존하는 것은 아니다.** 매우 긴 대화에서 지침이 누락되거나 다른 작업 맥락과 섞일 수 있다.
분리 기준:
- 목표/산출물이 달라졌다.
- 중요한 결정이 PLAN.md, Seed, 브리프에 기록됐다.
- 실행 로그·원문 내용이 길어져 현재 대화의 맥락 확인이 어려워졌다.
- 같은 부서 안에서 다른 프로젝트를 시작한다.
### 13.2 handoff / continue-here 문서 템플릿
```markdown
# CONTINUE_HERE — [프로젝트/세션]
- 최종 목표 및 사용 중인 Seed: [경로·버전/해시]
- 현재 단계: [interview/seed/run/review/수정]
- 마지막으로 실제 성공한 명령·산출물 경로:
- 확인된 사실과 근거 파일:
- 실패/미완료/승인 대기 항목:
- 이전 세션에서 내린 결정:
- 다음에 **한 번만** 실행할 명령/요청:
- 실행 금지사항/승인 조건:
- 세션 재개 시 반드시 먼저 확인할 파일:
```
새 세션은 “이전 내용 다 알아서 계속”이 아니라 다음처럼 시작한다.
```text
handoffs/CONTINUE_HERE.md를 먼저 읽고, 참조된 Seed와
실제 현재 파일 상태/git status를 대조해줘.
완료된 작업은 반복하지 말고, 미완료/승인 대기만 보고한 뒤 이어서 진행해.
```
### 13.3 토큰/비용을 줄이는 우선순위
1. **불필요한 상시 역할을 줄인다.** 한 번에 4개가 필요하지 않다면 Reviewer를 호출할 때만 켠다.
2. **동일한 정보를 여러 에이전트에 복사하지 않는다.** 짧은 브리프 + 파일 경로를 전달한다.
3. **모든 판단에 최고가 모델을 쓰지 않는다.** 고난도 해석·검수와 단순 파일 처리를 분리한다.
4. **반복성 스크립트는 별도 실행한다.** 정기 뉴스레터·데이터 수집에 매번 전체 CYS 루프를 띄우지 않는다.
5. **재시도를 제한한다.** REVISE 무한 루프보다 실패 이유/비용/다음 액션을 기록한다.
6. **실측한다.** 실험마다 토큰·시간·인용/품질 변화와 총 작업 비용을 함께 기록한다.
세미나에서는 4개 역할의 상호 읽기·피드백 때문에 단일 모델보다 토큰 사용량이 늘 수 있고 사례에 따라 200~400%라는 질문도 나왔다. **이는 현장 발언/추정의 맥락이지 검증된 공통 배수는 아니다.** 프로젝트별 실측 비교가 필요하다.
### 13.4 업데이트 안전수칙
세미나에서는 CYS의 **업데이트 버튼이 설치 교체에 가까워 맥락 손실을 일으킨 사례**가 언급됐다. 다음을 기본으로 한다.
- 업데이트 전에 .cys 등 현재 설정·대화 요약·부서 파일을 외부 위치에 백업한다.
- requirements/·`briefs/`·`reviews/`·변경 중인 Git 저장소 상태까지 확인한다.
- 원본 소스/부서 운영본/설치된 스킬 복사본을 구분한다.
- 업데이트 후 역할 설정, 명세 참조 경로, MCP 연결, 파일 재개 능력을 시험한다.
- 승인 요청은 자동 승인하지 않는다. **삭제·수정·유료 실행·발행 권한**을 구별한다.
---
## 14. 15분 입문 실습 — Ouroboros로 To-do 웹페이지 만들기
첨부 ouroboros-15min-workshop.html의 학습 목표는 복잡한 팀 운영 이전에 **Interview → Seed → Run** 세 단계를 작은 산출물로 확인하는 것이다. 설치와 MCP 연결은 실습 전 완료하는 것을 전제로 한다.
### 0~2분: 환경과 작업 폴더
PowerShell에서 실습 폴더로 이동한다(자기 컴퓨터 경로로 교체).
```powershell
Set-Location "C:\harness-workspace\ouroboros-practice"
```
Codex에서 해당 폴더를 열고 Ouroboros MCP 연결을 확인한다. 필요하면 **Codex 대화창**에서 ooo setup을 진행한다. 파일 .mcp.json과 .mcp.codex.json이 존재하는 것만으로 연결 성공이라고 판단하지 않는다.
### 2~6분: Interview
**Codex 대화창:**
```text
ooo interview 15분 실습용 할 일 목록 웹페이지를 만들고 싶어.
사용자는 나 혼자이고, 할 일 추가와 완료 표시만 필요해.
HTML, CSS, JavaScript로 만들고 서버나 빌드 도구는 원하지 않아.
새로고침하면 목록이 사라져도 괜찮아.
빈 할 일은 추가되지 않아야 해.
결과물은 practice/todo/ 안에 만들어줘.
```
후속 질문에서 로그인·DB·삭제·배포 등을 이번 실습에서 제외하고, 입력/출력/테스트 조건을 합의한다.
### 6~9분: Seed
```text
ooo seed
```
Seed의 “할 일 추가, 빈 입력 거부, 완료 체크 시 취소선” 기준을 확인한다. Seed가 이미 생성된 경우에는 중복 실행하지 않고 실제 경로부터 확인한다. 교육 자료처럼 practice/todo/seed.yaml에 **복사본을 저장할 수 있지만**, 도구 내부 원본과 세션 ID를 보존한다.
### 9~14분: Run
**Codex 대화창 — 플러그인 호출 예시:**
```text
ooo run practice/todo/seed.yaml
```
진행 상태를 확인하려면(지원되는 환경에서):
```text
ooo status
```
터미널에서 실행하려면 해당 버전의 ouroboros run CLI 구문과 실제 프로젝트 작업 디렉터리를 확인한다. 플러그인의 ooo run 요청을 PowerShell과 혼동하지 않는다.
### 14~15분: 결과 확인
- [ ] HTML 파일을 브라우저에서 열었다.
- [ ] 할 일을 입력하면 목록이 추가된다.
- [ ] 빈 입력은 목록에 추가되지 않는다.
- [ ] 완료 체크를 하면 해당 항목에 취소선이 나타난다.
- [ ] 테스트 실패 또는 미구현 사항을 숨기지 않고 기록했다.
필요할 때 ooo evaluate <실제 실행 세션 ID>를 통해 별도 평가할 수 있는 환경인지 확인한다. 15분은 **실습 목표 시간**이며 인터뷰·검증 속도에 따라 완료까지 더 걸릴 수 있다.
---
## 15. 55분 워크숍과 장시간 프로젝트 실습 운영안
### 15.1 Research Survey 기본 55분 — 첨부 강의 구성 유지
| 단계 | 시간 | 교육생 활동 | 제출할 흔적 |
|---|---:|---|---|
| 시작·환경 | 7분 | 도구/결과 폴더 구분·실행 확인 | 프로젝트 경로 |
| 주제·후보 | 7분 | 질문을 제시하고 6~8편 추천 | 실제 출처가 있는 후보 |
| 선택·코멘트 | 8분 | 2~3편 선택, 포함·제외 조건 | selection, RQ 초안 |
| 검색 범위·신뢰도 | 8분 | 학회·연도·출처·미확인 범위 | plan, 검색 로그 |
| 원문 비교 단계 | 8분 | 후보 보고서와 상세 리뷰 차이 이해 | 표 근거 점검 기록 |
| 이어하기·문제해결 | 5분 | 상태·API 오류·미완료 원인 확인 | status, 오류 분류 |
| 실습 확인 | 7분 | 자신의 주제로 다음 행동 정의 | 체크리스트·질문 답변 |
| 운영 여유 | 5분 | 질의·시연 오버런 | 미완료 후속 과제 |
**참고:** 자료의 섹션별 분량을 합하면 50분이므로 위 계획에는 운영 여유 5분을 별도로 표시했다. 이 55분 안에 여러 논문의 전면 정독과 완성된 과학적 서베이까지 보장하지 않는다.
### 15.2 팀 하네스 구축 4~5시간 실습 — 교육용 제안 운영안
| 단계 | 권장 진행 | 산출물 |
|---|---|---|
| ① 과제 선택·계획 | 도메인·문제·성공 기준 정리 | PLAN.md |
| ② Ouroboros 인터뷰 | 사용자 의도·제약·미결 질문 수렴 | 인터뷰 기록 |
| ③ Seed 확정·복사 | 합의된 명세, provenance와 경로 확인 | requirements/import-v1/ |
| ④ CYS 역할 분담 | 업무 복잡도에 따른 1·3·4역할 결정 | 역할 계약/브리프 |
| ⑤ 첫 실행 | Run 또는 Worker **한 경로로** 수행 | 코드/리서치 산출물 |
| ⑥ 검수·피드백 | Gate·Reviewer·A/B 가능성 검토 | Review/평가 |
| ⑦ 인계·발표 | 변경 이력·재개 방법·다음 실험 정리 | CONTINUE_HERE.md, 데모 |
세미나에서 소개한 “4~5시간에 한 사이클”은 **경험적 예시**이며, 과제 난이도와 검증 요구에 따라 달라진다. 질문 개수를 늘리는 것이 아니라 **하나의 결과물을 확실히 만들고 검수**하는 데 우선순위를 둔다.
### 15.3 교육생 발표용 3분 데모 구성
1. 해결할 문제와 기존 실패 1가지.
2. Interview에서 어떤 질문으로 명세가 좁혀졌는가.
3. Seed와 작업 위치가 어디에 고정되었는가.
4. CYS 역할/검수 경계와 실제 산출물.
5. 실패 1가지, 수정 1가지, 평가 결과와 다음 개선.
---
## 16. 문제 해결: 증상 → 확인 → 다음 행동
| 증상 | 먼저 확인할 것 | 조치 |
|---|---|---|
| ooo가 동작하지 않는다 | 대화창 스킬인지 실제 CLI인지, MCP 연결/설치 | 연결·설치 상태 확인, 버전별 인터페이스 분리 |
| 인터뷰가 엉뚱한 질문을 한다 | PLAN의 대상·범위·성공 예시 부족 | 약 20줄 수준의 출발 맥락과 구체 제외조건 추가 |
| 인터뷰가 너무 일찍 끝났다 | 미정/위험/판정 기준이 남았는지 | 누락된 질문만 추가. 불필요한 문항 수 늘리기 금지 |
| 다른 프로젝트 Seed를 가져왔다 | ID·목표·원본 경로·해시 | 자동 최신 선택 금지, 올바른 쌍 다시 식별 |
| Seed는 옳은데 다른 폴더가 수정된다 | cwd, --project-dir, worktree | 실제 수정 위치 확인. 무턱대고 재실행 금지 |
| --dry-run이면 안전하다고 생각했다 | 실행 모드별 플래그 적용 범위 | 기본 orchestrator에서 작동 보장 안 됨. 공식 도움말 점검 |
| 부서 버튼/역할 화면이 다르다 | CYS 앱 버전·모드 | 전문가용/부서 추가 메뉴 확인, 생성 후 설정 파일 검사 |
| CSO가 품질 결론까지 내린다 | 구두 세미나 정의와 운영 계약 충돌 | 이 교재의 CSO=운영·비용 계약으로 통일(합의 후) |
| 검색 결과가 없다 | API 실패? 실제 0건? 원문 접근 제한? | 오류를 분리 기록하고 검색 전략 수정 |
| 결과 보고서는 있는데 서베이가 없다 | report는 후보 보고 단계일 수 있음 | 원문 리뷰·종합 작성 단계를 별도 요청 |
| Reviewer가 계속 재수정 요구 | 근거 없는 판정/종료 조건 누락 | Master가 우선순위·재시도 한도 정의 |
| 컨텍스트가 오래돼 다른 작업과 섞인다 | Seed/brief/handoff 최신성 | 작업 분리, 새 세션에서 파일 기준 재개 |
| 업데이트 후 설정이 사라졌다 | 업데이트 전 설정·로그·Git 백업 | 기존 자료로 복구, 변경 전 승인 게이트 복원 |
| 비슷한 질문인데 품질 차이가 크다 | 기존 컨텍스트·모델·검색 시점·평가기준 | A/B 고정 조건 다시 맞추고 결과를 재측정 |
---
## 17. 최종 제출물 체크리스트
### 필수 산출물
- [ ] PLAN.md에 목표·입력·출력·제약·수용 기준이 있다.
- [ ] 인터뷰와 Seed의 대응 관계가 맞고 ID·버전을 확인했다.
- [ ] requirements/ 원본 스냅샷/출처/해시를 보존했다.
- [ ] 실제 프로젝트 루트·수정 worktree·결과 폴더를 구분했다.
- [ ] CYS를 썼다면 역할별 책임·권한·승인 조건을 기록했다.
- [ ] Master 브리프와 Worker 실제 실행 보고를 남겼다.
- [ ] 결과물을 열어보거나 재현 명령으로 확인했다.
- [ ] Reviewer 검수/운영자 승인과 미검증 항목을 구분했다.
- [ ] 평가 기준과 개선 전후 비교(또는 아직 비교 불가 사유)가 있다.
- [ ] 새 세션이 재개할 수 있는 CONTINUE_HERE.md가 있다.
### Research Survey 과제 추가 제출물
- [ ] 추천 후보의 실재·출처·게재 상태가 확인됐다.
- [ ] 사용자 선택과 코멘트, RQ, 포함·제외 기준이 기록됐다.
- [ ] 학회/저널/API 검색 범위와 실패 로그가 남았다.
- [ ] 원문 정독 여부와 페이지/섹션/표 근거가 연결됐다.
- [ ] 데이터셋·baseline·평가 분할 차이를 비교 문장에 표시했다.
- [ ] 원문 접근 실패·반대 결과·검수 미실시가 숨겨지지 않았다.
---
## 18. 자료별 근거와 확인이 필요한 경계
| 원천 자료 | 이 통합 가이드에 반영한 핵심 | 주의할 제한 |
|---|---|---|
| **세미나 녹취·기존 정리본** | 작업별 하네스, 피드백 개선, CYS 사용, 컨텍스트 관리, A/B, 업데이트 위험 | 현장 체감이나 대략적 수치가 성능 검증을 대신하지 않음 |
| **`네 역할 팀 구조.html`** | Master/CSO/Worker/Reviewer 계약, 문서 인계, 리뷰 verdict, 1·3·4역할 | 실제 영상 부서 운영 설계. Research Survey에 옮긴 계약은 교육용 적용 |
| **`ouroboros-15min-workshop.html`** | Codex 대화창 ooo interview → seed → run, To-do 실습 | 설치·MCP 준비가 선행되고 15분 완료를 보장하지 않음 |
| **`OUROBOROS_INTERVIEW_SEED_IMPORT.md` / .html** | 내부 JSON/YAML 식별·복사·해시, 3경로 분리, worktree 및 운영본 구분 | 예시 로컬 경로/옵션은 설치 버전에 종속 |
| **`lecture.html`** | Research Survey v2 Discover→Select→Plan→Search→Read→Synthesize, 출처·평가·미완료 상태 | 논문 실제 검색/정독·모든 학회 재현율은 이 문서가 검증하지 않음 |
### 외부 명령 참고 — 설치 버전별 검증 필요
- [Ouroboros 공식 Getting Started](https://github.com/Q00/ouroboros/blob/main/docs/getting-started.md)
- [Ouroboros 공식 CLI Reference](https://github.com/Q00/ouroboros/blob/main/docs/cli-reference.md)
- [Ouroboros 공식 Codex 런타임 안내](https://github.com/Q00/ouroboros/blob/main/docs/runtime-guides/codex.md)
- [Ouroboros Seed Authoring Guide](https://github.com/Q00/ouroboros/blob/main/docs/guides/seed-authoring.md)
**문서의 상태:** 사용자가 제공한 강의·설계·워크숍 자료를 바탕으로 작성한 **통합 교육 가이드**다. 여기에 기재한 CLI 실행, MCP 연결, CYS 부서 설정, 실제 논문 API 검색, 프로젝트 생성·구현·배포를 이번 문서 제작 중 수행한 것은 아니다. 교육용으로 보충한 폴더 구조·프롬프트·평가 Rubric은 **제안**이며 특정 제품의 자동 생성 파일이나 공식 명세라고 주장하지 않는다.
---
**한 문장으로 마무리:** 인터뷰로 **의도를 명확히 하고**, Seed로 **계약을 고정하고**, Run/Worker로 **실행 근거를 만들고**, Reviewer와 평가셋으로 **실패를 발견하고**, 파일과 피드백으로 **다음 버전의 하네스를 개선**한다.



엔지니어H님, 안녕하세요! 통합 실습 가이드라는 이름답게 환경·권한·폴더 점검부터 PLAN.md 템플릿까지 순서대로 따라갈 수 있게 정리돼 있어서 정독했어요.
"교육용 제안 구조이며 도구가 강제하는 공식 표준이 아니다"라고 선을 그어 둔 점, 그리고 명령을 입력하는 위치(터미널, 대화창, CYS 채팅)를 구분해 둔 점이 입문자가 가장 많이 헷갈리는 부분을 미리 막아 줘요. "결과물 한 건을 먼저 만들고 나서 과정을 스킬/하네스로 추출한다"는 원칙도 오래 남을 것 같습니다.
바로 실습해 보고 싶어지는 글이에요. 고롱고롱, 좋은 자료 감사합니다 ✨