Claude AI and Code

Set up

Create CLAUDE.md. And, write down contents that ai should be aware of
- /init command 로 CLAUDE.md 파일을 생성해도 되지만, 기본적인 내용을 채워서 줌. 내 요구사황과 맞지 않음
- markdown file - it needs three headers
Create settings.json file under .claude folder - Project scope
Set up plugins

Claude AI

Project

Claude AI의 프로젝트(Projects) 기능은 특정 주제나 업무에 맞춰 대화와 문서를 한곳에 체계적으로 정리할 수 있는 전용 맞춤형 작업 공간(Workspace)입니다. 매번 새로운 대화를 시작할 때마다 배경 설명을 반복할 필요 없이, 프로젝트 내의 모든 대화가 동일한 컨텍스트(문맥)를 유지하도록 돕는 핵심 기능입니다.

프로젝트 기능의 주요 특징은 다음과 같습니다:

지식 기반(Knowledge Base) 문서 업로드: 파일당 최대 30MB로 개수 제한 없이 업로드할 수 있습니다 (업로드한 파일의 총 텍스트가 모델의 컨텍스트 윈도우인 약 200K 토큰을 초과하면 자동으로 RAG 모드로 전환됩니다). 이력서, 브랜드 스타일 가이드, 코드베이스, 회의록, PDF 문서 등을 업로드해 두면, Claude가 프로젝트 내의 모든 대화에서 이 데이터들을 기본 지식으로 참고하여 답변합니다.
맞춤형 지침(Project Instructions) 설정: Claude가 해당 프로젝트에서 어떤 역할과 어조를 취해야 하는지, 어떤 규칙을 따라야 하는지에 대한 고정 지침을 설정할 수 있습니다.
컨텍스트(Context) 연속성 유지: 프로젝트 환경 내에서는 이전에 업로드한 문서와 지침이 모든 대화에 자동으로 적용됩니다. 따라서 긴 호흡이 필요한 심층 연구, 콘텐츠 제작, 또는 코딩 작업을 할 때 일관성 있는 결과물을 얻을 수 있습니다.
팀 협업 공유 기능: 팀(Team) 및 엔터프라이즈(Enterprise) 요금제를 사용하는 기업 고객의 경우, 프로젝트 폴더를 팀원들과 공유하여 조직 전체의 ‘공동 지식 기반’을 구축하고 함께 작업할 수 있습니다.

사용 방법:

Claude 화면의 사이드바에서 Projects를 클릭합니다.
새 프로젝트를 생성하고 이름을 지정합니다.
작업에 필요한 관련 문서(노트, 기획안, 코드 등)를 업로드합니다.
Claude가 숙지해야 할 지침(Instructions)을 추가한 뒤 대화를 시작합니다.

Claude Code Overview

Claude Code를 활용해 복잡한 개발 프로젝트를 구조화하고 자동화하는 고급 기법을 다룹니다. 특히 전역 설정(Claude.md), 작업의 순서도를 부여하는 스킬(Skills), 작업을 위임하는 서브에이전트(Subagents), 그리고 외부 도구와 연동하는 MCP(Model Context Protocol)를 통해 완전한 AI 개발 파이프라인을 구축하는 방법론을 제시합니다.

URLs

Claude Code Components

1. 초기 설정 및 모드 활용 (Initialization & Modes)

프로젝트의 방향성을 설정하고 효율적인 작업 환경을 구성하는 단계입니다.

Claude.md (Global Context): 프로젝트의 가장 기본이 되는 지침서로, AI가 작업을 시작할 때 가장 먼저 읽어야 하는 전역(Global) 문서입니다.
- 활용 팁: 다른 사람들의 유스케이스(Use case)를 분석하고, 가이드 공학(Guide Engineering)을 적용하여 작성합니다. Claude-Code-best-practice Git 저장소를 참고하는 것이 좋습니다.
- 100 줄 이내로 작성 권장. 세부 내용은 하위 폴더의 Claude.md 에 작성.
작업 모드 (Modes):
- Shift + Tab: 모드 전환 및 탐색 단축키.
- Accept edit on: AI의 코드 수정을 자동으로 수락하여 편하게 사용하는 모드.
- Plan mode: 코드를 즉시 작성하기 전, 기획 글이나 아키텍처를 먼저 구조화할 때 사용합니다.

2. 사용자 정의 자동화 (Orchestration Workflow)

반복되는 작업을 자동화하고 자신만의 작업 흐름을 생성하는 단계입니다.

[!NOTE] Pattern Command → Agent (with skill) → Skill

세 개념은 “누가 실행하고, AI 추론이 개입하며, 컨텍스트를 어떻게 사용하는지”에 따라 명확히 구분됩니다.

구분	Commands	Skills	Subagents
개념	CLI 시스템 제어 도구	특정 업무를 위한 AI 지침서 (워크플로우)	독립적으로 일하는 하위 AI 작업자
AI 추론 사용	사용 안 함 (즉시 실행)	사용함 (프롬프트 실행)	사용함 (별도 모델/토큰)
컨텍스트 윈도우	영향 없음	메인 대화의 메모리 사용	완전히 독립된 메모리 공간
사용 목적	환경 설정, 비용 확인, 요약 등 시스템 관리	복잡한 코드 리뷰, 최적화 등 정형화된 작업 수행	방대한 로그 읽기, 병렬 탐색 등 메인 대화 보호
비유	키보드의 단축키	직무별 업무 매뉴얼	잡무를 대신 처리해주는 부사수

