# 용어 사전

이 문서에서 사용하는 기술 용어를 쉽게 설명합니다.
처음 보는 용어가 있다면 여기서 찾아보세요.

> 각 용어는 **한 줄 정의**, **일상 비유**, **왜 필요한지** 순서로 설명됩니다.

---

## 네트워크 / 접속

### SSH (Secure Shell)

원격 컴퓨터에 암호화된 통신으로 안전하게 접속하는 방법입니다.

**비유**: 멀리 있는 컴퓨터의 키보드와 화면을 내 앞으로 가져오는 것과 같습니다. 마치 원격 데스크톱이지만, 텍스트 명령어로 조작합니다.

**왜 필요한가**: Windows에서 Mac 서버에 접속해서 코드를 실행하고, Claude Code를 사용하려면 SSH가 필요합니다. 모든 통신이 암호화되어 중간에서 누가 엿볼 수 없습니다.

---

### SSH 키 (공개키 / 비밀키)

비밀번호 대신 사용하는 디지털 열쇠 쌍입니다. 항상 두 개가 한 세트입니다.

- **비밀키** (`id_ed25519`): 내 컴퓨터에만 보관하는 열쇠. 절대 다른 사람에게 보내면 안 됩니다!
- **공개키** (`id_ed25519.pub`): 서버에 등록하는 자물쇠. 다른 사람에게 보내도 괜찮습니다.

**비유**: 비밀키는 집 열쇠, 공개키는 자물쇠입니다. 자물쇠(공개키)를 서버 문에 달아두면, 그 열쇠(비밀키)를 가진 사람만 문을 열 수 있습니다.

**왜 필요한가**: 매번 비밀번호를 입력하지 않아도 안전하게 접속할 수 있습니다. 비밀번호보다 훨씬 보안이 강하고, 자동화 도구에서도 사용할 수 있습니다.

---

### Tailscale

팀원들의 컴퓨터를 안전한 가상 네트워크로 연결하는 VPN 서비스입니다. 설치하고 로그인하면 자동으로 연결됩니다.

**비유**: 팀원들만 들어올 수 있는 비밀 터널입니다. 카페에서든 집에서든, 이 터널을 통하면 사무실 안에 있는 것처럼 Mac 서버에 접속할 수 있습니다.

**왜 필요한가**: 사무실 밖에서도, 서로 다른 네트워크에 있어도 Mac 서버에 안전하게 접속할 수 있습니다. 복잡한 네트워크 설정 없이 설치만 하면 바로 사용 가능합니다.

---

### 방화벽 (Firewall)

외부에서 컴퓨터에 무단 접속하는 것을 막는 보안 장치입니다.

**비유**: 건물 출입구의 보안 게이트입니다. 허가된 사람(트래픽)만 통과시키고, 나머지는 차단합니다.

**왜 필요한가**: Mac 서버를 외부 해킹 시도로부터 보호합니다. SSH 접속 포트만 열어두고 나머지는 차단하면 보안이 크게 강화됩니다.

---

### ACL (Access Control List)

누가 어디에 접속할 수 있는지 정하는 규칙 목록입니다.

**비유**: "1층 로비는 모든 직원 출입 가능, 서버실은 IT팀만 출입 가능"처럼 장소별 출입 규칙을 정리한 표입니다.

**왜 필요한가**: Tailscale에서 ACL을 설정하면 "개발팀만 Mac 서버에 접속 가능"처럼 세밀한 접근 제어를 할 수 있습니다.

---

## 개발 도구

### Claude Code

Anthropic이 만든 AI 코딩 도우미입니다. 터미널(명령줄)에서 실행합니다.

**비유**: 옆자리에 앉아서 함께 코딩하는 시니어 개발자입니다. 코드 작성, 버그 수정, 코드 리뷰, 테스트 작성 등을 대화하듯 요청할 수 있습니다.

**왜 필요한가**: 코드를 직접 작성하고 수정하는 것은 물론, 프로젝트 구조를 이해하고 복잡한 리팩토링까지 도와줍니다. 개발 생산성을 크게 높여줍니다.

---

### MCP 서버 (Model Context Protocol)

Claude Code에 추가 기능을 연결하는 플러그인 시스템입니다.

