leean.dev

Claude Code에 일 가르치기

Sat, 10 Oct 2026 00:00:00 GMT

Claude Code를 쓰다 보면 "플러그인 깔았어요", "스킬 하나 만들었어요", "훅 걸어 뒀어요" 같은 말을 자주 듣게 됩니다. 개발자끼리는 익숙한 말이지만, 처음 보는 사람에게는 다 비슷하게 들립니다.

이 글은 그 네 가지를 개발 지식 없이 이해하는 것을 목표로 합니다. 각각이 무엇인지, 어떻게 설치하는지, 설치가 됐는지 어떻게 확인하는지까지 다룹니다. 설치는 명령어를 외우지 않고 Claude에게 말로 시키는 방법을 위주로 적었습니다.

다음 두 글에서는 제가 실제로 쓰고 있는 것들을 골라 소개합니다. 이 글은 그 글들을 읽기 위한 준비편입니다.

먼저, Claude Code는 새로 온 비서다

Claude Code는 내 컴퓨터 안에서 일하는 AI 비서라고 생각하면 됩니다. 말로 부탁하면 파일을 열어 보고, 고치고, 프로그램을 실행합니다.

이 비서는 똑똑하지만 우리 집(내 컴퓨터, 내 일하는 방식)에 대해서는 아무것도 모르는 상태로 출근합니다. 그래서 매번 "보고서는 이 양식으로", "끝나면 꼭 이것 확인해" 같은 말을 반복하게 됩니다.

네 가지 확장은 이 반복을 줄이는 도구입니다. 비유로 정리하면 이렇습니다.

이름	비유	한 줄 설명
스킬	업무 매뉴얼	특정 일을 할 때 꺼내 보는 절차서
hooks	사무실 규칙과 알람	정해진 순간에 비서가 잊어도 무조건 실행되는 규칙
플러그인	입사 선물 세트	매뉴얼, 규칙, 도구를 한 상자에 담아 한 번에 설치
mods	책상과 모니터 꾸미기	Claude Code 화면과 표시 방식 자체를 바꾸는 것

하나씩 보겠습니다.

스킬: 업무 매뉴얼

스킬은 "이런 일을 할 때는 이렇게 해라"를 적어 둔 문서입니다.

회사에 새로 온 사람에게 "회의록은 이 순서로 정리해", "보고서 문체는 이렇게 맞춰"라고 매번 말하는 대신, 매뉴얼을 서랍에 넣어 두는 것과 같습니다. 비서는 평소에는 매뉴얼 제목만 알고 있다가, 관련된 일이 들어오면 그 매뉴얼을 꺼내 읽고 그대로 따릅니다.

예를 들면 이런 스킬이 있습니다.

어려운 내용을 듣는 사람 수준에 맞춰 쉽게 풀어 주는 스킬(이 글도 그 스킬로 다듬었습니다)
한국어 문서에서 "AI가 쓴 티"를 걷어내는 스킬
블로그 글의 표지 이미지를 만드는 스킬

실체는 폴더 하나에 든 글 문서(SKILL.md)입니다. 프로그램이 아니라 글이라서, 개발자가 아니어도 직접 만들고 고칠 수 있습니다.

핵심: 스킬은 비서가 "필요할 때 스스로 꺼내 보는" 지식입니다. 꼭 따른다는 보장은 없습니다. 상황을 잘못 판단하면 매뉴얼을 안 꺼낼 수도 있습니다.

hooks: 사무실 규칙과 알람

hooks는 정해진 순간에 자동으로 실행되는 규칙입니다.

스킬과의 차이가 중요합니다. 스킬은 비서가 판단해서 꺼내 보는 것이고, hooks는 비서의 판단과 상관없이 무조건 돌아갑니다. 사무실 출입문에 달린 출입 카드 확인기에 가깝습니다. 직원이 깜빡해도 문은 카드를 확인합니다.

"정해진 순간"에는 이런 것들이 있습니다.

