Sign In

KAERI 클로드코드 특강

⭐️전부 제대로 안보이시는분⭐️
pdf파일:
claude-code-handson.pdf4.18MB
Loading PDF preview

아직 설치를 못했어요.

•
설치방법
•
claudecode install
◦
mac
◦
win
•
antigravity install : https://antigravity.google/
•
[advanced]cmux install(mac only) : https://cmux.com/ko
폴더 만들고 워크스페이스로 열기
윈도우 창 안에 사이드바 여러개를 둘 수 있음, 사이드바가 워크스페이스가 됨

1차시

바이브 코딩 툴 6종 비교표를 보고 Claude Code 를 선택하는 근거를 설명할 수 있다
대화형 세션 접두사(/ ! @)와 단축키(Shift+Tab, Ctrl+O, Ctrl+B, Esc Esc)를 실제로 사용할 수 있다

코딩에이전트 도구 비교

툴
실행 방식
에이전트
코드 실행
로컬 LLM
비용
Claude Code
CLI + IDE
O (서브·팀)
O
O (프록시)
Pro $20/월
Cursor
IDE 전용
O (Agent 탭)
O
제한적
$20/월
Windsurf (Codeium)
IDE 전용
O (Cascade)
O
X
$15/월
Cline / Roo Code
VS Code 확장
O
O
O
토큰 실비
Aider
CLI
X (페어)
O
O
토큰 실비
GitHub Copilot
IDE 확장
제한적
제한적
X
$10/월

대화형 세션 접두사 & 단축키

접두사
의미
예시
/
슬래시 명령 / 스킬
/model sonnet, /plan, /cost
!
셸 명령 실행 → 결과를 컨텍스트에 추가
! git status
@
파일 경로 자동완성
@src/app.py 이 파일 리뷰해줘
단축키
동작
Shift+Tab
권한 모드 토글 (Plan ↔ Accept Edits ↔ Default)
Ctrl+O
작업 상태 보기
Ctrl+B
실행 중 명령을 백그라운드로 전환
Esc Esc
이전 상태 롤백
자주쓰는 명령
명령
설명
/model
모델 전환 (haiku / sonnet / opus)
/effort
low | medium | high | max | auto
/plan
분석만 수행, 쓰기 금지
/context
현재 로드된 컨텍스트 시각화
/compact
대화 압축 (토큰 절약)
/clear
컨텍스트 초기화
/cost / /usage
비용·사용량 확인
/rewind
이전 체크포인트로 복원
/init
CLAUDE.md 자동 생성
/memory
자동 메모리 관리
/permissions
현재 권한 규칙 확인
/security-review
브랜치 변경분 보안 스캔
/resume
이전 세션 불러오기
/agents / /skills / /mcp / /hooks
에이전트·스킬·MCP·훅 관리

bypass 모드 —

claude가 한번에 일을 끝낼때까지 나는 신경쓰고 싶지 않다면 --dangerously-skip-permissions 를 붙입니다
--dangerously-skip-permissions 플래그를 붙이면 Claude Code가 파일 읽기·쓰기·명령 실행 등 모든 권한 확인 다이얼로그를 건너뜁니다. 비대화형으로 실행할 때 사용합니다.

2차시

"생각을 문서로" 첫 프롬프트 템플릿을 직접 작성할 수 있습니다
/plan 모드로 안전하게 코드베이스를 선조사할 수 있습니다
/rewind · /compact · /context로 세션을 관리할 수 있습니다
작업 완료 후 Claude Code에 git commit을 요청할 수 있습니다
CLAUDE.md 을 작성해달라고 하고 수정할 수 있습니다

STEP1. 계획 세우고 직접 해보기

Claude Code로 개발할 때 가장 효과적인 패턴은 계획 → 구현 → 검증의 반복입니다.
메모를 바탕으로 첫 프롬프트를 작성합니다.
목표 · 제약 · 출력 형식을 명시할수록 좋습니다.
아래 템플릿을 복사해 여러분의 프로젝트에 맞게 수정해 보세요.
https://huggingface.co/papers 에 들어가서
매일 올라오는 논문 제목과 초록을 수집해서 정리하는 도구를 만들어줘.

