Claude Code를 5주 더 쓰며 스킬과 CLAUDE.md를 키운 방식

1탄을 쓴 게 4월 1일이니 5주 정도 지났다. 그때 글의 마지막 인사이트가 "반복 작업은 스킬로 만들 것" 한 줄이었다. 그 한 줄이 이후 5주 동안 어떻게 굴러갔는지 정리해두려고 한다.

11일 회고는 결과 분석에 가까웠다. 549 메시지·42 세션·108 커밋 같은 수치가 중심이었고, 잘됐던 것·안됐던 것·인사이트가 각각 한 칸씩 차지했다. 이번 글은 그 후 운용 시스템을 어떻게 키워왔는지에 집중한다. 수치로 재측정하는 회고는 다음 편으로 미뤄두고, 여기서는 내가 어떤 스킬을 만들고, 어떤 룰을 박고, 어떤 식으로 자가 점검 절차를 안에 넣었는가를 다룬다.

5주 동안 박은 스킬 인벤토리

처음에 "스킬을 만들어라"는 추상적인 제안이었다. 막상 만들어보니 어떤 작업을 스킬로 떼어내야 하는지가 가장 어려웠다. 5주를 돌아보니 결국 세 번 이상 같은 설명을 반복하게 되는 작업이 스킬 후보였다. 다음은 실제로 박고 지금까지 살아 움직이는 스킬들이다.

가장 두껍게 진화한 blog-post-writer

이 글도 이 스킬로 쓰고 있다. 처음 만든 건 3월 25일, 단순히 "블로그 글 작성 가이드"였다. 5주가 지난 지금은 SKILL.md가 574줄이고 안티패턴이 A부터 I까지 9개 박혀 있다.

진화 이력만 봐도 무슨 일이 있었는지 짐작이 된다.

흥미로운 건 패턴이다. 처음에는 무엇을 쓸지(주제, 구조)에 대한 룰이었다가, 점점 어떻게 안 쓸지(안티패턴) 쪽으로 무게가 옮겨갔다. 이게 자연스럽다. 글을 한 편 쓸 때마다 "이번엔 이 함정에 빠졌네"가 새로 보이고, 그걸 스킬에 박아두면 다음 글에서는 같은 함정에 안 빠진다.

특히 마지막 두 변경(G/H/I)은 자가 점검 절차로 실행 단계 안에 박혀 있다.

9. 글 자가 점검 —
   - grep -n "~" <file>   (paragraph당 2개 이상이면 이스케이프)
   - grep -n "§" <file>   (잔존 시 평문으로 치환)
   - 영문 용어 직역 점검   (의심 단어만 WebSearch로 짧게 확인)

룰을 박는 것보다 자가 점검 단계를 박는 게 훨씬 효과적이다. 룰은 잊어버려도 점검 단계는 매번 실행되기 때문이다.

스킬을 넘어 npm 패키지가 된 dooray-cli

원래는 사내 협업 도구의 업무를 자동으로 처리하고 싶다는 단순한 동기였다. "이 업무 댓글 가져와", "주간 보고 댓글로 달아줘" 같은 요청이 반복되니 스킬로 떼어냈다.

만들다 보니 "이건 그냥 CLI로 묶는 게 낫겠다"는 결론에 도달했다. 결과물은 npm 패키지(@bifos/dooray-cli)로 publish됐고, 그 안에 자체 스킬을 동봉하는 구조다. 설치하면 CLI도 깔리고 스킬도 같이 따라오는 식이다.

npm install -g @bifos/dooray-cli
# 설치 후 ~/.claude/skills/dooray-cli가 패키지의 skills/dooray-cli로 심볼릭 링크

이 글을 쓰면서 사내 업무 댓글에서 Grafana 대시보드 이미지를 가져온 것도 이 도구다. 첨부파일 list, 댓글 list, file download가 한 줄씩 들어가서, **"Dooray 업무에서 이미지 빼서 블로그에 첨부"**가 한 세션 안에서 끝났다.

