Claude Code의 설정, 무엇이 효과가 있는지 모른 채 계속 늘어나고 있지는 않나요? 저희는 늘어났습니다. 91일 동안 1,434개의 세션을 돌리며 규칙(Rule)도, 후크(Hook)도, 스킬(Skill)도 쌓아 올렸고, 지난주에 415MB의 로그를 전부 집계하여 "실제로 업무에 도움이 된 설정"을 계산했습니다.

이 기사는 다음에 설정을 수정할 날에 열어보기 위한 저장소로서 작성합니다. 91일 동안 실행하며 살아남은 설정만을 복사해서 바로 사용할 수 있는 실물로 나열합니다. 그만둔 설정과 그 이유도 마지막에 있습니다.

[toc]

설정 레이어는 아래에서부터 순서대로 쌓여 있습니다. 위로 올라갈수록 문제가 생겼을 때의 피해가 커지므로, 아래쪽이 안정된 후에 위로 올립니다.

~/.claude/rules/에는 9개의 파일, 총 12,670자가 있습니다. 로그 203만 자를 grep하여 확인한 준수율은 98.1%였습니다. 수치는 높지만, 내역을 보면 작성 방식에 따라 명암이 갈립니다. "모든 텍스트에 적용"이라고 적은 규칙은 문맥에 의해 덮어씌워집니다. 기사 작성 시에는 거의 100% 지켜졌지만, 외부 메일 초안 작성 시에는 경어 규칙이 깨졌습니다 (그리고 그것은 AI의 판단이 더 옳았습니다).

살아남은 것은, 어떤 결과물에 적용하고 싶은지의 사정거리(Scope)를 맨 앞에 적은 규칙뿐입니다.

# 실패한 방식: 사정거리가 없는 금지 목록 나열
- 「させていただきます」를 사용하지 말 것
# 살아남은 방식: 사정거리 → 규칙
...

이 레이어는 문체나 예법에서 양보할 수 없는 선이 있는 분들을 위한 것이라고 생각합니다. 없다면 건너뛰고 후크(Hook)부터 시작해도 좋습니다. 참고로 "규칙은 몇 개까지 지켜지는가"는 별도의 기사에서 실측했습니다. 3개라면 완전 준수, 30개라도 83%였습니다. 실패한 규칙에는 공통점이 있는데, 위치가 어디냐보다 모델의 출력 습관과 충돌하느냐에 따라 결정되었습니다.

규칙은 98.1%, 후크는 100%입니다. 기계적으로 차단하므로 깨질 수가 없습니다. 91일 동안 살아남은 것은 9개의 이벤트 18개였으며, 계통은 4가지였습니다.

가장 단순하면서도 가장 많이 사용하는 것은 완료 알림음입니다. 이것만으로 터미널 모니터링을 그만둘 수 있습니다. 위험 커맨드 차단의 골자는 이것입니다. exit 2로 반환하면 툴 실행 자체가 블록됩니다.

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin)['tool_input'].get('command',''))")
...

함정이 하나 있습니다. 정규 표현식을 이용한 검문은 무해한 커맨드를 오탐(False Positive)할 수 있습니다. 저희의 경우 「qiita」와 「publish」가 함께 포함된 읽기 계열 커맨드가 공개 조작 검문에 계속 걸렸습니다. 검문 후크에는 의도적인 실행을 통과시키기 위한 암호(환경 변수 플래그)를 처음부터 준비해 두어야 합니다.

완료 알림음만이라도 넣을 가치가 있습니다. 저희는 이것 덕분에 터미널을 지켜보는 시간이 사라졌습니다. 위험 커맨드 차단도 같은 날에 도입해도 좋습니다. 부작용은 오탐 정도입니다.

스킬(Skill)은 26개가 있지만, 자주 발화하는 것은 몇 개뿐입니다. 자주 발화하는 스킬은 description에 "언제 호출하는지"가 적혀 있습니다. 그것뿐이었습니다.

방치되었을 당시의 description은 "기사를 생성하는 스킬"이라는 한 줄뿐이었습니다. 지금 저희의 기사 파이프라인은 다음과 같습니다.

description: Qiita 기사를 자동 생성 및 게시하는 스킬. 소재 선정 → 조사 → 집필 → 품질 게이트 → 게시까지의 일관된 파이프라인. "/qiita", "오늘의 기사", "소재 제안"으로 실행

모델은 스킬 본문을 읽기 전에 description만으로 실행 여부를 판단하므로, "~로 실행"과 같은 트리거 목록을 나열하는 것이 효과적입니다. 이것을 추가한 것만으로 방치되었던 스킬이 현역으로 복귀한 사례가 여러 건 있습니다.

만드는 기준은, 동일한 절차를 3번 반복했을 때입니다. 만약 트리거(trigger)를 description에 적을 수 없다면, 그 시점에서 용도가 모호한 것이므로 만들지 않습니다. 저희 팀에서 버린 스킬들은 거의 이 패턴이었습니다.