패턴의 흐름: Command로 환경을 통제하고, 복잡한 반복 작업은 Skill을 호출하여 해결하며, 그 과정에서 컨텍스트가 길어지거나 방대한 탐색이 필요할 때 Claude가 Subagent를 생성해 백그라운드에서 처리합니다. Skill이 정의된 명확한 워크플로우가 없으면 Claude는 Subagent를 호출하지 않고 스스로 작업을 완료한다는 점에 주의하십시오.

세 개념의 상세 정의

세 개념은 AI 개입 여부, 컨텍스트 처리 방식, 사용자 커스텀 가능 여부 관점에서 명확히 구분됩니다.

Command (명령어)

Claude Code CLI 내부에 하드코딩된 고정 로직 기능입니다. AI의 추론 과정을 거치지 않고 시스템 단에서 즉각적으로 실행됩니다. AI 토큰을 소모하지 않으며, 주로 세션 상태를 관리하거나 시스템 설정을 변경하는 유틸리티 목적으로 사용됩니다. 과거에는 사용자가 커스텀 Command를 만들 수 있었으나, 현재는 모두 Skill 시스템으로 병합되었습니다.

예시: /help (도움말), /compact (컨텍스트 압축), /model (AI 모델 변경), /cost (토큰 사용량 및 비용 확인)

Subagent (하위 에이전트)

메인 대화와 완전히 분리된 독립적인 컨텍스트 창(Context Window)을 가진 특화된 AI 어시스턴트입니다. 대규모 파일 검색, 코드베이스 분석 등 메인 대화창에 불필요한 로그나 검색 결과를 가득 채워 문맥을 훼손하는 것을 방지하기 위해 사용됩니다. Subagent는 자신만의 격리된 공간에서 작업을 수행한 뒤, 요약된 핵심 결과만 메인 대화로 반환합니다.

예시: 내장 Subagent인 Explore(빠른 탐색용), Plan(계획 수립용), 또는 사용자가 프롬프트와 권한을 직접 지정해 만든 code-improver(코드 리뷰 및 개선 전용 에이전트)

Skill (스킬)

복잡한 다단계 절차나 지침을 모아둔 재사용 가능한 워크플로우(프롬프트 템플릿)입니다. SKILL.md 파일에 지침을 정의해 둡니다. Command처럼 /를 통해 수동으로 호출할 수도 있고(예: /skill-name), 대화 문맥상 필요하다고 판단될 때 Claude가 자동으로 트리거할 수도 있습니다. 매번 채팅창에 길게 복사/붙여넣기 해야 했던 작업 매뉴얼을 대체하며, 평소에는 메모리를 차지하지 않다가 필요할 때만 컨텍스트에 로드됩니다.

예시: 내장 번들 스킬인 /code-review, /batch, /debug 및 사용자가 프로젝트 맞춤형으로 만든 /deploy(배포 체크리스트), /summarize-changes(변경 사항 요약)

스킬 (Skills) vs. 젬 (Gems):
- 두 기능 모두 ‘특정 목적을 가지고 반복 사용’한다는 공통점이 있습니다.
- Gems: 단순히 단편적인 컨텍스트(Context)를 제공하는 데 그칩니다.
- Skills: 작업의 워크플로우(Workflow)와 순서도를 제공합니다. “이 순서대로 해줘”라는 지시가 가능합니다.
  
  [!NOTE] 💡 Skills 작성 팁: 처음부터 스킬을 완벽하게 짜기보다, 사용자가 AI와 함께 하나의 사이클(Cycle)을 온전히 완료해 본 뒤, 그 성공적인 과정을 “Skills로 다듬어 달라”고 요청하는 것이 가장 효율적입니다. (예: PIPE 연구, 웹/앱 개발, 사업 기획, 영어 학습 등 다양한 분야 적용 가능)
세션 기반 Skills + Command 자동 생성 방법:

작업 사이클이 완료된 세션에서 아래 프롬프트를 입력하면 Claude가 해당 작업을 분석하여 스킬과 커맨드를 자동 구성합니다.
“방금 우리가 세션에서 함께 진행한 작업 내역을 분석해서 단계별 순서도(Workflow)를 파악해 줘.
1. 이 흐름을 바탕으로 앞으로 동일한 작업을 반복할 수 있는 명확한 Skill 지침서를 작성해 줘.
2. 그리고 이 Skill을 즉시 실행할 수 있도록 나만의 맞춤형 Command를 .claude/commands 폴더에 파일 형태로 생성해 줘.”
내부적으로 Claude는 세션의 대화 기록과 파일 수정 내역을 분석해 핵심 단계(Steps)를 추출하고, 재실행 가능한 워크플로우로 다듬은 뒤, 명령어 하나로 전체 파이프라인을 실행하는 커맨드 파일을 .claude/commands/에 생성합니다.

AI 개입 여부와 컨텍스트 영향을 기준으로 정리하면 다음과 같습니다.

구분	AI 개입 여부	주 목적	컨텍스트(Context) 영향	사용자 커스텀
Command	X (고정 로직)	유틸리티 작업 및 CLI 환경 제어	메인 문맥에 기록되지 않으며 즉시 실행됨	불가능 (Skill로 통합됨)
Skill	O (프롬프트 기반)	반복적인 복잡한 절차 및 도구 사용 지시	호출 시 지침 내용이 메인 문맥에 로드됨	가능 (`SKILL.md`)
Subagent	O (독립적 AI)	문맥 오염 없이 무겁고 복잡한 탐색/분석 처리	격리된 공간에서 실행 후 결과만 메인 문맥에 추가	가능 (`.claude/agents/`)

한 줄 요약:

Command는 AI가 개입하지 않는 즉각적인 시스템 단축키입니다.
Skill은 AI에게 특정 작업을 “어떻게 해야 하는지” 알려주는 재사용 가능한 업무 매뉴얼입니다.
Subagent는 메인 대화방을 어지럽히지 않고 백그라운드에서 별도의 조사를 처리해주는 독립된 조수입니다. 특정 Skill을 실행할 때 배경에서 Subagent를 소환하여 작업을 위임하는 패턴도 자주 사용됩니다.

