AI 코딩 환경 설정 가이드: API 키부터 로컬 LLM까지 완벽 구축

AI 코딩을 처음 시작했을 때, 나는 API 키를 어디에 넣어야 하는지조차 몰랐다. 온라인 가이드를 그대로 따라 했는데 .env 파일을 만들지 않았고, 터미널에서는 ollama가 명령어로 인식되지 않았다. 배경지식이 없는 상태에서 에러 화면만 붙들고 이틀을 그냥 보내고 말았다.

도움말과 개발 블로그, 커뮤니티 덧글을 뒤적이며 API 키 발급부터 클라우드 LLM 연결, 노트북에서 직접 돌아가는 로컬 모델까지 하나씩 환경을 작동시켰다. 이 글은 그 과정을 남긴 기록이며, 실제로 막혔던 지점도 같이 적어 두었다.

AI 코딩, 왜 지금 시작해야 할까요?

막상 시도해 보니 문법을 먼저 외워야 하는 시대가 아니라, 요구사항을 정확히 설명할 수 있는 사람이 유리한 상황이 되어 있었다. 내 경우로는 매주 반복하는 엑셀 정리 업무가 있었다. "키워드를 뽑아서 그래프를 그리는 파이썬 스크립트를 작성해줘" 한 줄 프롬프트였는데, 몇 초 만에 동작하는 코드가 나왔다. 변수 정도만 고쳐 반복 업무에 그대로 썼다. 몇 시간 걸리던 일이 몇 분으로 줄었다.

물론 전부가 순조로웠던 것은 아니다. 이후에 만난 에러 대부분은 코드 그 자체가 아니라 ImportError나 모듈 경로 같은, 문법적으로는 드러나지 않는 쪽에서 나왔다. 문법을 몰라도 되지만 "실행 환경을 갖추는 데 하루가 걸리는" 현실은 그대로다. 이 글의 구성도 그 현실을 기준으로 삼았다.

핵심 준비물: API 키 발급과 클라우드 LLM 연결

첫 단계는 강력한 LLM에 접근하는 일이다. 흔히 쓰는 방식은 OpenAI의 GPT-5나 Anthropic의 Claude 4를 API로 호출하는 것이다. 키를 발급받은 뒤, 개발 환경에서 그 모델들의 기능을 호출해 쓰게 된다. 두 모델을 준비하는 과정부터 정리한다.

1. GPT-5 API 키 발급

GPT-5는 코드 생성과 디버깅에서 결과가 비교적 잘 나오는 편이라 가장 먼저 다루었다.

1. OpenAI 플랫폼 가입: platform.openai.com에 접속해 계정을 만든다.
2. API Keys 이동: 로그인 후 왼쪽 메뉴에서 'API keys'를 찾는다.
3. Secret Key 생성: 'Create new secret key'로 키를 만들고 용도를 알아볼 수 있는 이름을 붙인다.
4. 복사 후 보관: 키는 생성할 때 한 번만 표시된다. 외부에 노출되지 않게 바로 옮겨 두고, 필요하면 다시 만들면 된다.

2. Claude 4 API 키 발급

Claude 4는 장문 코드베이스나 긴 문서를 다룰 때 강점을 보여서 함께 사용하기로 했다.

1. Anthropic 개발자 콘솔 접속: console.anthropic.com에 들어가 계정을 만든다.
2. API Keys 섹션 이동: 대시보드에서 'API Keys' 항목을 찾는다.
3. 키 생성: 'Create API Key'를 눌러 키를 만든다.
4. 복사 후 보관: 키는 다시 볼 수 없으니 그 순간 안전한 곳에 옮겨 둔다.

3. API 키 관리의 중요성

발급받은 키는 계정으로 LLM을 부를 수 있는 열쇠라서, 유출되면 몰래 사용돼 과금이 붙을 수 있다. 이 설정에서 가장 흔한 실수가 .gitignore에 .env를 안 넣는 일이다. 커밋 전에 두 번은 확인하는 습관을 들여 두는 게 좋다.

• 환경 변수 사용: 키를 코드에 하드코딩하지 않고 운영체제의 환경 변수로 관리하는 게 가장 안전하다.
• .env 파일 활용: 프로젝트 내 .env에 모아 두고, Git에 올라가지 않도록 .gitignore에 꼭 추가한다.
• 접근 권한 최소화: 팀 프로젝트라면 열람 권한을 좁혀 두고 키를 주기적으로 교체해 주는 편이 속이 편하다.

로컬 AI 코딩 환경 구축: Ollama와 온디바이스 LLM