비서가 답변을 끝내려는 순간
비서가 파일을 고치기 직전이나 직후
내가 메시지를 보낸 순간
작업을 시작하거나 끝낸 순간

제가 실제로 쓰는 예를 들면, 비서가 답변을 끝내려는 순간 답변 속 링크가 실제로 열리는지 검사하는 hook이 있습니다. 죽은 링크가 있으면 답변을 끝내지 못하게 막고 고치라고 돌려보냅니다. "링크를 꼭 확인해"라고 매번 말하는 대신, 확인을 건너뛸 수 없게 만든 것입니다.

핵심: "꼭 지켜야 하는 것"은 스킬보다 hooks로 만듭니다. 매뉴얼은 안 읽을 수 있어도 출입문은 피해 갈 수 없습니다.

플러그인: 입사 선물 세트

플러그인은 스킬, hooks, 명령어, 외부 도구 연결을 한 상자에 담은 묶음입니다.

누군가 "이렇게 일하면 편하다"는 방식을 통째로 포장해 둔 것입니다. 상자 하나를 설치하면 그 안의 매뉴얼과 규칙이 한꺼번에 들어옵니다. 지우고 싶을 때도 상자째 뺍니다.

플러그인은 "마켓플레이스"라는 진열대에서 고릅니다. Anthropic이 운영하는 공식 진열대가 있고, 개인이나 회사가 만든 진열대도 있습니다. 앱 스토어와 비슷하다고 생각하면 됩니다.

핵심: 처음에는 스킬이나 hooks를 직접 만들기보다, 잘 만든 플러그인을 하나 설치해서 써 보는 것이 빠릅니다.

mods: 책상과 모니터 꾸미기

mods는 Claude Code 화면 자체를 바꾸는 확장입니다.

앞의 셋이 비서의 "일하는 방식"을 바꾼다면, mods는 비서가 일하는 "모습이 보이는 방식"을 바꿉니다. 화면 아래 상태 표시, 입력창 위의 안내 띠, 작업 중에 나오는 문구 같은 것들입니다.

예를 들어 저는 작업 중 문구를 "생각 중", "실행 중" 같은 한국어로 바꾸고, 비서의 기억 공간이 얼마나 찼는지를 날씨(맑음, 구름, 소나기, 폭풍)로 보여 주는 mod를 만들어 씁니다. 대화가 길어져 비서가 앞의 내용을 잊기 시작할 때가 되면 날씨가 나빠지니 한눈에 알 수 있습니다.

핵심: 일의 결과는 바뀌지 않지만, 지금 무슨 일이 일어나는지 보기가 편해집니다. 넷 중에서는 가장 마지막에 손대도 되는 것입니다.

설치하기: 명령어 대신 말로 시키기

네 가지 모두 Claude에게 말로 부탁해서 설치할 수 있습니다. 명령어를 몰라도 됩니다. Claude Code를 열고 이렇게 입력하면 됩니다.

플러그인 설치

공식 마켓플레이스에서 쓸 수 있는 플러그인 목록을 보여 주고, 각각 뭘 하는 건지 한 줄씩 설명해 줘.

방금 목록에서 ○○ 플러그인 설치해 줘.

직접 고르고 싶다면 입력창에 /plugin을 치면 설치 화면이 열립니다. 방향키로 고르고 Enter를 누르면 됩니다.

스킬 만들기

내가 회의 녹음 정리를 자주 하는데, 회의록을 항상 "결정 사항, 할 일, 담당자" 순서로 정리하는 스킬을 만들어 줘. 모든 프로젝트에서 쓸 수 있게 해 줘.

남이 만든 스킬을 가져올 때는 이렇게 부탁합니다.

이 GitHub 주소에 있는 스킬을 내 전역 스킬로 설치해 줘. 설치 전에 그 스킬이 무슨 일을 하는지 먼저 요약해 줘.

hook 만들기

답변을 끝낼 때마다 답변에 들어 있는 링크가 실제로 열리는지 검사하는 hook을 만들어 줘. 열리지 않는 링크가 있으면 답변을 끝내지 말고 고치게 해 줘.