직관적 역할 매핑 및 실전 적용 가이드

Command → Agent → Skill 패턴을 가상 스튜디오의 업무 위임 시스템으로 치환하면 설계 감각을 잡기 수월합니다.

나 (User) = 작업 지시를 내리는 테크니컬 디렉터(TD)
Command = 호출 벨 또는 무전기 (즉각적인 액션)
Agent = 격리된 회의실에서 내 일을 대신해 줄 주니어 개발자 (독립된 작업자)
Skill = 그 주니어 개발자에게 쥐어주는 사내 표준 코딩 컨벤션 및 작업 매뉴얼 (행동 지침서)

실제 작업 중 다음과 같은 생각이 든다면 그것이 해당 기능을 설계해야 할 타이밍입니다.

상황 A: “내 메인 작업 흐름(Context)을 방해받고 싶지 않아.” → Agent 도입

메인 대화창에서 전체 파이프라인 구조를 잡고 있는데, 특정 스크립트(예: TBN 매트릭스 계산 로직)의 버그를 잡거나 대량의 코드를 리팩토링해야 하는 경우입니다. 여기서 이 얘기를 시작하면 코드가 수백 줄씩 쏟아져 지금까지의 대화 문맥이 엉망이 됩니다. 이럴 때 Agent를 스폰합니다. “이 폴더에 가서 코드 에러 원인만 분석해서 핵심 결과만 나한테 보고해”라고 격리된 공간으로 작업을 던지는 행동입니다.

상황 B: “이 작업은 매번 비슷한 규칙과 포맷이 필요해.” → Skill 작성

새로운 커스텀 UI를 만들 때마다 PySide 구조를 텍스트로 설명해야 하는 경우입니다. 항상 객체 지향적으로 짜야 하고, 특정 네이밍 컨벤션을 지켜야 하고, 로직과 UI를 분리해야 하는 반복 요구사항을 텍스트 파일(SKILL.md)로 박제해 둡니다. “PySide UI를 짤 때는 무조건 이 구조를 따라라”라는 나만의 가이드라인을 만드는 행동입니다.

상황 C: “그럼 이걸 어떻게 연결해서 실행하지?” → Command (트리거)

작업 환경도 분리했고(Agent), 규칙도 정했으니(Skill), 일을 시작시켜야 할 때입니다. CLI 환경에서 명령어를 입력하여 이 전체 사이클을 구동합니다.

실전 시나리오: Houdini to Blender 파이프라인 툴 개발

목표: Houdini의 데이터(skinprim 등)를 Blender 5.0으로 넘겨 Groom을 제어하는 애드온의 UI를 개발한다고 가정합니다.

Step 1. Skill 정의 (사전 세팅)

프로젝트 폴더 내에 .claude/skills/blender-pyside-ui.md 스킬을 미리 작성해 둡니다. 내용: “Blender 애드온 내에서 PySide 창을 띄울 때는 반드시 윈도우 부모(parent)를 Blender 메인 윈도우로 설정할 것. 스크립트 구조는 MVC 패턴을 따르고, 변수명은 스네이크 케이스를 쓸 것.”

Step 2. 메인 대화에서 Command 실행 (작업 지시)

메인 터미널 창에서 전체 파이프라인 구조를 구상 중에 UI 뼈대가 필요해지면, 명령어(Command)를 통해 Agent를 호출합니다.

/agent "새로운 UI 스크립트를 작성해줘. 툴 이름은 'Groom Deform Tool'이고, 반드시 내 /blender-pyside-ui 스킬 가이드를 읽고 적용해서 만들어."

Step 3. Agent의 백그라운드 작업 (실행 및 결과 반환)

호출된 Agent는 메인 대화창 밖(백그라운드)에서 스킬(가이드라인)을 읽고, 프로젝트 폴더를 뒤져서 어디에 파일을 생성할지 확인한 뒤, 스킬에 명시된 규칙대로 PySide UI 코드를 작성합니다. 작업이 끝나면 메인 창에 이렇게 보고합니다: “요청하신 스킬 규칙에 따라 ‘Groom Deform Tool’의 UI 스크립트 작성을 완료했습니다. 파일은 ui_main.py에 저장되었습니다.”

설계의 핵심은 내가 반복적으로 AI에게 요청해야 하는 내용은 Skill로 저장하고, 파일 검색이나 코드 작성 등 길고 지루한 실무 작업은 내 시야(메인 컨텍스트) 밖의 Agent에게 던지는 구조를 만드는 것입니다. 결국 이 패턴은 “나의 생각(Main Context)을 보호하면서, 일관된 품질의 코드(Skill)를, 방해 없이(Agent) 생산해 내는 시스템”을 구축하는 과정입니다.

개념 조합 가이드

세 개념은 서로 종속적인 관계가 아닙니다. 하나를 만들면 다른 하나가 필수로 있어야 하는 상관관계는 없으며, 필요에 따라 꺼내 쓰는 완전히 독립적이고 모듈화된 도구들입니다.

단독 사용 (가장 일반적)

단순히 코드 컨벤션을 맞추고 싶다 → Skill 하나만 정의하면 끝
복잡한 버그의 원인을 리서치하고 싶다 → Subagent 하나만 호출해서 끝

조합 사용 (Subagent + Skill 협력)

“고객 요청사항 분석 Subagent”가 수십 개의 파일을 뒤지며 리서치를 수행하다가 엑셀 파일을 읽어야 할 때, 미리 정의해둔 “엑셀 읽기 Skill”을 가져다 쓰는 구조입니다. 서브에이전트(작업 반장)가 스킬(도구/레시피)을 활용하는 아키텍처입니다.

