AI 에이전트와 Orca 오케스트레이션 — 5주 강의 노트

01. Claude Code·Codex CLI 설치와 로그인

터미널에서 실행하는 두 도구를 설치하고 각자의 계정으로 로그인합니다. 아래 예시는 macOS에서 Homebrew가 준비된 Claude Code 설치와 macOS·Linux용 Codex 공식 설치 방식입니다. Windows에서는 각 공식 문서의 운영체제별 안내를 따릅니다.

# macOS: Homebrew로 Claude Code 설치
brew install --cask claude-code
claude --version
claude

# macOS·Linux: Codex 공식 설치 스크립트
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex

설치와 로그인 안내: Claude Code 공식 빠른 시작, Codex CLI 공식 문서.

02. 작업 폴더 위치를 먼저 확인하기

에이전트를 시작한 위치는 파일을 찾고 지침을 읽는 출발점입니다. 연습용 폴더를 만들고 현재 경로와 파일을 확인한 뒤 그 안에서 에이전트를 실행합니다.

mkdir -p ~/agent-course
cd ~/agent-course
pwd
ls -a

# 사용할 도구 하나를 선택해 실행
claude
# 또는
codex

• 상대 경로는 현재 폴더를 기준으로 읽습니다. README.md와 ../README.md는 다른 위치입니다.
• 에이전트에게 현재 작업 경로와 수정할 파일을 먼저 확인하게 합니다.
• 다른 프로젝트를 시작할 때는 해당 폴더로 이동한 새 세션을 사용합니다.

03. 싱글 에이전트에게 작고 명확한 작업 맡기기

목표, 수정 범위, 완료 기준을 한 요청에 적습니다. 먼저 설명을 받고 작은 변경을 실행한 뒤 실제 파일과 실행 결과를 확인합니다.

# 에이전트 대화창에 입력할 요청 예시
현재 폴더를 확인하고 README.md를 만들어 줘.
내용은 프로젝트 소개, 실행 방법, 완료 기준으로 구성해 줘.
다른 파일은 수정하지 말고, 완료 후 변경한 내용을 설명해 줘.

• 읽기 → 계획 → 변경 → 검증을 한 번의 작은 작업으로 연습합니다.
• 결과가 다르면 기대한 문장이나 동작을 구체적으로 알려 다시 수정합니다.
• 완료 기준: README.md가 실제로 존재하고 요청한 세 항목을 포함합니다.

04. CLAUDE.md·AGENTS.md로 작업 지침 남기기

Claude Code용 CLAUDE.md와 Codex용 AGENTS.md를 프로젝트 루트에 만듭니다. 각 도구의 대화창에서 /init로 초안을 만들거나 파일 생성을 요청한 뒤, 프로젝트에 맞게 내용을 검토합니다.

# 각 도구의 대화창에서 실행
/init

# 지침 문서에 담을 내용 예시
설명과 결과 보고는 한국어로 작성한다.
수정 전에 작업 경로와 대상 파일을 확인한다.
요청 범위 밖의 파일을 바꾸지 않는다.
완료 보고에 변경 파일과 검증 결과를 포함한다.

실행 명령과 폴더 구조도 지침에 적고, 실제 프로젝트가 바뀌면 함께 갱신합니다. 1주차 산출물은 README.md, CLAUDE.md, AGENTS.md와 첫 작업의 검증 기록입니다.

01. 확장 기능의 역할 구분하기

• 스킬: 언제 무엇을 어떤 순서로 할지 알려 주는 재사용 가능한 작업 지침입니다.
• MCP: 에이전트가 서버의 도구와 자료에 접근할 수 있도록 연결하는 표준입니다.
• 플러그인: 스킬이나 MCP 연결 등 관련 기능을 설치 가능한 묶음으로 배포합니다.

“문서에서 근거를 찾아 답하기”를 예로 들면, 검색 순서는 스킬에 담고 문서 접근은 MCP로 제공하며 둘을 플러그인으로 함께 배포할 수 있습니다.

02. 작은 스킬 설치와 실행

