공통 준비 — Windows 실습 환경 만들기

작성일: 2026-08-20 (명령어·주소는 이 날짜에 공식 문서로 확인)
대상: Windows 10 / 11 노트북, 터미널을 처음 쓰는 비개발자
끝나면: Claude Code에서 하네스 구성해줘 가 동작하는 상태

빠른 설치 (아는 사람용 · 10분)

터미널이 익숙한 분은 이 블록만 순서대로 실행하면 됩니다. 처음이면 1절부터 천천히 내려가세요.

1. Git 설치 (PowerShell)

winget install --id Git.Git -e --source winget

2. Claude Code 설치

irm https://claude.ai/install.ps1 | iex

3. 에이전트 팀 기능 켜기 → PowerShell 창을 새로 열기

setx CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1

4. 실습 저장소 받기 + 그 폴더로 이동

git clone https://github.com/namojo/harness-edu.git C:\harness-edu

cd C:\harness-edu

5. Claude Code 실행 → 브라우저 로그인 (Pro/Max 구독 계정)

claude

6. 플러그인 설치 — Claude Code 입력창 안에서 한 줄씩

/plugin marketplace add revfactory/harness
/plugin install harness@harness-marketplace
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

7. 동작 확인 — 입력창에 하네스 구성해줘 를 넣고 되묻는 질문이 오면 완료입니다. 답하지 말고 ESC 로 입력창에 돌아온 뒤 /exit (자세히).

8. Python (6차시용) — python --version 이 3.10 이상이 아니면 설치 후 창을 새로 열기

winget install --id Python.Python.3.13 -e --source winget

막히면: 'git' 용어가 ... 인식되지 않습니다 → 문제 해결 ① · claude 명령을 못 찾음 → ② · 플러그인 추가 실패 → ⑤

1. 이 문서는 무엇인가

이 과정에서 우리는 AI에게 일을 한 번 시키는 것이 아니라, 여러 번 같은 품질로 시키는 구조를 만듭니다. 그 구조를 하네스(Harness) 라고 부릅니다. 하네스를 만들려면 세 가지가 필요합니다.

여기에 실습 파일(생산 보고서 엑셀, 샘플 데이터 등)이 담긴 저장소를 내 노트북으로 받아 오면 준비가 끝납니다.

이 문서를 끝내면 다른 설치가이드의 "설치 전 확인"은 모두 통과한 상태가 됩니다. macOS를 쓰신다면 이 문서 대신 공통 준비 — macOS 를 보세요.

이 과정에서 설치하지 않는 것: Node.js, bun, Docker, WSL2, 별도 편집기.
Claude Code는 자체 실행 파일로 설치되므로 개발 언어 런타임이 필요하지 않습니다. (6차시용 Python은 아래 3-9절에서 함께 설치합니다.)

2. 설치 전 확인

실습 자료 규칙 — 실습 폴더에는 가상 데이터만 넣습니다. 실제 고객명·주민등록번호·계약금액이 담긴 파일은 복사해 오지 않습니다. AI 도구는 그 폴더의 파일을 읽을 수 있습니다.

3. 설치 절차

3-1. PowerShell 여는 법 (모든 명령의 출발점)

[시작] 버튼(창문 모양) → 검색창에 아래를 입력 → Enter

PowerShell

이 PS C:\Users\본인이름> 을 프롬프트라고 부릅니다. 뒤에 명령을 붙여넣고 Enter를 누르는 것이 전부입니다. 관리자 권한으로 열 필요는 없습니다.

복사·붙여넣기 하는 법 (앞으로 계속 씁니다)
회색·검은 블록 오른쪽의 [복사] 버튼을 누르고 → PowerShell 창을 클릭 → Ctrl+V → Enter.
붙지 않으면 마우스 오른쪽 버튼 한 번을 누르세요(옛 방식 창에서는 우클릭이 붙여넣기입니다).

3-2. Windows 버전 확인

winver

3-3. Git for Windows 설치

먼저 이미 깔려 있는지 확인합니다.

git --version

인식되지 않으면 아래로 설치합니다.

winget install --id Git.Git -e --source winget

설치가 끝나면 PowerShell 창을 완전히 닫고(오른쪽 위 X) 3-1번 방법으로 새로 엽니다. 그리고 다시 git --version 으로 확인합니다.