**비유**: 스마트폰에 앱을 설치하는 것과 같습니다. 기본 기능에 원하는 기능을 추가로 붙일 수 있습니다.

**왜 필요한가**: GitHub MCP를 연결하면 Claude가 직접 PR을 만들 수 있고, Playwright MCP를 연결하면 브라우저를 자동으로 조작할 수 있습니다. Claude의 능력을 확장합니다.

---

### VS Code (Visual Studio Code)

Microsoft가 만든 무료 코드 편집기입니다. 전 세계 개발자들이 가장 많이 사용합니다.

**비유**: 개발자용 워드 프로세서입니다. 글을 쓰는 대신 코드를 작성하는 도구이며, 다양한 확장 기능을 설치할 수 있습니다.

**왜 필요한가**: "Remote - SSH" 확장 기능을 설치하면, Windows 컴퓨터에서 Mac 서버의 코드를 마치 내 컴퓨터에 있는 것처럼 편집할 수 있습니다.

---

### Dev Container (개발 컨테이너)

동일한 개발 환경을 "상자"에 담아서 모든 팀원에게 배포하는 기능입니다.

**비유**: 밀키트(요리 키트)와 같습니다. 재료, 도구, 레시피가 모두 들어있어서 누가 열어도 같은 요리를 만들 수 있습니다.

**왜 필요한가**: "내 컴퓨터에서는 되는데, 네 컴퓨터에서는 안 돼" 문제를 해결합니다. 모든 팀원이 정확히 같은 환경에서 개발할 수 있습니다.

---

### Docker

프로그램을 격리된 환경(컨테이너)에서 실행하는 도구입니다.

**비유**: 프로그램마다 독립된 방을 만들어주는 것입니다. 각 방에는 그 프로그램에 필요한 것만 들어있어서, 다른 프로그램과 충돌하지 않습니다.

**왜 필요한가**: Dev Container가 Docker를 기반으로 동작합니다. 여러 프로젝트의 개발 환경을 서로 영향 없이 독립적으로 관리할 수 있습니다.

---

## 시스템 관리

### tmux

서버에서 프로그램을 끊기지 않게 실행하는 터미널 관리 도구입니다.

**비유**: TV를 끄지 않고 리모컨만 내려놓는 것입니다. 나중에 리모컨을 다시 들면 끄기 전 화면이 그대로 있습니다. SSH 접속을 끊어도 작업이 계속 돌아갑니다.

**왜 필요한가**: Claude Code로 긴 작업을 시키고 퇴근해도 작업이 중단되지 않습니다. 다음 날 다시 접속하면 진행 상황을 그대로 확인할 수 있습니다.

---

### Homebrew

Mac용 프로그램 설치 관리자입니다. 터미널에서 명령어 한 줄로 프로그램을 설치합니다.

**비유**: App Store의 개발 도구 전문 버전입니다. `brew install 프로그램명`만 입력하면 자동으로 다운로드, 설치, 설정까지 해줍니다.

**왜 필요한가**: Mac 서버에 필요한 개발 도구(Node.js, Git, tmux 등)를 쉽고 일관되게 설치할 수 있습니다.

---

### winget

Windows 10/11에 기본 내장된 프로그램 설치 관리자입니다.

**비유**: Mac의 Homebrew와 같은 역할을 Windows에서 합니다. PowerShell에서 `winget install 프로그램명`으로 설치합니다.

**왜 필요한가**: Windows에서 Git, VS Code 등 필요한 도구를 명령어 한 줄로 빠르게 설치할 수 있습니다.

---

### chezmoi ("셰즈모아"로 읽음)

설정 파일을 여러 컴퓨터에 동기화하는 도구입니다. 프랑스어로 "chez moi"는 "내 집"이라는 뜻입니다.

**비유**: 모든 컴퓨터의 설정을 하나의 USB에 담아서 동기화하는 것입니다. 한 곳에서 설정을 바꾸면 다른 컴퓨터에도 자동으로 적용됩니다.

**왜 필요한가**: 팀원이 여러 명이어도 동일한 Claude Code 설정, Git 설정 등을 한 번에 관리하고 배포할 수 있습니다.

---

