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

작성일: 2026-08-01 (버전·다운로드 주소는 이 날짜 기준 공식 사이트 확인)
대상: Windows 10 / Windows 11 노트북, 터미널을 처음 열어 보는 분
소요 시간: 30~40분 (다운로드 속도에 따라 다름)

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

1. Node.js LTS 설치 — 아래 주소를 브라우저에 붙여넣고 LTS 버튼 → .msi 실행 → 기본값 Next (단, Tools for Native Modules는 체크 해제)

https://nodejs.org

2. Git for Windows 설치 — 아래 주소 → 다운로드 → 기본값 Next 연타

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

3. PowerShell을 새로 열고 (설치 후 새 창 필수) 실습 폴더 만들기

mkdir "$env:USERPROFILE\Desktop\AX실습"

4. 실습 폴더로 이동

cd "$env:USERPROFILE\Desktop\AX실습"

5. 세 가지 한 번에 확인

node -v; npm -v; git --version

버전 번호 3줄(v24.18.1 / 11.16.0 / git version 2.55.0.windows.3 형태)이 나오면 준비 완료입니다.

막히면: 'node' 용어가 ... 인식되지 않습니다 → 문제 해결 A / npm.ps1을 로드할 수 없습니다 → 문제 해결 B

터미널이 처음이면 아래 상세 절차로 내려가세요.

1. 이 문서는 무엇인가

교육에서 쓰는 AI 도구(파이, 안티그래비티, Codex CLI, korean-law-mcp)를 설치하기 전에 한 번만 해 두는 공통 준비입니다. PowerShell 여는 법, Node.js 설치, 실습 전용 폴더·계정 분리까지 다룹니다.

법률 업무 예시: 파이(Pi)에게 "이 폴더의 계약서 초안 3건에서 손해배상 조항만 뽑아 표로 정리해 줘"라고 시키려면, 파이를 실행할 토대(Node.js)와 자료를 둘 안전한 폴더가 먼저 있어야 합니다. 그 토대를 만드는 문서입니다.

이 문서를 끝내면 다른 설치가이드의 "설치 전 확인"은 모두 통과한 상태가 됩니다.

2. 설치 전 확인

보안 원칙 (이 문서 전체에 적용)

1. 실제 사건 자료를 실습 폴더에 넣지 않습니다. 실습은 가상 정보로만 합니다.
2. API 키는 받은 화면에서 바로 입력하고, 문서·메신저·메일에 붙여넣지 않습니다. 보관 위치(예: "회사 비밀번호 관리자")만 기록합니다.
3. 회사 보안 프로그램(백신·DLP·EDR)이 설치를 막으면 끄지 말고 담당자에게 문의합니다.

3. 설치 절차

① PowerShell 여는 법 (모든 가이드의 출발점)

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

PowerShell

이 PS C:\Users\본인이름> 을 프롬프트라고 부릅니다. 뒤에 명령을 붙여넣고 Enter를 누르는 것이 전부입니다.

복사·붙여넣기 하는 법 (앞으로 계속 씁니다)
회색 블록의 명령을 마우스로 긁어 Ctrl+C → PowerShell 창을 클릭 → Ctrl+V → Enter.
붙지 않으면 마우스 오른쪽 버튼 한 번을 누르세요(옛 방식 창에서는 우클릭이 붙여넣기). 블록 안에 PS C:\...> 표시가 보이면 그 부분은 복사하지 않습니다.

② Windows 버전 확인

아래를 붙여넣고 Enter.

winver

③ Node.js LTS 설치

Node.js는 파이·Codex CLI 같은 터미널 AI 도구가 돌아가는 엔진입니다. 반드시 LTS(장기 지원) 를 설치합니다.

1) 브라우저 주소창에 아래를 붙여넣고 Enter.

https://nodejs.org

2) 큰 다운로드 버튼 중 LTS 라고 적힌 쪽을 누릅니다.

3) 받은 .msi 파일을 더블클릭하고, 설치 마법사를 아래 표대로 넘깁니다.

4) 가장 중요한 단계 — PowerShell 창을 완전히 닫고(오른쪽 위 X) ①번 방법으로 새로 엽니다.

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

④ Git for Windows 설치

1) 브라우저 주소창에 아래를 붙여넣고 Enter.

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

2) 받은 .exe 를 더블클릭 → "허용하시겠어요?" [예] → 모든 화면에서 기본값 그대로 [Next] → [Install] → [Finish].

마지막 화면의 View Release Notes / Launch Git Bash 체크는 해제해도 됩니다.

3) 여기서도 PowerShell 창을 닫고 새로 엽니다.