왜 새 창이 필요한가: 설치 프로그램이 명령의 위치를 시스템에 등록했지만, 이미 열려 있던 창은 그 변경을 모릅니다. 이 단계를 건너뛰어 생기는 오류가 초보자 오류 1위입니다.

Git이 왜 필요한가: ① 실습 저장소를 받아 오고(git clone), ② 플러그인을 GitHub에서 내려받는 데 쓰이고, ③ Windows에서 Claude Code가 파일 작업을 할 때 함께 설치되는 Git Bash를 사용합니다. 공식 문서도 Windows에서 Git for Windows 설치를 권장합니다.

3-4. Claude Code 설치

irm https://claude.ai/install.ps1 | iex

여기서도 PowerShell 창을 닫고 새로 엽니다. 그리고 확인합니다.

claude --version

업데이트는 신경 쓰지 않아도 됩니다. 이 방식으로 설치하면 Claude Code가 백그라운드에서 스스로 최신 버전으로 갱신합니다.

3-5. 에이전트 팀 기능 켜기 (하네스 필수 조건)

하네스는 전문가 에이전트 여러 명이 팀으로 협업하는 기능을 씁니다. 이 기능은 기본이 꺼져 있어 한 번 켜 주어야 합니다.

setx CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1

성공: 지정한 값을 저장했습니다.

이 설정은 새로 여는 창부터 적용됩니다. PowerShell을 닫고 새로 열어 값을 확인하세요.

echo $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

설정 파일로 켜는 방법도 있습니다 — %USERPROFILE%\.claude\settings.json 의 env 항목에 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 을 넣어도 동일합니다. JSON 문법을 틀리면 설정 전체가 무시되므로, 처음이라면 위의 setx 방법을 쓰세요.

3-6. 실습 저장소 받기 (실습 폴더 만들기)

실습 파일(생산 보고서 엑셀, 샘플 CSV, 과제 문서)이 담긴 저장소를 내 노트북으로 받습니다.

git clone https://github.com/namojo/harness-edu.git C:\harness-edu

Cloning into 'C:\harness-edu'...
remote: Enumerating objects: 300, done.
Receiving objects: 100% (300/300), 6.20 MiB | 4.10 MiB/s, done.

git clone https://github.com/namojo/harness-edu.git "$env:USERPROFILE\harness-edu"

이제 그 폴더로 이동합니다. 실습은 항상 이 폴더 안에서 합니다.

cd C:\harness-edu; pwd

Path
----
C:\harness-edu

3-7. Claude Code 실행 · 로그인

3-6에서 이동한 harness-edu 폴더 안에서 실행합니다. (프롬프트 끝이 harness-edu> 인지 확인)

claude

처음 실행하면 순서대로 물어봅니다.

Claude Code 나가는 법: 입력창에 /exit 를 넣고 Enter (또는 Ctrl+C 두 번). 다시 들어가려면 폴더로 cd 한 뒤 claude.

3-8. Harness 플러그인 설치 (스코프 선택 주의)

여기서부터는 PowerShell이 아니라 Claude Code 입력창에 입력합니다. / 로 시작하는 명령은 Claude Code 자체 명령입니다.

/plugin marketplace add revfactory/harness

/plugin install harness@harness-marketplace

Plugin is now active.              → 바로 쓸 수 있습니다
Run /reload-plugins to activate.   → 아래 명령을 한 번 실행하세요

/reload-plugins

이어서 문서 작업용 Anthropic Skills 플러그인도 설치합니다. (엑셀·워드·PPT 실습에서 씁니다) 이때도 User scope를 고릅니다.

/plugin marketplace add anthropics/skills

/plugin install document-skills@anthropic-agent-skills

설치 범위가 맞는지 확인하기

입력창에서 /plugin 을 실행하고 Installed 탭을 보면, 목록이 범위별로 묶여 표시됩니다. 두 플러그인이 User 그룹 아래에 있으면 정상입니다.

/plugin uninstall harness@harness-marketplace

claude plugin marketplace add revfactory/harness
claude plugin install harness@harness-marketplace --scope user
claude plugin marketplace add anthropics/skills
claude plugin install document-skills@anthropic-agent-skills --scope user

