아키텍트 개발자를 위한 Claude Code 설정 10선

6개월 동안 Claude Code를 매일 사용하면서 10가지 설정 패턴에 도달했습니다. 이 설정들이 없었다면 에이전트(Agent)가 잘못된 방향으로 진행한 부분을 수정하기 위해 한 달에 10~15시간을 허비했을 것입니다. 설정을 적용한 이후에는 그 시간이 눈에 띄게 줄어들었습니다.

이 글은 "Claude Code란 무엇인가"를 설명하는 튜토리얼이 아닙니다. 이미 이 도구를 사용하고 있으며, 거기서 더 많은 것을 끌어내고 싶은 분들을 위한 설정 모음입니다. 각 섹션의 마지막에 그대로 복사해서 사용할 수 있는 설정을 두었으니 바로 사용해 보세요.

처음 몇 달 동안 저지른 가장 큰 실수는 CLAUDE.md에 모든 것을 다 집어넣은 것이었습니다. 3월 시점에 제 파일은 4만 자까지 불어나 있었습니다. 아키텍처 결정, 스타일 가이드, 테스트 규약, 프롬프트(Prompt) 예시, 도메인 모델, 온보딩, 변경 이력까지 말이죠. 컨텍스트(Context)는 많을수록 결과가 좋아질 것이라고 믿었습니다.

하지만 그렇지 않았습니다. 원인은 어텐션(Attention) 메커니즘에 있습니다. 트랜스포머(Transformer)는 긴 문서의 중간에 있는 정보를 유지하는 데 서툽니다. 4만 자에 달하게 되자, Claude는 파일 중간에 있는 규칙을 "잊어버리기" 시작했습니다. 무시하는 것이 아니라 말 그대로 보이지 않게 된 것입니다. 실험을 통해서도 확인했습니다. 에이전트에게 자신의 CLAUDE.md 300행에 있는 규칙을 재현해 달라고 요청했을 때, 수행하지 못했습니다.

엄격한 상한선을 둡니다. 메인 파일은 8,000자까지로 제한합니다. 나머지는 필요에 따라 읽어오는 별도의 파일로 분리합니다.

제가 사용 중인 구성입니다:

.claude/
├── CLAUDE.md # 상주 컨텍스트, 8,000자까지
├── skills/
...

CLAUDE.md에는 예외 없이 매 세션마다 필요한 것만 둡니다. 스택(Stack), 중요한 금지 사항, specs 및 skills로의 링크 등입니다. 그 외의 모든 것은 필요할 때 읽어옵니다.

리팩터링(Refactoring) 후 메인 파일은 6,000자가 되었고, 답변은 명확하게 정확해졌습니다. 긴 세션에서도 중간에 컨텍스트를 잃지 않게 되었으며, 세션 초기화 시의 토큰(Token) 소비량은 약 35% 감소했습니다.

많은 개발자는 settings.json을 한 번도 열지 않습니다. 기본 설정으로도 잘 작동하니까 충분하다고 생각하기 때문입니다. 제가 첫 한 달이 지난 후 바로 추가한 설정을 소개합니다.

읽기와 테스트를 확인 없이 허용하기:

