27장: 프로덕션 등급 AI 코딩 패턴

이것이 중요한 이유

이전 두 장에서는 하네스 엔지니어링 및 상황 관리에 대해 생각하는 방법에 대한 높은 수준의 지침인 "원칙"을 정리했습니다. 이 장은 다릅니다. 8가지 구체적이고 직접 재사용 가능한 코딩 패턴에 중점을 둡니다. 각 패턴은 명확한 문제 정의, 구현 접근 방식 및 소스 코드 증거와 함께 Claude Code의 실제 구현에서 추출됩니다.

이러한 패턴은 공통된 특성을 공유합니다. 사소해 보일 만큼 단순해 보이지만 프로덕션 환경에서 필요에 따라 반복적으로 검증되었습니다. "편집 전 읽기" — 읽지 않고 편집할 사람이 누가 있겠습니까? 그러나 AI 모델은 실제로 읽기를 건너뛰고 직접 편집하기 때문에 Claude Code는 도구 오류로 이를 시행합니다. "방어적 Git" — 물론 강제로 푸시하면 안 되지만 Claude Code는 전체 프롬프트 단락에서 푸시를 강조합니다. 압박을 받는 모델은 실제로 최단 경로를 선택하기 때문입니다.

소스 코드 분석

27.1 패턴 1: 편집 전 읽기

문제: AI 모델은 현재 내용을 읽지 않고 파일을 편집하려고 시도하여 오래되거나 잘못된 가정을 기반으로 편집을 유발할 수 있습니다.

Claude Code는 이중 계층 보호를 통해 이를 시행합니다.

1. 프롬프트 레이어(소프트 제약 조건): FileEditTool의 설명에는 "편집하기 전에 대화에서 읽기 도구를 한 번 이상 사용해야 합니다. 이 도구는 파일을 읽지 않고 편집을 시도하면 오류가 발생합니다"라고 명시되어 있습니다(자세한 내용은 8장 참조).
2. 코드 레이어(하드 제약 조건): FileEditTool의 call() 메서드는 편집을 실행하기 전에 현재 대화에 대상 파일에 대한 읽기 호출이 포함되어 있는지 확인합니다. 그렇지 않으면 오류를 반환합니다.

이중 계층 보호 장치의 설계 중요성은 다음과 같습니다. 프롬프트는 "소프트 제약 조건"입니다. 모델은 대부분의 경우 프롬프트를 따르지만 특정 조건(컨텍스트가 너무 길어 지침을 "잊어버리게" 만들고 여러 차례 대화에서 주의가 흐트러짐)에서는 프롬프트가 무시될 수 있습니다. 코드 레이어는 "하드 제약"입니다. 모델이 프롬프트를 무시하더라도 도구 자체는 실행을 거부합니다.

27.2 패턴 2: 단계적 자율성

문제: AI 에이전트는 "모든 단계에서 사용자에게 묻기"(낮은 효율성)와 "묻지 않음"(높은 위험) 사이의 균형을 찾아야 합니다.

Claude Code는 가장 제한적인 것부터 가장 허용적인 것까지 권한 모드 그라데이션을 설계했습니다(자세한 내용은 16장 참조).

default → acceptEdits → plan → BypassPermissions → auto → dontAsk │ │ │ │ │ │ │ │ │ │ └── 완전 자율성 │ │ │ │ └── 분류자가 자동 결정 │ │ │ └── 권한 확인 건너뛰기 │ │ └── 계획만, 실행 안 함 │ └── 자동 수락 수정, 기타 확인 └── 모든 단계 확인

핵심 디자인은 모드 자체가 아니라 폴백을 통한 자동화입니다. auto 모드는 YOLO 분류자(자세한 내용은 17장 참조)를 사용하여 자동으로 권한 결정을 내리지만 두 개의 안전 밸브가 있습니다. 거부 추적 구현은 매우 간결합니다.