플러그인이 뭔가요: Claude Code에 기능을 얹는 확장입니다. Harness 플러그인은 "어떤 전문가 팀을 만들어야 하는가"를 설계해 주는 도구이고, document-skills 는 엑셀·워드·PPT 파일을 직접 읽고 만드는 능력을 더합니다.

3-9. Python 설치 (6차시 준비)

여기서부터는 다시 PowerShell 입니다. Claude Code에서 /exit 로 나온 뒤 진행하세요.

먼저 이미 있는지 확인합니다.

python --version

winget install --id Python.Python.3.13 -e --source winget

여기까지가 설치의 전부입니다. 6차시에서 쓸 계산 도구를 Claude Code에 연결하는 것은 별도 문서(MCP 서버 설치가이드)에서 합니다. Python만 준비되어 있으면 그 문서는 5분이면 끝납니다.

4. 설치 확인 (1분)

Claude Code에서 /exit 로 나온 뒤, PowerShell에서 한 줄씩 실행합니다.

git --version; claude --version; python --version; echo $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

git version 2.55.0.windows.1
2.1.211 (Claude Code)
Python 3.13.1
1

설치 상태를 한 번 더 진단하려면:

claude doctor

최종 체크리스트 — 교육 전까지 아래가 모두 되어 있어야 합니다.

• Claude Pro 이상 구독 확인 (claude.ai 계정 메뉴)
• git --version 이 버전 번호를 출력
• claude --version 이 버전 번호를 출력
• python --version 이 3.10 이상을 출력 (6차시용)
• echo $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 가 1 출력
• C:\harness-edu 폴더 존재 (또는 사용자 폴더) — 경로에 OneDrive·Desktop 없음
• claude 실행 후 한국어로 대화 성공
• /plugin → Installed 탭에서 harness, document-skills 가 User 범위에 표시
• 아래 6절 첫 동작 테스트 통과

5. 초기 설정·연동

5-1. PowerShell 최소 조작 5가지

실습 폴더 이동 명령은 앞으로 계속 씁니다. 이 블록을 즐겨찾기해 두세요.

cd C:\harness-edu

방금 친 명령 다시 쓰기: 키보드 ↑ → 직전 명령이 그대로 나옵니다. 오타를 고쳐 Enter.

5-2. Claude Code 기본 조작 4가지

5-3. 실습 파일 여는 방법

실습 폴더에는 여러 형식의 파일이 들어 있습니다. 대부분 추가 설치 없이 볼 수 있지만, .md 파일은 Windows에 기본 뷰어가 없습니다.

① 설치 없이 — GitHub 웹에서 보기 (권장)

교안과 .md 파일은 GitHub 웹페이지에서 가장 잘 읽힙니다. 표와 제목이 정돈된 상태로 보이고, 설치가 필요 없습니다.

https://github.com/namojo/harness-edu

내 PC에서 만든 파일이 아니라 원본 교안을 볼 때 이 방법이 가장 빠릅니다.

② 내가 만든 파일까지 편하게 — VS Code 설치 (선택)

AI가 만들어 준 .md 리포트를 보기 좋게 열고, CSV·JSON도 한글이 깨지지 않게 보려면 무료 편집기 하나가 편합니다. 필수는 아닙니다.

winget install --id Microsoft.VisualStudioCode -e --source winget

winget이 없으면 code.visualstudio.com 에서 설치 파일을 받아 기본값으로 설치하세요.

③ 엑셀에서 CSV 한글이 깨질 때

실습 CSV는 UTF-8 형식입니다. 파일을 더블클릭해서 열면 엑셀이 다른 형식으로 잘못 읽어 루미ì—르 처럼 보일 수 있습니다. 아래 순서로 열면 정상입니다.

VS Code로 열면 이 과정이 필요 없습니다.

이 폴더의 파일들이 각각 무슨 내용인지 한 줄씩 정리해줘.

안전 원칙
① 실제 업무 파일이 있는 폴더에서 실습하지 않습니다. 항상 harness-edu 폴더에서 실행하세요.
② AI가 파일을 수정·삭제하려 할 때 승인 여부를 물어봅니다. 내용을 읽고 판단하세요 — 습관적으로 승인하지 않습니다.
③ 회사 보안 프로그램(백신·DLP)이 설치를 막으면 끄지 말고 IT 담당자에게 문의합니다.

