0 실습 환경 준비

마이크로소프트가 무료·오픈소스로 배포하는 코드 에디터. 기본은 가벼운 에디터지만 확장을 붙이면 IDE처럼 커진다. 이 챕터의 기본 작업대로, 파일 편집·통합 터미널·Git·환경변수를 한 창에서 다룬다.

💡 이후 모든 실습 코드를 여기서 열고 고치고 실행한다. 한 화면에 도구를 모아 '지금 무슨 창인지 몰라 생기는 오류'를 줄인다.

Windows용 VSCode 설치본 두 종류. System은 PC 전체(관리자권한 필요, Program Files), User는 내 계정 폴더(관리자권한 불필요, AppData)에만 설치된다.

💡 공무원 PC의 관리자권한 제한을 정면으로 넘는 첫 갈림길. 권한이 없으면 User Installer가 기본 선택이다.

VSCode에 언어지원·포매터·Git도구·AI도우미 등을 추가하는 플러그인. 유명 도구를 흉내 낸 위장 확장이 마켓플레이스에 올라오므로, 이름만 보지 말고 게시자·검증 배지·설치 수를 대조해 설치한다.

💡 게시자 대조를 건너뛰면 자격증명·코드가 탈취될 수 있다. '진짜를 가짜로, 가짜를 진짜로' 오인하지 않는 것이 확장 설치의 핵심 안전 규칙이다.

브라우저 밖에서 자바스크립트를 실행해 주는 프로그램(런타임). 코드는 '글자'일 뿐이고 런타임이 있어야 동작한다. 이 플랫폼도 npm run dev로 Node 위에서 뜬다.

💡 실습 코드를 내 PC에서 직접 돌리는 실행 엔진. Node가 없으면 npm·npx·Claude Code CLI 어느 것도 쓸 수 없다.

npm은 Node에 딸려 오는 라이브러리 설치·버전 관리자(Node를 깔면 자동으로 함께 설치됨). npx는 설치하지 않고 도구를 '한 번만' 실행하는 명령으로, npm에 동봉되어 별도 설치 대상이 아니다.

💡 남이 만든 도구를 내려받고(npm), 전역설치로 PC를 어지럽히지 않고 한 번만 실행(npx)하는 두 손잡이. 관리자권한 없는 환경에서 npx·로컬 설치가 안전한 기본값이다.

Node 여러 버전을 깔고 갈아 끼우는 버전 관리자. macOS/Linux는 nvm(nvm-sh, --lts 플래그 지원), Windows는 별개 프로그램인 nvm-windows(coreybutler)를 쓴다. 둘은 이름만 비슷할 뿐 서로 다른 프로그램이며 명령 문법도 다르다.

💡 관리자권한 없이 사용자 영역에 Node를 깔 수 있어 공무원 PC에 적합. 단 nvm-windows는 'lts' 키워드를 인자로 받지 않으므로 버전 번호를 확인해 설치해야 한다.

오래 안정적으로 유지·보수되는 릴리스 계열. 실습·업무용 기본 선택이다. 특정 숫자를 외우지 말고 'LTS 최신'을 받은 뒤 node -v로 실제 값을 확인·기록한다.

💡 버전 숫자를 문서에 못박으면 곧 낡는다. '확인·기록'으로 각자 환경의 실제 버전을 근거 삼는 습관이 이 챕터의 검증 철학이다.

package.json은 프로젝트 신분증(이름·scripts·dependencies), package-lock.json은 설치된 정확한 버전 도장, node_modules는 라이브러리 실물 폴더다. 앞 둘은 커밋하고, node_modules는 무겁고 재생성되므로 .gitignore로 제외한다.

💡 npm init으로 프로젝트를 만들고 npm install로 라이브러리를 복원하는 흐름의 뼈대. 무엇을 커밋하고 무엇을 빼는지 구분이 첫 프로젝트의 핵심.

파일 변경 이력을 스냅샷(커밋)으로 저장하고 원하는 시점으로 되돌리는 분산 버전관리 프로그램. 인터넷 없이 로컬에서도 동작한다.

💡 바이브 코딩에서 AI가 코드를 꼬아 놓아도 직전 정상 상태로 한 번에 되돌리는 안전장치. 되돌릴 수 있어야 마음 놓고 실험한다.

status로 변경 확인 → add로 커밋 대상 지정 → commit으로 스냅샷 확정 → push로 원격 업로드 → pull로 최신 내려받기 → log로 되돌릴 지점 조회. clone은 원격을 로컬로 복제한다.

💡 이 6~7개 명령이 실습에서 되돌리기·협업의 전부다. main은 안정 보관용, 실험은 작업 브랜치에서.

