먼저, 내 노트북부터 고르세요
공통 준비 문서는 운영체제별로 하나씩 있습니다. 본인 것 하나만 하면 됩니다.
Windows 10 (1809 이상) 또는 11. PowerShell로 진행합니다. 자동 점검 스크립트도 제공합니다.
공통 준비 · Windows 시작하기 → Mac 사용자macOS 13 (Ventura) 이상. 터미널로 진행하며 대부분 한 줄 명령으로 끝납니다.
공통 준비 · macOS 시작하기 →시작 전에 구독을 먼저 확인하세요. 이 과정의 실습에는 Claude Pro / Max / Team / Enterprise 중 하나가 필요합니다. 무료 플랜으로는 Claude Code를 쓸 수 없습니다. claude.ai → 왼쪽 아래 계정 메뉴에서 플랜을 확인하세요. API Key는 필요하지 않습니다.
1. 전체 설치 지도
문서는 세 개입니다. 1번과 3번이 필수이고, 2번만 선택입니다. Python 설치까지 1번(공통 준비)에 들어 있습니다 — 3번은 도구를 연결하는 5분짜리 작업이라 6차시 직전에 해도 됩니다.
-
1
공통 준비 — 모든 실습의 출발점
Git · Claude Code · 에이전트 팀 · Harness 플러그인 · 실습 저장소 · Python까지 한 번에 준비합니다.
끝나면: Claude Code에서
하네스 구성해줘가 동작합니다. -
2
Codex CLI — 두 번째 AI 붙이기
ChatGPT Plus 구독으로 OpenAI 터미널 AI를 붙입니다. 같은 지시서를 두 도구에 주고 결과를 비교하는 실습에 씁니다.
구독이 없으면 건너뛰어도 됩니다. 비교 실습은 관찰 학습으로 대체할 수 있습니다.
-
3
MCP 서버 (Tool) — 나만의 도구 붙이기
파이썬 40줄짜리 계산기를 Claude Code와 Codex 양쪽에 붙입니다. "AI가 못 하는 정확한 계산은 코드에 맡긴다" 를 손으로 확인합니다.
6차시 필수입니다. 하는 일은 패키지 하나 설치 + 도구 연결 둘뿐 — Python 자체는 1번에서 이미 깔았으므로 5분이면 끝납니다.
교육 전날까지 1번(공통 준비)을 끝내 두세요. Python까지 여기 들어 있습니다 — 6차시 당일에 Python 설치부터 시작하면 실습 시간을 통째로 씁니다. 3번(MCP 연결)은 6차시 전까지, 2번(Codex)은 선택입니다.
설치할 때 "범위(scope)"를 묻는 화면이 두 번 나옵니다 — 둘 다 User 를 고르세요.
| 무엇 | 선택 | 왜 |
|---|---|---|
| Harness · Skills 플러그인 | User scope | 과정 중 폴더를 계속 옮겨 다니므로, 특정 폴더에만 설치되면 4차시부터 동작하지 않습니다 |
| MCP 서버 (6차시) | --scope user 명시 | 기본값이 local(그 폴더 전용)이라 붙이지 않으면 7차시에서 도구가 사라집니다 |
2. 무엇을 설치하나 (그리고 무엇을 설치하지 않나)
| 설치하는 것 | 왜 필요한가 | 어디서 |
|---|---|---|
| Claude Code | 하네스가 실행되는 작업장. 터미널에서 대화하는 AI | 공통 준비 |
| Git | 실습 저장소를 받고, 플러그인을 내려받는 데 사용 | 공통 준비 |
| 에이전트 팀 기능 | 전문가 여러 명이 동시에 일하게 하는 스위치 (하네스 필수 조건) | 공통 준비 |
| Harness 플러그인 | "하네스 구성해줘" 한마디로 에이전트 팀을 설계해 주는 도구 | 공통 준비 |
| Anthropic Skills | 엑셀·워드·PPT 파일을 직접 읽고 만드는 능력 | 공통 준비 |
| 실습 저장소 | 생산 보고서 엑셀, 샘플 데이터, 과제 문서 | 공통 준비 |
| Codex CLI | 두 번째 AI — 비교 실습·도구 이식성 확인 | 선택 (2번) |
| Python 3.10+ | 6차시 계산 도구(MCP)를 돌리는 데 필요 | 공통 준비 3-9절 |
| 선택 — 실습 파일을 편하게 보려면 | 왜 | 어디서 |
|---|---|---|
| VS Code (무료) | .md 리포트를 보기 좋게, CSV·JSON을 한글 깨짐 없이 열기 | 공통 준비 5-3절 |
| 없이도 됩니다 | 교안은 GitHub 웹에서 가장 잘 읽히고, .md 는 메모장으로도 읽힙니다. 엑셀·워드·PPT·한글 파일은 Claude Code가 직접 읽습니다 | — |
설치하지 않는 것: Node.js, bun, Docker, WSL2, 안티그래비티.
Claude Code는 자체 실행 파일로 설치되므로 개발 언어 런타임이 필요하지 않습니다. 이미 설치되어 있어도 문제는 없습니다.
3. 준비물 체크 (설치 시작 전에)
| 항목 | 필요한 것 | 확인 방법 |
|---|---|---|
| 구독 | Claude Pro 이상 (필수) / ChatGPT Plus 이상 (선택) | 각 서비스 계정 메뉴 |
| 운영체제 | Windows 10 (1809+) / 11 · macOS 13 이상 | Windows winver · Mac → 이 Mac에 관하여 |
| 저장 공간 | 2GB 이상 여유 | — |
| 메모리 | 4GB 이상 | — |
| 관리자 권한 | 필요 없음 | 사용자 폴더에 설치됩니다 |
| 인터넷 | claude.ai · github.com 접속 가능 | 브라우저로 두 주소가 열리는지 확인 |
회사 노트북에서 설치할 때 — 보안 프로그램(백신·DLP·EDR)이 설치를 막을 수 있습니다. 임의로 끄지 말고 IT 담당자에게 문의하세요. 교육장에서 가장 빠른 우회는 사내 Wi-Fi 대신 휴대폰 테더링입니다.
4. 준비 완료 체크리스트
공통 준비를 마쳤다면 아래가 모두 되어 있어야 합니다. 하나라도 비면 해당 문서의 문제 해결 절을 보세요.
- Claude Pro 이상 구독 확인
git --version이 버전 번호를 출력claude --version이 버전 번호를 출력- 에이전트 팀 환경변수가
1(Windowsecho $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS· Macecho $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) C:\harness-edu(Mac은~/harness-edu) 폴더 존재claude실행 후 한국어로 대화 성공/plugin→ Installed 탭에서 harness, document-skills 가 User 범위에 표시- 입력창에
하네스 구성해줘→ 되묻는 질문이 옴 (답하지 말고 ESC →/exit) python --version(Mac은python3 --version) 이 3.10 이상을 출력
6차시 전까지 추가로 — MCP 서버 설치가이드(5분)를 마치면 아래가 됩니다.
claude실행 후/mcp→production-metrics가 connected
5. 실습 폴더 지도 (한 번 보고 넘어가세요)
과정 중에 폴더를 여러 번 옮겨 다닙니다. 매 차시 "어디서 claude 를 켜야 하나" 가 헷갈리는 것이 가장 흔한 막힘이라, 전체 지도를 미리 한 장으로 봅니다.
harness-edu/
├── xlsx/ 1차시 생산보고서 엑셀 (첫 실행 체험)
├── ad/ 2차시 광고 매체 성과 10개 + 용어집 ← 정하늘 대리 사례
├── codex/ 3차시 트렌드 리포트 지시서 (도구 비교)
├── harness/ 4차시 제안서 하네스 (팀 만들기)
├── my-harness/ 4차시 ← 여기서 처음 직접 만듭니다
├── map/ 5차시 서울시청 인근 식당 15,144건
├── tool/mcp-server/ 6차시 계산 MCP 서버 (Python)
│
├── slide/ dashboard/ codex-engineering/ 확장 트랙 (선택)
│
├── harness-100/ 7차시 내려받는 하네스 컬렉션 (git clone)
└── my-work/ 7차시 ← 내가 만드는 것. 직접 생성합니다
├── meeting/ harness-100 84번을 이식
├── deck/ harness-100 13번 + 이미지 스킬 (선택)
└── routine/ 내 반복 업무 하네스 — 처음부터 직접| 규칙 | 내용 |
|---|---|
| 차시마다 이동합니다 | 각 차시 첫머리에 cd 명령이 있습니다. 그 폴더에서 claude 를 켜야 파일을 찾습니다 |
| 지금 어딘지 모르겠으면 | Windows pwd · macOS pwd 를 터미널에 입력하면 현재 위치가 나옵니다 |
| 파일을 못 찾는다고 하면 | 십중팔구 다른 폴더에서 켠 것입니다. /exit 후 올바른 폴더에서 다시 켜세요 |
my-work/ 는 비어 있습니다 | 7차시에 직접 만듭니다. 지금 없는 것이 정상입니다 |
| 폴더 이름은 영문으로 | 직접 폴더를 만들 때 한글·공백·특수문자를 피하세요. 일부 도구에서 경로 인식이 실패합니다 |
바탕화면·문서 폴더에 두지 마세요. OneDrive·iCloud 동기화 폴더 안에서는 파일이 잠기거나 경로가 바뀌어 실습이 자주 깨집니다. Windows는 C:\harness-edu, macOS는 ~/harness-edu 를 그대로 쓰세요.
6. 자동 점검 스크립트 (Windows · 선택)
설치를 마친 뒤 빠진 게 없는지 한 번에 점검하는 스크립트입니다. 빠진 항목만 설치하며, 여러 번 실행해도 안전합니다.
cd "$env:USERPROFILE\Downloads"
irm https://namojo.github.io/harness-edu/install/setup-windows.ps1 -OutFile setup-windows.ps1
Unblock-File .\setup-windows.ps1
.\setup-windows.ps1
자세한 옵션과 실행 결과 예시는 공통 준비 · Windows 9-A절에 있습니다. macOS는 명령이 이미 한 줄씩이라 별도 스크립트를 만들지 않았습니다.
7. 자주 묻는 질문
개발을 전혀 모르는데 따라 할 수 있나요?
네. 이 가이드는 터미널을 처음 여는 분을 기준으로 썼습니다. 명령을 이해할 필요 없이 복사해서 붙여넣으면 되고, 각 단계마다 화면에 무엇이 나와야 정상인지 그림처럼 적어 두었습니다. 막히는 지점은 대부분 "창을 새로 열지 않아서" 생기므로, 문서가 시키는 대로 창을 닫았다 여는 것만 지켜도 대부분 해결됩니다.
Claude 구독이 꼭 필요한가요?
필요합니다. Claude Code는 Pro 이상 구독에서 동작하며 무료 플랜은 지원하지 않습니다. 회사 계정(Team/Enterprise)이라면 관리자가 Claude Code 사용을 허용했는지 미리 확인하세요.
Codex(ChatGPT)까지 있어야 하나요?
아닙니다. 대부분의 모듈은 Claude Code만으로 진행됩니다. Codex는 "같은 지시서를 다른 AI에 줬을 때 결과가 어떻게 달라지는가" 를 직접 보기 위한 선택 항목입니다.
회사 보안 때문에 설치가 막히면요?
보안 프로그램을 끄지 마세요. IT 담당자에게 필요한 것만 요청하면 됩니다 — github.com·claude.ai 접근, 그리고 Windows라면 PowerShell CurrentUser 실행 정책 RemoteSigned 허용. 그래도 어려우면 교육 담당자에게 알려 주세요.
교안·실습 파일은 무엇으로 열어야 하나요?
대부분 이미 있는 프로그램으로 열립니다. 교안(.md)은 GitHub 웹에서 보는 것이 가장 편하고, 엑셀·워드·PPT는 평소 쓰는 오피스로 열면 됩니다. 한글(.hwpx) 파일은 직접 열 필요가 없습니다 — AI가 읽습니다.
AI가 만들어 준 .md 리포트를 자주 보게 되므로 VS Code(무료)를 하나 깔아 두면 편합니다. UTF-8 CSV의 한글 깨짐도 없습니다. 자세한 것은 공통 준비 5-3절에 있습니다.
실제 업무 파일로 실습해도 되나요?
하지 마세요. 실습 폴더에는 가상 데이터만 넣습니다. AI 도구는 실행한 폴더의 파일을 읽을 수 있습니다. 실 데이터 적용은 교육 이후 IT·보안 검토를 거쳐 진행합니다.
설치한 것을 나중에 지울 수 있나요?
가능합니다. 각 문서의 제거·되돌리기 절에 원래 상태로 되돌리는 명령이 정리되어 있습니다. 실습 폴더는 통째로 삭제하면 됩니다.
8. 설치가 끝났다면
설치 중 막히면 교육 전날까지 담당자에게 알려 주세요. Windows 점검 스크립트를 돌렸다면
%USERPROFILE%\harness-setup-logs\의 로그 파일을 함께 보내 주시면 원인 파악이 빠릅니다.