6. 첫 동작 테스트 (3분)

실습 폴더에서 claude 를 실행하고, 입력창에 아래를 넣습니다.

지금 이 폴더에 어떤 파일과 폴더가 있는지 한국어로 요약해줘.

이제 Harness 플러그인이 살아 있는지 확인합니다.

하네스 구성해줘

/exit

7. 문제 해결

① 'git' 용어가 ... 인식되지 않습니다

• 원인: Git 설치가 안 됐거나, 설치 전부터 열려 있던 창을 그대로 쓰고 있습니다.
• 해결: ⑴ PowerShell 창을 모두 닫고 새로 열어 git --version 재확인 → ⑵ 그래도 안 되면 PC 재부팅 → ⑶ 여전하면 설정 → 앱 → 설치된 앱 에서 Git 검색. 없으면 3-3절을 다시 합니다.

② 'claude' 용어가 ... 인식되지 않습니다

• 원인: 설치는 됐지만 명령 경로(PATH)가 아직 반영되지 않았습니다.
• 해결 1: PowerShell을 닫고 새로 열어 다시 claude --version.
• 해결 2: 그래도 안 되면 아래를 한 번 실행한 뒤, 창을 새로 엽니다.

$claudePath = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$claudePath*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$claudePath", "User")
}

③ 'winget' 용어가 ... 인식되지 않습니다

• 원인: Windows 앱 설치 관리자(App Installer)가 없거나 오래된 Windows 10입니다.
• 해결: Git 설치 파일을 직접 받습니다. 브라우저 주소창에 아래를 붙여넣고 → 다운로드 → 모든 화면 기본값 그대로 Next → Install → Finish.

https://git-scm.com/downloads/win

④ 로그인은 됐는데 "구독이 필요합니다" 라고 나옵니다

• 원인: 무료 플랜 계정으로 로그인했습니다. Claude Code는 Pro 이상이 필요합니다.
• 해결: Claude Code 입력창에서 /logout → 다시 claude 실행 → 구독 계정으로 로그인. 회사 계정이면 관리자에게 Claude Code 사용 허용 여부를 확인하세요.

⑤ /plugin marketplace add 가 실패합니다

• 확인 1: PowerShell에서 git --version 이 동작하는지 (플러그인은 Git으로 내려받습니다).
• 확인 2: 저장소 이름을 정확히 입력했는지 — revfactory/harness, anthropics/skills.
• 확인 3: 사내 방화벽이 github.com 을 막고 있을 수 있습니다. 휴대폰 테더링으로 바꿔 재시도해 보세요.

⑥ 다운로드가 멈추거나 "연결할 수 없음"이 뜹니다

• 원인: 사내 프록시·방화벽·백신이 접속을 막거나 회선이 일시적으로 끊겼습니다.
• 해결: ⑴ 브라우저에서 https://claude.ai 와 https://github.com 이 열리는지 확인 → ⑵ 사내 Wi-Fi 대신 휴대폰 테더링으로 재시도(교육장에서 가장 빠른 방법) → ⑶ 설치 명령은 여러 번 재실행해도 안전합니다(↑ → Enter) → ⑷ 계속 막히면 백신을 임의로 끄지 말고 IT 담당자에게 문의.

⑦ 이미 바탕 화면(OneDrive)에 받았습니다 / 폴더를 찾지 못합니다

• 원인: OneDrive 폴더 백업이 켜져 있으면 바탕 화면의 실제 위치가 C:\Users\이름\OneDrive\바탕 화면 으로 바뀝니다. 그 안에 저장소를 두면 동기화가 .git 파일을 잠가 "다른 프로그램이 사용 중" 오류가 나고, 실습 파일이 계속 업로드됩니다.
• 해결: 아래를 붙여넣으면 동기화되지 않는 C:\harness-edu 로 옮깁니다. 옮길 것이 없으면 그렇게 알려 줍니다.

$dst = "C:\harness-edu"
$found = @([Environment]::GetFolderPath("Desktop"), "$env:USERPROFILE\Desktop", "$env:USERPROFILE\Documents", $env:USERPROFILE) |
         ForEach-Object { Join-Path $_ "harness-edu" } |
         Where-Object { $_ -ne $dst -and (Test-Path $_) } | Select-Object -Unique