Git이 왜 필요한가: 버전 관리 도구이지만, 이 교육에서 필요한 진짜 이유는 함께 설치되는 Git Bash(bash 셸) 입니다. 파이(Pi)는 Windows에서 명령을 실행할 때 bash 셸을 필요로 하며, 공식 문서가 "대부분의 사용자에게는 Git for Windows로 충분하다"고 안내합니다. 파이를 쓸 계획이면 필수입니다.

⑤ 실습 폴더 만들기

실제 사건 폴더와 물리적으로 분리된 실습 전용 폴더를 만듭니다.

mkdir "$env:USERPROFILE\Desktop\AX실습"

    디렉터리: C:\Users\본인이름\Desktop

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----      2026-08-01   오후 2:10                AX실습

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

cd "$env:USERPROFILE\Desktop\AX실습"

실습 자료 규칙: 이 폴더에는 가상 사건 자료만 넣습니다. 실제 의뢰인 이름·주민등록번호·사건번호가 담긴 파일은 절대 복사해 오지 않습니다. AI 도구는 이 폴더의 파일을 읽을 수 있습니다.

⑥ 수업용 개인 구글 계정 만들기 (실습 계정 분리)

1) 브라우저 시크릿 창(Ctrl+Shift+N)을 열고 주소창에 아래를 붙여넣습니다.

https://accounts.google.com/signup

2) 수업용 개인 구글 계정(실습 전용)을 하나 만듭니다. 차시 교재에서 "수업용 개인 구글 계정"이라고 부르는 것이 바로 이 계정입니다. 예시 형태:

본인이니셜.ax.edu@gmail.com

3) 비밀번호는 회사 비밀번호 관리자에 저장합니다.

왜 분리하나: AI 도구 로그인 시 그 계정의 파일·메일 접근 권한을 요구하는 경우가 있습니다. 업무 계정으로 로그인하면 의뢰인 자료가 담긴 드라이브·메일함이 권한 범위에 들어갈 수 있습니다. 실습 계정에는 아무것도 없으므로 사고가 나도 피해가 없습니다.

4. 설치 확인 (30초)

한 줄씩 실행합니다.

node -v

npm -v

git --version

세 명령이 모두 버전 번호를 출력하면 공통 준비 완료입니다.

5. 초기 설정·연동

PowerShell 최소 조작 5가지

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

cd "$env:USERPROFILE\Desktop\AX실습"

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

API 키 보관 원칙 (다음 가이드부터 계속 적용)

• 키는 받은 화면에서 곧바로 터미널에 붙여넣고, 그 창을 닫습니다.
• 키를 메신저·메일·워드 문서·교육 자료 여백에 적지 않습니다. 유출 시 과금과 데이터 접근이 그대로 따라갑니다.
• 보관 위치(예: "1Password > AX교육 항목")만 메모합니다.
• 화면 공유·녹화 중에는 입력하지 않습니다. 입력해야 하면 공유를 잠시 멈춥니다.
• 실습이 끝나면 발급처에서 키를 폐기(revoke)합니다.

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

Node.js가 실제로 동작하는지 확인합니다.

node -e "console.log('준비 완료:', 2026, '년', 8, '월')"

이어서 실습 폴더에 가상 파일을 하나 만듭니다.

"가상 사건: 홍길동 vs 김철수 물품대금 청구" | Out-File -Encoding utf8 "$env:USERPROFILE\Desktop\AX실습\연습메모.txt"

7. 문제 해결

A. 'node' 용어가 ... 인식되지 않습니다

전체 문구: node : 'node' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다.

• 원인: 설치 프로그램이 명령 위치(PATH)를 등록했지만, 설치 전부터 열려 있던 창은 옛 정보를 들고 있습니다.

• 해결:

  1. PowerShell 창을 모두 닫고 새로 엽니다 → node -v 재확인.
  2. 안 되면 PC 재부팅 후 재확인.
  3. 그래도 같으면 설치 여부 확인: 설정 → 앱 → 설치된 앱 에서 Node.js 검색. 없으면 ③단계를 다시 합니다.

B. npm.ps1을 로드할 수 없습니다

전체 문구: npm : 이 시스템에서 스크립트를 실행할 수 없으므로 C:\Program Files\nodejs\npm.ps1 파일을 로드할 수 없습니다.

• 원인: PowerShell 스크립트 실행 정책이 Restricted로 잠겨 있습니다. Windows 기본 설정에서 종종 발생합니다.
• 해결: 아래로 본인 계정 범위만 완화합니다 (시스템 전체를 바꾸지 않는 안전한 범위).

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

확인 질문에 Y → Enter. 예상 결과: 메시지 없이 프롬프트 복귀, 이후 npm -v 동작.