// restored-src/src/utils/permissions/denialTracking.ts:12-15
export const DENIAL_LIMITS = {
  maxConsecutive: 3,
  maxTotal: 20,
} as const

// restored-src/src/utils/permissions/denialTracking.ts:40-44
export function shouldFallbackToPrompting(
  state: DenialTrackingState
): boolean {
  return (
    state.consecutiveDenials >= DENIAL_LIMITS.maxConsecutive ||
    state.totalDenials >= DENIAL_LIMITS.maxTotal
  )
}

분류자가 작업을 연속 3회 또는 총 20회 거부하면 시스템은 영구적으로 수동 사용자 확인으로 대체됩니다. 이는 가장 자율적인 모드에서도 시스템이 인간의 의사 결정으로 돌아갈 수 있는 능력을 유지한다는 것을 의미합니다. 자율성은 "전부 아니면 전무"가 아니라 모든 위치에 안전망이 있는 연속 스펙트럼입니다.

27.3 패턴 3: 방어적인 Git

문제: AI 모델은 Git 작업을 실행할 때 "최단 경로"를 선택하여 데이터가 손실되거나 복구하기 어려운 상태로 이어질 수 있습니다.

Claude Code는 다음을 포함한 핵심 규칙과 함께 BashTool 프롬프트에 완전한 Git 안전 프로토콜을 포함합니다(자세한 내용은 8장 참조).

1. 후크를 건너뛰지 마세요(--no-verify): 사전 커밋 후크는 프로젝트의 품질 관문입니다.
2. 수정하지 않음(사용자가 명시적으로 요청하지 않는 한): git commit --amend는 이전 커밋을 수정하며 후크 실패 후 이를 사용하면 사용자의 이전 커밋을 덮어쓰게 됩니다.
3. 특정 파일 선호: 실수로 .env 또는 자격 증명 파일을 추가하는 것을 방지하려면 git add -A 대신 git add <specific-files>를 사용하세요.
4. 메인/마스터에 강제로 푸시하지 마세요: 사용자가 요청하더라도 경고합니다.
5. 수정하기보다는 새 커밋 만들기: 후크 실패 후 커밋이 발생하지 않았습니다. 이 시점에서 --amend는 이전 커밋을 수정합니다.

규칙 5가 특히 중요합니다. 후크가 실패하면 모델의 자연스러운 성향은 "문제를 수정한 다음 수정"입니다. 그러나 프롬프트에서는 인과 관계를 명시적으로 설명합니다.

사전 커밋 후크 실패는 커밋이 발생하지 않았음을 의미하므로 --amend는 이전 커밋을 수정하여 이전 작업을 파괴하거나 변경 사항을 잃을 수 있습니다. 올바른 조치는 문제를 수정하고, 다시 준비하고, 새 커밋을 생성하는 것입니다.

이러한 규칙이 존재한다는 것은 모델이 실제로 이러한 실수를 한다는 것을 나타냅니다. 훈련 데이터에는 후크 실패와 일반 커밋을 구분하지 않고 "마지막 커밋 수정"을 수정하도록 권장하는 수많은 Git 튜토리얼이 포함되어 있습니다.

27.4 패턴 4: 구조화된 검증

문제: AI 모델은 실제로 검증을 실행하지 않고도 "테스트 통과" 또는 "코드가 정확함"을 주장할 수 있습니다.

Claude Code는 시스템 프롬프트에서 명확한 검증 체인을 설정합니다(자세한 내용은 6장 참조). 테스트 실행 → 출력 확인 → 정직하게 보고합니다. 단순해 보이는 이 흐름은 여러 메커니즘을 통해 강화됩니다.

가역성 인식. 운영은 위험에 따라 등급이 지정되며 모델은 이를 다르게 처리할 것으로 예상됩니다.

범위 제약. 모델에는 "X에 대한 승인이 Y로 확장되지 않습니다"라는 메시지가 표시됩니다. 버그를 수정해도 테스트 케이스 수정이나 테스트 건너뛰기가 승인되지 않습니다.