요구사항:
- Python 3.12, requests + BeautifulSoup
- 결과물: papers_YYYYMMDD.md (날짜별 마크다운)
- 실행: python collect_papers.py --date today
- 에러 처리: 네트워크 실패 시 3회 재시도
💡 팁: Claude Code 터미널에서 Shift+Tab을 누르면 Plan Mode와 Normal Mode를 전환할 수 있습니다. 첫 프롬프트 전에 Plan Mode로 전환해 선조사부터 시작하는 것을 권장합니다.
✍️ 직접 해보기
1.
Claude Code 터미널을 열고 Shift+Tab으로 Plan Mode를 켭니다.
2.
위의 첫 프롬프트 템플릿(또는 자신의 메모 내용)을 붙여넣고 Enter를 누릅니다.
3.
Claude가 파일 구조를 탐색하고 계획을 제안하는 과정을 관찰합니다.
4.
Claude의 응답에서 잘못된 전제나 빠진 요구사항이 있으면 바로 피드백합니다.
/plan(또는 Plan Mode)은 Claude가 읽기만 하고 아무것도 수정하지 않는모드입니다.
복잡한 코드베이스를 처음 분석하거나, 대규모 리팩토링 전 영향 범위를 파악할 때 필수입니다.
구분
도구
상태
비활성화 (쓰기 차단)
Edit · Write · Bash
🔴 사용 불가
활성화 (탐색 허용)
Read · Grep · Glob · WebFetch
🟢 사용 가능
주요 활용처
복잡한 코드베이스 아키텍처 감사, 파일 간 의존성 파악, 안전한 설계 변경 계획 수립
—
⚠️ 주의: Plan Mode에서 "좋아 보인다"는 응답을 받았다고 곧바로 Normal Mode로 전환하지 마세요. 반드시 계획 내용을 직접 읽고 검토한 뒤 실행하세요.
✍️ 직접 해보기
1.
Shift+Tab으로 Plan Mode를 확인합니다 (하단 상태바에 "plan mode on" 표시).
2.
다음 프롬프트를 입력합니다: 작업 계획을 단계별로 작성해줘
3.
Claude가 제안한 계획을 읽고, 누락된 부분이나 위험한 부분을 댓글로 피드백합니다.
4.
계획에 동의하면 Shift+Tab으로 Normal Mode로 전환하고 구현을 시작합니다.

STEP2 · /rewind · /compact · /context — 세션 관리도구 써보기

Claude Code 세션은 길어질수록 토큰이 쌓이고 약 1시간 후부터 응답 품질이 급락합니다.
아래 네 가지 도구를 상황에 맞게 써서 세션을 건강하게 유지하세요.
명령
트리거 상황
동작
/context
AI가 맥락을 잃었다고 느껴질 때
현재 로드된 토큰 수와 활성 파일을 시각화하여 점검
/compact
토큰 한도 80% 근접 시
핵심 주제만 요약으로 보존하고, 중간 대화 내역을 영구 삭제
/rewind N
잘못된 방향으로 수정됐을 때
N단계 이전으로 코드와 맥락을 동시에 복원
Esc 두 번
방금 내린 지시를 취소하고 싶을 때
중간 편집을 전부 롤백하고 대화 요약만 유지
⚠️ 주의: /compact는 중간 대화를 영구 삭제합니다. 중요한 결정 사항이나 참고해야 할 중간 결과물은 반드시 파일로 저장한 뒤 실행하세요.
/export save to file로 저장합니다.
✍️ 직접 해보기
1.
Claude Code에서 논문 수집 도구 구현을 약 90% 진행합니다.
2.
/context를 입력해 현재 토큰 사용량을 확인합니다.
3.
토큰이 60% 이상이면 /compact를 실행하고, 요약 내용이 올바른지 확인합니다.
4.
나머지 10% 구현을 이어서 완료합니다.
5.
구현 도중 잘못된 방향으로 갔다면 /rewind 3으로 3단계 전으로 돌아가 보세요.

STEP 3 · git 활용 — 작업 완료 후 커밋 요청하기


슬라이드 5 · git 활용 실제 화면 — 자연어로 "이제 푸쉬해"라고 요청하면 Claude가 git push를 실행합니다
작업 단위가 끝날 때마다 Claude Code에 로컬 git commit을 요청하세요.
Claude는 변경 파일 목록을 파악하고, 의미 있는 커밋 메시지를 자동으로 작성합니다.
모든 기능 구현이 완료된 후에는 push와 배포도 요청할 수 있습니다.
# 커밋 요청 예시
지금까지 구현한 논문 수집 도구를 git commit 해줘.
커밋 메시지는 Conventional Commits 형식(feat: ...)으로 작성해줘.

# 푸시 요청 예시
좋아, 로컬 커밋 완료됐으면 이제 origin main으로 push해줘.
✍️ 직접 해보기
1.
논문 수집 도구 구현이 완료되면 Claude Code에 다음과 같이 요청합니다.
지금까지 작업한 내용을 git commit 해줘. feat: add HuggingFace papers crawler 형식으로.
1.
Claude가 제안하는 커밋 메시지와 파일 목록을 확인합니다.
2.
이상이 없으면 승인하고, 잘못된 파일이 포함됐다면 제외를 요청합니다.
3.
(실습 환경에서 가능하다면) push까지 요청해 결과를 확인합니다.

STEP 4 · CLAUDE.md — 작업 규칙 파악하기

CLAUDE.md는 프로젝트 루트에 두는 AI용 작업 규칙서입니다.
Claude Code는 세션을 시작할 때 이 파일을 자동으로 읽어 컨텍스트로 사용합니다.
300줄 이하로 간결하게 유지하는 것이 핵심입니다.
# KAERI reactor-sim — 작업 규칙

## 기본
- Python 3.12, `uv` 패키지 매니저, FastAPI 0.115
- 타입힌트 필수, mypy strict
- 테스트: `uv run pytest` (pytest-asyncio 사용)

## 코드 스타일
- 공용 상수는 app/constants.py
- 도메인/리포 분리 유지 (app/domain, app/repo)
- raw SQL 금지 — SQLAlchemy 2.0 Core 사용

## 커밋
- Conventional Commits (feat/fix/refactor/test/docs)
- 커밋 전 mypy + pytest 통과 확인

## 금지
- YOU MUST NOT commit .env 또는 secrets/
- 외부 네트워크 호출 추가 금지 (방화벽 deny)
💡 팁: CLAUDE.md를 처음 만들 때 Claude Code에 "이 프로젝트의 CLAUDE.md 초안을 작성해줘"라고 부탁하면 코드베이스를 탐색해서 초안을 만들어 줍니다. 이후 팀과 함께 다듬으세요.
⚠️ 주의: CLAUDE.md가 너무 길면 오히려 중요한 규칙이 묻힙니다. 300줄을 넘기 시작하면 덜 중요한 내용을 과감히 삭제하거나 별도 파일로 분리하세요.
✍️ 직접 해보기
1.
실습 프로젝트 루트에서 Claude Code에게 요청합니다.
이 프로젝트의 CLAUDE.md 초안을 작성해줘.
Python 3.12, uv, pytest 사용 환경이고,
.env 파일 커밋 금지 규칙은 반드시 포함해줘.
1.
생성된 초안을 열어서 팀의 실제 규칙과 맞지 않는 항목을 수정합니다.
2.
CLAUDE.md를 git commit하고, 새 세션을 열어 규칙이 적용되는지 확인합니다.

STEP 5 · Q&A — Claude Code에 적합한 일 vs 부적합한 일

"Claude Code로 하면 좋은 일과 그렇지 않은 일은 무엇인가?"라는 질문에 대한 답입니다.
안전하게 맡기는 세 가지 팁도 함께 기억해 두세요.
✓ 적합
✗ 부적합
스펙이 문서화된 기능 구현
"알아서 잘 해줘" 스타일 모호 요청
테스트 주도 리팩토링
인간 판단이 필요한 설계 선택
코드베이스 탐색·설명
프로덕션 긴급 장애 대응
Git 워크플로우 자동화
규제 대상 크리티컬 로직 단독 작성
반복 패턴 처리 (비슷한 파일 여러 개)
승인 없는 외부 통신 추가
로그·에러 분석
도메인 지식 부재 영역
안전하게 맡기는 3가지 팁:
스펙을 파일로 먼저 작성 후 @스펙.md 형태로 참조하여 구현 요청
항상 Plan Mode로 선조사 후 Normal Mode로 실행
테스트 없는 코드 요청 금지 — 항상 테스트 코드를 함께 요청

STEP 6 · 2차시 정리 — 루브릭(평가표)을 미리 작성하자

2차시에서 배운 흐름을 한 줄로 정리하면 다음과 같습니다.
생각을 글로 표현  →  Claude Code의 응답 확인  →  커밋  →  배포
이 흐름에서 가장 중요한 단계는 "응답 확인"입니다.
Claude Code가 올바른 결과를 냈는지 판단하려면 도메인 지식이 필요합니다.
도메인을 모르면 잘못된 코드를 승인하게 됩니다.
따라서 구현을 시작하기 전에 평가 기준을 먼저 작성해 두세요.
이것을 **루브릭(채점표)**이라고 합니다.
# collect_papers.py 검수 루브릭

