Claude Code 구성 설정을 위한 30가지 작동 원칙 (피드백 요청)

I. Context Economics

1. Dilution Is the Failure Mode (희석이 실패 모드이다)

컨텍스트 내의 모든 요소는 주의를 놓고 경쟁합니다. 실패 모드는 단순히 낭비된 토큰이 아닙니다—그것은 희석입니다. 더 큰 컨텍스트 창(context window)이 희석을 완화하지 못하고 오히려 증폭시킵니다. 규칙 하나를 추가하는 눈에 보이는 비용은 계속 떨어지는 반면, 주의 집중 비용은 그렇지 않기 때문입니다.

상태(phase, 구축된 내용, 대기 중인 내용)는 다른 곳에 위치해야 하며, 이상적으로는 파이프라인(pipeline)에 의해 기계적으로 업데이트되어야 합니다.

II. 계층 규율 (Layer Discipline)

5. 적절한 계층 찾기

문제가 발생하면, 이를 해결할 수 있는 가장 구조적인 계층을 찾아 그곳에서 해결하십시오. 계층은 다음과 같습니다:

• 구조 (Structure): 훅 (hooks), 도구 제한 (tool restrictions), 파일 권한 (file permissions)
• 프로세스 설계 (Process design): 에이전트 (agents) 간의 관심사 분리 (separation of concerns)
• 에이전트 지침 (Agent instructions): 판단 및 순서 지정 (sequencing)에 집중
• 경로 범위 규칙 (Path-scoped rules): 관련이 있을 때만 로드되는 행동 규칙
• 환경 규칙 (Ambient rules): 매 세션마다 로드되는 행동 기대치
• CLAUDE.md: 프로젝트 방향 설정 (가장 희석되기 쉬움)

만약 빌더(builder)가 계속해서 테스트를 수정한다면, 이는 지침(layer 3)이 아니라 훅(layer 1)이 필요한 상황입니다. 반복되는 문제에 대해 구조적 강제(structural enforcement) 대신 더 많은 지침으로 대응하는 것이 가장 흔한 실수입니다.

문제가 오케스트레이션(orchestration) 자체(다음에 무엇이 실행될지, 어떤 순서로 실행될지, 어떤 재시도(retries)를 할지)인 경우, 가장 구조적인 옵션은 에이전트의 차례별 판단(turn-by-turn judgment)에 맡기는 대신 결정론적 스크립트(deterministic script)에 제어 흐름(control flow)을 유지하는 것입니다. 코드로서의 오케스트레이션(Orchestration-as-code)은 관례에 의한 분리(separation-by-convention, 2)나 코디네이터 지침(coordinator instructions, 3)보다 우선순위가 높습니다. 스크립트는 추론을 통해 우회할 수 없으며, 스스로 작업을 수행하기로 조용히 결정할 수도 없기 때문입니다. 이것이 판단/메커니즘 축에서 어디에 위치하는지는 III 섹션을 참조하십시오.

6. 적시 지식 (Just-in-Time Knowledge)

지침은 영구적인 부하로 미리 로드되는 것이 아니라, 문맥적으로 관련이 있는 순간에 전달될 때 가장 효과적입니다. 경로 범위 규칙(Path-scoped rules)은 Claude가 일치하는 파일에 접근할 때 로드됩니다. 기술(Skills)은 호출될 때 로드됩니다. 에이전트 프롬프트(Agent prompts)는 생성 시점(spawn time)에 문맥을 전달합니다. 특정 도메인을 위한 범위 지정 규칙 파일은 다른 도메인에서 작업하는 동안 문맥(context)을 소모하지 않습니다.

