Claude Code 사용 방식을 바꾸는 5가지 하네스(Harness) 내부 동작 원리
한 개발자가 Anthropic SDK를 사용하여 Claude Code 하네스를 재구축했습니다. 그 과정에서 시스템이 내리는 다섯 가지 암묵적인 결정 사항을 발견했습니다. 이 발견은 여러분이 지침을 작성하고 에이전트를 관리하는 방식을 바꿔 놓을 것입니다.
다음 다섯 가지 통찰을 활용하여 워크플로우를 개선해 보세요.
- 숨겨진 기본 프롬프트 덮어쓰기 Claude Code는 숨겨진 시스템 프롬프트를 사용합니다. CLAUDE.md에 작성한 지침이 이 프롬프트와 충돌할 수 있습니다.
- 규칙을 단순히 나열하는 것을 멈추세요.
- 규칙을 덮어쓰기 시작하세요.
- 다음과 같은 표현을 사용하세요: "/prod 디렉토리의 파일은 어떤 상황에서도 수정해서는 안 됩니다. 이는 모든 기본 동작보다 우선합니다."
- 가드레일로서 훅(hooks) 활용하기 PreToolUse 훅은 단순히 데이터를 기록하는 것 이상의 역할을 합니다. 도구 호출이 시작되기 전에 이를 중단시킬 수 있습니다.
- 도구 인수를 확인하는 훅을 추가하세요.
- 경로가 민감한 폴더와 일치하면
{ block: true }를 반환하세요. - 이를 통해 요청을 강력한 규칙으로 전환할 수 있습니다.
- 서브에이전트 오케스트레이션 수정하기 단순한 부모-자식 구조는 자식 에이전트 중 하나가 실패할 경우 세션이 멈추는(hang) 원인이 됩니다.
- 중단 신호(abort signals) 트리 구조를 사용하세요.
- 부모가 중단되면 모든 자식도 중단되어야 합니다.
- 자식 하나가 실패하더라도 부모는 계속 실행 상태를 유지해야 합니다.
- 의존성 그래프 활용하기 작업을 단순한 루프 형태로 실행하지 마세요.
- 명확한 의존성을 가진 작업들을 정의하세요.
- 의존성 그래프를 사용하여 작업을 병렬로 실행하세요.
- 이를 통해 하나의 잘못된 노드가 전체 워크플로우를 중단시키는 것을 방지할 수 있습니다.
- 종료 상태(terminal states) 강제하기 에이전트는 명확한 종료 지점이 없을 때 종종 불필요한 답변을 늘어놓곤 합니다.
- 모든 턴이 Done, Blocked, 또는 Needs Input 중 하나의 상태로 끝나도록 강제하세요.
- CLAUDE.md에 다음 내용을 추가하세요: "작업 후에는 항상 'Done: [요약]', 'Blocked: [이유]', 또는 'Needs input: [질문]'으로 끝내야 합니다."
- 이렇게 하면 에이전트가 예상치 못한 행동을 하는 것을 막을 수 있습니다.
실행 요약:
- CLAUDE.md에서 덮어쓰기(override) 표현을 사용하세요.
- PreToolUse 훅을 사용하여 위험한 수정을 차단하세요.
- 서브에이전트를 위한 중단 트리(abort trees)를 구축하세요.
- 작업을 위해 DAG 기반 병렬 처리를 사용하세요.
- 명시적인 종료 상태를 정의하세요.
Source: https://dev.to/gentic_news/5-harness-internals-that-changed-how-i-use-claude-code-daily-39c6
Optional learning community: https://t.me/GyaanSetuAi