코딩하기 귀찮아하는 SE(시스템 엔지니어)입니다. "CLAUDE.md에 규칙을 적어두면 된다"라고 생각했는데, "적혀 있어도 실행되는 경우가 있다"라는 말을 듣고 서둘러 설정을 재검토한 이야기를 쓰겠습니다.

서론: CLAUDE.md의 규칙은 "부탁 수준"이었다

**コピペ de UI (Copy-paste de UI)**라는 사이트를 혼자서 Claude Code를 사용하여 운영하고 있습니다. UI 컴포넌트의 동작 데모, 샘플 소스, AI 프롬프트를 두는 곳입니다.

사례 페이지를 양산하는 커스텀 명령어를 만들어 두어, 꽤 안정적으로 운영하고 있었습니다. CLAUDE.md에는 "git commit은 금지", "npm install은 금지"라고 명문화되어 있었고, Claude Code도 기본적으로는 이를 지켜주었습니다.

기본적으로는, 이라는 점이 포인트입니다.

사내 직원으로부터 "CLAUDE.md의 규칙은 읽고 지나칠 때가 있어"라는 말을 들었습니다. 지시가 길어질수록 묻히게 된다. 복잡한 태스크 도중에는 규칙보다 "지금 해야 할 일"이 우선시되는 경우가 있다는 것입니다.

그 말을 듣는 순간 "아, 그런 거구나"라고 깨달았습니다.

CLAUDE.md의 규칙은 "의도를 전달하는 것", settings.json은 "물리적인 차단"

CLAUDE.md에 작성한 규칙은 Claude가 읽고 판단하기 위한 것입니다. "이 프로젝트에서는 git commit을 해서는 안 된다"라는 의도를 전달할 수 있습니다. 하지만 "읽고 판단한다"라는 구조상, 복잡한 상황에서는 간과될 수 있습니다.

settings.json의 퍼미션(Permissions) 설정은 다릅니다. AI가 금지된 명령어를 실행하려고 하는 순간, 시스템 레벨에서 멈춥니다. "CLAUDE.md에 적혀 있습니다"라는 확인 프로세스를 거치지 않습니다.

문장으로 된 규칙은 "주의해달라고 부탁하는 것". 설정 파일은 "물리적으로 움직이지 못하게 하는 것".

이 차이를 모르고 있었습니다.

실제로 적용한 settings.json의 내용

.claude/settings.json을 만들어서 다음과 같은 내용을 작성했습니다.