점진적 도입 순서

초기 단계: 기본 Command만 쓰면서 Claude Code 자체에 익숙해집니다.
도입 단계: 매번 반복해서 요청하는 프롬프트나 단순한 유틸리티 기능이 생기면 가벼운 Skill로 만들어 둡니다.
심화 단계: 여러 단계를 거쳐야 하거나 메인 채팅방 대화 내용이 너무 길어져서 맥락이 꼬이는 복잡한 작업이 생길 때 Subagent를 구축해 무거운 업무를 위임합니다.

훅스 (Hooks):
- 이벤트 기반 트리거(Event Trigger)로 작동하며, 특정 상황에 맞춰 AI의 동작을 예약하거나 실행합니다.
- 소프트웨어 공학의 Signal & Slot 패턴과 유사하며, cron(크론)을 활용해 특정 시간에 맞춰 작업을 실행하도록 설정할 수 있습니다.

3. 확장 및 외부 통합 (Scaling & Integration)

단일 AI의 한계를 넘어, 여러 에이전트와 외부 도구를 결합하는 심화 단계입니다.

MCP (Model Context Protocol):
- AI가 로컬 환경이나 외부 도구들과 연결되는 단계입니다.
- Awesome MCP Servers 등을 참고하여, 파이프라인의 어느 단계(Step)에서 외부 도구의 개입이나 추가 컨텍스트가 필요한지 판단하여 연동합니다.

Agents - How to create

에이전트를 생성하는 방법은 크게 두 가지입니다. /agents 명령어를 통한 대화형 방식과 마크다운 파일을 직접 작성하는 수동 방식입니다.

방법 1: `/agents` 명령어 사용 (권장)

Claude Code 창에서 /agents 명령어를 입력합니다.
Create new agent를 선택한 후 저장 위치(스코프)를 지정합니다.
- Personal (~/.claude/agents/): 모든 프로젝트에서 사용 가능
- Project (.claude/agents/): 현재 프로젝트 내에서만 유효, 팀 공유에 적합
Generate with Claude를 선택하면 역할과 목적을 자연어로 설명하는 것만으로 에이전트의 식별자, 설명, 시스템 프롬프트를 자동 생성합니다.
에이전트가 사용할 도구(Tools)와 AI 모델(Sonnet / Haiku 등)을 선택합니다.
메모리 설정이 필요하면 User scope 또는 Project scope를 활성화합니다.
s 또는 Enter로 저장하면 즉시 사용 가능합니다.

방법 2: 마크다운 파일 직접 생성

에이전트 파일은 YAML 프론트매터(설정) + 시스템 프롬프트(본문) 구조입니다. name과 description은 필수 항목입니다.

---
name: code-reviewer
description: 코드의 변경 사항을 분석하고 품질 개선 및 버그에 대한 리뷰를 제공할 때 이 에이전트를 사용하세요.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
memory: project
---

당신은 코드 리뷰 전문 에이전트입니다.
전달받은 코드의 보안 취약점, 성능 저하 요인, 가독성을 분석하여 리팩토링 제안을 작성해 주세요.
코드를 직접 수정(Write/Edit)하지 마세요.

파일을 직접 생성한 경우 에이전트를 즉시 인식시키려면 Claude Code 세션을 재시작하거나 /agents 명령어를 실행해 새로고침해야 합니다.

생성된 에이전트는 Claude Code가 자동으로 적절한 상황에서 호출하며, 명시적으로 호출하려면 @에이전트이름 형식으로 직접 지정할 수 있습니다 (예: @code-reviewer 이 파일 검토해줘).

Agents - Skills and Hooks 설정

에이전트에 스킬(Skills)과 훅(Hooks)을 설정하는 것은 모두 마크다운 파일 상단의 YAML 프론트매터 영역에서 이루어집니다.

Skills 설정

스킬을 설정하면 서브에이전트가 실행될 때 미리 정의된 워크플로우 컨텍스트를 컨텍스트 윈도우에 로드한 상태로 시작합니다. 서브에이전트는 부모 대화의 스킬을 자동으로 상속받지 않으므로 반드시 명시해야 합니다.

---
name: backend-expert
description: 백엔드 아키텍처 및 복잡한 API 로직을 설계할 때 사용하세요.
skills:
  - user-auth-flow
  - db-optimization-tips
---
시스템 프롬프트 본문...

Hooks 설정

훅은 에이전트가 도구를 사용하기 직전(PreToolUse), 직후(PostToolUse), 또는 작업을 마칠 때(Stop) 특정 명령어를 자동 실행합니다. 에이전트 파일 내에 작성된 훅은 해당 에이전트가 활성화된 동안에만 작동합니다.

이벤트	용도
`PreToolUse`	도구 실행 직전 — 위험 명령어 차단/검증 등
`PostToolUse`	도구 실행 직후 — 파일 수정 후 린터나 테스트 자동 실행 등
`Stop` (에이전트 내부에서는 `SubagentStop`)	에이전트가 응답을 완료할 때 — 보고서 생성, 후처리 등

PreToolUse 훅에서 도구 실행을 막으려면 검증 스크립트가 exit code 2를 반환하도록 작성합니다. Claude Code는 어떤 도구를 쓰려는지 정보를 JSON 형태의 stdin으로 전달합니다. Stop 훅에서 exit code 2를 반환하면 Claude는 작업을 멈추지 않고 계속 진행합니다 — 단, stop_hook_active 필드가 true일 때는 반드시 exit 0을 반환해야 무한 루프를 방지할 수 있습니다.

훅 설정은 settings.json과 동일한 중첩 딕셔너리 구조를 사용합니다.