서브 에이전트(Sub-agent)는 7개입니다. 설계에서 효과적이었던 것은 금지 사항을 가장 먼저 적는 것이었습니다. 조사 담당은 코드를 작성할 수 없습니다. 작성 담당은 단 1개뿐입니다. 교열 담당은 채점 기준을 가집니다.

---
name: researcher
description: 기술 조사 에이전트. 라이브러리 선정·API 사양·경쟁사 조사를 수행함. 코드 편집은 절대로 하지 않음
...

본체는 tools 행입니다. 편집 도구(editing tool)를 넘겨주지 않으면, 조사 담당은 물리적으로 코드를 망가뜨릴 수 없습니다.

1개로도 문제가 없다면 7개는 필요 없습니다. 저희도 첫 한 달 동안은 0개였습니다.

세션(session) 길이의 중앙값은 0분입니다. 절반 이상은 1회 왕복으로 끝나는 자동 실행으로, 매일 아침의 실측 집계·심야의 초안 생성·실패 감지가 launchd로 돌아가고 있습니다.

<key>ProgramArguments</key>
<array>
<string>/opt/homebrew/bin/python3</string>
...

거만하게 쓰고 있지만, 이 매일 아침의 집계 작업은 이번 주에 4일 동안 멈춰 있었습니다. 원인은 170건의 API 취득 도중 1번 타임아웃(timeout)이 발생하면 전체가 무너지는 구조였고, 재시도(retry) 로직을 작성하지 않았기 때문입니다. 이를 깨달은 것은 4일 후, 리포트의 날짜가 오래된 것을 사람이 확인했을 때였습니다.

수정한 것은 재시도로, 3회 시도·10초 대기입니다. 아울러 작업의 성패 로그에 의존하는 것을 그만두고, 검증은 데이터의 날짜를 확인하기로 했습니다 (리포트가 3일 전 것이라면 고장).
실패를 감지하는 별도의 작업도 필요하다고 생각하지만, 솔직히 아직 작성하지는 않았습니다.

자동화에 손을 대는 것은 "동일한 명령어를 매일 수동으로 입력하는" 것이 2개 이상 생겼을 때부터 해도 늦지 않다고 생각합니다. 첫 번째부터 자동화하면 모니터링 없이 조용히 죽어버립니다(silent death). 저희가 그랬습니다.

세션을 넘나드는 기억은 메모리 디렉토리에 "1파일=1사실"로 저장합니다. 현재 140개 이상의 파일이 있습니다. 전체를 로드하지 않고, 상시 읽는 것은 1줄 요약 인덱스뿐이며, 내용은 필요할 때 Read 시킵니다.

- [기사의 승리 패턴](feedback_winning_lane.md) — 먹히는 형식·제목·NG 구성
- [PDCA 측정 루프](project_pdca_ops.md) — 매일 아침 6:40 실측. 가설 없는 기사는 쓰지 않음

거대한 한 장의 CLAUDE.md에 전부 적는 방식은, 저희 팀에서는 가장 먼저 실패했습니다.

생존 전략보다 참고가 될지도 모릅니다.

• 거대한 CLAUDE.md: 모든 것을 담은 한 장은 가독성이 떨어집니다. 루트(root)는 얇게 가져가고, 상세 내용은 rules/와 memory/로 분할하십시오.
• 대화까지 구속하는 문체 규칙: 실측해 보니 기사에서는 위반 사례가 0건이었지만, 대화에서는 지켜지지 않았습니다. 대화를 구속하는 부분은 완전히 헛수고였습니다.
• 후크(hook)의 대량 모니터링: 이벤트를 닥치는 대로 걸었던 시기가 있었으나, 발화 로그를 보고 미사용 항목을 삭제했습니다. 검문(checkpoint)은 늘릴수록 오작동(false positive)도 늘어납니다.
• 트리거가 없는 스킬: description에 기동 조건을 적을 수 없는 스킬은, 적을 수 없는 시점에서 이미 용도가 모호했습니다.
• 템플릿을 통한 기사 양산: 설정은 아니지만, 동일한 골격으로 양산한 기사는 25개에 좋아요 합계가 6개였습니다. 양산을 멈추고 실측 기반의 1개에 집중하는 것이 숫자가 더 잘 나왔습니다.

전부가 필요하지는 않습니다. 저희의 91일을 역산했을 때, 처음 15분 안에 넣을 가치가 있는 것은 이 파일 하나뿐입니다.

{
"hooks": {
"Stop": [
...

check-dangerous-cmd.sh의 내용은 위의 골자를 그대로 저장하면 됩니다. 그 다음 1주일 동안은 규칙을 1개 파일(사정거리 포함), 그다음 1개월 동안은 정리(inventory)를 진행하십시오. 91일 분량의 발화 로그를 보고 내린 결론은, 더하는 것보다 빼는 것이 더 효과적이었다는 것입니다. 이것이 전부입니다.

저의 숙제도 남아 있습니다. 규칙 9개 파일 중 어떤 것을 지울지는, 30개의 실험 결과를 보고 나서도 아직 결정하지 못했습니다. 정리 결과는 숫자가 나오면 다시 쓰겠습니다.

참고: