Week2 - Tools

CLAUDE.md · Subagent · Skills · MCP

Quiet Operators Lab
1
Chapter 1

CLAUDE.md

클로드 헌법

CLAUDE.md — 무엇이고 어떻게 작동하나요?
  • AI가 세션 시작 시 자동으로 로드하는 마크다운 파일
    • 매번 같은 지시를 반복할 필요 없음
  • 마크다운 헤더(#)와 목록(-)으로 구조화
    • AI의 페르소나, 어조, 핵심 규칙 정의
  • 프로젝트 내내 규칙 준수 보장
CLAUDE.md auto-load Claude AI Engine 세션 규칙 적용 CLAUDE.md 에 정의된 규칙들 페르소나 보안 규칙 어조/서식 직무 특성 세션 시작 시 자동 로드 흐름
References: Claude Code overview — code.claude.com/docs
CLAUDE.md 작성 예시 — HR팀
# 페르소나
당신은 HR팀 전용 AI 어시스턴트입니다.
항상 존댓말(~습니다체)을 사용하고, 간결하게 답변하세요.

## 보안 규칙
- 이름·전화번호·주민등록번호는 반드시 `***`로 마스킹 처리할 것
- 채용 보고서에 성별·나이·출신 학교 관련 편향 표현 금지
- 외부 공유 문서에 사내 급여 정보 포함 금지

## 문서 서식
- 제목(#): Arial 20pt 굵게
- 소제목(##): Arial 16pt 굵게
- 본문: 줄간격 1.5, 문단 간 빈 줄 1개

## 자주 쓰는 용어
- 채용 단계: 서류 → 1차 면접 → 2차 면접 → 최종 합격
- 상태 표기: 검토중 / 진행중 / 합격 / 불합격 / 보류
~/.claude/CLAUDE.md 또는 ./CLAUDE.md — 팀 공유 가능
References: Claude Code overview — code.claude.com/docs
저장 위치와 적용 범위
  • 사용자용: ~/.claude/CLAUDE.md
    • 내 컴퓨터의 모든 프로젝트에 공통 적용
    • 나만의 코딩 철학, 환경 설정 등 개인 규칙
  • 프로젝트용: ./CLAUDE.md
    • 특정 폴더에 위치 — 팀원과 Git으로 공유 가능
    • 서식, 보안 규칙, 직무 특성 등 팀 공통 규칙
  • 두 파일이 모두 존재하면 병합 적용
    • 프로젝트 규칙이 개인 규칙보다 우선순위
References: Claude Code overview — code.claude.com/docs
실습 1 — 개인정보 마스킹 규칙
  • 1. 프로젝트 폴더 루트에 CLAUDE.md를 만듭니다.
  • 2. 파일에 "이름, 전화번호를 *으로 자동 처리할 것" 작성
  • 3. 저장 후 클로드 코드 새 대화 시작
  • 4. 클로드 코드에게 요청:
    • "고객 지원팀에 내 전화번호 010-1111-1111을 010-222-2222로 바꾸고, 이메일은 woobina@gmail.com을 woobin.dev@gmail.com으로 수정하도록 요청하는 이메일 초안을 .md로 작성해줘"
  • 5. 개인 정보 마스킹 된 것 확인
References: Claude Code Docs · CLAUDE.md 실습 가이드
실습 2 — 편향 방지 지침
  • 1. 채용 보고서에 성별·연령 편향 표현 금지
    • 예: "젊은 개발자", "여성 후보자" 등 제거
  • 2. CLAUDE.md에 규칙 추가
    • 성별·나이 관련 표현 자동 감지 및 제거
  • 3. 클로드 코드에게 다음 사항을 요청: "다음 문장을 기반으로 "2030 젊은 피로 가득한 역동적인 팀에서 함께 성장할 활력 넘치는 주니어 개발자를 모십니다." 우리 개발팀 채용 공고문 작성해줘."
  • 4. 표현 수정된 것 확인
References: 생성형 AI 활용 보안 가이드 — 전남대학교
실습 3 — 회사 문서 서식 적용
  • 1. 서식 규칙 정의
    • Arial 폰트, # 제목 20pt 굵게, ## 소제목 16pt 굵게
    • 줄간격 1.5, 문단 간 빈 줄 1개
  • 2. CLAUDE.md에 규칙 추가
    • ## 문서 서식 섹션에 세부 규칙 작성
  • 3. 마크다운 문서를 워드 문서로 전환 요청
  • 4. 서식 적용된 것 확인
References: Claude Code Docs · 기업 문서 표준화 가이드
2
Chapter 2

서브에이전트

복잡한 업무를 분담하는 AI 팀 운영법

서브에이전트 작동 방식
사용자 복잡한 작업 지시 메인 에이전트 계획 수립 · 조율 Sonnet 모델 Explore 에이전트 고속 읽기 전용 (Haiku) Plan 에이전트 실행 전 리서치 담당 커스텀 에이전트 파일 수정 · 초안 작성 독립 Context A .claude/worktrees/a/ 독립 Context B .claude/worktrees/b/ 독립 Context C .claude/worktrees/c/ 결과 통합 메인으로 반환 ※ 각 서브에이전트는 독립된 컨텍스트에서 동시(병렬) 실행됩니다
References: Claude Code overview — code.claude.com/docs
언제, 왜 쓰나요?
  • 맥락 격리 (Context Isolation)
    • 방대한 데이터 분석 결과가 메인 대화창을 어지럽히지 않음
  • 독립 워크트리
    • .claude/worktrees/에서 독립 작업
    • 파일 충돌 없이 동시 수정 가능
  • 비용 및 속도 최적화
    • Explore 에이전트는 Haiku(저비용) 모델 사용
메인 Context Window 깔끔하게 유지됨 위임 서브 Context A 독립 실행 서브 Context B 독립 실행 요약 결과 반환 .claude/ worktrees/ agent-a/ agent-b/ 파일 충돌 없음 맥락 격리 구조
References: Claude Code overview — code.claude.com/docs
Subagent 만드는 방법
  • .claude/agents 폴더 안에 .md 파일 추가
    • 각 파일이 하나의 서브에이전트가 됩니다
  • 호출 방식 선택 가능
    • @subagent_name — 명시적 호출
    • 자동 호출 — 메인 에이전트가 필요시 자동 호출
  • Subagent 파일은 구성을 위한 YAML frontmatter(오른쪽 마크다운 파일 상단 부분)를 사용하고 그 뒤에 Markdown의 시스템 프롬프트가 옵니다
agent.md 샘플
---
name: explore
description: 고속 읽기 전용 탐색
model: claude-haiku-4-5
---

# Explore 에이전트

코드베이스를 빠르게 탐색합니다.

## 기능
- 파일 패턴 검색
- 기호 위치 파악
- 의존성 분석
활용 사례
  • 일상 업무: 이메일 분류 + 답장 초안 동시 처리
    • 에이전트 A: 수백 개 이메일을 카테고리별로 분류
    • 에이전트 B: 우선순위 이메일 답장 초안 작성
  • 리서치: 조사 + 보고서 작성 병렬 진행
    • 에이전트 A: 경쟁사 웹사이트 조사
    • 에이전트 B: 사내 보고서 양식에 맞게 정리
  • 창의적 토론: 낙관론자 vs 비관론자 에이전트
    • 사업 계획의 장단점을 두 관점에서 동시에 검토
  • 수업 콘텐츠 저장 [데모]
  • 자동 채점 [데모]
References: Claude Code Docs · IBM HR AI 활용 가이드
실습 1 — 명함 생성 에이전트
  • 1. Google 스타일 명함 HTML로 만들어줘
    • 클로드에게 기본 명함 HTML 요청
  • 2. 만들어진 HTML 확인 후 글씨 크기, 배치, 색상 톤 수정 요청
    • UI/UX 피드백을 통한 반복 개선
  • 3. 만족스러운 결과가 나오면 "지금 한 작업을 수행할 수 있는 서브에이전트를 이 프로젝트 폴더에 만들어줘"
    • 작업을 자동화하는 서브에이전트 생성
  • 4. 새로운 대화를 시작하고 맥락을 클리어 후 "홍길동/010-1234-1234로 명함 작성해달라고" 요청 (엑셀에 명부 전달 후 병렬 처리도 가능)
    • 서브에이전트가 독립적으로 작동하는지 검증
  • 5. 구글 디자인 명함을 잘 만들어냄
    • 서브에이전트 자동화 완성!
References: Subagent 실습 가이드 · Claude Code Docs
실습 2 — 외부 서브에이전트 사용하기
  • 1. https://github.com/VoltAgent/awesome-claude-code-subagents에는 여러 유용한 서브에이전트가 있음
  • 2. 10. Research & Analysis 항목에 research-analyst 서브에이전트 링크 클릭
  • 3. https://github.com/VoltAgent/awesome-claude-code-subagents/blob/main/categories/10-research-analysis/research-analyst.md 내용을 복사해서 직접 .md로 저장하거나, 클로드 코드에게 링크를 건내주고 프로젝트 폴더에 서브에이전트 저장해달라고 요청
  • 4. 새로운 대화를 시작한 후, "@research-analyst 앤트로픽의 미소스에 대해 조사해줘" 라고 요청
  • 5. 리서치 서브에이전트가 소환되어 조사하는 것을 확인
References: awesome-claude-code-subagents — GitHub
3
Chapter 3

스킬 (Skills)

반복 업무를 /명령어 하나로 자동화하기

스킬 — 무엇이고 어떻게 작동하나요?
  • 스킬은 자주 반복되는 업무 프로세스를 저장하고 나중에 꺼내 쓰는 방법
  • SKILL.md 파일로 정의된 패키지 지식
    • YAML 영역: 이름, 설명, 허용 도구
    • Markdown 영역: 구체적인 업무 매뉴얼(SOP)
  • 저장 위치
    • 개인: ~/.claude/skills/
    • 팀 공유: .claude/skills/
    • 폴더 구조: ~/.claude/skills/skill_name/SKILL.md
    • 선택적 폴더: assets/, references/, scripts/
  • /명령어로 즉시 실행 (자동 호출도 가능)
SKILL.md name: brief description: 3줄 요약 스킬 — SOP 내용 — 사용자 /brief 스킬 탐색 ~/.claude/skills/ .claude/skills/ SKILL.md 로드 AI 실행 SOP 따라 작업 수행 결과 출력 3줄 요약 + 행동 지침 자동 생성 /brief report.md /draft-email 김철수 보안관제 /slide week2.md
SKILL.md 작성 예시
---
name: brief
description: 문서를 3줄 요약과 1개의 행동 지침으로 정리합니다.
---

# Brief 스킬

## 지침
1. 인자로 받은 파일을 읽습니다.
2. 핵심 내용을 3줄로 요약합니다.
3. 가장 중요한 행동 지침 1개를 제안합니다.
4. 형식: **요약:** ... / **행동:** ...

## 사용법
/brief [파일명]   예) /brief report.md
description 까지는 항상 로딩되고, 나머지는 필요할 때 차차 로딩 (context 효율성 좋음)
스킬 활용 사례
  • 요약 스킬 /brief
    • 회의록, 보고서를 3줄 + 행동 지침으로 즉시 정리
  • 이메일 초안 스킬 /draft-email 이름 직무
    • 면접 제안 메일을 이름·직무 인자로 자동 작성
  • 슬라이드 메이커 /slide
    • 마크다운 → 완성된 HTML 슬라이드 자동 변환
  • 문서 변환 (Big Four): /docx /xlsx
    • Md → Word, 보고서 자동화, 영수증 처리
References: Extend Claude with skills — code.claude.com/docs
실습 1 — K-스킬 설치하기
  • 1. https://github.com/NomaDamas/k-skill에는 다양한 K-skill이 존재
  • 2. geeknews-search 클릭
  • 3. 클로드 코드에게 https://github.com/NomaDamas/k-skill/tree/main/geeknews-search 링크를 전달해주며 현재 프로젝트 폴더에 스킬 저장해달라고 요청
  • 4. 클로드 코드 새로운 대화 시작
  • 5. geeknews에 올라온 최신 뉴스 피드 5개 알려줘 → 사이트 통해 정보 확인
References: k-skill — GitHub
실습 2 — Skill Creator (메타 스킬)
  • 1. https://github.com/anthropics/skills/tree/main/skills에는 앤트로픽 공식 스킬이 있음
  • 2. skill-creator 클릭 (스킬 잘 만들어주는 스킬임)
  • 3. https://github.com/anthropics/skills/tree/main/skills/skill-creator 링크를 주고 "유저 폴더에" 저장해달라고 요청
  • 4. 새로운 대화를 시작한 후 md 파일을 기반으로 html 슬라이드 덱을 만드는 스킬을 만들어달라고 요청
  • 5. 실행 → 결과 확인 → 스킬 개선 요청 → 반복
References: Anthropic Official Skills — GitHub
4
Chapter 4

MCP

Claude를 외부 세상과 연결하는 보편적 포트

MCP 아키텍처 — Host · Server · External
HOST Claude Code AI Engine 사용자 인터페이스 JSON-RPC 2.0 stdio / SSE MCP SERVER 연결 통로 Notion Server Google Sheets Server Playwright Server 필요한 내용만 처리 후 전달 Notion 정책 위키 · 문서 Google Sheets 채용 데이터 · HR Web / 파일 검색 · 파일시스템 보안 포인트 민감한 데이터가 AI 서버로 통째로 넘어가지 않음 내 컴퓨터 내에서 필요한 정보만 처리 후 결과만 전달 로컬 리소스: stdio 방식 (고속) 원격 리소스: SSE 방식 (실시간 스트리밍)
References: Google Cloud MCP Guide · Model Context Protocol — Wikipedia
MCP 활용 사례
  • Notion: 문서 검색 및 요약
    • "정책 위키에서 재택근무 규정을 찾아 마크다운으로 저장해"
  • Google Sheets: 실시간 데이터 편집
    • "15행 지원자 면접 상태를 '합격'으로 변경해"
  • 파일시스템: 파일 탐색 자동화
    • "문서 폴더에서 '계약서' 단어가 들어간 파일 목록 만들기"
  • Playwright: 웹 자동화
    • "주변 맛집 5곳을 구글 맵 링크 + 대표 메뉴로 정리해"
MCP 없이 AI 과거 학습 지식 (오래된 정보) 환각(Hallucination) "아마도 이럴 것…" vs MCP 사용 실시간 데이터베이스 직접 조회 정확한 최신 데이터 환각 방지 stdio 방식 로컬 시스템 리소스 파일시스템 · 로컬 앱 빠른 속도 프로세스 간 통신 SSE 방식 원격 리소스 Notion · Sheets · API 실시간 스트리밍 Server-Sent Events
References: Google Cloud MCP Guide · modelcontextprotocol/servers — GitHub
실습 1 — 노션 데이터베이스에 주식 정보 자동 기록
  • 1. notion mcp server 검색 후 설치 (설치 스콥 확인) → 클로드 코드에게 링크 전달하며 mcp 설치해달라고 요청
  • 2. Notion API 토큰 발급 (notion.so → Settings → Integrations) 및 DB/페이지 정보 확보
  • 3. 클로드 코드 새로운 대화 시작 (MCP 서버 로드)
  • 4. 클로드에게 요청: "오늘 삼성 전자(005930) 주식 가격을 조회해서 노션 데이터베이스에 Date/Stock/Price 칼럼으로 기록해줘"
  • 5. 노션 페이지 확인 → 자동으로 주식 정보가 기록된 것을 확인
  • Notion MCP 설치
  • Notion 스킬
References: Notion MCP 설치 · Notion 스킬 · Notion API Integration · MCP Notion Server Setup
실습 2 — Playwright MCP로 쿠팡 장바구니 자동화
  • 1. Playwright MCP: 웹 브라우저 자동화를 통한 웹 크롤링 및 상호작용
  • 2. MCP 설정: ~/.claude/mcp-servers.json에 Playwright 서버 추가 → 클로드 코드에게 링크 전달하며 playwright mcp 설치해달라고 요청
  • 3. 클로드 코드 새로운 대화 시작 (Playwright MCP 로드)
  • 4. 요청: "쿠팡(coupang.com)에서 에어팟(AirPods) 검색 → 최저가 상품 찾아서 → 장바구니에 담아줘"
  • 5. 자동 수행 확인
    • 사이트 접속 → 검색 → 가격순 정렬 → 최저가 상품 클릭 → 장바구니 추가
  • Playwright MCP 설치
References: Playwright 설치 · Playwright MCP · Web Automation with Claude
언제 스킬을, 언제 서브에이전트를 쓸까?
  • 스킬
    • 매번 같은 형식으로 처리 (회의록 정리, 보고서 양식)
    • /명령어 하나로 즉시 실행
    • 판단 거의 없음 → 반복 업무 자동화
  • 서브에이전트
    • 조사, 분석, 비교처럼 생각을 많이 해야 할 때
    • 여러 파일·정보를 아우르는 복잡한 업무
    • 독립 컨텍스트에서 병렬 처리 → 맥락 깔끔함
  • 합치면 최강
    • 서브에이전트로 분석 결과를 낸다 → 스킬로 정해진 형식에 담는다
References: agent-vs-skill.md · Week 2 실습 가이드
비교표 — 언제 뭘 쓸까?
구분 스킬 서브에이전트
역할 반복 업무 표준화 복잡한 작업 전문가
사용 시기 형식이 정해진 일 조사·분석·판단 필요
호출 /skill [인자] @agent 설명
예시 회의록 정리
보고서 양식 통일
경쟁사 분석
시장 조사
합치면 최강: 서브에이전트로 분석 결과 도출 → 스킬로 정해진 형식에 담기
References: agent-vs-skill.md · 실무 워크플로 · Week 2 퀘스트 3·4 안내
오늘 배운 것 — 4가지 핵심 도구
  • CLAUDE.md — AI 운영 지침서
    • 페르소나·보안·서식 규칙을 한 번만 설정, 세션마다 자동 로드
  • 서브에이전트 — AI 팀 운영
    • 복잡한 업무를 병렬 처리, 맥락 격리로 효율 극대화
  • 스킬 — 반복 업무 자동화
    • /명령어 하나로 SOP를 즉시 실행, 팀 전체 공유 가능
  • MCP — 외부 시스템 연결
    • Notion·Sheets·웹 등 실시간 데이터와 안전하게 연동
References: Claude Code overview — code.claude.com/docs · Week 2 가이드 문서