스킬을 만들다 외부 도구로 발전시킨 사례인데, 어떤 스킬은 결국 독립 도구로 가야 한다는 신호를 일찍 받아두는 게 낫다는 걸 배웠다. CLI가 따로 있으면 다른 환경(다른 컴퓨터, 다른 사용자)에서도 쓸 수 있다.

만든 당일에 효용을 입증한 docs-link-audit

저장소가 커지면서 broken link, orphan 문서, 백틱으로만 적힌 경로 같은 게 누적됐다. 한 번 정리한 뒤 또 누적되는 패턴이 보여서 스킬로 떼어냈다.

4가지 축으로 자동 스캔한다.

1. Unlinked path mention — 백틱으로만 적혀 있고 마크다운 링크가 아닌 경로
2. Broken link — [text](target)의 target이 실제로 존재하지 않음
3. Orphan doc — 어디에서도 참조되지 않는 .md 파일
4. Cross-link 후보 — 같은 키워드를 다루는데 상호 참조 없는 두 문서

만든 당일에 돌렸더니 broken 4건, orphan 23건, 구조 버그(README.md 폴더 안에 또 README.md가 들어 있는 케이스) 1건이 한 번에 잡혔다. 한 번에 정리하면서 **"애초에 이걸 자동화 안 해뒀으면 또 누적됐을 거다"**라는 확신이 들었다.

이게 스킬을 만들 만한지 판단하는 또 다른 기준 같다. 검증 사이클이 있는 작업은 쓰고 점검한 뒤 다시 쓰는 과정에서 점검 부분을 스킬로 떼어두는 게 거의 항상 이득이다.

사내 권한 신청을 자동화한 apms 세 종류

apms-iam-console-access, apms-linux-server-access, apms-nca-access 세 개. 사내 시스템에서 권한을 신청하는 폼 작성을 cmux 브라우저 자동화로 풀어냈다.

이 분야의 핵심 인사이트는 입력칸을 채우고 Enter를 누르는 것만으로는 폼이 동작하지 않더라는 거였다. JS 콜백을 직접 호출해야 autocomplete가 잡혔고, 권한 팝업은 snapshot에 안 잡혀서 eval로 직접 조작해야 했다. 한 번 길을 뚫어두면 같은 폼이 재출현할 때 다시 헤매지 않는다.

스킬에는 "어떤 input은 일반 fill로 안 되고 JS 콜백 직접 호출이 필요하다"는 핵심 인사이트가 박혀 있다. 같은 폼이 갱신되어도 이 인사이트가 살아남는 한 다음에 적응하기 쉽다.

채용 흐름을 연결한 job-analyzer와 resume-writer

채용 공고 URL을 받으면 회사 기술 블로그·공식 자료를 조사하고 본인 경력에 맞춰 직무 분석 문서를 만드는 게 job-analyzer. 그 결과를 받아 회사·직무 맞춤 이력서를 생성하는 게 resume-writer.

이 둘은 체이닝되는 두 스킬이라는 게 특징이다. 한 스킬의 산출물(interview/<회사>-분석.md)이 다른 스킬의 입력이 된다. 처음에는 한 스킬로 뭉쳐 있었는데, 직무 분석을 여러 번 돌려놓고 그중 일부만 이력서로 만드는 패턴이 생기면서 분리했다.

스킬 분리의 신호도 이 과정에서 학습됐다. 한 스킬의 산출물이 다른 작업의 시작점이 되면 분리해야 한다. 한 스킬에 모든 걸 넣으려 하면 매번 처음부터 돌게 되어 비용이 커진다.

스킬을 키우는 패턴

5주 동안 만든 스킬들을 돌아보면 몇 가지 공통 패턴이 보인다.

작게 시작해서 사고 한 번에 한 줄씩 박힌다