### launchd

Mac에서 프로그램을 자동으로 시작하고 관리하는 시스템 서비스입니다.

**비유**: Windows의 "시작 프로그램"과 "서비스"를 합친 것입니다. Mac이 켜지면 자동으로 지정된 프로그램들을 실행합니다.

**왜 필요한가**: Mac 서버가 재시작되어도 Tailscale, GitHub Actions Runner 등이 자동으로 다시 실행됩니다. 관리자가 수동으로 켤 필요가 없습니다.

---

### symlink (심볼릭 링크)

파일이나 폴더의 바로가기(별명)입니다.

**비유**: 바탕화면에 만드는 바로가기 아이콘과 같은 원리입니다. 바로가기를 열면 원본 파일이 열립니다.

**왜 필요한가**: 설정 파일을 한 곳에서 관리하면서, 여러 프로그램이 각자 기대하는 위치에서 찾을 수 있도록 연결해줍니다.

---

## 보안

### Ed25519

SSH 키의 암호화 알고리즘(방식) 중 하나입니다. 현재 가장 안전하고 빠른 방식입니다.

**비유**: 자물쇠에도 종류가 있듯이(번호 자물쇠, 열쇠 자물쇠 등), SSH 키에도 종류가 있습니다. Ed25519는 가장 최신의, 가장 튼튼한 자물쇠입니다.

**왜 필요한가**: 오래된 방식(RSA 등)보다 보안이 강하고, 키 크기가 작아 성능도 좋습니다. 특별한 이유가 없다면 Ed25519를 사용하세요.

---

### authorized_keys

SSH 접속을 허가할 공개키 목록을 저장하는 파일입니다.

**비유**: 건물 로비의 "출입 허가자 명단"입니다. 이 명단에 이름(공개키)이 있으면 출입(SSH 접속)이 허용됩니다.

**왜 필요한가**: Mac 서버의 `~/.ssh/authorized_keys` 파일에 팀원들의 공개키를 등록하면, 해당 팀원들만 서버에 접속할 수 있습니다.

**위치**: Mac 서버의 `~/.ssh/authorized_keys`

---

### sudo

관리자(root) 권한으로 명령어를 실행하는 접두어입니다. 실행 시 비밀번호를 물어봅니다.

**비유**: "관리자 권한으로 실행"을 뜻합니다. Windows에서 프로그램을 우클릭해서 "관리자 권한으로 실행"하는 것과 같습니다.

**왜 필요한가**: 시스템 설정 변경, 프로그램 설치 등 중요한 작업은 일반 사용자 권한으로 할 수 없습니다. `sudo`를 붙여야 실행됩니다.

---

## CI/CD

### GitHub Actions

코드를 저장소에 올리면(Push) 자동으로 빌드, 테스트, 배포를 실행하는 자동화 시스템입니다.

**비유**: 코드를 보내면 자동으로 검사하고, 문제가 없으면 출시까지 해주는 로봇 공장 라인입니다.

**왜 필요한가**: 사람이 수동으로 "빌드 -> 테스트 -> 배포"를 반복하는 대신, 코드를 Push하면 자동으로 모든 과정이 진행됩니다. 실수를 줄이고 시간을 절약합니다.

---

### Self-hosted Runner

GitHub Actions 작업을 GitHub 클라우드가 아닌, 자체 서버(예: Mac Mini, Mac Pro 등)에서 직접 실행하는 것입니다.

**비유**: 세탁을 세탁소(GitHub 클라우드)에 맡기는 대신, 집에 세탁기(자체 서버)를 두고 직접 하는 것입니다.

**왜 필요한가**: 우리 서버에서 실행하면 더 빠르고, 추가 비용이 없으며, 내부 네트워크의 데이터베이스 등에 접근할 수 있습니다.

---

---

## Claude Forge 워크플로우

### TDD (Test-Driven Development)

시험지를 먼저 만들고, 그 다음에 답안을 작성하는 개발 방식입니다.

**비유**: 요리 전에 레시피(테스트)를 먼저 쓰고, 그에 맞춰 요리(코드)하는 것입니다.