Ant 전용 강화 지시문. Capybara v8은 "검증 없이 완료를 주장"하는 모델의 경향에 대한 명시적인 대책을 추가했습니다.

// restored-src/src/constants/prompts.ts:211
// @[MODEL LAUNCH]: capy v8 thoroughness counterweight
`Before reporting a task complete, verify it actually works: run the
test, execute the script, check the output. Minimum complexity means
no gold-plating, not skipping the finish line. If you can't verify
(no test exists, can't run the code), say so explicitly rather than
claiming success.`

@[MODEL LAUNCH] 주석은 이것이 모델 버전별 동작 수정임을 나타냅니다. 모델이 업그레이드되면 팀에서는 이 지침이 여전히 필요한지 여부를 재평가합니다.

27.5 패턴 5: 범위 일치 응답

문제: AI 모델은 버그를 수정하는 동안 리팩토링하고, 기능을 추가하는 동안 문서를 업데이트하는 등 추가 작업을 "우연히" 수행하는 경향이 있어 변경 범위가 통제 불능 상태가 됩니다.

Claude Code의 시스템 프롬프트에는 일련의 매우 구체적인 범위 제한 지시문이 포함되어 있습니다(자세한 내용은 6장 참조). 가장 중요한 세트는 getSimpleDoingTasksSection()에서 제공됩니다.

// restored-src/src/constants/prompts.ts:200-203
"Don't add features, refactor code, or make 'improvements' beyond what
 was asked. A bug fix doesn't need surrounding code cleaned up. A simple
 feature doesn't need extra configurability. Don't add docstrings,
 comments, or type annotations to code you didn't change."

"Don't add error handling, fallbacks, or validation for scenarios that
 can't happen. Trust internal code and framework guarantees."

"Don't create helpers, utilities, or abstractions for one-time operations.
 Don't design for hypothetical future requirements. ... Three similar
 lines of code is better than a premature abstraction."

이러한 지시문의 특수성에 주목하세요. 추상적인 "단순함을 유지하세요"가 아니라 결정 가능한 규칙입니다. "수정하지 않은 코드에 독스트링을 추가하지 마세요", "세 줄이 반복되는 것이 조기 추상화보다 낫습니다."

또 다른 우아한 범위 제한은 "인증이 확장되지 않음"입니다. 사용자가 git push를 승인했으며 모델은 이를 "사용자가 모든 Git 작업을 승인합니다"로 해석할 수 있습니다. 프롬프트는 이러한 추론을 깨뜨립니다. 권한 부여 범위는 명시적으로 지정된 범위이며 그 이상은 없습니다.

27.6 패턴 6: 일반 지침에 대한 도구 수준 프롬프트

문제: 일반 시스템 프롬프트에 지침이 너무 많으면 모델이 적시에 올바른 지침을 불러오기가 어렵습니다.

Claude Code를 사용하면 시스템 프롬프트에 모든 동작 지침을 입력하는 대신 각 도구가 자체 동작 하네스를 수행할 수 있습니다(자세한 내용은 8장 참조).

도구 수준 프롬프트의 장점은 시간적 정렬입니다. 모델이 BashTool을 호출하기로 결정하면 BashTool의 설명(Git 안전 프로토콜 포함)이 주의의 초점 내에 있습니다. Git 안전 프로토콜이 시스템 프롬프트에 있는 경우 모델은 수만 개의 컨텍스트 토큰에서 이를 "호출"해야 하므로 긴 세션에서는 신뢰할 수 없습니다.

도구 수준 프롬프트의 또 다른 장점은 캐시 효율성입니다. tools 매개변수의 일부인 도구 설명은 API 요청에서 상대적으로 안정적인 위치를 차지합니다. 도구 설명 수정은 시스템 프롬프트 세그먼트가 아닌 도구 목록 해시에만 영향을 미칩니다. 캐시 중단 감지의 perToolHashes(restored-src/src/services/api/promptCacheBreakDetection.ts:36-38)는 전체 캐시 접두어를 무효화하는 대신 변경된 도구 설명을 정확하게 추적하기 위해 존재합니다.