Git 원격 저장소를 웹에서 호스팅하는 서비스. HTTPS 인증은 gh auth login(브라우저 인증, 복붙 없음)이 1순위이며, PAT(Personal Access Token)는 대안이다. PAT는 fine-grained·최소 권한·짧은 만료를 쓰고, 발급 화면을 닫으면 값을 다시 볼 수 없다.

💡 토큰 수작업 복붙은 유출 위험이 크므로 브라우저 인증을 우선한다. 이 우선순위가 비밀 유출 차단이라는 챕터 주제와 정합한다.

터미널은 명령을 글자로 입력하고 결과를 글자로 돌려받는 창, 셸은 그 명령을 해석·실행하는 프로그램. Windows 기본 셸은 PowerShell, macOS는 zsh다. 권장 실습 표준은 OS 무관 VSCode 통합 터미널이다.

💡 node·git·code 같은 도구는 대부분 이 검은 창에서 실행된다. 읽기·이동·목록 명령은 아무것도 망가뜨리지 않고, Ctrl+C가 언제나 탈출구임을 알면 두려움이 사라진다.

경로는 파일·폴더의 주소로 절대경로(최상위부터)와 상대경로(현재 위치 기준 ./ ../)가 있고 구분자는 Windows \ vs macOS/Linux /. 최소 명령셋은 pwd(위치)·cd(이동)·ls/dir(목록)·mkdir(생성)·Ctrl+C(중단).

💡 '파일이 없다'는 오류의 대부분은 현재 위치 착각이다. 실행 전 pwd로 위치를 확인하는 습관이 오류 절반을 없앤다.

PATH는 셸이 명령(node·git·code)의 실행파일을 찾아다니는 '폴더 목록' 환경변수다. 목록에 없으면 설치했어도 command not found가 난다. Windows PATH는 절대 setx로 만지지 말고 GUI(사용자 변수 → Path → 편집 → 새로 만들기)에서 항목 추가로만 편집한다.

💡 '설치는 했는데 node를 못 찾는다'의 99%가 PATH 문제다. setx는 값 길이 1024자 제한이 있어 긴 PATH를 조용히 잘라 시스템을 망가뜨리므로 PATH 편집에 쓰면 안 된다.

입력한 명령을 셸이 못 찾았다는 오류(오타·미설치·PATH 미반영). 환경변수는 프로세스 시작 시 한 번 읽히므로, 설치가 PATH를 바꿔도 이미 열린 터미널·앱은 옛 값을 쓴다. 새 터미널 → VSCode 재시작 → 재로그인 순으로 시도한다.

💡 이 오류의 절반 이상이 '새로 안 열어서'다. 재설치보다 재시작·재로그인이 먼저다.

셸 환경변수(setx/export)는 컴퓨터 셸 전체에 적용되는 설정이고, .env.local은 프로젝트 폴더 안의 비밀·설정 파일(KEY=값)이다. 이 플랫폼은 .env.example을 .env.local로 복사해 API 키를 여기 넣고, 앱은 process.env로 읽는다.

💡 둘을 혼동하면 키를 엉뚱한 곳에 두어 유출된다. API 키는 셸이 아니라 프로젝트 파일(.env.local)에 두고 .gitignore로 커밋을 막는다.

외부 AI 서비스가 '이 요청이 누구 것인지' 인증하는 비밀 토큰. 웹사이트 비밀번호와 같아 노출되면 남이 내 계정으로 호출하고 내 앞으로 요금을 발생시킨다. 생성 순간 딱 한 번만 전체 값이 보이므로 그 자리에서 .env.local에 저장한다.

💡 실습에서 앱이 실제로 Claude를 호출하려면 키가 필요하다. 키는 서버 전용이며 브라우저·화면·채팅·스크린샷에 절대 노출하지 않는 것이 안전의 출발점이다.

Git이 추적하지 말아야 할 파일 목록. 이 플랫폼 .gitignore는 node_modules·.env·.env.local·.env*.local·data/app.db를 이미 차단한다. .env.local이 git status에 안 보이면 정상이다.

💡 키 파일이 한 번 커밋되면 이력에 영구히 남는다. 사전 차단이 유일하게 확실한 예방이며, 이미 커밋됐다면 키 재발급이 우선이다.

키가 커밋·노출됐다고 의심되면 히스토리 삭제보다 콘솔에서 키를 즉시 폐기(revoke)·재발급하는 것이 우선이다. 한 번 push된 키는 이미 노출된 것으로 간주한다.

💡 이력에서 지워도 이미 노출된 키는 안전하지 않다. 폐기·재발급만이 확실한 조치다.