**기술 설명**: 코드를 쓰기 전에 "이 코드가 이렇게 동작해야 한다"는 테스트를 먼저 작성합니다. 테스트가 통과할 때까지 코드를 구현하고(GREEN), 통과하면 코드를 정리합니다(IMPROVE).

**Claude Forge 용도**: `/tdd` 커맨드가 RED → GREEN → IMPROVE 사이클을 자동으로 진행합니다.

---

### 에이전트 (Agent)

특정 전문 분야를 가진 AI 팀원입니다.

**비유**: 마치 "코드 리뷰 전문가", "테스트 전문가", "보안 전문가"가 각각 따로 있는 것과 같습니다.

**기술 설명**: 역할별로 전문화된 프롬프트와 도구 세트를 가진 AI 서브프로세스입니다. 독립적인 컨텍스트에서 작업하며, 결과만 메인 에이전트에 반환합니다.

**Claude Forge 용도**: `/plan`, `/tdd`, `/code-review` 등 커맨드를 실행하면 해당 전문 에이전트(planner, tdd-guide, code-reviewer 등)가 자동으로 호출됩니다.

---

### 핸드오프 (Handoff)

"여기까지 했어요" 하고 남기는 인수인계 문서입니다.

**비유**: 야간 근무자가 퇴근하며 주간 근무자에게 "여기까지 했고, 이건 남았어"라고 메모를 남기는 것입니다.

**기술 설명**: 현재 작업 상태, 변경 내용, 남은 TODO, 검증 권장 설정을 `.claude/handoff.md`에 기록합니다.

**Claude Forge 용도**: `/handoff-verify`가 인수인계 문서 생성과 fresh-context 자동 검증을 한 번에 처리합니다.

---

### 린트 (Lint)

코드 맞춤법 검사기입니다.

**비유**: 글의 맞춤법을 자동으로 잡아주듯, 코드의 스타일 위반, 잠재적 버그, 보안 문제를 실행 전에 잡아줍니다.

**기술 설명**: 코드를 실행하지 않고 텍스트만 분석하여 문제를 찾는 정적 분석 도구입니다. ESLint, Prettier, golangci-lint 등이 대표적입니다.

**Claude Forge 용도**: `/handoff-verify`가 빌드, 테스트와 함께 린트도 자동으로 실행합니다.

---

### 파이프라인 (Pipeline)

여러 작업을 순서대로 자동 실행하는 흐름입니다.

**비유**: 공장의 생산 라인과 같습니다. 원재료(코드)가 검사 → 조립 → 포장(빌드 → 테스트 → 배포)을 자동으로 거치는 것입니다.

**기술 설명**: CI/CD 파이프라인에서 빌드, 테스트, 배포 단계가 순서대로 자동 실행됩니다.

**Claude Forge 용도**: `/auto` 커맨드가 plan → tdd → code-review → verify → commit까지의 전체 파이프라인을 한 번에 실행합니다.

---

### RED-GREEN-IMPROVE

TDD의 3단계 사이클입니다.

**비유**: (빨간불) 시험에 일부러 떨어지기 → (초록불) 최소한으로 합격하기 → (개선) 답안을 더 깔끔하게 다듬기.

**기술 설명**: RED = 실패하는 테스트 작성, GREEN = 최소한의 코드로 테스트 통과, IMPROVE = 코드 정리 및 개선(테스트는 계속 통과 유지).

**Claude Forge 용도**: `/tdd` 커맨드가 이 사이클을 자동으로 반복 실행합니다.

---

### Fresh Context (새 컨텍스트)

편향 없이 처음부터 검증하는 방식입니다.

**비유**: 자기가 쓴 글의 오타는 못 찾지만, 다른 사람이 보면 바로 찾는 것과 같습니다. 새로운 눈(AI)으로 검증합니다.

**기술 설명**: 기존 대화 맥락을 모르는 새로운 AI 서브에이전트를 생성하여, 확인 편향 없이 독립적으로 빌드/테스트/린트를 검증합니다.

**Claude Forge 용도**: `/handoff-verify`가 verify-agent를 fresh context로 생성하여 검증합니다.

---

> 이 문서에서 설명하지 않은 용어가 있다면, [GitHub Issues](https://github.com/sangrokjung/claude-forge/issues)에서 문의하세요.