27.7 패턴 7: 쉘 텍스트 구문 분석을 통한 구조적 검색

문제: 모델이 grep, find, ls 및 기타 셸 명령의 원시 출력을 직접 사용하는 경우 매 라운드마다 path:line:text, 줄바꿈으로 구분된 경로, 카운트 요약 및 다양한 노이즈 접두어를 구문 분석해야 합니다. 검색 라운드가 증가함에 따라 이러한 "모델이 문자열 분할을 반복적으로 수행하도록 하는" 접근 방식은 컨텍스트와 추론 예산을 모두 낭비합니다.

Claude Code의 검색 디자인은 이미 부분적으로 반대 방향을 반영하고 있습니다. 검색은 Bash의 사용 사례가 아니라 독립적인 읽기 전용 도구입니다(자세한 내용은 8장 참조). GrepTool 및 GlobTool는 모두 셸 파이프라인이 아닌 내부적으로 전용 구현을 사용하고 내부적으로 구조화된 결과를 먼저 생성한 다음 모델에서 tool_result로 사용할 수 있는 최소 형식으로 직렬화합니다.

GrepTool의 내부 출력에는 검색 패턴, 파일 목록, 일치하는 콘텐츠, 개수 및 페이지 매김 정보가 포함됩니다.

// Simplified from GrepTool's outputSchema
{
  mode: 'content' | 'files_with_matches' | 'count',
  numFiles,
  filenames,
  content,
  numLines,
  numMatches,
  appliedLimit,
  appliedOffset,
}

GlobTool의 내부 출력은 마찬가지로 모델에 직접 제공되는 rg --files의 원시 stdout이 아닌 구조화된 객체입니다.

// Simplified from GlobTool's outputSchema
{
  durationMs,
  numFiles,
  filenames,
  truncated,
}

하지만 더 흥미로운 점은 다음 단계입니다. Claude Code는 이러한 개체를 다시 모델로 완전히 JSON 직렬화하지 않습니다. 대신, "내부적으로 구조화되고 외부적으로 텍스트화"되는 타협을 선택합니다. files_with_matches 모드의 GrepTool는 파일 경로 목록만 반환하고, count 모드에서는 path:count 요약을 반환하며, content 모드에서만 실제 일치하는 줄을 반환합니다. GlobTool는 경로 목록과 잘림 힌트만 반환합니다. 이는 실제 최적화 목표가 "구조 자체"가 아니라 모델이 현재 결정에 필요한 최소한의 정보만 보는 동안 하네스 자체 구조를 허용하는 것임을 보여줍니다.

하네스 엔지니어링 관점에서 이는 grep/glob 자체보다 더 중요한 패턴인 단계별 검색 프로토콜로 이어집니다. 이상적인 에이전트 기반 검색은 모델이 대량의 일치하는 라인을 미리 삼키도록 허용하지 않고 세 개의 레이어로 분할되어야 합니다.

1. 후보 파일 레이어: 첫 번째 반환 경로, 안정적인 ID, 수정 시간 및 기타 경량 메타데이터로 "어떤 파일을 살펴볼 가치가 있는지"에 답합니다.
2. 적중 요약 레이어: 그런 다음 파일당 일치 횟수, 첫 번째 적중 위치, 첫 번째 발췌문을 반환하고 "먼저 확장할 파일"에 답합니다.
3. 스니펫 확장 레이어: 마지막으로 선택한 파일에 대해서만 정확한 스니펫과 줄 번호를 반환하고 "어떤 특정 코드 세그먼트를 살펴봐야 하는지"에 답합니다.