## 기능 검증 (각 항목: Pass / Fail)
- [ ] --date today 실행 시 오늘 날짜 논문 수집됨
- [ ] papers_YYYYMMDD.md 파일이 생성됨
- [ ] 논문 제목과 초록이 모두 포함됨
- [ ] 네트워크 실패 시 3회 재시도 후 에러 메시지 출력
- [ ] .env 파일 없이도 실행 가능

## 코드 품질
- [ ] mypy strict 통과
- [ ] pytest 전체 통과
- [ ] 함수 단위 분리 (스크래핑 / 파싱 / 저장 분리)

## 보안
- [ ] 하드코딩된 URL 외 외부 통신 없음
- [ ] 비밀키 코드에 없음
✍️ 직접 해보기
1.
자신의 프로젝트에 맞는 루브릭 파일(rubric.md)을 작성합니다.
2.
Claude Code로 기능을 구현한 뒤, 루브릭의 각 항목을 직접 테스트합니다.
3.
모든 항목이 Pass이면 git commit을 요청합니다.
4.
루브릭과 함께 배운 전체 워크플로우를 팀원에게 설명해 보세요.

2차시 마무리 체크리스트

아이디어를 메모 파일(컨셉.md 등)로 먼저 정리했습니다
Plan Mode(Shift+Tab)로 선조사한 뒤 구현을 시작했습니다
/context로 토큰 사용량을 확인하고 /compact를 실행했습니다
작업 완료 후 Claude Code에 git commit을 요청했습니다
프로젝트 루트에 CLAUDE.md를 300줄 이하로 작성했습니다
구현 전에 루브릭(평가표)을 미리 작성했습니다
적합/부적합 작업 구분 기준을 팀과 공유했습니다

3차시 — MCP · Skills · 커스텀 에이전트

내 도구 만들기 · 외부 시스템 연결 — SKILL.md 한 파일로 슬래시 명령을 정의하고, MCP로 외부 시스템을 연결합니다.

슬라이드 1 · 3차시 타이틀 — 내 도구 만들기 · 외부 시스템 연결

이번 차시에서 할 일

이번 차시에서는 Claude Code의 확장 메커니즘 두 가지, Skills와 MCP를 사용하고 Skills를 직접 만들어 봅니다. 반복 작업을 슬래시 명령으로 자동화하고, 외부 시스템(법령 DB, GitHub, PostgreSQL 등)을 Claude Code 안으로 끌어들이는 방법을 익힙니다.
Skills(SKILL.md)의 개념과 저장 위치별 범위를 설명할 수 있다
3줄짜리 SKILL.md를 직접 작성해 슬래시 명령으로 호출할 수 있다
skill-creator 플러그인으로 워크플로우를 스킬화할 수 있다
스킬 vs 서브에이전트 차이를 구분해 적절히 선택할 수 있다
.mcp.json을 작성해 팀과 MCP 설정을 공유할 수 있다

STEP 1 · Skills 개념 — SKILL.md 하나로 슬래시 명령 만들기


슬라이드 2 · Skills — 마이크로 자동화 아키텍처 (SKILL.md 개념 요약)

STEP 1 · 스킬로 스킬 만들기 — skill-creator 플러그인

✍️ 직접 해보기
1.
"주간 보고서 초안 작성 워크플로우를 스킬로 만들고 싶습니다"처럼 목적을 설명합니다.
2.
Claude의 인터뷰 질문에 응답하여 제출합니다.
3.
작업이 마무리 되면 스킬로 만들어달라고 합니다.

STEP 2 · 추천 스킬 — 한글(HWP/HWPX) 문서 스킬


 hwpx-skill: HWP/HWPX 문서 생성·변환·읽기·편집 워크플로우 A~H

 hwpx-skill 출력 예시 — 재난관리계획 공문서 형식 HWP 생성 결과

hwpx-skill 출력 예시 — AI 교육 현황 진단 보고서 공공기관 형식
hwpx-skill은 마크다운/텍스트/URL을 HWPX 공문서로 변환하거나, 기존 HWPX를 편집하고, HWP 바이너리를 HWPX로 변환하는 Claude 스킬입니다. 공공기관에서 필수로 사용하는 한글 파일을 Claude Code로 자동 생성할 수 있어 공공기관 환경에서 특히 유용합니다.
워크플로우
설명
A
마크다운/텍스트/URL → HWPX 문서 생성
B
템플릿 플레이스홀더 치환
C
기존 HWPX 문서 편집 (unpack → 수정 → pack)
D
레퍼런스 HWPX 기반 새 문서 생성
E
HWPX 텍스트 읽기/추출
F
양식 복제 (테이블/이미지/스타일 100% 보존)
Made with Slashpage