{
"permissions": {
"allow": [
...

읽기와 확인만 필요한 작업은 모두 중단 없이 통과됩니다. git에 쓰는 것이나 삭제하는 것은 모두 확인을 요구합니다. 세션당 중단 횟수가 1520회에서 23회로 줄었습니다. 체감상 세션이 1.5배 정도 쾌적해졌습니다.

deny는 allow보다 우선되므로, 위험한 명령어를 확실하게 차단할 수 있습니다. 파괴적인 데이터 조작도 동일한 메커니즘으로 막을 수 있습니다:

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

이것들은 전부 프로젝트 루트의 .claude/settings.json에 두고 리포지토리(Repository)에 커밋합니다. 팀원 모두가 동일한 가드레일(Guardrail)을 갖게 됩니다. 개인적인 설정은 커밋하지 않는 .claude/settings.local.json으로 분리합니다(후술할 9번 참조).

acceptEdits는 파일 변경 시마다 나타나는 확인 요청을 없애줍니다. 시간 절약처럼 들리겠지만, 효과적으로 작동하는 것은 특정 종류의 태스크(Task)에 한정됩니다.

활성화할 상황:

• 타입 마이그레이션(Type Migration): JS → TS, any 수정, 인터페이스(Interface) 업데이트
• 기계적인 수정: 이름 변경(Rename), import 치환, 포맷팅(Formatting)
• 이미 작성된 로직에 대한 테스트 생성
• 문서나 주석 업데이트

활성화하지 않을 상황:

• 새로운 기능 구현
• 복잡도와 상관없는 아키텍처 리팩터링
• auth, payment, data layer 수정
• "완료" 기준을 10초 안에 언어화할 수 없는 태스크

실례를 들어보겠습니다. "사용하지 않는 import를 정리해줘"라는 태스크에서 acceptEdits를 활성화했습니다. 에이전트는 import를 정리한 후, "파일을 보는 김에"라며 몇 가지 서비스를 다시 만들기로 결정했습니다. 형식적으로는 맞지만, 그 판단은 우리의 패턴보다 떨어지는 것이었습니다. 예정에 없던 30분의 리뷰가 발생했습니다.

도입한 규칙: acceptEdits는 실수를 잡아낼 자동 테스트가 있는 경우에만 사용합니다. 테스트가 없다면 수동으로 확인합니다.

Hooks는 Claude Code에서 가장 과소평가되고 있는 기능입니다. 에이전트의 도구 실행 전후로 동작하는 shell 스크립트로, stdin으로부터 JSON 형식의 컨텍스트를 전달받습니다. 제 워크플로우를 바꾼 3가지를 소개합니다.

#!/bin/bash
# ~/.claude/hooks/stop.sh
TASK=$(cat /tmp/claude_current_task 2>/dev/null || echo "no task recorded")
...

세션이 끝날 때마다 시간과 태스크가 로그에 기록됩니다. 한 달 뒤에는 솔직한 리포트를 얻을 수 있었습니다. 평균적으로 하루에 2시간 15분 동안 에이전트와 작업하며, 4~5번의 세션을 진행했습니다. 그전까지는 Claude Code를 '가끔' 사용하고 있다고 생각했습니다. 하지만 데이터는 다른 사실을 보여주고 있었습니다.

PreToolUse hook은 stdin으로부터 JSON 형식의 도구 입력을 받습니다. exit 2를 반환하면 실행이 차단되며, stderr의 내용이 에이전트에게 전달됩니다:

#!/bin/bash
# ~/.claude/hooks/pre_tool.sh
INPUT=$(cat)
...

처음 3개월 동안 이 hook은 7번 작동했습니다. 그중 5번은 에이전트가 타당한 조작을 제안하여 확인 후 수동으로 실행했습니다. 나머지 2번은, 멈춰줘서 다행이라고 생각했습니다.

#!/bin/bash
# macOS
osascript -e 'display notification "Claude Code 가 태스크를 완료했습니다" with title "Claude Code"'
...

매우 단순한 것이지만, 습관을 바꾸어 놓았습니다. 30초마다 터미널을 들여다보는 것을 그만두고, 에이전트가 작동하는 동안 실제로 다른 태스크로 전환할 수 있게 되었습니다. 병행 작업의 생산성이 향상되었습니다.

settings.json에서의 연결:

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

Claude Code에서는 동일한 태스크에 대해 서로 다른 모델로 병행 세션을 실행하고, 그 결과를 통합할 수 있습니다. 시간 낭비처럼 들릴 수도 있지만, 실제로는 3~4시간의 팀 논의를 대체합니다.

롤백하기 어려운 결정에 사용합니다. 모듈 구성, 데이터 스키마, 서비스 간의 컨트랙트(Contract), 시스템 핵심 부분의 패턴 선택 등입니다.

서로 다른 모델에 보내는 3가지 요청:

Opus: "[X]를 설계해줘. 우선순위: 신뢰성과 컨트랙트의 명시성"
Sonnet: "[X]를 설계해줘. 우선순위: 개발 속도"
Haiku: "[X]를 설계해줘. 최소한의 복잡성, 최소한의 추상화"

트레이드오프(Trade-off)가 서로 다른 3가지 제안을 얻을 수 있습니다. 그 후 Opus로 네 번째 세션을 열어, 우리의 컨텍스트를 바탕으로 3가지의 좋은 부분들을 통합하도록 요청합니다.

소요 시간은 2025분입니다. 최근의 큰 리팩터링(이벤트 드리븐(Event-driven) 부분의 재구축)에서는 이것이 일주일 치의 팀 논의를 대체했습니다. 23명이 논의하는 것보다 더 깔끔한 해답에 도달했습니다.

팀에 기술 리뷰를 해줄 두 번째 시니어 개발자가 없을 때 특히 효과적입니다.

에이전트 작업의 깊이는 태스크와 기대하는 프로세스를 얼마나 자세히 기술하느냐에 따라 달라집니다. 저는 이를 4개의 레벨을 가진 자체 제작 skill로 형식화했습니다 (/effort는 내장 명령어가 아니라 제가 정의한 skill입니다. 내장 명령어로는 think / ultrathink와 같은 키워드로 사고의 깊이를 높일 수 있습니다).

# skill: effort-levels
/effort low
빠른 초안. 설명 없음, 계획 없음. 그냥 코드를 작성함.
...

/effort max를 사용했을 때, 반년 만에 전체 롤백이 필요했던 케이스는 제로였습니다. 레벨을 명시하지 않은 태스크에서는 에이전트가 잘못된 방향으로 나아가 마지막에 가서야 깨달은 케이스가 3~4번 있었습니다.

덤으로 얻는 효과도 있습니다. /effort max라고 써보고 이 태스크에 너무 과하다고 느껴진다면, 그것은 태스크가 생각보다 간단하다는 신호입니다. 그 반대도 마찬가지입니다.

Context Rot (컨텍스트 부패)란 긴 세션 동안 컨텍스트가 축적됨에 따라 답변 품질이 저하되는 현상을 말합니다. 에이전트는 자기 모순을 일으키고, 이미 결정된 사항을 "잊어버리며", 이미 거절한 안을 다시 제안하기 시작합니다.

3가지 징후:

• 동일한 세션 내에서 이미 논의하고 거절한 안을 에이전트가 다시 제안함
• 방금 막 작성한 코드를 수정하라고 권유함
• 10개 메시지 전에 부여한 태스크에 대해 "컨텍스트를 명확히 합시다"라고 답변함

징후가 나타나면 계속하지 마세요. 계속하는 것은 상황을 악화시킬 뿐입니다. 짧은 요약과 함께 새로운 세션을 시작하세요.

새로운 세션으로의 인계 템플릿:

# 계속하기 위한 컨텍스트
**태스크:** [무엇을 하고 싶은지 1문장으로]
**완료된 사항:**
...

이 템플릿을 작성하는 데는 35분이 걸립니다. 저하된 세션을 계속 붙들고 있는 것보다 510배 빠릅니다.

저 개인적인 트리거는 다음과 같습니다: 3개 메시지 연속으로 태스크가 진전되지 않으면, 가차 없이 재시작합니다.

동일한 논점에 대해 한 세션 내에서 에이전트를 2번 수정했다면, 멈춰야 합니다. 이것은 에이전트의 고집이 아닙니다. 태스크 설정이나 컨텍스트에 무언가 문제가 있다는 신호입니다.

이 규칙을 적용하기 전에는, "고집스러운" 태스크에 1.5~2시간을 허비하곤 했습니다. 보충 설명을 주고, 에이전트가 다시 만들고, 그래도 아니면 또 보충 설명을 주는 식의 악순환이었습니다.

'2회 수정 규칙'을 도입한 이후로는, 2번째 수정에서 멈추고 태스크를 처음부터 다시 구성합니다. 방법은 세 가지가 있습니다:

1. 더 작게 분할하기. 에이전트가 X를 두 번 연속으로 제대로 수행하지 못한다면, X가 너무 클 가능성이 있습니다. X1과 X2로 나누어 순차적으로 해결하세요.

2. 기대하는 결과의 예시를 제공하기. "제대로 해줘" 대신 "최종적으로는 이렇게 보여야 해"라고 구체적인 사례를 보여줍니다. 결과의 정확도 차이는 확연합니다.

3. 뼈대(雛形) 작성하기. 구조나 시그니처(Signature)를 제가 초안으로 작성하고, 에이전트가 내용을 채우게 합니다. 아키텍처 관련 태스크에서 특히 효과적입니다. "이것이 서비스의 인터페이스이니 구현을 작성해"라고 하는 것이, 단순히 "X를 위한 서비스를 작성해"라고 하는 것보다 훨씬 정확하게 작동합니다.

지난 반년 동안, 2회 수정 규칙 덕분에 제 계산으로는 15~20시간을 절약했습니다. 이전에는 허공으로 사라졌을 시간입니다.

Claude Code의 설정은 계층적으로 병합됩니다. 팀 공유용 .claude/settings.json, 개인용이며 커밋하지 않는 .claude/settings.local.json, 그리고 사용자 전체용 ~/.claude/settings.json이 있습니다. 이를 통해 공유 가드레일(Guardrail)과 개인의 작업 속도를 양립시킵니다.

.claude/settings.json (팀 공유용·엄격함, 리포지토리에 커밋):

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

.claude/settings.local.json (개인용·로컬, .gitignore에 포함):

{
"permissions": {
"allow": [
...

로컬 환경에서는 빠르게 움직일 수 있습니다. Docker나 데이터베이스 조작을 할 때마다 멈추지 않아도 됩니다. 반면, deny에 넣은 운영 환경과 관련된 파괴적인 조작은 팀 설정에 의해 확실히 차단된 상태로 유지됩니다. deny는 allow보다 우선순위가 높기 때문에, 로컬의 allow가 공유 가드레일을 덮어쓸 걱정도 없습니다.

권한 모드 자체도 --permission-mode plan과 같이 실행 시점에 전환할 수 있으므로, 조사만 하고 싶을 때는 plan 모드를, 기계적인 작업일 때는 acceptedEdits를 사용하는 식의 구분도 효과적입니다.

Skills는 .claude/skills/에 두는 Markdown 파일로, 필요할 때 불러옵니다. 에이전트는 해당 파일의 내용을 추가 컨텍스트로 받아들입니다.

목표는 고유한 컨텍스트를 항상 에이전트의 메모리에 유지하지 않는 것입니다. 필요한 때에만 불러옵니다.

저의 구성:

.claude/skills/
├── nestjs-conventions.md # NestJS 모듈 규약
├── clean-arch.md # 프로젝트에서의 CA(Clean Architecture) 원칙과 예시
...

각 skill은 특정 종류의 태스크를 위한 컨텍스트입니다:

• 새로운 NestJS 모듈 작성 → nestjs-conventions

• 아키텍처를 리팩터링하기 → clean-arch

• 코드 리뷰를 하기 → code-review-checklist

nestjs-conventions.md의 일부 예시:

# 이 프로젝트에서의 NestJS 규약
## 모듈 구성
각 모듈은 domain/, application/, infrastructure/, presentation/을 포함
...

skills로 이전한 후의 결과:

• 메인 CLAUDE.md가 4만 자에서 6,000 자로 축소
• 고유한 컨텍스트는 필요할 때만 로드됨
• 표준 세션의 토큰 소비가 30~40% 감소
• 에이전트가 서로 다른 도메인의 규칙을 혼동하지 않게 됨

이 10가지 설정은 6개월간의 반복(iteration) 결과입니다. 일부는 문서로부터 자명하게 도출된 것이 아니며, 일부는 무언가가 제대로 작동하지 않았을 때 겪은 직접적인 고통에서 비롯되었습니다.

이 기간 동안 가장 깨달은 점은, Claude Code는 상자에서 꺼내자마자 바로 잘 작동하는 도구가 아니라는 것입니다. 이는 워크플로(workflow)를 설정하기 위한 플랫폼입니다. 기본 상태는 "충분한" 수준으로 작동하지만, 올바른 설정은 "진심으로 빨라지는" 수준으로 끌어올립니다.

제 추산으로는, 이 10가지 설정은 첫 6개월 동안 총 50~60시간을 절약해 주었습니다. 대략 일주일 치의 노동 시간입니다.

목록에 포함되지 않은 본인만의 설정이 있다면 꼭 댓글로 알려주세요. 특히 hooks에 대해서는 아직 발견하지 못한 패턴이 분명히 있을 것입니다.

여담: 여러 모델을 병렬로 실행하기 시작하면(섹션 5), 다음에 마주하게 될 질문은 "어떤 워크플로가 어떤 모델에 얼마만큼의 비용을 쓰고 있는가"입니다. 저희 EvoLink는 프로바이더(provider)를 가로지르는 워크플로 단위의 비용 가시화(cost visibility) 작업을 진행하고 있습니다. 관심이 있다면 한 번 살펴보시기 바랍니다.