{
"permissions": {
"deny": [
...

이것을 넣으면, 예를 들어 Claude가 git commit을 실행하려고 할 때, 명령어가 실행되기 전에 멈춥니다. CLAUDE.md를 읽고 있는지 여부와 상관없이 말이죠.

npm 관련 2줄은 "설치나 실행은 자신의 판단으로 한다"라는 규칙을 명시한 것입니다. 마찬가지로 git 관련도 "커밋·푸시(Commit/Push)는 자신이 수동으로 한다"라는 의도로 넣어두었습니다.

어떤 조작을 스스로 컨트롤하고 싶은지는 프로젝트나 운용 스타일에 따라 달라지므로, 그대로 복사하기보다는 자신의 운용 방식에 맞춰 선택적으로 사용하세요.

포인트는 와일드카드 *를 붙이는 것입니다. git commit이라고만 적으면 git commit -m "..."가 통과되어 버립니다. 명령어 이름 뒤에 무엇이 붙더라도 멈추도록 작성하는 것이 중요합니다.

그럼 CLAUDE.md는 필요 없는 걸까?

이런 생각이 반드시 드실 겁니다. "settings.json으로 금지할 수 있다면, CLAUDE.md의 규칙란은 불필요한 것 아닌가?"

불필요하지 않습니다. 역할이 다릅니다.

settings.json은 "하게 하지 않기" 위한 설정입니다. "왜 하지 않는가"라는 문맥은 들어있지 않습니다.

CLAUDE.md의 "git commit은 금지. 사용자가 수동으로 커밋하는 운용을 위해"라는 기술은, Claude가 왜 그 규칙이 있는지 이해한 상태에서 움직이기 위한 것입니다. 이해가 있다면, 금지되지 않은 다른 상황에서도 판단이 흔들리지 않게 됩니다.

CLAUDE.md가 "규칙과 그 이유를 가르쳐주는 교과서"라면, settings.json은 "만약 어기더라도 멈추게 하는 안전장치"입니다.

둘 다 있어야 비로소 이중 잠금이 됩니다. 한쪽만 있다면 한쪽의 약점이 그대로 남게 됩니다.

세션을 넘어가도 설정이 유효함

또 하나 좋았던 점은, settings.json은 세션을 넘어서도 유효하다는 점입니다.

Claude는 세션을 넘어서 기억을 유지하지 않습니다. 새로운 채팅을 열 때마다 초기화됩니다. CLAUDE.md를 매번 읽게 하면 규칙은 전달되겠지만, 읽고 지나칠 리스크는 매번 따라옵니다.

settings.json은 파일로서 .claude/ 디렉토리에 놓여 있기 때문에, 누가 어떤 세션에서 해당 프로젝트를 열더라도 자동으로 적용됩니다.

"규칙을 매번 전달하지 않아도 된다"가 아니라, "규칙을 매번 지킬 수 있는 상태가 자동으로 유지된다"는 것입니다.

커스텀 에이전트(Custom Agent, ops-knowhow-keeper, zenn-writer 등)를 여러 개 만들면, 각각에 대해 "어떤 도구를 사용해도 되는지"에 대한 권한 설정도 할 수 있습니다. "기사 작성 에이전트는 Read와 Write만 허용하고, Bash는 사용하지 못하게 한다"와 같은 제어가 가능해집니다. 아직 그 정도까지 깊게 활용하고 있지는 않지만, 에이전트가 늘어나면 정리하고 싶은 부분입니다.

settings.json으로 할 수 있는 것은 권한 관리뿐만이 아니다

권한의 deny/allow를 깊게 활용하면서 깨달은 점인데, settings.json은 더 넓은 의미의 "Claude Code 동작 설정 파일"입니다.

조사해 보니 주로 다음과 같은 것들을 할 수 있습니다.

환경 변수 (Environment Variable) 설정

Claude의 실행 환경에 변수를 전달할 수 있습니다. 프로젝트마다 실행 환경을 통일하고 싶을 때 사용할 수 있습니다.

Hooks 등록

명령어 실행 전후에 테스트(Test)나 린트(Lint) 등을 자동으로 실행할 수 있습니다. "Claude Code가 무언가를 변경하면 자동으로 lint를 실행한다"와 같은 방식으로 사용할 수 있습니다.

설정 파일의 구분 사용

설정에는 3개 계층이 있어 개인용, 프로젝트 공유용, 로컬 전용을 구분해서 사용할 수 있습니다. 팀 단위로 사용한다면 공유 설정만 Git으로 관리하고, 개인의 취향은 로컬 전용에 작성하는 방식으로 운영할 수 있습니다.

저는 현재 권한 관리만 사용하고 있지만, Hooks는 응용 사례의 양산 워크플로우(Workflow)와 궁합이 좋아 보여서 조만간 시도해 보고 싶습니다.

settings.json은 "금지 규칙을 쓰는 파일"이 아니라 "Claude Code의 동작을 설계하는 파일"입니다. 권한 관리는 그중 하나의 기능일 뿐입니다.

공식 문서(Official Documentation)는 이곳입니다.

"돌아가니까 괜찮겠지"라며 한동안 방치했었다

솔직히 이것을 도입하기 전까지는 "뭐, CLAUDE.md에 적혀 있으니 괜찮겠지"라고 생각하며 지낸 기간이 꽤 있었습니다.

사내 동료가 말해주지 않았다면 아마 한동안 깨닫지 못했을 것입니다. "가끔 규칙이 무시되는" 상황을 마주하지 않았던 것은 아니지만, "Claude의 상태가 안 좋았을 뿐"이라며 넘겨버렸습니다.

"적혀 있으니까 괜찮다"와 "실행할 수 없도록 되어 있으니까 괜찮다"는 전혀 다른 안도감을 줍니다.

금지하고 싶은 것이 있다면 문장으로 적는 것뿐만 아니라 설정으로 차단한다. 이 발상이 빠져 있었습니다.

settings.json 도입을 계기로 Claude Code 주변의 워크플로우를 몇 가지 더 재검토했습니다. 커스텀 명령어(Custom Command), Rule MD, 토큰 최적화(Token Optimization) 등에 관한 이야기도 쓰고 있습니다. 괜찮으시다면 함께 읽어보시기 바랍니다.

UI 컴포넌트 데모, 샘플 소스, AI 프롬프트를 올려둔 사이트는 이곳입니다.

Discussion