검토한 스킬 폴더를 프로젝트의 스킬 경로에 놓아 설치합니다. Claude Code는 .claude/skills/, Codex는 .agents/skills/를 사용합니다. 아래는 같은 실습 스킬을 두 도구에서 써 보는 예시입니다.

# 프로젝트 루트의 터미널에서 실행
mkdir -p .claude/skills/lesson-review .agents/skills/lesson-review
cat > .claude/skills/lesson-review/SKILL.md <<'EOF'
---
name: lesson-review
description: 강의 노트의 누락과 실습 완료 기준을 검토할 때 사용한다.
---
강의 노트를 읽고 누락된 주제와 확인할 항목을 한국어로 정리한다.
파일을 수정하지 말고 발견 사항과 근거 위치를 보고한다.
EOF
cp .claude/skills/lesson-review/SKILL.md .agents/skills/lesson-review/SKILL.md

# Claude Code 대화창
/lesson-review

# Codex 대화창
$lesson-review

경로와 호출 방법: Claude Code 스킬 문서, Codex 스킬 문서.

03. MCP 서버 연결 후 실제 검색하기

읽기 전용 OpenAI 공식 문서 서버를 연결합니다. 사용할 CLI에 해당하는 명령을 터미널에서 실행하고, 에이전트 대화에서 문서 검색을 요청합니다.

# Codex CLI
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

# Claude Code
claude mcp add --transport http openaiDeveloperDocs https://developers.openai.com/mcp
claude mcp list

# 연결 후 대화창에 입력
OpenAI 문서 MCP를 사용해 Codex의 AGENTS.md 안내를 찾아 줘.
핵심 규칙과 공식 문서 링크를 함께 알려 줘.

연결 예시의 출처는 OpenAI Docs MCP 공식 안내입니다. 서버가 목록에 등록되었는지와 실제 검색 요청이 성공했는지를 각각 확인합니다.

04. 플러그인 설치부터 첫 요청까지

공식 OpenAI Developers 플러그인을 예로 설치 흐름을 익힙니다. Codex에서는 /plugins에서 검색해 설치하고, Claude Code에서는 아래 대화창 명령을 사용합니다.

# Codex 대화창: 검색 후 설치
/plugins

# Claude Code 대화창: 마켓플레이스 추가 후 설치
/plugin marketplace add openai/openai-developers-for-claude
/plugin install openai-developers@openai-developers

설치 후 새 세션에서 “공식 문서를 찾아 OpenAI API의 도구 호출 흐름을 설명해 줘”라고 요청합니다. 필요한 연결 설정은 공식 플러그인 안내를 따릅니다.

01. 메인 에이전트와 서브에이전트

메인 에이전트는 목표와 전체 맥락을 관리하고, 서브에이전트는 한정된 하위 작업을 수행해 결과를 돌려줍니다. Claude Code에서 먼저 읽기 전용 검토를 위임해 봅니다.

# Claude Code 대화창에 입력할 요청 예시
서브에이전트에게 README.md의 실행 안내 검토를 맡겨 줘.
파일은 수정하지 말고, 빠진 단계와 근거 위치를 보고하게 해 줘.
결과를 받은 뒤 네가 수정 제안을 종합해 줘.

직접 정의할 때는 .claude/agents/에 역할과 절차를 담습니다. 설정 형식은 Claude Code 서브에이전트 공식 문서에서 확인합니다.

02. 멀티에이전트 작업을 나누는 기준

여러 에이전트가 각자 세션에서 협업할 때는 담당 파일과 의존성을 명시합니다. 서브에이전트라는 역할과 병렬 실행 여부는 별도로 판단합니다.

• 독립적인 조사와 검토는 동시에 진행할 수 있습니다.
• 콘텐츠와 디자인은 인터페이스를 먼저 합의하면 병렬로 만들 수 있습니다.
• 두 결과가 필요한 통합 작업은 선행 결과가 도착한 후 시작합니다.
• 같은 파일의 수정이 겹치면 담당자를 한 명으로 정하거나 작업 순서를 둡니다.