클라우드 LLM은 강력하지만 인터넷이 있어야 하고, 쓰면 쓸수록 비용이 쌓인다. 로컬 LLM은 컴퓨터 안에서 스스로 실행되는 모델이라 인터넷 없이도 쓰고, 데이터가 밖으로 나가지 않는다. 이런 로컬 모델들을 쉽게 관리하는 도구가 Ollama다.

1. Ollama 설치 가이드 (Windows/Mac)

1. 공식 웹사이트 방문: ollama.com에 접속한다.
2. 운영체제에 맞는 설치 파일 다운로드: Windows나 macOS용 파일을 받는다.
3. 설치 진행: 실행 후 '다음'을 몇 번 누르면 끝난다. 항목을 건드릴 필요는 없었다.
4. 설치 확인: 터미널(명령 프롬프트 또는 PowerShell)에서 ollama --version을 입력해 버전이 표시되는 걸 확인한다.

2. CodeLlama3, DeepSeek-Coder-V2 모델 다운로드 및 실행

코딩에 맞춘 모델을 받아서 바로 사용할 수 있다.

1. 모델 다운로드: 터미널에서 아래 명령어를 입력하면 다운로드가 시작된다.
   • CodeLlama3: ollama pull codellama3
   • DeepSeek-Coder-V2: ollama pull deepseek-coder-v2 모델 크기가 커서 네트워크 상태에 따라 몇 분에서 더 오래 걸린다.
2. 모델 실행: 다운로드가 끝나면 ollama run codellama3 또는 ollama run deepseek-coder-v2로 채팅을 시작한다. 터미널에서 바로 코드 질문이나 스니펫 요청이 가능하다. "파이썬으로 피보나치 수열을 계산하는 함수를 작성해줘" 입력하면 모델이 코드를 돌려준다.

3. 로컬 LLM의 장점과 한계

표의 한계가 실제로는 더 절실하게 느껴졌다. 내 노트북은 별도 그래픽 카드 없이 RAM 16GB 수준이다. 코드 전문 모델은 몇 GB 단위라 다운로드에도 시간이 걸렸고, 대화 한 줄이 돌아오는 데도 오래 걸렸다. 답변의 완성도도 GPT나 Claude에 견주면 한 단계 정도 아래라, 규모가 큰 프로젝트를 맡기면 답답하다. "설치하면 웬만한 건 문제없다"는 문구는 실제로는 과장이었다.

그래서 실용적으로는, 프라이버시가 중요한 작업이나 인터넷이 없는 환경에서는 로컬을, 복잡한 개발은 클라우드 LLM과 병행하는 구성을 하게 됐다. 둘 중 하나만 고집할 이유는 없었다.

개발 생산성을 위한 도구 설치

코드 생산성이 올라가면서 필요해지는 도구들이 있다. AI가 만든 코드를 실행, 관리, 추적하게 도와주는 것들이다.

1. VS Code 설치 및 필수 확장

Visual Studio Code(VS Code)는 가볍고 확장 생태계가 풍부해서 많이 쓰는 편집기다.

1. 다운로드: code.visualstudio.com에 접속해 운영체제에 맞는 버전을 받아 설치한다.
2. 필수 확장 설치: 왼쪽 사이드바의 확장 아이콘(네모 겹침 모양) 클릭으로 원하는 확장을 검색해 설치한다.
   • Python: 파이썬 개발의 기본적인 확장.
   • Jupyter: 데이터, 머신러닝 작업용 노트북 환경.
   • GitHub Copilot (또는 Codeium, Tabnine): AI 코드 자동 완성 도구. 하나를 골라 키나 계정을 연결한다.
   • Prettier: 저장 시 코드 형식을 자동으로 정돈해 준다.
   • GitLens: 변경 이력을 라인 단위로 보여줘서 어느 시점에 무슨 코드가 바뀌었는지 추적하기 편하다.

2. 터미널 도구 설치

명령어 기반으로 Git과 빌드를 다루려면 터미널이 필요하다.

• Windows: Git과 함께 제공되는 Git Bash와, 여러 셸을 한 창에서 관리하는 Windows Terminal을 쓰고 있다. Windows Terminal은 Microsoft Store에서 받을 수 있다.
• macOS: 내장 터미널만으로 충분하다. 탭이나 분할 화면이 필요하면 iterm2.com의 iTerm2가 편하다.

이 정도를 깔아 두면 AI 생성 코드를 실행하고 Git으로 이력을 관리하며 프로젝트를 쌓아갈 준비가 갖춰진다.

첫 AI 코딩 프로젝트 시작하기

준비가 끝났다. 실제 코드를 만들어보는 단계를 남겼다.

1. 프로젝트 폴더 생성