mod 만들기

작업 중에 나오는 문구를 한국어로 바꾸는 mod를 만들어 줘.

설치하거나 만든 뒤 바로 반영되지 않으면 Claude Code를 껐다가 다시 켜면 됩니다.

설치됐는지 확인하기

설치했다고 끝이 아닙니다. 실제로 들어왔는지 확인하는 방법입니다.

확인할 것	방법
플러그인	입력창에 `/plugin`을 치고 설치된 목록을 봅니다
hooks	입력창에 `/hooks`를 치면 어떤 순간에 무엇이 걸려 있는지 나옵니다
스킬	Claude에게 "지금 쓸 수 있는 스킬 목록 보여 줘"라고 묻습니다
mods	화면이 바뀌었는지 눈으로 확인합니다. 안 바뀌었다면 Claude에게 "○○ mod가 왜 안 보이는지 확인해 줘"라고 묻습니다

가장 확실한 방법은 직접 시험해 보는 것입니다. 회의록 스킬을 만들었다면 회의 메모를 하나 던져서 정한 순서대로 나오는지 봅니다. 링크 검사 hook을 만들었다면 일부러 틀린 링크를 넣어 달라고 해서 막히는지 봅니다.

설치 전에 한 번 생각할 것

플러그인과 hooks는 내 컴퓨터에서 프로그램을 실행할 수 있습니다. 앱을 아무 데서나 받지 않듯이, 이것도 출처를 보고 설치하는 편이 안전합니다.

공식 마켓플레이스나 많이 쓰이는 저장소의 것부터 씁니다.
남이 만든 스킬이나 플러그인은 설치 전에 Claude에게 "이게 무슨 일을 하는지, 내 파일을 어디까지 건드리는지 요약해 줘"라고 먼저 물어봅니다.
한꺼번에 많이 설치하지 않습니다. 하나씩 넣고 써 보면 무엇이 효과가 있는지 알 수 있습니다.

정리

스킬: 비서가 필요할 때 꺼내 보는 업무 매뉴얼
hooks: 비서가 잊어도 반드시 돌아가는 규칙
플러그인: 매뉴얼과 규칙을 한 상자에 담은 선물 세트
mods: Claude Code 화면을 내 취향대로 바꾸는 것

시작은 플러그인 하나를 설치해 써 보는 것으로 충분합니다. 다음 글에서는 제가 매일 쓰는 플러그인 중 추천할 만한 것들을 골라 소개합니다.

AI한테 내 돈을 맡겨도 될까?

Fri, 09 Oct 2026 00:00:00 GMT

주식 자동매매 프로그램을 혼자 만들고 있습니다. 뉴스와 공시가 뜨면 AI가 읽고 "이건 호재다, 오래 갈 재료다"를 판단하고, 조건이 맞으면 사고팝니다.

만들면서 가장 오래 고민한 질문은 하나였습니다. AI한테 주문 버튼까지 줘도 될까? 결론은 "안 준다"였습니다. AI는 판단하고 제안까지만 합니다. 돈이 실제로 나가는 길은 미리 정한 규칙대로만 움직이는 코드가 지킵니다.

먼저 밝혀 둘 것이 있습니다. 이 프로그램은 아직 실제 돈으로 거래하지 않았습니다. 10월 12일에 처음 켜고, 11월에 증권사 모의투자로 2주를 돌린 뒤 실전 여부를 정합니다. 그래서 이 글은 "써 보니 안전했다"가 아니라 "맡기지 않도록 이렇게 설계했다"는 기록입니다.

10월 9일 덧붙임: 일정을 3주 앞당겼습니다. 10월 12일 주에 증권사 모의서버로 리허설을 하고, 10월 19일부터 모의투자 2주를 돌립니다.

비유로 보면: 애널리스트와 회계팀

회사에 비유하면 이렇습니다.