03. 작업 계약과 인계 결과 작성하기

다른 세션은 내 대화를 모두 알고 있다고 가정할 수 없습니다. 작업 지시만 읽어도 실행할 수 있도록 대상, 변경, 제약, 소유권, 완료 기준을 함께 보냅니다.

# 위임할 작업 명세 예시
대상: content/body.html
변경: 1주차 강의의 설치 안내 작성
제약: 한국어, CSS 추가 금지
소유권: content/body.html만 수정
완료 기준: 설치 예시와 실습 팁 포함, HTML 태그 닫힘
인계 결과: 변경 파일, 검증 결과, 남은 문제, 커밋 SHA

04. 병렬 결과를 합치고 독립적으로 검토하기

실습에서는 A에게 내용 검토, B에게 명령어 검토를 맡기고 메인 에이전트가 두 보고서를 종합합니다. 변경이 필요한 항목은 담당자를 정한 뒤 반영합니다.

• 두 보고서가 같은 문제를 지적하면 근거를 합치고 중복 항목을 정리합니다.
• 의견이 충돌하면 실제 파일과 실행 결과로 확인합니다.
• 3주차 완료 기준: 작업 명세 두 개, 결과 두 개, 근거를 포함한 종합 보고 한 개입니다.

01. 브랜치로 변경의 흐름 나누기

Git은 로컬 변경 이력을 관리하고, GitHub는 저장소 공유와 코드 검토에 사용합니다. 기존 Git 저장소의 루트에서 현재 브랜치와 작업 상태를 확인한 뒤 실습 브랜치를 만듭니다.

git status
git branch --show-current
git switch -c lesson-notes

02. 커밋으로 검토 가능한 단위 남기기

에이전트에게 README.md의 실습 설명을 개선하게 한 뒤 직접 diff를 읽습니다. 목적이 같은 변경을 한 커밋으로 묶고, 의도한 파일만 스테이징합니다.

git diff -- README.md
git add README.md
git diff --cached
git commit -m "docs: add agent practice notes"
git log -1 --oneline
git status

커밋 SHA는 작업 결과를 정확히 가리키는 식별자입니다. 에이전트 간 인계에는 브랜치 이름과 SHA를 함께 남깁니다.

03. 워크트리로 병렬 작업 공간 만들기

워크트리는 하나의 저장소에서 서로 다른 브랜치를 별도 폴더에 펼치는 기능입니다. 커밋을 마친 뒤 main으로 돌아와 콘텐츠와 디자인용 작업 공간을 나누어 봅니다.

# 아래 브랜치와 경로가 아직 없을 때 실행
git switch main
git worktree add -b practice-content ../agent-course-content
git worktree add -b practice-design ../agent-course-design
git worktree list

• 콘텐츠 에이전트는 agent-course-content에서, 디자인 에이전트는 agent-course-design에서 실행합니다.
• 작업 폴더의 파일과 스테이징 상태는 분리되지만 저장소의 커밋과 브랜치 정보는 공유합니다.
• 워크트리로 나눠도 같은 파일을 다르게 고치면 통합 시 충돌할 수 있으므로 파일 소유권을 정합니다.

04. GitHub PR로 변경 설명과 검토 연결하기

GitHub 원격 저장소 origin과 인증이 준비된 상태에서 lesson-notes 브랜치를 올립니다. GitHub의 새 Pull Request 화면에서 base는 main, compare는 lesson-notes로 선택합니다.

# 원래 작업 폴더에서 실행
git switch lesson-notes
git remote -v
git push -u origin lesson-notes

• PR 설명에는 바뀐 동작, 변경 이유, 검증 결과를 적습니다.
• 검토자는 파일 차이와 완료 기준을 확인하고 수정 요청이나 승인을 남깁니다.
• 충돌이 있으면 양쪽 의도를 확인해 해결하고 검증한 뒤 통합합니다.
• 4주차 완료 기준: 커밋 SHA, 워크트리 목록, 검증 결과를 적은 PR 초안입니다.