7. 훅은 추론으로 우회할 수 없다 (Hooks Can't Be Reasoned Past)

동작을 차단하는 훅은 추론을 통해 우회할 수 없지만, "X를 하지 마시오"라고 말하는 지침은 우회할 수 있습니다. 행동 규칙이 계속 위반된다면, 이를 구조적 훅으로 격상시키는 것이 다음 단계입니다. 훅 출력에 코칭 피드백(#11)을 포함하면 조용한 거부보다 훨씬 효과적입니다.

에이전트는 시행착오 없이 실행 가능한 피드백을 받게 됩니다.

8. 하나의 질문에 답하기

CLAUDE.md는 "이 프로젝트는 무엇이며, 각 요소는 어디에 있는가?"라는 질문에 답합니다: 프로젝트의 정체성, 아키텍처 지침, 취약한 영역 등입니다. 행동 규칙(Behavioral rules), 도메인 지식(Domain knowledge), 프로세스 지침(Process instructions)은 모두 더 적합한 위치가 있습니다: 조건부로 로드되거나 프로젝트 전반에 걸쳐 템플릿화될 수 있는 곳들입니다.

III. 판단(Judgment) vs. 메커니즘(Mechanism)

여기에서의 축은 두 개의 끝점을 가집니다: 스크립트(결정론적(deterministic), 판단 없음)와 기술(skill, 상황을 읽는 것이 올바른 행동을 결정하기 때문에 LLM이 루프 내에 포함됨)입니다. 세 번째 지점이 그 사이에 위치합니다. 단계 자체가 판단을 요구하는 스크립트는 비결정론적(non-deterministic) 에이전트들의 결정론적 오케스트레이션(orchestration)입니다. 즉, 시퀀싱(무엇이, 어떤 순서로 실행되는지, 몇 번 재시도하는지)은 코드이므로 추론을 통해 넘어서거나 조용히 적응할 수 없는 반면, 각 단계 내부의 작업은 여전히 판단을 수행하는 에이전트입니다. 결정론은 시퀀싱에 두고, 판단은 단계(steps)에 두십시오.

9. 기술의 토큰 비용은 식별(Discernment)의 비용이다

스크립트는 더 저렴하고, 빠르며, 완전히 결정론적입니다. 루프 내에 LLM을 포함시켜 토큰 비용을 지불하는 이유는 올바른 행동이 상황을 읽는 것에 달려 있기 때문입니다. diff를 검토하고 적절한 메시지를 작성하는 커밋 기술(commit skill)은 git commit -m "update"가 결코 할 수 없는 일을 수행합니다. 단순히 pytest를 실행하기만 하는 테스트 러너(test runner)는 기술(skill)일 필요가 없습니다. 요구되는 판단에 맞춰 메커니즘을 매칭하십시오.

10. 기계적인 것은 자동화하고, 판단을 위해 턴(turns)을 확보하라

에이전트가 자신의 턴 중 절반을 스크립트나 기술로 처리할 수 있는 상용구(boilerplate)를 실행하는 데 소비한다면, 이는 세 가지 비용을 동시에 발생시킵니다: 주의력 분산(명확성 저하), 기계적인 출력으로 가득 찬 컨텍스트(품질 저하), 그리고 판단 가치가 없는 API 비용(비용 발생)입니다. 최고의 기술은 기계적인 단계에는 스크립트를 사용하고, 판단이 필요한 부분에 LLM의 주의력을 예약합니다. 명확성, 품질, 비용 모두 동일한 방향을 가리키고 있습니다.

코칭이 침묵하는 차단보다 낫다

행동을 차단하면서 에이전트에게 그 이유를 알려주는 훅(hook)은 침묵하는 거부(silent denial)보다 훨씬 효과적입니다. 가공되지 않은 git commit에 대해 침묵하며 차단하면, 에이전트는 다른 경로를 찾으려 시도합니다: 수동으로 스테이징(staging)을 하거나, 대안적인 구문을 시도하며, 결국 해당 기술(skill)을 우회하여 커밋할 수 있는 방법을 찾아내고 맙니다. 반면 "차단됨: diff를 검토하고 프로젝트 컨벤션을 따르는 /commit 기술을 사용하세요"라고 알려주면 에이전트는 즉시 올바른 도구로 향합니다. 차단 자체는 여전히 결정론적(deterministic)이지만, 코칭을 통해 이를 유용하게 만드는 것입니다.

12. 판단력이 복리로 작용하는 곳에 투자하라

모든 라인이 판단(judgment)을 얻게 된다면, 포괄성(comprehensiveness)은 희석이 아닌 강화가 됩니다. 비용 계산은 프롬프트가 어디에 위치하느냐에 따라 달라집니다. 다음 세 가지 범주가 중요합니다:

판단 승수(Judgment multipliers, 예: 플래너(planners), 평가자(evaluators)): 포괄적인 프롬프트는 생성되는 모든 하위 에이전트와 제품의 품질 상한선을 높입니다. 깊이 있게 투자하십시오.
판단 엔드포인트(Judgment endpoints, 예: 문서 큐레이터(doc-curator)): 하위에 품질 게이트(quality gate)가 없습니다. 기준이 내재화되어 있어야 합니다.
실행 에이전트(Execution agents, 예: 빌더(builders), 검증자(verifiers)): 상위의 판단 에이전트가 강력하다면 가볍게 유지할 수 있습니다.

IV. 자율성 및 안전성

13. 도로가 아닌 절벽을 보호하라

실패를 감지할 수 있고 복구 가능하다면, 허용적인(permissiveness) 태도가 선호됩니다. 만약 실패가 되돌릴 수 없다면, 기본적으로 거부하십시오.
허용성은 두 가지, 즉 가시성과 적응성을 얻어다 줍니다. 실수는 증거입니다. 수정해서는 안 될 파일을 수정하는 빌더는 구조적으로 수정해야 할 패턴을 보여주며, 이는 엄격한 제약이 있었다면 숨겨졌을 것입니다. 또한 유능한 모델은 규칙이 예상하지 못한 예외 상황(edge cases)에 판단력을 발휘하여 더 나은 경로를 찾고 놀라운 상황에서 복구해내지만, 이는 오직 그럴 수 있는 여유가 있을 때만 가능합니다. 모델이 더 유능해질수록 제약에는 복리로 작용하는 비용이 따릅니다. 에이전트가 더 유능할수록, 가두어 둠으로써 포기해야 하는 것이 더 많아집니다. 절벽(예: git push --force, 추적되지 않은 작업에 대한 rm -rf)은 어떤 하위 에이전트도 되돌릴 수 없으므로 명시적으로 거부합니다. 그 외의 모든 것은 실행되도록 두고 지켜보십시오.

관찰 가능성(Observability) 없는 적응성은 리스크(Liability)입니다.

Claude의 적응성(Adaptiveness)은 파이프라인 내에서 가장 위험한 특성이기도 합니다. 무언가 실패했을 때, Claude는 멈춰서 보고하지 않습니다. 대신 적응합니다. 잘못된 방식으로 호출된 코디네이터(Coordinator)는 평가자(Evaluator)와 모든 품질 게이트(Quality gate)를 우회하여 스스로 모든 것을 수행해 버립니다. 고장 난 스킬(Skill)은 해당 스킬이 강제하던 모든 검사를 우회하여 조용히 로우 바시(Raw bash)로 폴백(Fallback)합니다. 이러한 조용한 적응은 탐지를 무력화하며, 복구 가능한 실패를 탐지 불가능한 실패로 변질시킵니다. 파이프라인 설계는 단순히 원래의 실패뿐만 아니라, 그 적응에 대한 탐지 기능도 구축해야 합니다.

15. 적응 과정을 드러내기

적응 자체가 문제는 아닙니다. 문제는 조용한 적응입니다. "X를 예상했으나 Y를 발견하여 Z를 수행함으로써 조정했습니다" 또는 "X를 시도했으나 Y 때문에 작동하지 않았습니다"라고 보고하는 에이전트는 설계된 대로 업무를 수행하고 있는 것입니다. 편차를 보고하는 것은 오버헤드(Overhead)가 아니라 업무의 일부입니다. 계획이 성공한 것처럼 보이도록 조용히 결과물을 만들어내는 에이전트는 모든 다운스트림(Downstream) 검사를 무력화합니다. 에이전트의 능력이 향상되고 파이프라인이 더 자율적으로 변할수록, 에이전트가 보고하는 내용이 인간을 루프 안에 유지(Human in the loop)시키는 핵심적인 지지대가 됩니다.

16. 언제 그만두어야 할지 알기

Claude는 결과물을 내놓도록 훈련되었으며 거의 항상 우회 방법(Workaround)을 찾아낼 수 있는데, 이것이 바로 문제입니다. 훈련의 핵심은 에이전트가 돌파할 수 없는 시점을 인식하는 것이 아니라, 돌파해서는 안 되는 시점을 설정하는 것입니다. Y를 사용하여 X를 구축하라는 요청을 받았을 때, 만약 Y가 고장 났다면 비극적일 정도로 유능한 에이전트는 조용히 범위를 "Y 없는 X"로 축소하고, 사용자가 경로를 수정할 수 없도록(사용자가 상황을 볼 수 없으므로) "성공"을 전달해 버립니다. 우회 방법이 결과물의 정체성을 바꾸거나, 범위를 조용히 축소하거나, 사용자가 반드시 알아야 할 문제를 덮어버리는 경우라면, 올바른 조치는 멈추고 보고하는 것입니다. 실제 문제를 드러내는 것은 업무의 대체 수단이 아니라 업무의 일부입니다. 정직한 중단은 인간의 결정 능력을 보존하지만, 비극적인 완수는 그 능력을 박탈합니다.

17. 인간은 기계적 승인이 아닌 결정을 위해 존재합니다

가치 높은 인간의 업무는 계획을 세우고, 범위를 정하며, 작업이 완료되었을 때 결정하는 것입니다.

자율 실행 (autonomous execution)이 가능해짐에 따라, 인간의 역할은 점점 더 체크포인트(checkpoint) 형태를 띠게 됩니다. 즉, 실시간으로 일상적인 도구 호출 (tool calls)을 승인하는 것이 아니라, 출력물을 검증하고, 승인(promotion)을 결정하며, 범위 설정 (scoping)에 관한 질문에 답하는 역할입니다. 구조적 강제 (Structural enforcement) (거부 규칙 (deny rules), 범위가 지정된 도구 (scoped tools), 훅 (hooks))가 안전 계층을 처리하므로, 인간의 주의력은 오직 인간만이 내릴 수 있는 결정에만 집중될 수 있습니다. bypassPermissions는 방해를 받지 않기 위한 정답이 아닙니다. 구조를 강화하는 것이 정답입니다.

V. 관심사의 분리 (Separation of Concerns)

18. 가장 강력한 규칙은 제한된 도구이다

Write 도구가 없는 에이전트는 프롬프트(prompt)에 무엇이라 적혀 있든 코드를 수정할 수 없습니다. 읽기 전용 (read-only) 도구만 가진 평가자 (evaluator)는 검토 도중 설득당해 즉석에서 수정을 수행할 수 없습니다. Write/Edit 권한이 없는 조정자 (coordinator)는 위임 (delegation)이 느리다고 느껴질 때 "직접 처리하겠다"라고 결정할 수 없습니다. 지시 사항 (instruction)에 의해 강제되는 행동적 분리는 제안에 불과하지만, 도구 구성 (tool configuration)에 의해 강제되는 행동적 분리는 제약 (constraint)입니다. 이는 에이전트 수준에서의 7번 원칙과 같습니다: 지시 사항은 제안이며, 도구 제한은 제약입니다.

19. 인센티브가 갈라질 때는 전문화하라

빌드 (build)와 평가 (evaluation)를 모두 수행하는 에이전트는 자신의 작업에 대해 관대하게 점수를 매기려는 인센티브를 갖게 됩니다. 특히 대안이 처음부터 다시 시작하는 것일 때 더욱 그렇습니다. 빌더 (builder)는 배포 (shipping)를 최적화하고, 평가자 (evaluator)는 결함을 찾아내는 것을 최적화합니다. 이 둘을 결합하면 두 압박의 평균치만을 얻게 됩니다. 분리는 각 압박을 격리하여 각 에이전트가 실제로 수행하도록 설계된 작업에 따라 평가받게 합니다. 이 원칙은 일반화될 수 있습니다: 역할을 결합했을 때 파이프라인이 감사 (audit)할 수 없는 충돌이 발생하는 곳이라면 어디든 에이전트를 분리하십시오. 왜냐하면 타협은 하류 단계의 체크 (downstream check)가 검사할 수 있는 산출물 (artifact)에서 일어나는 것이 아니라, 에이전트의 추론 (reasoning) 내부에서 일어나기 때문입니다.

20. 각 핸드오프 (Handoff)는 필터이다

핸드오프는 이전 에이전트가 본 내용을 그들이 반환한 내용으로 압축합니다. 즉, 다음 에이전트는 추론 과정이 아닌 출력물 (output)을 받게 됩니다. 그것이 종종 핵심입니다. 리서처 (researcher) 에이전트는 로그를 탐색하여 발견 사항을 전달하고, 문서 큐레이터 (doc-curator)는 라이브러리 문서를 중요한 내용 위주로 다듬습니다. 이 압축 자체가 가치입니다.

하지만 동일한 메커니즘이 신호 (signal)를 누락시킬 수도 있습니다. 빌더 (builder)가 특정 접근 방식을 왜 선택했는지 전달하지 않은 채 평가자 (evaluator)에게 작업을 넘기면, 평가자는 그것이 의도된 선택인지 아니면 실수인지 구분할 수 없습니다.

노이즈를 제거하여 신호를 증폭할 수 있는 지점에 각각의 경계 (boundary)를 배치하십시오. 이 실패는 양방향으로 발생합니다. 에이전트 (agent) 수가 너무 적으면 구조적 강제성 (structural enforcement)이 무너지고, 너무 많으면 신호가 저하됩니다. 어떤 필터도 완벽하지 않으며, 필터링이 도움이 되는 자연스러운 지점은 한정되어 있기 때문입니다. 또한 각 인수인계 (handoff) 과정에서는 생성 오버헤드 (spawn overhead)와 재정렬 (re-orientation) 비용이 발생합니다. 적절한 입도 (granularity)란 실제로 필요한 역량 분리 (capability separations)를 제공하는 최소한의 에이전트 수입니다. 코디네이터 (Coordinator) + 빌더 (builder) + 평가자 (evaluator) 조합이 대부분의 사례를 커버합니다. 계획 수립 (planning) 자체가 판단력이 많이 요구되는 단계라면 플래너 (planner)를 추가하십시오. "빌드가 통과되었는가?"라는 질문이 "이것이..."라는 질문과 분리 가능한 문제라면 검증자 (verifier)를 추가하십시오.