애널리스트(AI): 뉴스를 읽고 의견을 냅니다. "이 공시는 호재일 확률 80%" 같은 식입니다. 의견은 내지만 회사 통장에는 손을 못 댑니다.
회계팀(코드): 정해진 규정대로만 돈을 움직입니다. 애널리스트가 아무리 확신해도 한도를 넘는 지출은 결재하지 않습니다.
팀장(AI): 하루가 끝나면 성적표를 보고 "내일은 이 전략 비중을 줄이자"고 제안합니다. 다만 규정집 자체는 고칠 수 없고, 제안도 정해진 범위 안에서만 받아들여집니다.
사장(나): 규정집을 바꿀 수 있는 사람은 한 명뿐입니다.

AI가 두 자리에 앉아 있지만 둘 다 통장 비밀번호를 모릅니다. 이 구조가 글 전체의 요지입니다.

AI가 할 수 없게 막은 것

1. 주문을 직접 내는 것

AI 판단기는 숫자 몇 개만 돌려줍니다. 호재일 확률, 재료가 오래 갈 확률, 기사가 이 종목과 관련 있을 확률, 찌라시일 확률입니다. 이 숫자가 높아도 주문은 바로 나가지 않습니다. 코드가 정한 진입 조건을 통과하고, 그다음 리스크 검사까지 통과해야 주문이 나갑니다.

AI가 멈추면 새로 사는 것만 멈춥니다. 이미 산 종목의 손절과 익절은 코드가 계속 처리합니다.

2. 얼마나 살지 정하는 것

가격, 등락률, 수량, 날짜 계산은 전부 코드가 합니다. 언어 모델은 계산을 틀리기 쉽고, 틀려도 그럴듯하게 틀리기 때문입니다. AI에게는 "이 뉴스가 무슨 뜻인가"만 묻습니다.

3. 손실 한도를 바꾸는 것

손실 한도는 코드에 고정해 두었습니다.

한 종목이 3% 떨어지면 바로 팝니다.
하루에 계좌가 3% 줄면 그날은 새로 사지 않습니다.
한 주에 7% 줄면 매매를 멈춥니다.
15% 줄면 전부 멈추고, 제가 직접 풀기 전까지 다시 켜지지 않습니다.
한 종목에 계좌의 40%를 넘게 넣지 않고, 동시에 3종목까지만 들고 있습니다.

팀장 AI는 매일 전략의 목표 수익이나 손절 폭을 조정할 수 있습니다. 하지만 위 한도보다 느슨하게는 못 바꿉니다. 전략이 손절을 5%로 잡아도 실제로는 더 촘촘한 3%가 적용됩니다. 허용 범위를 벗어난 제안은 거부되고, 리포트에 "거부됨"으로 남습니다.

4. 열쇠를 보는 것

증권사 API 키, 공시 API 키, 알림용 주소 같은 비밀값은 AI가 도는 환경에서 아예 지운 채로 AI를 실행합니다. AI에게 넘기는 자료에도 넣지 않습니다. 보여 주지 않으면 실수로 흘릴 일도 없습니다.

5. 기사 속 "강력 매수"에 넘어가는 것

뉴스에는 "지금 사야 할 종목" 같은 홍보성 문구가 섞여 있습니다. AI는 이런 문장을 읽고 판단이 흔들릴 수 있습니다. 그래서 "이 기사는 찌라시인가"를 따로 묻고, 그 확률이 높으면 다른 점수가 아무리 좋아도 사지 않습니다.

그래도 AI가 틀린 순간들

막아 두었는데도 개발하는 동안 AI가 틀린 장면을 여러 번 봤습니다.

"4조원"이 "$4 Billion"이 됐습니다. 판단 모델이 영어로 읽을 때 더 정확해서 한국어 뉴스를 먼저 영어로 번역합니다. 그런데 번역 AI가 원화 금액을 달러로 바꿔 버렸습니다. 4조원은 약 30억 달러이니 규모가 엉뚱해집니다. 판단기는 번역문만 보기 때문에 아무도 모른 채 틀린 판단이 나올 수 있었습니다. 번역 지시에 "원화는 원 단위 그대로 두고 달러로 바꾸지 말라"를 넣어 고쳤습니다.