if (-not $found) { "옮길 것이 없습니다. 현재 위치를 확인하세요: $dst" }
elseif (Test-Path $dst) { "이미 $dst 가 있습니다. 남은 사본은 직접 확인하세요: $($found -join ', ')" }
else { Move-Item -LiteralPath $found[0] -Destination $dst; "옮김: $($found[0])  ->  $dst" }

왜 옮겨야 하나: 이 과정은 AI가 실행한 폴더의 파일을 읽고 씁니다. 그 폴더가 동기화 중이면 ① 파일 잠금으로 쓰기가 실패하고 ② 탐색기 경로와 실제 경로가 달라 "파일이 없다"는 오류가 반복됩니다. 처음부터 C:\harness-edu 에 두는 것이 가장 확실한 해결입니다.

⑧ 에이전트 팀이 만들어지지 않습니다

• 확인: 새 PowerShell 창에서 echo $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 가 1 인지.
• 해결: 비어 있으면 3-5절을 다시 하고 반드시 창을 새로 열어 claude 를 실행합니다. 이미 실행 중인 Claude Code에는 적용되지 않습니다.

⑨ 한글이 깨져 보입니다

• 해결: Windows 11의 터미널(Windows Terminal) 로 여세요. 시작 → 터미널 검색 → 실행. 표시만 깨지는 것이고 동작에는 문제가 없습니다.

8. 제거·되돌리기

1) 플러그인 제거 — Claude Code 입력창에서

/plugin uninstall harness@harness-marketplace

2) Claude Code 제거 — PowerShell에서

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

3) 설정·대화 기록까지 지우기 (선택 — 되돌릴 수 없습니다)

Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force

4) 에이전트 팀 설정 되돌리기

setx CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 0

5) Git 제거 — 설정 → 앱 → 설치된 앱 → Git → 제거
6) 실습 폴더 삭제 — C:\harness-edu 를 휴지통으로 옮기고 휴지통을 비웁니다.

9. 다른 설치 방법 (본문이 막힐 때만)

A. 자동 점검 스크립트 (설치 후 확인용 · 권장)

위 절차를 마친 뒤, 빠진 게 없는지 한 번에 점검하는 스크립트입니다. 빠진 항목만 설치하며, 여러 번 실행해도 안전합니다.

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

   ==========================================
    최종 점검 결과
   ==========================================
    Git                  설치됨
    Claude Code          설치됨
    Claude 로그인        완료
    Agent Teams          활성
    harness 플러그인     설치됨
    실습 폴더            준비됨

    모든 항목 준비 완료. 교육 참여 준비가 끝났습니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

실행 로그는 %USERPROFILE%\harness-setup-logs\ 에 저장됩니다. 문의할 때 이 파일을 첨부하면 원인 파악이 빠릅니다.

B. winget 으로 Claude Code 설치

본문의 설치 스크립트가 사내 정책으로 막힐 때 씁니다. 단, 자동 업데이트가 되지 않아 직접 갱신해야 합니다.

winget install Anthropic.ClaudeCode

갱신은 winget upgrade Anthropic.ClaudeCode.

C. 이 과정에서 쓰지 않는 것

• WSL2 · Docker: 이 과정의 실습은 Windows에서 그대로 동작합니다. 설치하지 마세요.
• npm 설치: Node.js 22 이상이 이미 있는 분만 npm install -g @anthropic-ai/claude-code 로 대체할 수 있습니다. Node.js를 새로 깔 필요는 없습니다.
• Claude 데스크탑 앱: 터미널 없이 쓰는 GUI 버전입니다. 이 과정은 터미널 기준으로 진행하므로 필수가 아닙니다.

10. 다음 단계

확인한 출처

• Claude Code 설치 요구사항·명령 — code.claude.com/docs/en/setup
• 에이전트 팀 활성화 (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) — code.claude.com/docs/en/agent-teams
• 터미널 입문 안내 — code.claude.com/docs/en/terminal-guide
• Harness 플러그인 설치·요구사항 — github.com/revfactory/harness
• Anthropic Skills 플러그인 — github.com/anthropics/skills