언제 무엇을 쓰는가

문제

같은 일을 CLAUDE.md에도, 스킬에도, 훅에도 넣을 수 있습니다. 어디에 넣어야 하는지가 매번 헷갈립니다.

기준표

표를 두 개로 나눕니다. 위쪽은 규칙을 두는 위치를, 아래쪽은 작업을 나누는 방법을 다룹니다. 섞어서 보면 여덟 개 중 하나를 고르는 문제가 됩니다. 나누면 대개 한쪽만 보면 됩니다.

규칙을 두는 위치

판단 기준은 강제력입니다. 아래로 갈수록 강해집니다.

원하는 것	쓸 것	지켜지는 방식
모든 세션에서 지켜야 할 규칙	CLAUDE.md	권고이며, 읽히지만 밀릴 수 있음
특정 영역에만 적용할 규칙	Rules	권고이며, 범위가 좁아 덜 밀림
반복하는 절차	Skill	호출돼야 작동
예외 없이 실행돼야 하는 검사	Hook	강제이며, 하네스가 실행

작업을 나누는 방법

판단 기준은 무엇을 분리하고 싶은가입니다.

원하는 것	쓸 것	분리하는 것
컨텍스트를 더럽히지 않을 조사	Subagent	컨텍스트
서로 충돌하면 안 되는 병렬 작업	Worktree	작업 공간
외부 서비스 데이터	MCP 또는 CLI	데이터 출처
위 묶음을 팀에 배포	Plugin	배포 단위

이유

표의 “권고”와 “강제”를 가르는 이유가 있습니다.

CLAUDE.md에 쓴 문장은 모델이 읽는 참고 자료입니다. 대부분의 경우 지켜지지만, 컨텍스트가 길어지거나 지시가 서로 경합하면 밀려납니다. 문서가 길수록 개별 규칙의 무게는 가벼워집니다.

훅은 다릅니다. 하네스가 실행하므로 모델의 판단이 개입하지 않습니다. 통과하지 못하면 그 지점에서 멈춥니다.

“이것을 모르면 Claude가 실수한다”는 CLAUDE.md에 쓰고, “이것을 안 하면 안 된다”는 훅으로 만드십시오. 후자를 문서에 쓰면 지켜지는지 확인할 방법이 없는 채로 지켜지길 바라게 됩니다.

자연어 트리거($키워드 같은 것)를 정의하는 방식도 같은 함정에 빠집니다. 규칙을 정의한 사람조차 몇 주 뒤에는 그 트리거를 잊습니다. 사람이 매번 기억해야 작동하는 규칙은 지켜지는지 확인할 수 없습니다.

브라우저를 열어야 할 때

두 축으로 갈립니다.

상황	도구
로그인 세션·쿠키가 필요한 판독	사용자 브라우저 세션을 그대로 쓰는 도구 (기본)
영상 녹화, trace, 디바이스 에뮬레이션, 격리 프로필	Playwright

기본은 전자입니다. 사용자의 브라우저 세션을 쓰므로 로그인이 걸린 화면을 그대로 읽을 수 있고, 별도 로그인 절차가 필요 없습니다.

Playwright는 전자가 못 하는 것이 필요할 때 꺼냅니다. 영상 녹화, trace 수집, 특정 디바이스 에뮬레이션, 그리고 사용자 로그인이 섞이면 안 되는 깨끗한 프로필입니다.

애매하면 임의로 고르지 말고 물어보십시오. 잘못 고르면 되돌리는 비용이 묻는 비용보다 큽니다.

디자인 도구에서 값을 읽어야 할 때

비용 순서가 있습니다.

MCP 읽기 도구를 먼저 씁니다. 구조와 변수 값을 그대로 반환합니다.
그다음은 속성 패널에서 텍스트를 추출하는 방법입니다.
마지막이 스크린샷입니다.

값을 읽는 데 스크린샷을 쓰지 마십시오. 찍고, 좌표를 추정하고, 다시 찍는 순환이 토큰을 가장 많이 씁니다. 스크린샷은 화면이 어떻게 보이는지 확인하는 도구입니다. 값이 얼마인지 알아내는 도구는 아닙니다.

호출 한도 때문에 상위 경로를 아끼게 되는 경우가 있습니다. 그때 만든 우회책은 한도가 풀린 뒤에도 관성으로 남기 쉽습니다. 지금 쓰는 우회책이 원래 옳아서인지 제약 때문이었는지 가끔 다시 확인하십시오.

자동 루프를 돌릴 수 있는 조건

세 조건을 모두 만족해야 합니다.

한 세션에 닫히는 수직 슬라이스로 쪼개집니다.
통과·실패가 명령 출력으로 나옵니다.
루프가 끝난 뒤 계획이나 로드맵을 갱신하는 절차가 있습니다.

2번이 결정적입니다. “동작하게 만들어라” 같은 기준은 매 회차마다 사람의 판단을 요구하고, 그러면 루프가 아니라 반복 작업입니다.

루프의 대상은 결정론적인 코드여야 합니다. 검증기, 빌더, 테스트처럼 같은 입력에 같은 출력을 내는 것입니다. 모델이 생성하는 비결정론적 산출물을 성공 조건에 직접 걸면, 모델이 그 조건을 끝내 만족시키지 못할 때 루프가 끝나지 않습니다. 그런 항목은 루프에 넣지 말고 1회성 게이트로 분리하십시오.

스킬의 자동 호출을 허용하는 범위

부작용 유무로 가릅니다.

스킬 성격	설정
읽기 전용 조회	모델 자율 호출 허용
커밋·푸시·초기화 등 부작용 있음	수동 호출만 허용

조회 스킬은 모델이 필요할 때 알아서 부르는 편이 낫습니다. 사람이 매번 기억해서 불러야 하면 쓰이지 않습니다.

부작용이 있는 스킬은 반대입니다. “메시지만 뽑아줘”라고 했는데 커밋까지 하는 사고를 막으려면 호출 자체를 사람의 결정으로 두어야 합니다.

CLAUDE.md에 “예외 없이 /x를 실행한다”라고 써놓고 x를 수동 호출 전용으로 잠가두면, 그 지시는 구조적으로 실행 불가능한 죽은 코드입니다. 문서만 읽으면 멀쩡해 보인다는 점이 문제입니다. 지침을 쓸 때는 그 지침이 참조하는 도구가 모델에게 실제로 보이는지 함께 확인하십시오.

하지 말 것

반드시 지켜져야 할 것을 CLAUDE.md에 쓰기. 문서는 권고이고, 권고는 잊힙니다. 강제하려면 훅으로 만드십시오.

애매할 때 도구를 임의로 고르기. 브라우저 도구가 둘 다 가능해 보이면 묻는 편이 비용이 적습니다.

값 판독에 스크린샷 쓰기. 좌표를 추정하고 다시 찍는 순환이 토큰을 씁니다.

비결정론적 산출물을 루프의 성공 조건으로 걸기. 모델이 그 조건을 못 맞추면 루프가 끝나지 않습니다.