Claude Code는 아직 이 세 가지 계층을 독립적인 도구로 완전히 분할하지 않았지만 기존 구현에는 이미 전용 검색 도구 및 구조화된 중간 결과라는 두 가지 주요 전제 조건이 있습니다. 추가 증거는 ToolSearchTool가 이미 일반 텍스트에 국한되지 않는 더 풍부한 블록 유형인 tool_reference를 반환할 수 있다는 것입니다. 이는 Claude Code와 같은 하네스에서 "셸 텍스트를 직접 구문 분석하는 모델"이 유일한 옵션이 아니며 최선의 옵션이 아닐 수도 있음을 나타냅니다.

27.8 패턴 8: 적절한 크기의 도우미 경로

문제: 모든 쿼리가 메인 루프의 무거운 모델, 전체 도구 풀 및 다중 턴 에이전트 루프를 따르는 경우 경량 도우미 경로는 비용이 많이 들고 느려지며 작업에 필요한 것보다 더 많은 기능 표면이 부여되는 경우가 많습니다.

Claude Code의 접근 방식은 노골적으로 "전역적으로 작은 모델로 전환"하는 것이 아니라 호출 사이트당 가장 비싼 차원을 줄이는 것입니다. 세션 제목 생성 및 도구 사용 요약은 모두 queryHaiku()를 거칩니다. claude.ts는 compact, side_question, extract_memories 등도 non-agentic queries로 분류합니다. 한편 /btw는 작은 모델로 새 에이전트를 가동하지 않고 상위 세션 컨텍스트를 상속하고 runForkedAgent()를 통해 원샷 사이드 쿼리를 실행하고 도구 기능을 0으로 줄이고 1로 바꿉니다.

이는 Claude Code의 실제 패턴이 단순히 "로컬 모델 선택"이 아니라 더 일반적인 적절한 크기 조정 기능을 보여줍니다. 때로는 모델 축소, 때로는 도구 축소, 회전 축소, 때로는 컨텍스트 축소입니다. 표준 하위 에이전트, 포크, /btw 및 제목/요약 도우미는 각각 다른 차원에 따라 정리됩니다.

여기서 가장 중요한 점은 모든 도우미 경로에 동일한 "모든 기능을 갖춘 에이전트" 형식을 제공하지 마세요입니다. 부가 질문은 "현재 질문에 답변"하는 데 필요한 기능만 유지하므로 가볍습니다. 제목 생성은 "짧은 문자열 생성"에 필요한 모델 강도만 유지하므로 비용이 저렴합니다. Claude Code는 "모델 크기, 도구 권한, 회전 예산, 컨텍스트 상속"을 전역적으로 통합된 구성이 아닌 독립적으로 확장 가능한 4개의 손잡이로 처리합니다.

패턴 증류

8가지 패턴 요약표

표 27-1: 8가지 생산 등급 패턴 요약

도구 실행 수명주기의 패턴 위치

그림 27-1: 도구 실행 수명 주기에서 8개 패턴의 위치

적절한 크기의 도우미 경로는 도우미 경로에서 작동합니다. 도우미 쿼리에 실제로 무거운 모델, 전체 도구 및 다중 회전 상태가 필요한지 여부를 결정합니다. 구조화된 검색은 초기 탐색 단계에 위치합니다. 즉, 모델에 표시되는 검색 결과와 이러한 결과가 컨텍스트에 입력되는 세부 수준을 결정합니다. 도구 수준 프롬프트는 전체 수명 주기에 걸쳐 적용됩니다. 나머지 7개 패턴은 모두 도구 프롬프트를 통해 구현됩니다. 편집 전 읽기 및 범위 일치 응답은 실행 전 준비를 제한합니다. 방어적 Git 및 Graduated Autonomy는 실행 중 안전 경계를 제어합니다. 구조화된 검증은 실행 후 정확성을 보장합니다.

전역 패턴: 이중 계층 제약 조건