대부분의 AI API는 종량제(쓴 만큼 과금)라 무한루프·과다 호출이 곧 비용이다. 콘솔에서 예산 알림·소액 한도를 켜고, 실습 입력은 실제 개인정보(PII) 대신 합성 데이터(예: 홍길동, 010-0000-0000)만 쓴다.

💡 외부 AI로 전송되는 순간 PII는 유출이다. 이 플랫폼은 전송 전 서버에서 주민번호·카드번호를 차단하지만, 근본 방어선은 애초에 진짜 정보를 넣지 않는 것이다.

실제 개인정보 대신 지어낸 가짜 예시 데이터로 실습하는 원칙. 입력이 외부 AI 서버(제3자)로 전송된다는 사실을 상시 고지하고, 전송 전 PII를 스캔·차단한다.

💡 AI 코딩 도구는 하나같이 코드·프롬프트를 외부로 전송한다. '무엇을 입력하느냐'가 '어떤 도구를 쓰느냐'보다 중요하다.

세 갈래다. 대화형 웹 AI(무설치·브라우저), 에디터 내장(Cursor·VSCode AI 확장), 터미널 CLI(Claude Code, 에이전트형). 설치 문턱과 자동화 힘이 반대로 움직인다.

💡 설치가 막히면 웹 AI/플랫폼 샌드박스, VSCode가 있으면 AI 확장(문턱 최저), 본격 자동화가 필요하면 Claude Code CLI로 고른다. Claude Code의 정확한 패키지명·명령은 Anthropic 공식 문서에서 확인한다.

이 플랫폼의 브라우저 실습 화면. 교육용 서버에 API 키가 구성돼 있을 때만 실제 AI를 호출하며, 키가 없으면 503 'AI backend not configured'를 반환한다. 사용자는 개인 키를 직접 다루지 않는다.

💡 관리자권한·프록시로 설치가 막혔지만 인터넷이 되는 경우의 실습 경로. 단 서버 키가 구성돼 있을 때만 실 호출되므로, 503이 뜨면 강사·운영자에게 문의하고 개인 키를 넣지 않는다.

완전 인터넷 차단(망분리)에서는 사전 반입된 워크북 PDF만 동작한다(사이트·웹AI·마켓플레이스 모두 불가). 제한적 교육용 인터넷망이 있으면 /playground·/tour(실 호출 없는 모의 투어)도 가능하다.

💡 aiedu 플랫폼 자체가 외부 도메인의 웹앱이라 진짜 망분리 PC에서는 접속조차 안 된다. 망분리 청사에서는 워크북 PDF 사전 반입·배포가 기본 시나리오다.

정보화·전산 담당 제출용 표에 도구명·용도·공식 배포처 URL·버전 확인법·데이터 처리 범위·오프라인 대안을 채워 승인을 요청한다. 프록시는 담당이 준 공식 값만 설정하고 임의 우회는 금지한다.

💡 공무원 PC의 설치 승인 절차를 우회하지 않고 정식으로 넘는 경로. 프록시 인증정보가 .npmrc/.gitconfig에 평문 저장될 수 있으니 이 파일을 커밋·공유하지 않는다.

관리자권한이 없어 설치·쓰기가 거부되는 증상(EACCES, '관리자 권한 필요'). 사용자 영역 설치(User Installer·winget --scope user·nvm)로 우회하고, 안 되면 승인 요청, 그래도 안 되면 무설치로 간다.

💡 공무원 PC의 관리자권한 제한을 예외가 아니라 다수 시나리오로 전제하는 3단 대안의 첫 단추.

node -v · npm -v · npx --version · git --version · code -v처럼 도구가 설치·인식됐는지 스스로 확인하는 명령. '값(버전 문자열)이 출력되면 OK'가 판정 기준이고 특정 숫자를 외우지 않는다.

💡 '된 것 같다'가 아니라 명령의 출력으로 판정한다. 이 값을 노트에 기록해 각자 환경의 실제 버전을 근거로 삼는다.

증상→원인→조치를 좁혀 해결하는 과정. command not found(PATH), 프록시·인증서 오류, 권한 거부, 버전 불일치, 확장 미표시, 포트 충돌이 대표 유형이다. 재설치는 맨 마지막이다.

💡 혼자 막혔을 때 빠져나오는 안전망. 오류는 겁줄 대상이 아니라 진단 정보이며, 대부분 표의 첫 조치로 풀린다.

오류 메시지를 그대로 복사해 검색·AI 질문하되, 키·개인정보·경로 속 사용자명 같은 민감정보는 지우고 묻는 습관. 공식 문서를 먼저 본다.

💡 오류를 질문하다 키를 노출하는 사고를 막는다. '이 오류가 뜬다:(메시지) / 환경:Windows, 관리자권한 없음, 사내 프록시'처럼 제약을 함께 주면 답이 정확해진다.