• 회사 노트북 주의: 이 정책은 그룹 정책에 의해 재정의됩니다 또는 액세스가 거부되었습니다 로 실패하면 회사 보안 정책이 막는 것입니다. 우회하지 말고 IT 담당자에게 "PowerShell CurrentUser 실행 정책 RemoteSigned 허용"을 요청하세요.

C. npm ERR! code ETIMEDOUT / network request ... failed

• 원인: 사내 프록시·방화벽·백신이 npm 저장소를 막았거나 회선이 일시적으로 끊겼습니다.

• 해결:

  1. 브라우저에서 아래가 열리는지 확인합니다. 안 열리면 네트워크 차단입니다.

https://registry.npmjs.org

1. 사내 Wi-Fi 대신 휴대폰 테더링으로 바꿔 재시도합니다 (교육장에서 가장 빠른 방법).
2. npm 설치 명령은 여러 번 재실행해도 안전합니다. ↑ → Enter 로 재시도하세요.
3. 계속 막히면 프록시 설정이 필요합니다. IT 담당자에게 문의하고, 백신을 임의로 끄지 마세요.

D. SmartScreen: Windows의 PC 보호 — 인식할 수 없는 앱의 시작을 차단했습니다

• 원인: 내려받은 설치 파일의 평판 정보가 부족할 때 뜨는 경고입니다. 파일 손상이 아닙니다.
• 해결: 다운로드 주소가 nodejs.org 또는 git-scm.com 인지 먼저 확인하고, 맞다면 추가 정보 → 실행.
• 주소가 위 두 곳이 아니면 실행하지 마세요. 검색 결과 상단 광고 링크에서 가짜 설치 파일을 받는 사고가 실제로 발생합니다. 이 문서의 주소를 직접 붙여넣어 들어가세요.

E. AX실습 폴더를 찾지 못한다 / 한글 경로가 깨진다

• 증상: cd ...\Desktop\AX실습 이 경로를 찾을 수 없습니다 로 실패.
• 원인: 따옴표를 빼먹었거나, OneDrive 백업이 켜져 있어 바탕 화면 실제 위치가 C:\Users\이름\OneDrive\바탕 화면 으로 옮겨져 있습니다.

• 해결:

  1. 경로는 항상 큰따옴표로 감쌉니다.
  2. 진짜 바탕 화면 위치를 확인합니다.

[Environment]::GetFolderPath("Desktop")

8. 제거·되돌리기

1) 전역 설치한 AI 도구 먼저 제거 — 각 도구 가이드의 제거 절차를 먼저 수행합니다. 예: 파이

npm uninstall -g @earendil-works/pi-coding-agent

2) Node.js 제거 — 설정 → 앱 → 설치된 앱 → Node.js 검색 → ⋯ → 제거. 남은 캐시까지 지우려면:

Remove-Item -Recurse -Force "$env:APPDATA\npm", "$env:APPDATA\npm-cache" -ErrorAction SilentlyContinue

3) Git 제거 — 설정 → 앱 → 설치된 앱 → Git → 제거

4) 실습 폴더 삭제 — 바탕 화면 AX실습 을 휴지통으로 옮기고 휴지통도 비웁니다.

5) 실행 정책 되돌리기 (문제 해결 B를 실행했던 경우에만)

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Restricted

6) 권한 회수 — 실습 계정으로 로그인해 둔 서비스가 있으면 아래에서 액세스 권한을 삭제합니다.

https://myaccount.google.com/permissions

발급받은 API 키는 발급처에서 반드시 폐기(revoke) 합니다. 키는 지우기 전까지 계속 유효합니다.

다른 설치 방법

본문의 표준 경로(공식 .msi 설치)로 진행하는 것을 권장합니다. 아래는 해당되는 경우에만 보세요.

• ARM 노트북 (Surface Pro X 등): nodejs.org에서 자동 인식이 안 되면 운영체제 Windows, 형식 Installer (.msi), 아키텍처 arm64 를 직접 고릅니다. 파일명이 node-v24.18.1-arm64.msi 형태면 맞습니다.
• 이미 Node.js가 깔려 있는 경우: node -v 가 v22.19.0 이상이면 ③단계를 건너뛰어도 됩니다. 그보다 낮으면 nodejs.org에서 최신 LTS .msi 를 그대로 덮어 설치하면 갱신됩니다.
• 패키지 관리자(winget, Chocolatey): 이 교육에서는 회사 노트북 권한 문제가 잦아 검증·지원하지 않습니다. 사내 표준 배포 절차가 따로 있다면 IT 담당자의 안내를 따르세요.
• 압축본(.zip) 설치: PATH를 손으로 등록해야 해서 초보자에게 권하지 않습니다.

다음 단계

• 터미널 AI 에이전트 설치 → 파이(Pi) 설치가이드