• 문제 해결됨: 프롬프트만으로는 모델의 규칙 준수를 100% 보장할 수 없습니다.
• 핵심 접근 방식: 고위험 행동의 경우 프롬프트를 '소프트 제약'으로 사용하고 코드를 '하드 제약'으로 사용합니다.
• 코드 템플릿: 도구 설명에 규칙이 명시되어 있음 → call() 메서드가 전제 조건을 확인하고 → 충족되지 않으면 오류를 반환함
• 선제조건: 코드 레이어에서 전제조건을 감지하는 기능

전역 패턴: 안전 기울기

• 문제 해결: 다양한 작업에는 다양한 수준의 자율성이 필요합니다.
• 핵심 접근 방식: 각각 명확한 안전망을 갖춘 다단계 모드
• 전제조건: 운영 위험 수준을 평가할 수 있는 능력

글로벌 패턴: 단계적 검색 프로토콜

• 문제 해결: 개방형 코드베이스 검색은 빠르게 컨텍스트를 소비하고 모델이 텍스트 결과를 반복적으로 구문 분석하도록 합니다.
• 핵심 접근 방식: 먼저 후보 파일을 반환한 다음 요약을 누른 다음 필요에 따라 정확한 스니펫을 확장합니다.
• 전제 조건: 검색 도구는 원시 표준 출력뿐만 아니라 페이지 매김, 개수 및 안정적인 참조를 반환할 수 있습니다.

글로벌 패턴: 역량 적정 규모 조정

• 문제 해결: 도우미 쿼리는 기본적으로 기본 스레드의 전체 기능을 상속하므로 비용과 위험이 필요 이상으로 높아집니다.
• 핵심 접근 방식: 하나의 '모든 기능을 갖춘 에이전트'만 제공하는 대신 통화 사이트당 모델, 도구, 차례 또는 컨텍스트를 독립적으로 줄입니다.
• 전제 조건: 런타임은 모델 라우팅, 도구 권한 및 예산 전환을 독립적으로 제어할 수 있습니다.

당신이 할 수 있는 일

1. 중요한 동작에 대한 이중 계층 제약 조건을 구현합니다. 동작을 위반하면 되돌릴 수 없는 결과가 발생할 경우 프롬프트에만 의존하지 마십시오. 도구 코드에 전제 조건 검사를 추가하세요.
2. 바이너리 스위치가 아닌 디자인 권한 그라데이션. 에이전트에 최소 3가지 자율성 수준 제공: 수동 확인, 분류자 자동 결정(대체 포함), 완전 자율성
3. Git 작업 프롬프트에서 인과관계를 명시적으로 설명합니다. "수정하지 않음"만으로는 충분하지 않습니다. "후크 실패 후 수정하면 이전 커밋이 수정되어 변경 내용이 손실됩니다"라고 설명하세요.
4. 검증 출력을 표시하려면 모델이 필요합니다. "테스트 통과"라는 텍스트 보고서를 허용하지 마십시오. 실제 테스트 출력을 표시해야 합니다.
5. 모호한 지침을 구체적인 규칙으로 대체하세요. "코드 품질 유지"를 "수정되지 않은 코드에 주석을 추가하지 않음"으로 바꾸십시오. "세 줄이 반복되는 것이 조기 추상화보다 낫습니다."
6. 해당 도구에 행동 지침을 첨부하세요. Git 안전 규칙은 Bash 도구 설명에 들어가고, 파일 작업 규칙은 파일 도구 설명에 들어갑니다. 시스템 프롬프트에 모든 것을 쌓지 마세요.
7. 모델이 쉘 검색 텍스트를 반복적으로 구문 분석하도록 하지 마세요. 검색을 "후보 파일 → 적중 요약 → 정확한 스니펫" 3단계로 분할합니다. 이는 큰 grep 출력을 미리 반환하는 것보다 컨텍스트 효율적입니다.
8. 모든 도우미에게 모든 기능을 제공하지 마세요. 제목, 요약, 부가 질문 및 메모리 추출 경로는 기본 루프를 복사하는 대신 모델, 도구 또는 회전을 별도로 다듬어야 합니다.