---
name: secure-developer
description: 소스코드 보안 진단 및 안전한 Bash 명령어 실행이 필요할 때 호출하세요.
model: sonnet
skills:
  - security-checklist-2026
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: python3 ./scripts/check_dangerous_commands.py
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: git diff
---

당신은 보안 취약점을 예방하고 안전한 개발 환경을 유지하는 전문 서브에이전트입니다.
컨텍스트로 주어지는 보안 스킬을 기반으로 코드를 철저히 분석해 주세요.

Skills/Hooks 자동 설정 방법

/agents 명령어의 대화형 UI에는 skills나 hooks를 직접 선택하는 항목이 제공되지 않습니다. 다음 두 가지 방법으로 설정합니다.

방법 A: Generate with Claude 활용 (권장)

/agents → Generate with Claude 단계에서 자연어로 스킬과 훅의 의도를 명시하면 Claude가 YAML 프론트매터를 자동으로 구성합니다.

예시 프롬프트: “코드 리뷰 프로젝트용 에이전트를 만들어줘. 기존에 만들어둔 security-checklist 스킬을 탑재하고, Edit 도구를 쓴 직후에는 npm run lint가 실행되도록 훅을 걸어줘.”

저장 단계에서 e (Save and edit)를 눌러 파일을 열고 생성된 skills / hooks 블록을 최종 확인합니다.

방법 B: 수동 편집

/agents UI로 기본 틀을 만든 뒤, 저장 단계에서 e 키로 편집창을 열어 프론트매터에 skills와 hooks 항목을 직접 추가합니다.

팀 단위 배포가 필요한 경우 플러그인(Plugin) 형태로 에이전트를 패키징할 수 있으나, 보안상의 이유로 플러그인을 통해 가져온 에이전트의 hooks 필드는 무시됩니다. 훅이 반드시 필요한 경우에는 플러그인 내부의 에이전트 파일을 .claude/agents/로 복사해서 사용해야 합니다.

Session Management

PowerShell 환경에서 Claude Code 세션을 관리하는 것은 컨텍스트 유지와 토큰 비용 최적화의 핵심입니다. Claude Code는 명령을 실행한 디렉토리(통상 Git root)를 세션의 기준으로 삼고, 에이전트·메모리·훅 설정은 .claude/ 폴더에 저장되어 세션이 바뀌어도 유지됩니다.

세션 시작·재개·목록 조회

작업	명령어
새 세션 시작	`claude` (프로젝트 폴더에서)
세션 시작 시 이름 지정	`claude --name [이름]` 또는 `claude -n [이름]`
현재 창에서 초기화	`/clear`
마지막 세션 재개	`claude --continue` 또는 `claude -c`
특정 세션 재개	`claude --resume [세션ID]` 또는 `claude -r [세션ID]`
세션 목록 선택기 열기	`claude --resume` (인수 없이)
세션 분기	`/branch` (세션 내부) 또는 `claude --resume <ID> --fork-session`
세션 이름 변경	`/rename [이름]` (세션 내부에서)

세션 선택기(claude --resume) 안에서 사용할 수 있는 키:

Space: 해당 세션 미리보기
Ctrl+R: 세션 이름 변경
Ctrl+A: 모든 프로젝트의 세션 표시
Ctrl+B: 현재 Git 브랜치와 연결된 세션만 필터링

토큰 최적화 명령어

명령어	용도
`/compact`	대화 기록을 핵심만 요약해 컨텍스트를 압축
`/compact focus on X`	특정 주제 중심으로 요약
`/clear`	대화 기록 전체 초기화
`/cost`	현재 세션의 토큰 사용량 및 비용 확인

권장 워크플로우 패턴

작업 단위마다 Git 브랜치를 분리하고 세션을 시작하는 것이 가장 효과적입니다. 세션 중 Claude가 파일을 잘못 수정하더라도 git restore로 안전하게 롤백할 수 있습니다.

# 새 작업 시작
git checkout -b feature/refine-temp-posts
claude

# 반복 작업은 단발성 원라이너로 처리 (세션 오버헤드 없음)
claude "temp_posts 폴더의 마크다운 파일들을 규칙에 맞게 _posts로 통합해줘"

단발성 원라이너(claude "명령")는 대화 컨텍스트를 누적하지 않으므로 자동화 파이프라인 구축 시 유리합니다.

세션 관리 모범 사례:

한 세션에서 여러 작업을 섞지 말 것 — 작업 완료 시 /clear로 컨텍스트 비우기
대화가 길어지면 /compact로 중간 압축
작업 전 세션에 /rename [작업명]으로 이름 부여 (나중에 목록에서 식별 용이)
세션 분기가 필요하면 세션 내부에서 /branch 또는 CLI에서 claude --resume <세션ID> --fork-session으로 기존 기록을 보존한 채 새 방향 시도

세션 삭제 및 정리

완료된 세션을 반드시 삭제할 필요는 없지만, /resume 목록이 누적되어 원하는 세션을 찾기 어려워지거나 민감한 정보가 포함된 세션이 남아있는 경우 주기적으로 정리하는 것이 좋습니다. 단순히 토큰 낭비를 막으려는 목적이라면 /clear로 컨텍스트를 초기화하는 것만으로 충분합니다.

방법 1: claude project purge (권장)

프로젝트의 대화 기록, 프롬프트 히스토리, 디버그 로그 등 로컬 상태를 일괄 삭제합니다. 인수 없이 실행하면 대화형 목록이 열려 삭제 대상을 직접 선택할 수 있습니다.

claude project purge

방법 2: 로컬 파일 직접 삭제

Claude Code는 세션 데이터를 ~/.claude/projects/ 경로에 .jsonl 파일로 저장합니다.