원하는 위치에 my-ai-project 같은 이름으로 폴더를 만든다. VS Code를 열고 '파일(File)' > '폴더 열기(Open Folder)'로 그 폴더를 연다.

2. 간단한 Python 스크립트 예시와 AI 활용

1. 새 파일 생성: 탐색기에서 폴더를 우클릭하고 '새 파일(New File)'로 main.py를 만든다.

2. AI에게 코드 요청: main.py에 다음 주석을 작성한 뒤 Copilot 같은 확장의 제안을 기다리거나, LLM에 프롬프트를 직접 입력한다.

   # 목표: 사용자로부터 이름을 입력받아 환영 메시지를 출력하는 함수를 작성해줘.
   # 함수 이름: greet_user
   # 매개변수: name (문자열)
   # 반환값: "안녕하세요, [이름]님!" 형식의 문자열
   

   프롬프트 예시 (LLM에 직접 입력 시): "파이썬으로 greet_user라는 함수를 작성해줘. 이 함수는 name이라는 문자열 매개변수를 받고, '안녕하세요, [이름]님!' 형식의 환영 메시지를 반환해야 해."

3. AI 코드 활용: 예시로 이런 코드가 나왔다. 필요에 따라 어떻게 수정하느냐는 내용을 확인 후 넘어가면 된다.

   def greet_user(name: str) -> str:
       """
       사용자로부터 이름을 입력받아 환영 메시지를 출력하는 함수
   
       Args:
           name (str): 사용자의 이름
   
       Returns:
           str: "안녕하세요, [이름]님!" 형식의 환영 메시지
       """
       return f"안녕하세요, {name}님!"
   
   if __name__ == "__main__":
       user_name = input("이름을 입력해주세요: ")
       print(greet_user(user_name))
   

4. 코드 실행: VS Code 상단 '터미널(Terminal)' > '새 터미널(New Terminal)'을 연 뒤 아래 명령을 실행한다.

   python main.py
   

   "이름을 입력해주세요: " 문구가 뜨면 이름을 입력하고 Enter를 누른다. 환영 메시지가 정상적으로 출력되는 걸 확인할 수 있었다.

이런 작은 프로젝트를 수번 하다 보니 깨달은 게 하나 있다. API 연동이 된다고 해서 도구가 환경을 완전히 대신 준비하는 것은 아니라는 점이다. 프록시 환경이나 권한 설정 때문에 연동 자체가 막히는 경우는 이후에도 어렵지 않게 만날 수 있고, 그때는 npm이나 pip 같은 패키지 매니저의 기본 원리, 환경 변수가 어디서 읽히는지 정도만 알아도 디버깅 속도가 크게 달라졌다. 그 지식이 없으면 AI는 그저 화면을 더 보여줄 뿐이다.

결론

전체 환경을 갖추는 데는 며칠이 걸리지 않았다. 초반의 이틀 동안은 API 연결과 경로 설정에서 막히는데 보냈지만, 한 번 구조를 익히고 나니 두 번째 프로젝트부터는 속도가 확연히 달라졌다.

AI 코딩은 개발 경험이 없는 사람에게도 일부 문을 열어준다. 다만 자연어 프롬프트를 잘 쓰는 것만으로는 부족하다는 것도 같이 느꼈다. 결국은 실행 환경이 어디서 어떻게 돌아가는지 정도를 직접 제어할 수 있느냐가 실제 문제였고, 어떤 도구를 쓰든 흔들리지 않는 준비는 그 기본기였다.

환경 구축 자체가 목표는 아니다. 오류가 났을 때 어느 부분을 봐야 하는지가 좀 더 명확해지고 나니, 다음에 나올 어떤 도구를 만나도 이전만큼 헤매지는 않게 되었다.

---

지금 바로 해보면 되는 3가지

1. GPT-5 또는 Claude 4 API 키 발급: 플랫폼에 가입하고 키를 만들되, 환경 변수나 .env로 관리한다.
2. Ollama 설치 및 로컬 LLM 실행: 설치 후 codellama3 또는 deepseek-coder-v2를 받아 터미널에서 대화해 본다.
3. VS Code로 첫 파일 만들기: AI 확장과 파이썬 확장을 설치하고 main.py를 실행해 본다.

---

📚 참고 문헌 및 공식 레퍼런스 (References)

• Ollama Project Documentation, 『Local Model Serving & Quantization Architecture』
• Docker Official Guide, 『Containerized Development Environments for AI Workflows』

---

🔮 관련 인사이트 & 추천 가이드

• AI와 10분 만에 개인 홈페이지 만들기: Next.js와 Claude 첫 프로젝트
• 2026년형 AI 코딩 컨텍스트 설계: 규칙 파일, MCP, 벡터DB