관련성 점수가 엉터리였습니다. "이 기사가 이 종목 이야기인가"를 0~1로 물었더니, 멀쩡한 기사에도 0.03~0.2가 나왔습니다. 질문 문구를 조금 바꾸면 점수가 크게 출렁였습니다. 기준을 0.7로 두면 거의 아무것도 사지 못합니다. 기준을 0.3으로 낮추고, 실제 기사 50건에 직접 정답을 붙여 다시 맞춰 보기로 했습니다. AI가 내는 점수는 믿는 숫자가 아니라 검증할 숫자라는 걸 여기서 배웠습니다.

AI가 읽으면 안 되는 파일을 읽을 수 있었습니다. 팀장 AI가 새 전략 코드를 쓰는 기능이 있습니다. 이때 AI가 수집한 뉴스 원문 기록과 로그인 토큰 파일까지 읽을 수 있다는 걸 뒤늦게 발견했습니다. 증권사 뉴스는 약관상 제3자에게 넘길 수 없는 자료라 문제가 됩니다. 해당 폴더를 읽기 금지 목록에 넣어 막았습니다.

약관 때문에 뉴스 출처를 뺐습니다. 처음에는 포털 뉴스 검색 API를 쓰려 했습니다. 약관을 읽어 보니 AI 입력과 저장을 금지하는 조항이 있었습니다. 그래서 공시(DART)와 증권사 뉴스 제목만 남겼습니다. AI에게 무엇을 보여 줄지는 보안 문제이기도 하지만 약관 문제이기도 했습니다.

돌아보면 주문 쪽 코드에서 고친 버그가 AI 쪽보다 더 많았습니다. 주문 응답이 사라졌을 때 같은 주문이 두 번 나가지 않게 하는 처리 같은 것들입니다. 규칙 기반 코드라고 저절로 안전해지지는 않습니다. 다만 규칙 코드는 테스트로 확인할 수 있고, 틀린 걸 찾으면 같은 방식으로 다시 틀리지 않습니다.

개발자용: 구조

여기부터는 설계 이야기입니다.

흐름

수집: DART 공시와 증권사(한국투자증권 KIS Open API) 뉴스 제목을 주기적으로 가져와 중복을 지우고 종목 코드를 붙입니다.
판단기: 한국어 기사를 로컬 LLM(Ollama, qwen3:8b)으로 영어로 번역한 뒤, 로컬 판단 모델(Laya)에 질문 묶음을 한 번에 던집니다. 질문은 방향, 지속성, 관련성, 찌라시 네 가지입니다. 재료의 강도는 AI에게 묻지 않고 규칙으로 정합니다(공시 3, 실적·계약 키워드 기사 2, 그 밖의 기사 1). 시험해 보니 AI가 매긴 강도는 기사마다 거의 같아서 변별력이 없었습니다.
전략 엔진: 전략마다 YAML로 진입 조건, 수량, 청산 규칙을 정의합니다. 판단기를 쓰지 않는 대조군 전략도 하나 같이 돌려서, AI 판단이 실제로 도움이 되는지 비교합니다.
리스크 게이트: 진입 직전에 한도를 검사합니다. 한도표는 변경 불가 dataclass로 두었고, 이 경로의 코드는 AI가 자동으로 고칠 수 없게 "보호 경로"로 지정했습니다.
주문: 멱등 키로 중복 주문을 막고, 응답이 유실된 주문은 다시 내지 않고 체결 조회로 확인합니다. 장부와 증권사 잔고가 다르면 증권사 잔고를 기준으로 맞춥니다.
장부와 리포트: 전략별 가상 장부에 비용을 뺀 손익을 기록하고, 장 마감 후 메일로 리포트를 보냅니다. 경고는 디스코드로 옵니다.
매니저: 장 마감 후 Claude Code를 헤드리스(claude -p)로 실행해 리포트를 읽히고, 전략 파라미터 변경안을 JSON 스키마로 받습니다. 엔진과는 파일과 DB로만 연결되어 있어서 Claude가 응답하지 않아도 매매는 계속됩니다.