# 저장된 세션 파일 목록 확인
ls ~/.claude/projects/

# 전체 세션 초기화 (복구 불가)
rm -Recurse -Force ~/.claude/projects/*

MCP / Plugin / Subagent

[!NOTE]

MCP (주방/인프라) : AI가 외부 데이터와 연결될 수 있게 해주는 ‘수도관과 가스레인지’입니다.

Skill (레시피) : 연결된 도구를 ‘어떻게’ 사용해야 하는지 알려주는 구체적인 ‘요리법(절차적 지식)’입니다.

Connector (연결 튜브) : MCP나 API를 통해 외부 앱(Slack, Jira 등)과 AI를 물리적으로 이어주는 ‘연결 통로’를 통칭합니다.

Plugin (밀키트) : 이 모든 것(Skill, MCP, 설정 등)을 한 번에 설치할 수 있게 포장해 놓은 ‘밀키트’입니다.

Commands

Built-in

/model

It returns a list of model, and user can select one of them.

/plugin

Do everything under local scope

  /plugin install {plugin-name} -s local

/stats

7일, 30일, 전체 기간 등 특정 기간 동안의 누적 사용량 통계와 참여도 지표(engagement metrics)를 요약해서 보여줍니다

/context

현재 세션의 컨텍스트 윈도우(기억 용량) 내에서 어떤 파일과 대화가 공간을 차지하고 있는지 상세 내역을 분석해 줍니다

/cost

개발자 관점에서 현재 세션에 사용된 총 비용(달러)을 계산하여 알려줍니다

/statusline

화면 하단에 실시간 지표를 띄우기 위한 UI 설정 명령어. 셸 명령어를 설정 파일에 등록하면 Claude Code가 매 턱(tick)마다 JSON 데이터를 stdin으로 전달하고, 해당 명령의 출력이 상태 표시줄에 표시됩니다.

/status

프록시/네트워크 연결 상태를 점검하는 시스템 진단 명령어

My commands

/improve-frontend, /ui-design, /implement-frontend

Prompts

해당 제목 아래에는 양질의 대답 또는 작업을 위한 prompt 사용 케이스 및 스킬들을 정리한다.

어떤 agent가 필요한지 모를 때

현재 web site의 전체 기능은 만족해. 다만, 가독성이 떨어져서 web design,UI,UX를 업데이트하고싶어. 다만 디자인 경험이 없어서 어떻게 markdown render 를 업데이트해야지 가독성이 높아지는지는 모르겠어. 현재 voltagent-core-dev plugin 통해서 가져온 agents들 중에서 필요한 agent들을 선별해서 목적에 맞게 web site 의 가독성을 향상시켜줘

한 Session에서, 작업(workflow cycle)을 마무리 후, Skill과 Command 자동 생성

세션에서 함께 진행한 작업 내역을 분석해서 단계별 순서도(Workflow)를 파악해서, 동일한 작업을 반복할 수 있는 명확한 Skill 지침서를 작성해주고, 이 Skill을 즉시 실행할 수 있도록 나만의 맞춤형 Command을 만들어줘.

Command를 추가 텍스트와 함께 사용할 때

Claude Code space를 처음 시작할때,

나의 목적은 … 인데, 이에 맞는 command와 agents를 만들어줘.

Questions for terminologies

Make MCP vs Make MCP server & Form of results

네, 아주 정확한 지적입니다! MCP(프로토콜)를 만드는 것과 MCP 서버(도구)를 만드는 것은 완전히 다릅니다. 대부분의 사용자나 개발자가 “MCP를 만든다”라고 말할 때는 사실 “MCP 서버를 만든다”는 뜻입니다. 질문하신 ‘결과물의 형태’가 무엇인지, 규약(Protocol)과 구현체(Server)로 나누어 명확히 보여드릴게요.

MCP (Model Context Protocol) = “법전” (이미 만들어짐)
- 누가 만들었나? Anthropic과 파트너사들이 만들었습니다.
- 만드는 행위: 규칙을 정하고 문서를 쓰는 것입니다.
- 결과물의 형태: 문서 (Specification Document)
- “서로 통신할 때는 JSON-RPC 2.0 형식을 써라.”
- “연결할 때는 initialize라는 메시지를 먼저 보내라.”
- 이런 규칙들이 적힌 텍스트 문서(Markdown)와 이를 구현한 SDK(라이브러리)가 결과물입니다.
- 사용자님이 이걸 다시 만들 일은 거의 없습니다.
MCP 서버 (MCP Server) = “법을 따르는 시민” (우리가 만들 것)
- 누가 만드나? 사용자님이나 일반 개발자가 만듭니다.
- 만드는 행위: 실제 기능을 수행하는 코드를 짜는 것입니다.
- 결과물의 형태: 실행 가능한 소스 코드 파일 (.py, .js, .ts)
- 단순한 JSON 파일도 아니고, 단순한 글자 나열도 아닙니다.
- 컴퓨터에서 돌아가는 프로그램입니다.

Example :🔍 “MCP 서버”를 만들면 실제로 남는 것

사용자님이 “날씨 정보를 알려주는 MCP 서버”를 만든다면, 결과물은 아래와 같은 파이썬 코드 파일(weather_server.py) 하나입니다.

  # weather_server.py (이게 결과물입니다!)

  from mcp.server.fastmcp import FastMCP

  # 1. 서버 이름 짓기
  mcp = FastMCP("My Weather Server")

  # 2. 도구(Tool) 정의하기 (실제 기능)
  @mcp.tool()
  def get_weather(city: str) -> str:
      """도시 이름을 입력받아 날씨를 알려줍니다."""
      if city == "Seoul":
          return "맑음, 25도"
      return "알 수 없음"

  # 3. 서버 실행
  if __name__ == "__main__":
      mcp.run()

결론
- 단순 JSON인가요? ❌ 아니요. JSON은 이 서버가 Claude와 대화할 때 주고받는 말(메시지)의 형식일 뿐입니다. 결과물 자체는 코드(로직)입니다.
- 단순 글자 문서인가요? ❌ 아니요. 실제로 실행되어야 하는 프로그램입니다.
혼동의 원인: config.json
- 사용자님이 “JSON 아닌가?”라고 생각하신 이유는 아마 설정 파일 때문일 겁니다. 만들어진 MCP 서버(weather_server.py)를 Claude에게 등록할 때는 JSON 설정 파일을 건드려야 합니다.
```
  // claude_desktop_config.json (이건 '등록증'입니다)
  {
  "mcpServers": {
      "my-weather-bot": {
      "command": "python",
      "args": ["weather_server.py"]
      }
  }
  }
```

Meaning of making Plugin

Plugin(플러그인)의 결과물은 결국 “잘 포장된 폴더(저장소)”라고 생각하시면 됩니다. MCP 서버가 단순히 “실행 가능한 코드 조각(부품)”이라면, 플러그인은 이 부품을 사용자가 쉽게 설치하고 사용할 수 있도록 설명서와 설정을 함께 넣은 “완제품 박스”입니다. 구체적으로 플러그인을 만들었을 때 결과물이 어떤 파일 구조를 가지는지 눈으로 확인시켜 드릴게요.

📂 플러그인 결과물 (폴더 구조 예시)

만약 사용자님이 my-weather-plugin이라는 플러그인을 만들었다면, 그 결과물은 아래와 같은 파일들이 들어있는 하나의 폴더(또는 GitHub 저장소)입니다.

  my-weather-plugin/             <-- 이게 플러그인 결과물입니다!
  ├── README.md                  # [설명서] "이 플러그인은 날씨를 알려줍니다."
  ├── claude-plugin.json         # [신분증] 이름, 버전, 실행 명령어 정보 (가장 중요!)
  ├── src/                       # [본체] 실제 기능이 들어있는 코드
  │   ├── main.py                # <-- 여기에 MCP 서버 코드가 들어있음
  │   └── utils.py
  ├── prompts/                   # [페르소나] (옵션) 이 플러그인을 쓸 때 Claude의 행동 지침
  │   └── weather-expert.md      # "너는 기상 캐스터처럼 말해라"
  └── requirements.txt           # [준비물] 필요한 파이썬 라이브러리 목록

핵심 구성 요소 3가지
1. 신분증 (Manifest File)
  - 보통 claude-plugin.json 또는 package.json 같은 파일입니다.
  - 역할: Claude에게 “내 이름은 이거고, 나를 실행하려면 python main.py라고 입력해”라고 알려주는 명찰입니다.
  - 이게 없으면 그냥 코드 덩어리일 뿐, 설치 가능한 플러그인이 아닙니다.
2. 본체 (Code / Executable)
  - main.py 처럼 실제 날씨 정보를 가져오는 MCP 서버 코드입니다.
  - 앞서 말씀드린 “MCP를 만드는 과정”에서 나온 결과물이 바로 이 폴더 안에 들어갑니다.
3. 페르소나/프롬프트 (Prompts - 옵션)
  - 단순히 기능만 주는 게 아니라, “이 도구를 쓸 때는 기상 캐스터 말투를 써줘” 같은 시스템 프롬프트를 포함할 수 있습니다.
  - 사용자님이 말씀하신 Subagent(서브에이전트)의 성격이 여기서 정의됩니다.

🔌 차이점 한눈에 보기

구분	MCP 서버 (부품)	Plugin (완제품)
비유	모터 (Engine)	선풍기 (Fan)
형태	실행 가능한 코드 파일 (`server.py`)	코드를 포함한 설치 패키지 폴더
설치법	사용자가 직접 설정 파일 열어서 코드를 복붙해야 함 (DIY)	`claude plugin install <이름>` 명령어 한 번으로 설치됨
구성	코드 + 라이브러리	코드 + 라이브러리 + 설치 정보(Manifest) + 프롬프트

요약: 사용자님이 만들어야 할 것
- 사용자님이 “나만의 기획/개발/테스트 플러그인”을 만든다면, 결과물은 다음과 같습니다.
  1. Github 저장소를 하나 만듭니다.
  2. 그 안에 각 에이전트의 역할이 적힌 프롬프트 파일을 넣습니다. (planner.md, developer.md)
  3. 필요하다면 자동화 스크립트(MCP)를 넣습니다.
  4. 마지막으로 “이걸 어떻게 설치해라”가 적힌 설정 파일(manifest)을 넣습니다.
- 이 폴더 주소(URL) 자체가 바로 플러그인이 되는 것입니다!

How to deploy my MCP

Python으로 만든 MCP 서버를 다른 사람들에게 배포하는 방법은 크게 “전통적인 파이썬 패키지 배포 방식”과 “최신 MCP 전용 레지스트리 등록 방식” 두 가지로 나뉩니다. 사용자님이 만든 코드를 다른 사람이 쓰게 하려면 (1) 설치(Installation)와 (2) 연결(Configuration) 두 단계를 해결해줘야 합니다.

방법 1. PyPI (파이썬 패키지 저장소) 배포 [가장 추천 ⭐]
- 가장 표준적인 방법입니다. pip나 uv로 설치할 수 있게 만드는 것입니다.
  1. 패키징: pyproject.toml 파일을 만들고 프로젝트를 패키지로 만듭니다.
  2. 업로드: PyPI(Python Package Index)에 업로드합니다.
  3. 사용자 설치: 다른 사용자는 터미널에서 아래처럼 실행하거나, Claude 설정에 바로 입력할 수 있습니다.
    - 현대적인 방식 (uv 사용 시 - 매우 빠름): 사용자는 별도 설치 없이 설정 파일에 이렇게 적기만 하면 됩니다.
      { "mcpServers": { "weather-bot": { "command": "uvx", "args": ["weather-mcp-server"] } } }
- 전통적인 방식 (pip 사용 시): 사용자가 먼저 pip install weather-mcp-server를 한 뒤, 설정 파일에 경로를 적습니다.
방법 2. Docker 이미지 배포 [환경 문제 해결]
- 사용자의 파이썬 버전이나 라이브러리 충돌을 걱정할 필요가 없는 가장 깔끔한 방법입니다.
  1. 이미지 빌드: Dockerfile을 작성해서 도커 이미지를 만듭니다.
  2. 업로드: Docker Hub에 올립니다. (예: runab/weather-mcp)
  3. 사용자 설정: 사용자는 Claude 설정 파일에 다음과 같이 적습니다.
    { "mcpServers": { "weather-bot": { "command": "docker", "args": ["run", "-i", "--rm", "runab/weather-mcp"] } } }
방법 3. 깃허브(GitHub) 소스 공유 [가장 간단]
- 개발자들끼리 공유할 때 주로 씁니다.
  1. 업로드: GitHub 리포지토리에 코드를 올립니다 (main.py, requirements.txt).
  2. 사용자 행동:
    - git clone https://github.com/runab/my-mcp.git
    - pip install -r requirements.txt
  3. 연결: 사용자가 자신의 로컬 경로를 설정 파일에 적습니다.

🚀 “마켓플레이스”에 올리는 법 (Smithery.ai / Glama)
- 아까 보셨던 marketplace add 명령어처럼, 사람들이 검색해서 쉽게 찾게 하려면 MCP 레지스트리에 등록해야 합니다. 현재 가장 유명한 두 곳이 있습니다.
  1. Smithery.ai: 현재 Claude Desktop용 MCP들이 가장 많이 모여있는 곳입니다.
    - GitHub에 코드를 올린 후, Smithery 웹사이트에서 “Submit” 버튼을 눌러 내 리포지토리 주소를 등록합니다.
    - 등록되면 다른 사람들이 npx -y @smithery/cli install @runab/weather-mcp 같은 명령어로 한 방에 설치할 수 있게 됩니다.
  2. Glama: 또 다른 MCP 검색 엔진입니다. 여기도 GitHub 리포지토리를 등록하면 사람들이 검색할 수 있습니다.

요약: 배포 프로세스 4단계
1. 코딩: main.py를 짭니다. (FastMCP 등 사용)
2. 패키징: pyproject.toml을 설정해서 PyPI에 올리거나, Docker Hub에 올립니다.
3. 홍보 (옵션): Smithery.ai 같은 레지스트리에 내 프로젝트를 등록합니다.
4. 안내: 사용자에게 “이 JSON 코드를 claude_desktop_config.json에 복사/붙여넣기 하세요”라고 README.md에 적어줍니다.
가장 추천하는 시작 방법: 일단 GitHub에 소스 코드를 올리는 것부터 시작하세요. 그리고 README.md 파일에 “어떻게 설정 파일에 추가하는지” JSON 예시를 적어두는 것이 배포의 첫걸음입니다!

Spaces (Practices)

2026-06-07 - 내용관리자와 Ticket 관리 분석가 spaces 에서 테스트를 하면서 Claude code 연습 (Subagents, skills, user/project/global)

Space 01 : Online store for eyeglass frames (2)

구축과 운영 구분

Space 02 : Pipeline TD Labs

목적은 개인 프로젝트를 진행하면서, Technical Director(TD)로써의 역량을 향상시키고 더 나아가 VFX/Animation 업계에서 경쟁력있는 인재가 되는것이야. 내가 관심갖는 분야는 Hair/fur/feather/CFX/Crowd/USD/Cloth/simulation/optimization/computer graphics/mathmatics 야. 그리고 작업 도구는 Houdini/Blender/C++/Solaris/Python 이야.
작업 순서
1. 새 프로젝트 시작인지 기존작업 develop 인지 구분
  - 새 프로젝트

Ideas

text로 action 또는 개념을 입력하면, blender MCP를 통해서 열려있는 session 의 blender를 작동
- ex) curves object에 mesh object를 불러와줘 -> Object info를 생성

Space 03 : English Study

섬세하게(politely, formal, casual) 의미 전달해야하는 상황들을 정리

Space 04 : 문서 관리자

AI 정리해준 문서 정리
문서들 중에서 중복된 내용 정리, 내용 검증

Space 05 : 내용 관리자 (1)

사용자가 temp_posts 폴더의 파일에 내용을 추가한 후,

목표 : chat 방식의 ai로부터 얻은 답변들 중, 중요한 내용들을 추려서, 블로그에 정리 및 재참조가능하도록 함
작업 순서
1. temp_posts 폴더의 파일들의 내용을 읽기. 이때, 대화 하나는 Q와 A로 한 묶음으로 구성되어있다.
2. 한 대화를 읽은 뒤, 내용 파악후, _posts 폴더의 파일에 적혀있는 내용들중
필요한 역할들

Process
1. keyword 위주 정리한 노트를 사진 촬영 또는 스크린샷
2. 이미지와 노트 필기 main 주제 등 간략하면서 핵심 context 제공
3. 만들어진 노트가 가독성이 좋은지, 내용이 정확한지 확인
4. Gitpage에 업로드. 이때, 기존 노트를 분석해서, 전채적인 맥락과 기존 내용을 망가트리지 않기