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

작성일: 2026-08-20 (명령어·주소는 이 날짜에 공식 문서로 확인)
대상: macOS 13 이상 (Apple Silicon / Intel 모두 가능), 터미널을 처음 쓰는 비개발자
끝나면: Claude Code에서 하네스 구성해줘 가 동작하는 상태
Windows 사용자는 이 문서 대신 공통 준비 — Windows 를 보세요.

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

curl -fsSL https://claude.ai/install.sh | bash

echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc

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

cd ~/harness-edu && claude

⑤ 로그인 후 Claude Code 입력창 안에서 플러그인 설치

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

⑥ 입력창에 하네스 구성해줘 → 되묻는 질문이 오면 완료. 답하지 말고 ESC → /exit (자세히).

⑦ Python (6차시용) — python3 --version 이 3.10 이상인지만 확인. 없으면 xcode-select --install.

1. 이 문서는 무엇인가

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

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

2. 설치 전 확인

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

3. 설치 절차

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

Command+스페이스 → 아래를 입력 → Enter

터미널

복사·붙여넣기: 블록 오른쪽 [복사] 버튼 → 터미널 클릭 → Command+V → Enter.
비밀번호 입력 화면에서는 글자가 보이지 않습니다. 그대로 입력하고 Enter를 누르세요 (macOS의 정상 동작입니다).

3-2. macOS 버전 확인

sw_vers

ProductName:		macOS
ProductVersion:		15.5
BuildVersion:		24F74

3-3. Git 확인 (대개 이미 있습니다)

git --version

xcode-select --install

Git이 왜 필요한가: ① 실습 저장소를 받아 오고(git clone), ② Claude Code가 플러그인을 GitHub에서 내려받는 데 씁니다. Windows와 달리 macOS는 개발자 도구에 Git이 포함되어 있어 대부분 추가 설치가 필요 없습니다.

3-4. Claude Code 설치

curl -fsSL https://claude.ai/install.sh | bash

터미널 창을 완전히 닫고(Command+Q) 새로 열어 확인합니다.

claude --version

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

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

echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc

터미널을 닫고 새로 열어 값을 확인합니다.

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

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

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

Cloning into '/Users/본인이름/harness-edu'...
Receiving objects: 100% (300/300), 6.20 MiB | 5.30 MiB/s, done.

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

cd ~/harness-edu && pwd

[ -d ~/Desktop/harness-edu ] && mv ~/Desktop/harness-edu ~/harness-edu && echo "옮김 완료" || echo "옮길 것이 없습니다"

파인더에서 이 폴더를 열려면:

open ~/harness-edu

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

claude

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

여기서부터는 터미널이 아니라 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 플러그인도 설치합니다. 이때도 User scope를 고릅니다.

/plugin marketplace add anthropics/skills

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

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

입력창에서 /plugin → Installed 탭을 보면 목록이 범위별로 묶여 있습니다. 두 플러그인이 User 그룹에 있으면 정상입니다. 잘못 설치했다면 /plugin uninstall harness@harness-marketplace 로 지우고 다시 설치하면서 User를 고르세요.

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

3-9. Python 확인 (6차시 준비)

Claude Code에서 /exit 로 나온 뒤 터미널에서 진행합니다.

python3 --version

xcode-select --install

여기까지가 준비의 전부입니다. 6차시에서 쓸 계산 도구를 Claude Code에 연결하는 것은 별도 문서(MCP 서버 설치가이드)에서 합니다.

4. 설치 확인 (1분)

Claude Code에서 /exit 로 나온 뒤 실행합니다.

git --version; claude --version; python3 --version; echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

git version 2.39.5 (Apple Git-154)
2.1.211 (Claude Code)
Python 3.13.1
1

최종 체크리스트

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

5. 초기 설정·연동

5-1. 터미널 최소 조작 5가지

방금 친 명령 다시 쓰기: ↑ → 직전 명령이 그대로 나옵니다.

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

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