모르면 멈춘다 (fail-closed)

애매할 때 어느 쪽으로 넘어질지를 정해 두었습니다.

기준 자산을 모르면 비상 정지로 취급합니다.
평균 매입가를 모르면 들고 있지 않고 청산 쪽으로 갑니다.
data/HALT 파일이 있으면 전부 멈추고, 사람이 해제 명령을 실행해야 다시 돕니다.
금지 종목 목록은 제가 파일로 쓰고, 엔진이 60초마다 다시 읽습니다.

리플레이: 수익이 아니라 안전을 보는 시험

증권사 조회 응답을 날짜별로 그대로 기록해 두고, 그 하루를 다시 재생할 수 있게 했습니다. 시계는 기다리지 않고 바로 다음 시각으로 넘어가고, 판단기는 저장된 응답을 다시 씁니다.

이 재생의 합격 기준은 수익이 아닙니다.

예외 없이 끝까지 돌아야 합니다.
한도를 넘는 주문이 0건이어야 합니다. 체결마다 한도표와 다시 대조합니다.
장부 합계가 맞아야 합니다.

AI가 쓴 코드를 받아들이는 관문

매니저 Claude는 새 종목 감지 로직을 코드로 제안할 수 있습니다. 이 코드는 사람 검토 없이 반영되지만, 기계 관문을 차례로 통과해야 합니다.

별도 git worktree에서 Claude가 작성합니다. 쓸 수 있는 파일은 플러그인 파일, 그 테스트, 전략 YAML뿐입니다. 셸은 pytest 한 줄만 허용하고, 커밋은 Claude가 아니라 빌더 코드가 합니다.
AST 정적 검사로 허용 목록 밖의 import, open, exec, eval, getattr, 이중 밑줄 접근을 거부합니다.
전체 테스트를 돌립니다.
리플레이를 통과해야 main에 병합되고, 디스코드로 알림이 옵니다.

AI가 고칠 수 있는 범위는 "종목을 찾아내는 로직"으로 한정했습니다. 판단, 진입, 청산, 수량, 리스크는 기존 부품을 YAML로 조립하는 것만 허용합니다.

솔직히 적어 둘 한계가 있습니다. 정적 검사는 우회 방법이 나올 때마다 막았습니다(별칭 import, while, del, BaseException 등). 그래도 이건 샌드박스가 아닙니다. 무한 루프나 아주 큰 range 같은 건 정적 검사로 못 막습니다. 그래서 문서에도 "격리가 아니라 매니저 AI의 실수를 막는 장치"라고 적어 두었습니다. 대신 실행 중에 플러그인 호출이 2초를 넘기거나 예외가 나면, 그날 그 전략의 신규 진입을 끕니다.

10월 12일 주에 리허설을 하고, 10월 19일부터 모의투자 2주를 돌립니다(처음 이 글을 쓸 때는 11월이었는데 3주 앞당겼습니다). 다음 글에서는 AI 판단이 실제로 대조군보다 나았는지, 리스크 게이트가 몇 번 막았는지를 숫자로 정리하겠습니다.

블로그를 열며, 왜 leean.dev인가

Fri, 09 Oct 2026 00:00:00 GMT

이 블로그에는 AI로 실제 일을 맡겨 본 기록을 씁니다. 개발을 몰라도 따라올 수 있게 쓰고, 깊은 설계 이야기는 글 뒤쪽에 따로 둡니다.

이런 글을 씁니다

AI로 해봤다: 일상과 업무에서 AI에게 일을 맡겨 본 결과
자동화 레시피: 반복 작업을 자동으로 돌리는 방법
만들면서 배운 것: 직접 만든 프로그램의 설계와 회고