01. Orca에서 실행 환경 확인하기

Orca에서 프로젝트와 워크트리, 에이전트 세션을 확인하고 코디네이터와 작업자의 역할을 나눕니다. 설치된 Orca 버전과 일치하는 명령 안내를 먼저 읽습니다.

# Orca 관리 터미널에서 확인
orca status --json
orca skills get orchestration
orca orchestration worker-start --help

02. Run·Task·Dispatch 구분하기

• Run: 하나의 목표에 관한 작업과 메시지를 묶는 공간입니다. Run 생성 자체가 작업자를 실행하지는 않습니다.
• Task: 대상, 변경, 제약, 소유권, 완료 기준을 가진 작업 단위입니다.
• Dispatch: 특정 Task를 수행하는 한 번의 시도입니다. 재시도는 기존 시도와 구분해 추적합니다.
• 코디네이터: 준비된 작업을 시작하고 질문·결과·실패를 처리하며 다음 작업의 실행을 판단합니다.

새 실습의 코디네이터 터미널에서는 아래처럼 Run과 Task를 등록할 수 있습니다. 이미 작업을 배정받은 워커는 자신이 속한 Run을 새로 만들지 않습니다.

orca orchestration run-create --objective "강의 페이지 제작 실습" --json
orca orchestration task-create --task-title "콘텐츠 작성" --spec "대상: content/body.html; 변경: 5주 강의 작성; 제약: 한국어, 스타일 금지; 소유권: content/body.html만; 완료 기준: 주차 섹션 5개와 검증 결과" --json

03. DAG와 워크트리로 병렬 작업 설계하기

DAG는 방향이 있고 순환이 없는 그래프입니다. 노드는 작업, 화살표는 선행 결과가 필요하다는 뜻입니다. 그래프 엔지니어링은 이 의존성과 파일 소유권, 완료 증거, 실패 시 후속 절차를 설계하는 일입니다.

• 콘텐츠와 디자인처럼 독립적인 작업은 서로 다른 브랜치·워크트리에서 동시에 시작합니다.
• 통합은 두 선행 작업이 모두 성공한 뒤 시작하는 합류 지점입니다.
• 검수는 통합 결과를 입력으로 받고, 작성자와 다른 에이전트가 수행합니다.
• 수정이 필요하면 새 수정 작업과 후속 통합·재검수를 추가해 실행 이력을 남깁니다.

04. 이 페이지가 만들어지는 실행 그래프

이 페이지는 콘텐츠·디자인을 병렬로 만들고 통합·검수하는 그래프로 제작됩니다. 두 작성자는 orchestration/CONTRACT.md의 마크업 계약을 공유하고 각자 소유한 파일만 수정합니다.

사용자 목표 → 코디네이터
               ├─ T1 콘텐츠 · Codex · content 브랜치 · 워크트리 A ─┐
               └─ T2 디자인 · Claude · design 브랜치 · 워크트리 B ─┤
                                                               ↓
                       T3 통합 · main · 두 결과를 index.html로 조합
                                                               ↓
                       T4 검수 · 구조·내용·디자인·계약 확인
                                                               ↓
                       코디네이터가 근거와 남은 항목을 사용자에게 보고

• T1은 content/body.html을, T2는 design/shell.html과 design/style.css를 작성하고 각각 커밋합니다.
• T3은 T1·T2의 성공을 확인한 후 브랜치를 합치고 셸의 본문 자리표시자를 콘텐츠로 치환합니다.
• T4는 파일을 고치지 않고 검수 보고서를 작성합니다. 문제가 있으면 코디네이터가 사용자 결정에 따라 담당 작업을 다시 배정합니다.
• 작업자는 진행 중 heartbeat로 생존을 알리고 질문은 ask로 전달하며, Task ID와 Dispatch ID를 포함한 worker_done으로 결과를 한 번 보고합니다.
• 5주차 완료 기준: 실행 그래프, 작업별 커밋 SHA, 통합 페이지, 검수 보고서, 근거를 담은 최종 보고입니다.