실습 폴더에는 여러 형식의 파일이 들어 있습니다. 대부분 추가 설치 없이 볼 수 있지만, .md 파일은 미리보기로 열면 서식이 보이지 않습니다.

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

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

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

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

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

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

code.visualstudio.com 에서 Mac용을 받아 응용 프로그램 폴더로 끌어다 놓으면 끝입니다. Homebrew를 쓰신다면 brew install --cask visual-studio-code 도 됩니다.

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

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

넘버스는 UTF-8 CSV를 대개 그대로 잘 읽습니다.

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

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

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

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

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

하네스 구성해줘

/exit

7. 문제 해결

① command not found: claude

• 원인: 설치는 됐지만 실행 경로가 셸에 등록되지 않았습니다.
• 해결 1: 터미널을 Command+Q 로 완전히 종료하고 새로 열어 재확인.
• 해결 2: 그래도 안 되면 아래를 실행한 뒤 새 창을 엽니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

② zsh: permission denied 또는 설치가 중간에 멈춤

• 확인: 명령을 sudo 없이 실행했는지. Claude Code 설치에 관리자 권한은 필요하지 않으며, sudo 로 설치하면 권한이 꼬입니다.
• 해결: 홈 폴더 권한 문제라면 ls -ld ~/.local 로 소유자가 본인인지 확인하세요.

③ 로그인은 됐는데 "구독이 필요합니다"

• 원인: 무료 플랜 계정으로 로그인했습니다. Claude Code는 Pro 이상이 필요합니다.
• 해결: 입력창에서 /logout → claude 재실행 → 구독 계정으로 로그인.

④ /plugin marketplace add 가 실패합니다

• git --version 이 동작하는지 확인 (플러그인은 Git으로 내려받습니다).
• 저장소 이름 확인 — revfactory/harness, anthropics/skills.
• 사내 방화벽이 github.com 을 막을 수 있습니다. 휴대폰 테더링으로 재시도.

⑤ 다운로드가 멈추거나 연결이 안 됩니다

• 브라우저에서 https://claude.ai, https://github.com 이 열리는지 확인합니다.
• 사내 Wi-Fi 대신 휴대폰 테더링으로 재시도(교육장에서 가장 빠른 방법).
• 설치 명령은 여러 번 재실행해도 안전합니다(↑ → Enter).
• 계속 막히면 백신을 임의로 끄지 말고 IT 담당자에게 문의하세요.

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

• 새 터미널에서 echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 가 1 인지 확인합니다.
• 비어 있으면 3-5절을 다시 하고 반드시 창을 새로 열어 claude 를 실행합니다.

8. 제거·되돌리기

1) 플러그인 제거 — Claude Code 입력창에서 /plugin uninstall harness@harness-marketplace

2) Claude Code 제거

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

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

rm -rf ~/.claude ~/.claude.json

4) 에이전트 팀 설정 되돌리기 — ~/.zshrc 를 열어 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 줄을 지웁니다. (편집: open -e ~/.zshrc)

5) 실습 폴더 삭제 — ~/harness-edu 를 휴지통으로 옮기고 휴지통을 비웁니다.

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

• Homebrew: 이미 brew를 쓰고 있다면 brew install --cask claude-code. 단 자동 업데이트가 되지 않아 brew upgrade claude-code 로 직접 갱신해야 합니다.
• npm: Node.js 22 이상이 이미 있는 분만 npm install -g @anthropic-ai/claude-code. Node.js를 새로 깔 필요는 없습니다.
• 자동 점검 스크립트: Windows 전용입니다. macOS는 위 명령이 이미 한 줄씩이라 별도 스크립트를 만들지 않았습니다.

10. 다음 단계

확인한 출처

• Claude Code 설치 요구사항·명령 — code.claude.com/docs/en/setup
• 에이전트 팀 활성화 — code.claude.com/docs/en/agent-teams
• Harness 플러그인 — github.com/revfactory/harness
• Anthropic Skills 플러그인 — github.com/anthropics/skills