Setup 시스템: 새 컴퓨터에서 5분 안에 AI 환경 완성하기

Setup: AI 에이전트 환경을 5분 만에 완성하는 7단계 설정법

💡 /setup 한 번이면 API 키, DB 연결, Hook 파일까지 모두 자동 설정됩니다. 3-Tier 아키텍처로 비밀 정보도 안전하게 분리됩니다.

해당 Setup은 제가 컴퓨터나 다른 사람에게 저의 시스템을 빠르게 설정 시켜주기 위한 설정입니다.(참고)

문제 상황

새 프로젝트 시작할 때마다 이런 경험 있으신가요?

"API 키 어디다 넣지?", "환경 변수 설정 또 해야 하나?", "DB 연결은 어떻게 하더라?"

매번 검색하고, 복붙하고, 에러 나면 또 찾아보고... 설정에만 30분-1시간이 날아갑니다.

더 심각한 문제:

• API 키를 코드에 넣었다가 Git에 푸시 → 보안 사고
• 팀원마다 설정이 달라서 "내 컴퓨터에선 되는데?"
• 설정 파일이 여기저기 흩어져서 관리 불가

---

해결책: /setup 명령어

"한 번의 명령어로 모든 설정을 자동화"합니다.

PYTHONPATH=/Users/days/Desktop/work \\
  ./knowledge_base/venv/bin/python3 -m knowledge_base.cli setup

이 명령어 하나면:

• ✅ Python 가상환경 생성
• ✅ Docker 컨테이너 확인
• ✅ 파일 동기화
• ✅ API 키 설정 안내
• ✅ 사용자 설정 입력
• ✅ MCP 서버 연결

5분이면 끝납니다.

---

동작 방식: 3-Tier 보안 아키텍처

설정을 3계층으로 분리해서 보안과 편의성을 동시에 잡습니다.

┌─────────────────────────────────────┐
│ Tier 1: 비밀 정보 (~/.zshenv)         │
│ → API 키, 토큰 (Git과 완전 분리)        │
├─────────────────────────────────────┤
│ Tier 2: 사용자 설정 (user_settings.py) │
│ → 개인 정보, 경로 (.gitignore 등록)      │
├─────────────────────────────────────┤
│ Tier 3: 설정 허브 (config.py)         │
│ → 단일 진입점 (Single Source of Truth) │
└─────────────────────────────────────┘

왜 3계층인가?

Tier 보안 Git 예시

1	🔴 최고	❌ 제외	API 키, 토큰
2	🟡 중간	❌ 제외	이메일, 경로
3	🟢 공개	✅ 포함	DB 설정, 포트

핵심: 비밀 정보는 Git에 절대 올라가지 않습니다.

---

7단계 설정 프로세스

단계 동작 소요 시간

1	Python venv 생성	~30초
2	Docker 컨테이너 확인	~5초
3	파일 동기화	~5초
4	API 키 설정 확인	~10초
5	사용자 정보 입력	~30초
6	user_settings.py 저장	~1초
7	.mcp.json 생성	~1초

실제 실행 예시

1단계: Python 환경

🐍 Python 환경 설정 중...
✅ knowledge_base/venv 생성됨 (Python 3.10+)
✅ requirements.txt 설치 완료

2단계: Docker 확인

🐳 Docker 컨테이너 상태 확인...
✅ Milvus: Running (localhost:19530)
✅ Neo4j: Running (localhost:7687)

3단계: 파일 동기화

📂 Claude Code 설정 파일...
  ❓ CLAUDE.md 이미 존재합니다. 덮어쓸까요? (y/n): n
  ✅ .claude/hooks/*.sh 복사됨 (항상 덮어쓰기)

4단계: API 키 확인

🔑 API 키 설정 상태...
✅ ANTHROPIC_API_KEY: 설정됨
✅ GOOGLE_API_KEY: 설정됨
❌ JIRA_TOKEN: 설정 안 됨 → ~/.zshenv에 추가 필요

7단계: 완료

🎉 모든 설정이 완료되었습니다!
💡 Notion 별명 설정: services/notion/page_map.json 직접 편집
🔄 변경사항 적용: 에이전트 재시작

 

---

핵심 장점

1. Claude + Gemini 동시 지원

이전에는 LLM을 선택해야 했지만, 이제는 둘 다 자동 설정됩니다.

work/
├── CLAUDE.md      # Claude Code 규칙
├── GEMINI.md      # Gemini CLI 규칙
├── .claude/       # Claude 설정
│   ├── hooks/     # Hook 스크립트
│   └── commands/  # 커스텀 명령어
└── .gemini/       # Gemini 설정
    ├── hooks/
    └── commands/

2. 기존 설정 보호

❓ CLAUDE.md 이미 존재합니다. 덮어쓸까요? (y/n): n
ℹ️ CLAUDE.md 유지
✅ .claude/hooks/*.sh 복사됨 (항상 덮어쓰기)

파일 유형 정책 이유

CLAUDE.md / GEMINI.md	y/n 질문	사용자 커스텀 보존
Hook 파일	항상 덮어쓰기	시스템 필수 파일
Commands	항상 덮어쓰기	템플릿

→ 파일별로 선택할 수 있어서 기존 커스텀 설정이 날아가지 않습니다!

3. API 키 나중에 설정 가능

🔑 API 키 설정 상태...
❌ JIRA_TOKEN: 설정 안 됨

→ Enter로 패스하고 나중에 ~/.zshenv 직접 편집해도 됩니다.

---

기술 상세

Tier 1: ~/.zshenv (Git 외부)

# API Keys (절대 Git에 넣지 마세요!)
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AIza..."
export JIRA_TOKEN="..."
export NOTION_TOKEN="secret_..."

Tier 2: user_settings.py (상세 항목)

# 사용자 정보 (Git 제외)
USER_EMAIL = "gihyun@example.com"      # Jira 담당자 이메일
WORK_ROOT = "/Users/days/Desktop/work"  # 작업 루트 경로

# DB 설정
KNOWLEDGE_DB_NAME = "agent_brain.db"    # SQLite 파일명

# 모델 설정
GEMINI_MODEL_FLASH = "gemini-2.0-flash" # 빠른 작업용
GEMINI_MODEL_PRO = "gemini-2.5-pro"     # 복잡한 작업용
DEFAULT_MODEL_TIER = "flash"            # 기본 티어

# Vector DB 접속 정보
MILVUS_HOST = "localhost"
MILVUS_PORT = 19530

Tier 3: config.py (진입점)

# 모든 설정을 여기서 import
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")  # Tier 1
USER_EMAIL = getattr(user_settings, "USER_EMAIL", "")  # Tier 2
MILVUS_HOST = "localhost"  # Tier 3 (하드코딩)

DB 연결 정보

DB 용도 포트

SQLite	대화 기록, 요약	파일
Milvus	벡터 검색	19530
Neo4j	그래프 관계	7687

---

---

실제 사용

# Clone 후 Setup 실행 (이게 전부!)
git clone <repo-url> work && cd work
PYTHONPATH=$(pwd) ./knowledge_base/venv/bin/python3 -m knowledge_base.cli setup

5분 후 바로 사용 가능:

# Claude Code 시작
claude

# 또는 Gemini CLI
gemini

---

결론

Setup 덕분에:

• ✅ 5분 만에 전체 환경 구성 (7단계 자동화)
• ✅ 3-Tier 구조로 API 키 보안 (Git 사고 방지)
• ✅ 팀원 누구나 동일한 환경 (재현 가능)

/setup 한 번이면 AI 에이전트 개발 준비 완료입니다.