9월22일(화)
Clode 활용법
강의 노트에 담긴 핵심 메시지는 "AI를 만능 해결사로 두고 방임하는 것이 아니라, 인간이 명확한 핸들(주도권)을 쥐고 구조와 검증 체계를 통제하는 엔지니어링 파트너로 활용하라"는 것입니다.
원칙별 심층 의미와 실무 실행 방안은?
1. 하지 말아야 할 것 (Don'ts)
① 처음부터 과도한 풀세팅·하네스 구축 지양
핵심 의미: 툴, 프레임워크, 수많은 스킬과 플러그인을 시작부터 얹으면 시스템 복잡도만 올라가고 어디서 문제가 생겼는지 추적하기 어려워집니다. 클로드 자체의 기본 성능을 파악하는 것이 우선입니다.
실행 방안:
가장 순수한 기본 클로드 환경(CLI 또는 기본 대화창)에서 작업을 시작합니다.
작업 중 동일한 실수가 3회 이상 반복되거나, 매번 손으로 반복하는 번거로운 패턴이 명확해질 때만 해당 불편을 해소할 최소한의 스킬/규칙을 하나씩 추가합니다.
② 도구에 대한 FOMO(Fear Of Missing Out) 경계
핵심 의미: 커뮤니티나 남들이 유행처럼 쓰는 워크플로우와 프롬프트 템플릿이 내 프로젝트 환경과 비즈니스 로직에 반드시 들어맞는 것은 아닙니다.
실행 방안:
최신 유행 도구를 무조건 도입하지 말고, 내 작업에서 "이 도구가 없어서 생기는 병목이 실제로 존재하는가?"를 먼저 점검합니다.
③ AI에게 운전대(핸들)를 넘기지 말 것
핵심 의미: "알아서 다 짜줘", "이 오류 알아서 해결해줘" 식의 지시는 환각(Hallucination)과 비효율적 코드 양산의 지름길입니다. 테슬라 FSD를 쓰더라도 목적지와 안전 확인은 운전자의 몫이듯, 설계와 최종 의사결정은 인간이 해야 합니다.
실행 방안:
문제 해결 방식과 기술 스택, 라이브러리는 인간이 이미 검증한 규격으로 지정해 줍니다.
큰 덩어리를 통째로 넘기지 않고, 작게 쪼갠 단위 작업(모듈, 함수, 스키마) 단위로만 명령합니다.
2. 반드시 해야 할 것 (Dos)
① 컨텍스트 다이어트 및 세션 관리
핵심 의미: 대화창에 파일, 로그, 이전 오류 메시지가 계속 누적되면 컨텍스트 창이 오염되고 집중도가 떨어져 모델 성능이 급격히 저하됩니다. 실패한 시도의 로그가 남아있으면 미래의 추론에도 나쁜 편향을 줍니다.
실행 방안:
프레시한 세션 유지: 실패하거나 막힌 태스크는 계속 붙잡고 늘어지지 말고, 실패한 메시지를 지우거나 새 세션을 열어 정제된 요구사항으로 다시 시작합니다.
⇒ 1. 터미널 기반 개발 도구(Claude Code)에서 하는 방법
문서에 언급된 claude.md 파일 규칙을 활용하는 CLI 환경(Claude Code)에서는 세션 관리를 위한 전용 명령어가 제공됩니다./clear (대화 맥락 리셋)
이전까지 터미널에서 주고받았던 대화 기록, 실패했던 에러 로그, 과도한 출력 텍스트를 메모리(컨텍스트 창)에서 완전히 비웁니다.
프로젝트 파일이나 코드 자체는 그대로 유지되면서, 클로드의 기억만 깨끗한 상태(Fresh Session)로 초기화됩니다.
/compact (컨텍스트 압축 요약)
지금까지 작업한 중요한 결정 사항이나 핵심 파일 상태만 요약해 남겨두고, 불필요한 과정 로그를 털어내어 컨텍스트 용량을 확보합니다.
새로운 태스크 시작 시 프로세스 재실행
하나의 기능(모듈) 구현이나 디버깅이 끝났거나 꼬였을 때는 세션을 질질 끌지 않고 터미널을 종료(exit)한 뒤 새로 claude를 실행하여 시작합니다.
2. 일반 Claude 웹 브라우저(claude.ai)에서 하는 방법
'Start new chat' (새 채팅 열기)
버그 해결에 2~3번 이상 실패하거나 대화가 길어져 답변 속도가 느려지면, 기존 대화창을 붙잡고 늘어지지 말고 즉시 새 창을 엽니다.
직전 턴의 '메시지 편집(Edit)' 기능 활용
클로드가 엉뚱한 답변을 냈거나 코드가 틀렸을 때, 아래에 추가 질문으로 계속 교정하려 하지 말고 내가 방금 보낸 질문의 'Edit(연필 아이콘)'을 눌러 프롬프트를 수정합니다.
이렇게 하면 실패한 답변과 에러 로그가 대화 히스토리에서 사라지므로 컨텍스트 오염을 막을 수 있습니다.
스냅샷 프롬프트로 이전 작업 계승하기
새 창을 열 때 전체 이전 대화를 다 넣지 않고, 직전 세션에서 확정된 [최종 코드 + 에러 메시지 1개 + 작업 목표]만 깔끔하게 복사해 첫 프롬프트로 전달합니다.
문서 정제: claude.md나 시스템 지침은 모든 걸 적지 않고, 반드시 지켜야 할 핵심 규칙 4~5개 위주로 간결하게 유지합니다 (지침이 너무 길면 모델이 일부를 무시함).
② 구체적인 진짜 계획(Spec-First) 수립
핵심 의미: 내가 구현하려는 서비스의 입출력 규격, 상태 코드, 종료 조건(Definition of Done)을 모른 채 코딩을 시작하면 엉뚱한 결과가 나옵니다. 상세한 지시와 스펙 정의가 곧 AI 협업의 본질입니다.
실행 방안:
로직 구현에 들어가기 전, DB 스키마(DDL), Pydantic/인터페이스 스키마, API 엔드포인트 명세를 먼저 작성하게 하고 인간이 승인(Sign-off)합니다.
Pydantic은?: Python의 타입 힌트(Type Hints) 문법을 바탕으로 런타임에서 데이터의 타입 검증(Validation), 기본값 처리, 직렬화(Serialization/JSON 변환)를 강제하는 라이브러리
"코드를 바로 짜지 말고, 요구사항에 대한 구현 계획과 파일 구조부터 출력해"라고 먼저 제약합니다.
③ 검증 체계 구축 (피드백 루프)
핵심 의미: 클로드가 짠 코드가 맞는지 스스로 검증할 수 있는 '시험지'를 사람이 쥐어주어야 합니다. 검증 수단이 없으면 AI의 "잘 동작합니다"라는 말에 속게 됩니다.
실행 방안:
코드 작성 지시 시 테스트 코드(pytest, 단위 테스트)를 항상 함께 작성하도록 강제합니다.
pytest란 무엇인가? Python 표준 라이브러리(unittest)보다 훨씬 간결한 문법을 제공하는 테스트 도구입니다.
복잡한 클래스 구조나 보일러플레이트 코드 없이, 일반 함수 이름 앞에 test만 붙이고 Python 기본 문법인 assert 키워드만으로 검증할 수 있습니다.
터미널에서 pytest 명령어 한 줄만 치면 프로젝트 내의 모든 test*.py 파일을 자동으로 탐색해 통과(PASSED) 또는 실패(FAILED)를 명확하게 보여줍니다.
터미널 실행 결과와 테스트 통과 로그를 직접 눈으로 확인한 뒤 다음 단계로 넘어갑니다.
④ 비판적 사고 및 레드팀(Red Teaming) 관점 질의
핵심 의미: AI는 기본적으로 사용자의 제안에 순응하려는 성향(Sycophancy)이 강합니다. 무조건적인 긍정 답변을 차단하고 빈틈을 찾아내도록 역할을 부여해야 합니다.
실행 방안:
예시 프롬프트 전환:
❌ "유튜브 링크로 일주일치 인스타 글 써주는 서비스 월 9,900원에 만들려는데 어때?"
"내가 이 서비스에 네 돈을 투자한다고 했을 때, 절대 손해보지 않도록 결함, 한계점, 비용 구조, API 단가 문제를 철저하게 비판적으로 분석해줘."
VS Code 환경에서 클로드(Claude)를 연동해 바이브 코딩을 진행할 때 반드시 챙겨야 할 보안, 세션 관리, 비용 및 파일 무결성 주의 사항입니다.
- 세션 관리 및 로그아웃 관련 주의 사항
공용 PC 또는 회사 공용 장비 사용 시 세션 해제 필수
브라우저 웹(claude.ai)뿐만 아니라, VS Code 내장 터미널이나 확장에 저장된 인증 정보도 남아 있습니다.
Claude Code CLI를 사용했다면 터미널에서 아래 명령어로 명시적 로그아웃을 수행해야 토큰이 로컬에 남지 않습니다:
Bash
claude /logout
Roo Code / Cline 확장을 썼다면 설정 화면에서 등록된 API Key 문자열을 삭제하거나, 공용 PC일 경우 VS Code 자체 계정 동기화(Settings Sync)를 로그아웃해야 합니다.
다른 기기 동시 접속 및 세션 만료
Claude Pro 웹 세션 기반으로 연동된 도구는 다른 브라우저에서 새로 로그인하거나 세션이 만료되면 VS Code 내에서 401 Unauthorized 또는 Token Expired 오류를 뿜으며 멈춥니다. 이 경우 재인증(로그인)을 거쳐야 합니다.
- 보안 및 기밀 유출 방지 (가장 중요)
.env 및 API 키, DB 비밀번호 노출 차단
에이전트 확장(Claude Code, Roo Code 등)은 프로젝트 내의 파일들을 자율적으로 읽습니다.
만약 루트 폴더의 .env 파일에 발급받은 Gemini API 키, DB 접속 암호 등이 적혀 있다면, 프롬프트 컨텍스트에 그대로 포함되어 Anthropic 서버로 전송됩니다.
대응책: 프로젝트 루트에 .gitignore뿐만 아니라 .clauderules 또는 에이전트 무시 파일(.cursorignore, .rooignore)을 만들고 아래 항목을 등록해 에이전트가 열람하지 못하도록 차단해야 합니다.
Plaintext
.env
.pem
.key
qdrant_storage/
audit_log.db
data/
사내 원본 문서(data/) 직접 전달 주의
현재 구축 중인 하이브리드 RAG는 사내 문서를 로컬에 두고 상위 청크만 격리 전송하는 구조입니다.
하지만 VS Code 내에서 Claude에게 "data 폴더에 있는 사내 규정 PDF 읽고 요약해줘"라고 지시하면, RAG 인프라를 우회하여 원본 파일 전체가 Claude 서버로 업로드되므로 주의해야 합니다.
- 파일 덮어쓰기(Overwrite) 및 무결성 훼손 주의
자동 승인(Auto-approve) 모드 남용 금지
Roo Code나 Claude Code에는 터미널 명령어나 파일 저장을 사용자 확인 없이 즉시 실행하는 Auto-approve / Bypass Permissions 옵션이 있습니다.
이를 켜두면 프롬프트 오해로 인해 멀쩡히 동작하던 build_index.py나 app.py의 핵심 코드를 통째로 날리거나 지워버리는 사고가 발생할 수 있습니다.
원칙: 파일 생성/수정 Diff(변경점) 창을 눈으로 확인하고 승인(Approve)을 누르는 습관이 안전합니다.
Git 커밋을 작업 단위마다 생성
바이브 코딩을 시작하기 전, 반드시 현재 정상 동작하는 상태를 Git에 커밋(git commit -m "stable v2")해 두어야 Claude가 코드를 꼬아놓았을 때 즉시 롤백(git restore .)할 수 있습니다.
- 사용량(Rate Limit) 및 비용 폭탄 방지
5시간 쿨타임(Rate Limit) 체감 관리 (Pro 구독자)
긴 코드 파일(수백 줄 이상)을 통째로 몇 번 주고받으면 5시간 대화 한도가 급격히 소모됩니다.
"이 파일 전체 수정해줘" 대신 "app.py의 mask_pii() 함수 부분만 이렇게 고쳐줘"처럼 수정이 필요한 블록 단위로 좁혀서 요청해야 사용 가능 시간을 오래 유지할 수 있습니다.
지출 상한선(Spend Limit) 설정 (종량제 사용자)
API 키를 쓸 경우, Anthropic 콘솔(Settings -> Limits)에서 월간 한도(예: $20~$30)를 반드시 걸어두어 예기치 않은 반복 루프로 인한 과금을 방어해야 합니다.
VS Code에서 클로드(Claude)를 연동하여 바이브 코딩(자연어 기반 자동 코드 생성/수정/실행)을 수행하는 가장 표준적인 방법은 Claude Code(공식 CLI/터미널 에이전트) 또는 Roo Code / Cline(VS Code 마켓플레이스 확장 프로그램)을 사용하는 것입니다.
두 방식 중 가장 즉각적이고 완성도가 높은 Cline(또는 Roo Code) 확장 프로그램 방식과 Claude Code(공식 CLI) 방식을 종합한 실전 매뉴얼입니다.
VS Code 기반 Claude 바이브 코딩 환경 구축 및 활용 매뉴얼
-
사전 준비 (Anthropic API Key 발급)
Anthropic Console에 로그인합니다.
좌측 메뉴의 API Keys로 이동하여 Create Key를 클릭합니다.
생성된 키(sk-ant-api03-...)를 복사해 안전한 메모장에 임시 보관합니다. -
연동 방식 선택 및 설치
방식 A. VS Code GUI 확장 프로그램 (가장 추천: Roo Code 또는 Cline)
VS Code 내부에서 대화창을 띄워놓고 프로젝트 내 파일 생성, 코드 수정, 터미널 실행을 Claude에게 자율적으로 위임할 수 있는 Agent 도구입니다.
VS Code 실행 후 좌측 사이드바의 확장(Extensions) 아이콘(단축키 Ctrl + Shift + X)을 클릭합니다.
검색창에 Roo Code (또는 Cline)를 검색하여 [설치(Install)]를 클릭합니다.
설치 완료 후 좌측 사이드바에 생성된 로봇/새 모양 아이콘을 클릭합니다.
설정 화면(톱니바퀴 아이콘)에서 다음 항목을 지정합니다:
API Provider: Anthropic 선택
Anthropic API Key: 1단계에서 발급받은 API 키 입력
Model: claude-3-5-sonnet-20241022 선택
상단 모드를 Code 또는 Architect로 설정합니다.
방식 B. Claude Code (Anthropic 공식 CLI 도구)
VS Code의 내장 터미널에서 대화형 에이전트로 동작하며, 전체 프로젝트 구조를 분석하고 명령어를 직접 실행하는 방식입니다.
Node.js 설치: 시스템에 Node.js(v18 이상)가 설치되어 있는지 확인합니다.
VS Code 내장 터미널 열기 (Ctrl + ~ 또는 상단 메뉴 터미널 -> 새 터미널).
터미널에 다음 명령어를 입력하여 전역 설치합니다:
DOS
npm install -g @anthropic-ai/claude-code
프로젝트 디렉터리(D:\AI-RAG)로 이동한 후 Claude Code를 실행합니다:
DOS
cd /d D:\AI-RAG
claude
최초 실행 시 브라우저 인증 또는 API 키 입력을 완료하면 대화형 세션이 시작됩니다.
- 사내 KMS 구축을 위한 프로젝트 룰 주입 (.clinerules)
바이브 코딩 시 Claude가 기존 구축 매뉴얼(RTX 3070 8GB, 로컬 Qdrant, HuggingFace 임베딩 등)의 제약 사항을 벗어나지 않도록 프로젝트 루트 디렉터리에 지침 파일을 배치합니다.
VS Code 탐색기에서 D:\AI-RAG 폴더를 엽니다.
최상단에 .clinerules (Claude Code CLI 사용 시 CLAUDE.md) 파일을 생성하고 아래 내용을 입력합니다:
Markdown
사내 KMS RAG 개발 원칙 및 제약 조건
1. 하드웨어 및 인프라 사양
- OS: Windows 11, 단일 GPU: NVIDIA RTX 3070 (8GB VRAM)
- 벡터 DB: Docker Qdrant (포트 6333, 6334)
- 로컬 임베딩: Qwen/Qwen3-Embedding-0.6B (HuggingFace, device="cuda")
- 추론 엔진: Anthropic API (claude-3-5-sonnet-20241022)
- 웹 프레임워크: Streamlit
2. 핵심 구현 규칙
- VRAM 누수 방지: Streamlit에서 임베딩 모델과 Qdrant 리트리버는 반드시
@st.cache_resource싱글톤으로 유지할 것. - 보안 원칙: 외부 Claude API에는 코사인 유사도 상위 3개 청크(
similarity_top_k=3)만 전송할 것. - 환각 차단:
temperature=0.2로 고정하고, 제공된 컨텍스트 외의 내용은 "제공된 사내 문서에서 관련 내용을 확인할 수 없습니다"로 답변하도록 시스템 프롬프트를 강제할 것. - 출처 표시: 답변 하단에
st.expander를 통해 파일명과 페이지 라벨을 반드시 명시할 것.
- 실전 바이브 코딩 워크플로우
이제 코드를 직접 타이핑하지 않고, VS Code 내 Claude 확장 패널(또는 터미널)에 자연어로 작업을 지시합니다.
[지시 입력 (자연어)]
↓
[Claude의 변경 제안 검토 (Diff View)]
↓
[승인 (Accept) 버튼 클릭]
↓
[터미널 실행 및 에러 발생 시 로그 복사 전송]
Step 1. 인프라 및 환경 스크립트 작성 지시
입력 프롬프트:
"현재 작업 디렉터리에 Docker Qdrant 컨테이너 구동, data 폴더 생성, 파이썬 가상환경 생성 및 필수 라이브러리(streamlit, llama-index, anthropic, qdrant-client 등)를 설치하는 Windows용 setup.bat 파일을 작성하고 직접 실행해 줘."
Claude가 setup.bat을 생성하고 터미널 실행 승인을 요청하면 [Approve / Run]을 클릭합니다.
Step 2. 색인 파이프라인(build_index.py) 구현 지시
입력 프롬프트:
"./data 폴더의 문서를 청킹(512토큰, 중첩 50)하고, Qwen3-Embedding-0.6B로 CUDA 가속 임베딩하여 Qdrant의 company_docs 컬렉션에 적재하는 build_index.py를 작성해 줘."
파일 생성 diff를 확인한 뒤 [Save/Accept]를 누릅니다.
Step 3. Streamlit 대화형 UI(app.py) 구현 지시
입력 프롬프트:
".clinerules 규칙을 준수하여 Streamlit 기반 웹 인터페이스 app.py를 작성해 줘. 사이드바에 파일 업로더와 인덱싱 버튼을 두고, 메인 화면에는 카카오톡 형태의 멀티턴 채팅 UI와 출처 접이식(expander) 기능을 포함해야 해."
Step 4. 에러 발생 시 디버깅 지시
Streamlit 실행 도중 터미널에 오류가 발생하면 코드를 고치려 하지 말고, 터미널 로그를 그대로 Claude 대화창에 붙여넣습니다.
입력 프롬프트 예시:
"아래 에러가 발생했어. 원인을 파악해서 코드를 수정해 줘.
ModuleNotFoundError: No module named 'anthropic'"
- 자주 쓰는 단축키 및 작업 팁
인라인 코드 제안/질의: 에디터 내에서 코드를 드래그한 후 우클릭하여 Ask Cline 또는 Add to Context를 누르면 해당 코드 블록만 지정하여 리팩토링이나 기능 추가를 요청할 수 있습니다.
터미널 자동 실행 제어: 위험한 명령어(삭제 등)가 있을 수 있으므로 초기 설정 시 Always approve commands 옵션은 끄고, Claude가 실행하려는 명령어를 한 번씩 확인 후 승인하는 것이 안전합니다.
현재 환경에서 구글 드라이브 신규 문서 자동 생성 권한이 비활성화(Disabled)되어 있어, 외부 툴을 통한 새 Google Docs 파일 생성이 제한되었습니다.
따라서 원본 사내KMS 개발 구축 매뉴얼의 체계를 그대로 계승하면서, 지적된 5대 설계 결함(RBAC 권한 통제, GPU 동시성 락, 개인정보 비식별화, 감사 로그 DB, 문서 수명 주기 관리)을 완벽히 보완한 사내KMS 개발 구축 매뉴얼 V2 전체 최종본을 아래에 작성해 드립니다.
문서에 그대로 복사하여 새 문서로 저장하거나 기존 매뉴얼에 반영하여 활용하실 수 있습니다.