처음 만들 때 완벽한 스킬을 만들려 하지 않는다. 그냥 "이 작업을 할 때 어떤 절차를 밟나"를 짧게 적어둔다. 그 다음 사고가 한 번 나면 그 사고를 막는 룰을 한 줄 추가한다. 안티패턴 G(~ 취소선)는 실제로 글에서 한 단락 일부가 취소선으로 렌더링된 사고를 보고 박은 것이다.

이게 효과적인 이유는 룰이 사고에 묶여 있어서 잘 잊히지 않기 때문이다. "이런 식으로 하면 안 된다"는 추상적인 가이드보다 "이 사고를 막기 위한 룰이다"가 훨씬 잘 산다.

자가 점검 절차를 본문 룰과 별개로 박는다

룰을 박아두는 것만으로는 부족했다. 글을 쓰는 도중에 그 룰이 머릿속에 안 떠오를 때가 있기 때문이다. 그래서 SKILL.md의 실행 단계에 점검 절차 자체를 별도 스텝으로 박았다.

9. 글 자가 점검 — grep, WebSearch 같은 구체 명령으로 마무리에 검사

이게 들어간 뒤로 마크다운 사고가 거의 안 났다. 룰을 본문에 잘 적어두는 것보다, 점검 단계를 실행 흐름에 끼워 넣는 게 효과적이다.

글로벌과 프로젝트 분리는 "출처" 기준으로

처음에는 모든 스킬을 글로벌(~/.claude/skills/)에 둘지, 프로젝트(<project>/.claude/skills/)에 둘지 헷갈렸다. 5주 굴려보니 기준이 잡혔다.

• 글로벌: 어느 프로젝트에서나 쓰이는 스킬 (apms-*, dooray-cli, find-skills)
• 프로젝트: 그 프로젝트의 컨벤션·구조에 묶인 스킬 (blog-post-writer, docs-link-audit, job-analyzer, resume-writer)

그런데 blog-post-writer는 fos-study 컨벤션에 묶이지만 다른 프로젝트에서도 쓰고 싶을 때가 있다. 이건 프로젝트에 원본 두고 글로벌에서 심볼릭 링크로 해결했다.

~/.claude/skills/blog-post-writer -> <fos-study-root>/.claude/skills/blog-post-writer

원본은 한 곳, 참조는 여러 곳. 룰 변경이 모든 사용처에 즉시 반영된다.

CLAUDE.md가 두꺼워진 자리들

스킬이 "특정 작업의 절차"라면 CLAUDE.md는 "프로젝트 전체의 룰"이다. 5주간 두꺼워진 자리들을 보면 반복 사고가 가장 자주 나는 영역이 어디인지 보인다.

Bold + 괄호 마크다운 함정 (2026-04-02)

**텍스트(영문)** 형태로 쓰면 일부 파서에서 bold가 안 잡히는 케이스를 발견하고 박았다. 예를 들어 **구조(harness)**는 안 잡히고 **구조**(harness)로 써야 한다.

이건 글 한 편을 다 쓰고 블로그에서 확인했더니 bold가 빠져 있는 걸 보고 알게 된 경우다. 그 후로 같은 패턴이 보이면 자동으로 손이 가서 괄호를 bold 밖으로 빼낸다.

task/ 폴더 가이드 (2026-05-07)

회사 업무 기록을 팀별 디렉터리로 나누는 컨벤션을 짜고 있었는데, 처음에 "이 가이드는 별도 파일에 있다"고만 적었다가 그 별도 파일이 실제로는 만들어지지 않은 채 깨진 링크로 남아 있었다. 그래서 가이드 자체를 CLAUDE.md 본문에 흡수했다.

별도 파일로 분리하는 결정은 그 파일이 자체적으로 의미 있는 단위인가를 따져봐야 한다. 단순히 "본문이 길어졌다"가 분리 이유라면 분리 후에도 잘 안 읽힌다. 본문이 길어도 한 곳에 두는 게 나은 경우가 많다.

