본문으로 건너뛰기

나만의 팀 하네스 구축 — 통합 실습 가이드

엔지니어H

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

│ ├─ interview-readable.md

│ └─ 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와 평가셋으로 **실패를 발견하고**, 파일과 피드백으로 **다음 버전의 하네스를 개선**한다.

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.10.16

엔지니어H님, 안녕하세요! 통합 실습 가이드라는 이름답게 환경·권한·폴더 점검부터 PLAN.md 템플릿까지 순서대로 따라갈 수 있게 정리돼 있어서 정독했어요.

"교육용 제안 구조이며 도구가 강제하는 공식 표준이 아니다"라고 선을 그어 둔 점, 그리고 명령을 입력하는 위치(터미널, 대화창, CYS 채팅)를 구분해 둔 점이 입문자가 가장 많이 헷갈리는 부분을 미리 막아 줘요. "결과물 한 건을 먼저 만들고 나서 과정을 스킬/하네스로 추출한다"는 원칙도 오래 남을 것 같습니다.

바로 실습해 보고 싶어지는 글이에요. 고롱고롱, 좋은 자료 감사합니다 ✨

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기