cmux vs tmux 환경 안내 (글로벌 CLAUDE.md)

1탄에서 가장 많이 짚었던 함정이다. 내 환경은 cmux를 쓰는데 Claude가 자꾸 tmux 명령으로 답한다. 이건 글로벌 CLAUDE.md(~/.claude/CLAUDE.md)에 별도 룰 파일(~/.claude/rules/cmux-guide.md)로 분리해서 박았고, "터미널 자동화 시 cmux CLI 사용, 없으면 tmux 폴백"을 명시했다.

이 결정 후로 cmux/tmux 혼동은 거의 안 났다. 환경 정보는 한 번만 박아두면 평생 효과가 있다는 게 이런 영역의 핵심이다.

블로그 스킬에 흡수한 L2 공개 정책

회사 정보를 어디까지 노출할지의 기준은 처음에는 CLAUDE.md에 박았다. 그런데 실제로는 블로그 글을 쓸 때만 적용되니까, blog-post-writer 스킬의 3번 항목으로 옮겼다. CLAUDE.md에 있던 자리에는 "블로그 작성 시 L2 정책은 스킬 참조"만 남겼다.

룰의 위치를 정할 때 그 룰이 적용되는 컨텍스트가 좁으면 그 컨텍스트의 스킬에 두는 게 낫다. CLAUDE.md는 매 세션 로딩되는 비용이 있으니, 너무 많은 룰을 한 곳에 모으면 부담이 된다.

"함께 일하는 신입" 비유의 5주 후

1탄 마지막에 이런 문장을 썼다.

Claude는 알아서 잘 하는 AI가 아니라, 잘 설명하면 잘 하는 AI에 가깝다. 함께 일하는 신입이 있다고 생각하면 비슷하다.

5주가 지난 지금은 이 비유가 조금 정교해졌다.

신입에게 "다음에 같은 실수를 안 하도록" 하려면 두 가지가 필요하다. 첫째는 사고가 났을 때 그 사고를 룰로 만들어 박아두는 것. 둘째는 그 룰을 매번 떠올리게 하는 점검 절차. 룰만 박아두면 까먹고, 점검만 박아두면 무엇을 점검할지 흐릿하다. 둘이 같이 가야 한다.

스킬과 CLAUDE.md를 합쳐서 보면 결국 그 두 가지를 코드화한 시스템이다. 룰은 본문에, 점검은 실행 단계에. 같은 사고가 두 번 나면 다음 한 번을 막는 절차를 박는다.

이번 글을 쓰는 과정에서도 그 시스템이 작동했다. envelope이라는 단어를 무심코 직역으로 썼다가, 영문 직역 점검 단계에서 잡혀서 "공통 응답 포맷(response envelope)"으로 다듬었다. 그 발견이 다시 안티패턴 I로 박혔다. 다음 글에서는 envelope 같은 케이스가 시작 시점부터 의식된다.

다음 시리즈

이 글은 시리즈의 2탄이다. 운용 시스템 진화를 다뤘으니, 다음 편에서는 다른 축으로 갈 생각이다. 후보로 두 개를 잡아두고 있다.

• 3탄(정량 비교): 1탄의 카테고리로 5주 후를 다시 측정. Wrong Approach 비율은 줄었나, CI 파괴는 어떻게 변했나, 새로 생긴 카테고리(시리즈물 작성, 외부 시스템 자동화)는 어느 비중인가.
• 4탄(실패 모음집): 1탄의 "Wrong Approach 21건"을 풀어쓰는 후속. 패턴화된 실패 케이스 5~7개를 구체적으로 다루고, 각 케이스에서 어떤 가드를 박아 재발을 막았는지.

어느 게 먼저 나올지는 다음에 글감이 충분히 쌓였을 때 정한다. 지금은 운용 시스템 자체에 만족하고 있고, 그게 굴러가는 동안 데이터가 더 쌓일 거라 본다.