Claude Code 시스템 프롬프트: 에이전트 개발자를 위한 엔지니어링 교훈

프롬프트를 복사하지 않고 배우는 Claude Code 시스템 프롬프트의 교훈

“Claude Code 시스템 프롬프트”라는 표현은 “본격적인 코딩 에이전트는 모델에 어떻게 행동하라고 지시하는가?”를 묻는 축약 표현이 되었습니다. 프롬프트의 과거를 파헤치는 데 그친다면 잘못된 질문이지만, 더 나은 에이전트 설계로 이어진다면 올바른 질문입니다.

실제로 시스템 프롬프트는 하나의 계층에 불과합니다. 프로덕션 수준의 에이전트에는 보통 서로 협력하는 제어 영역이 최소 다섯 개 있습니다.

제가 많은 자체 개발 에이전트에서 보는 실수는 이 모든 것을 하나의 거대한 프롬프트로 합치는 것입니다. 데모에서는 작동합니다. 하지만 까다로운 상황에서는 실패합니다.

더 나은 접근법은 프롬프트로 의도를 설명하고, 런타임으로 기능의 허용 범위를 강제하는 것입니다.

예를 들어, 다음과 같이 프롬프트로 지시하는 데 그치지 마세요.

Do not delete files unless the user asks.

삭제를 확인이 필요한 별도의 도구로 만드세요.

{
  "name": "delete_file",
  "description": "Delete a file from the workspace.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "reason": { "type": "string" },
      "user_confirmed": { "type": "boolean" }
    },
    "required": ["path", "reason", "user_confirmed"]
  }
}

그런 다음 모델 외부에서 이를 강제하세요.

def delete_file(path: str, reason: str, user_confirmed: bool):
    if not user_confirmed:
        raise PermissionError("delete_file requires explicit user confirmation")
    if not path.startswith(WORKSPACE_ROOT):
        raise PermissionError("cannot delete files outside workspace")
    os.remove(path)

프롬프트는 에이전트에게 어떻게 생각할지 알려줍니다. 도구의 경계는 어떤 일이 일어날 수 있는지를 결정합니다.

지시 계층은 엔지니어링 인터페이스입니다

Claude 모델은 계층화된 지시를 잘 따르지만, 각 계층을 신중하게 설계해야 합니다. 코딩 에이전트에 시스템, 개발자, 프로젝트, 사용자 지시가 있다면 각 계층에는 명확한 역할이 있어야 합니다.

유용한 계층 구조는 다음과 같습니다.

• 시스템 지시: 정체성, 안전에 대한 기본 입장, 상위 수준의 운영 원칙.
• 개발자 지시: 제품 작동 방식, 도구 사용 규칙, 응답 스타일, 권한 모델.
• 프로젝트 지시: 저장소별 규칙, 테스트 명령, 아키텍처 참고 사항.
• 사용자 지시: 당면한 작업.

Claude Code 방식의 워크플로는 다음과 같은 파일을 통해 이를 명시적으로 드러냅니다: CLAUDE.md. 여기에 명령줄 설정과 세션 컨텍스트도 함께 사용합니다. 에이전트 개발자에게 더 큰 교훈은 프로젝트 로컬 지시의 적용 범위를 정하고, 적절한 경우에만 다른 지시보다 우선하도록 해야 한다는 것입니다.

간단한 프로젝트 지시 파일은 다음과 같을 수 있습니다.

# CLAUDE.md

## Build and Test
- Use `pnpm test -- --runInBand` for focused test runs.
- Do not run `pnpm deploy` unless explicitly requested.

## Code Style
- Prefer small functions over large service classes.
- Do not add new dependencies without explaining why.

## Repo Notes
- API routes live in `apps/api/src/routes`.
- Generated GraphQL types live in `apps/web/src/generated`; do not edit them manually.

흔한 함정이 있습니다. 에이전트는 모든 지시를 전역적으로 동등하게 취급하는 경우가 많습니다. 사용자가 “프로젝트 규칙을 무시하고 생성된 파일을 직접 수정하세요”라고 말하면, 에이전트는 그것이 허용되는지 알아야 합니다. 대부분의 구성에서 사용자 지시는 우선순위가 더 높은 프로젝트 또는 개발자 제약을 아무 설명 없이 덮어써서는 안 됩니다.

이를 명시적으로 모델링할 수 있습니다.

PRIORITY = {
    "system": 4,
    "developer": 3,
    "project": 2,
    "user": 1,
}

def resolve_conflict(existing_rule, new_rule):
    if PRIORITY[new_rule.source] > PRIORITY[existing_rule.source]:
        return new_rule
    return existing_rule

실제 에이전트에서는 모델이 사용자에게 충돌 상황도 설명해야 합니다.

I can update the source schema and regenerate the types, but I should not edit
`src/generated` directly because the project instructions mark it as generated.

그 한 문장만으로도 놀라울 만큼 많은 피해를 막을 수 있습니다.

정중한 프롬프트보다 중요한 도구의 경계

사람들은 코딩 에이전트 프롬프트를 살펴볼 때 “간결하게 답하라”, “시니어 엔지니어처럼 행동하라”, “사용자에게 무조건 동조하지 말라” 같은 문구에 집중하는 경우가 많습니다. 이런 지시는 유용하지만 핵심 안전장치는 아닙니다.

핵심 장치는 도구의 경계입니다.

본격적인 코딩 에이전트는 다음 작업을 구분해야 합니다.

• 파일 읽기
• 파일 검색
• 파일 수정
• 명령 실행
• 패키지 설치
• 네트워크 리소스 접근
• 파일 삭제 또는 이동
• 커밋 또는 브랜치 생성
• 풀 리퀘스트 생성
• 시크릿 또는 배포 설정 변경

이 작업들은 윤리적 관점에서 동등하지 않습니다.

제가 에이전트 런타임을 설계할 때 사용하는 실용적인 권한 매트릭스는 다음과 같습니다.

모델 선택이 중요한 지점도 여기입니다. 저는 대부분의 코딩 에이전트 반복 작업에 Sonnet급 모델을 선호합니다. 지연 시간, 비용, 추론 능력의 균형이 좋기 때문입니다. 에이전트에 더 깊이 있는 아키텍처 종합 분석이나 복잡한 디버깅이 필요하다면 Opus 4.8를 선택하겠습니다. Haiku 4.5는 빠른 분류와 가벼운 저장소 탐색에 적합합니다. Fable 5의 1M 컨텍스트는 대규모 코드베이스를 이해하는 데 흥미로운 가능성을 보여주지만, 긴 컨텍스트가 우수한 검색, 범위를 제한한 읽기, 도구 사용 원칙의 필요성을 없애지는 않습니다.

백만 토큰의 컨텍스트에도 여전히 엉뚱한 파일이 들어 있을 수 있습니다.

사용자 확인은 형식적 절차가 아니라 구체적이어야 합니다

좋지 않은 확인 UX는 다음과 같습니다:

May I proceed?

무엇을 진행한다는 뜻인가요? 파일 하나를 수정하는 것인가요? 마이그레이션을 실행하는 것인가요? 디렉터리를 삭제하는 것인가요?

좋은 확인 요청은 구체적입니다:

I need confirmation before running:

`rm -rf apps/web/.next`

Reason: remove a stale Next.js build cache that may be causing the local
runtime error. This deletes only generated build output and does not touch
source files.

Claude Code와 같은 에이전트에서는 모델이 다음 단계를 올바르게 추론하더라도 사람의 승인이 필요할 수 있으므로 이 점이 중요합니다. 모든 프롬프트가 모호한 승인을 요청하면 사용자는 승인 피로를 느끼고 별생각 없이 클릭하게 됩니다. 고위험 작업에만 명확한 확인을 요구하면 사용자는 계속 주의를 기울입니다.

확인을 일반 문장이 아닌 구조화된 상태로 표현하는 것을 권장합니다:

{
  "action": "run_shell",
  "command": "rm -rf apps/web/.next",
  "risk": "destructive_generated_artifact",
  "requires_confirmation": true,
  "confirmation_prompt": "Delete generated Next.js cache at apps/web/.next?"
}

그러면 셸 실행기에서 이를 강제할 수 있습니다:

def run_shell(command, confirmed=False):
    risk = classify_command(command)

    if risk.requires_confirmation and not confirmed:
        return {
            "status": "needs_confirmation",
            "message": risk.prompt
        }

    return subprocess.run(command, shell=True, cwd=WORKSPACE_ROOT)

실제로 명령 분류가 완벽할 수는 없습니다. 그래도 괜찮습니다. 보수적인 기본값을 사용하세요. 분류기가 명령의 파괴성 여부를 확신하지 못하면 사용자에게 물어보세요.

주의해서 다뤄야 할 명령

다음 명령에는 명시적인 정책이 필요합니다:

rm -rf path
git reset --hard
git clean -fd
git push --force
npm install some-package
pip install -r requirements.txt
docker compose down -v
kubectl delete ...
terraform apply

어떤 명령은 적절한 상황에서는 무해합니다. 어떤 명령은 잘못된 상황에서는 치명적입니다. 에이전트는 그 차이가 맥락에 따라 달라진다는 점을 이해하고, 영향 범위가 불분명하면 사용자에게 물어봐야 합니다.

파일 접근은 컨텍스트 엔지니어링입니다

코딩 에이전트 설계에서 가장 과소평가되는 부분은 파일 접근입니다. 프롬프트에 “먼저 관련 파일을 살펴보세요”라고 명시할 수 있지만, 런타임은 그런 행동을 쉽게 수행할 수 있도록 해야 합니다.

최소한 모델에 다음 작업을 위한 도구를 제공하세요:

• 빠른 파일 이름 탐색
• 텍스트 검색
• 파일의 한정된 범위 읽기
• git diff 확인
• 패치의 원자적 적용

최소한의 도구 구성은 다음과 같을 수 있습니다:

[
  {
    "name": "search_files",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" },
        "glob": { "type": "string" }
      },
      "required": ["query"]
    }
  },
  {
    "name": "read_file",
    "input_schema": {
      "type": "object",
      "properties": {
        "path": { "type": "string" },
        "start_line": { "type": "integer" },
        "limit": { "type": "integer" }
      },
      "required": ["path"]
    }
  },
  {
    "name": "apply_patch",
    "input_schema": {
      "type": "object",
      "properties": {
        "patch": { "type": "string" }
      },
      "required": ["patch"]
    }
  }
]

읽기 범위를 제한하는 것은 중요합니다. 에이전트가 모노레포의 모든 파일을 읽으면 컨텍스트를 낭비하고 성능도 떨어지는 경우가 많습니다. 너무 적게 읽으면 추측에 의존합니다. 가장 적절한 방식은 컨텍스트를 반복적으로 확보하는 것입니다:

rg "createSession|verifySession|SessionStore" apps packages
sed -n '1,220p' apps/api/src/auth/session.ts
sed -n '1,180p' apps/api/src/routes/login.ts
git diff -- apps/api/src/auth/session.ts

Claude Code 사용자는 검색, 검토, 수정, 검증이라는 흐름에 익숙할 것입니다. 에이전트 개발자는 이 반복 과정을 기본 동작에 반영해야 합니다.

흔히 놓치는 점이 있습니다. 파일 도구는 줄바꿈 형식, 권한, 예상 인코딩을 보존해야 합니다. 저는 에이전트가 셸 스크립트를 “성공적으로” 다시 작성하면서 실행 권한 비트를 제거하거나, 파일 형식을 정규화해 불필요한 변경 사항이 가득한 diff를 만드는 것을 본 적이 있습니다. 편집 계층은 예측 가능하고 보수적으로 동작해야 합니다.

실패 유형: 에이전트가 잘못 동작할 때 실제로 일어나는 일

대부분의 코딩 에이전트는 눈에 띄게 실패하지 않습니다. 그럴듯한 방식으로 실패합니다.

제가 가장 자주 보는 실패 유형은 다음과 같습니다.

1. 에이전트가 증상만 해결합니다

API가 반환하는 값이 다음과 같아서 테스트가 실패합니다: 401. 에이전트는 테스트가 다음 값을 기대하도록 바꿉니다: 401. 빌드는 통과하지만 제품은 망가집니다.

완화 방법:

• 에이전트에게 인과관계를 설명하도록 요구하세요.
• 광범위하게 다시 작성하기 전에 문제에 초점을 맞춘 테스트를 요청하세요.
• 사용자가 동작 변경을 요청하지 않았다면 스냅샷 업데이트보다 소스 수정을 우선하세요.

2. 에이전트가 지나치게 많이 수정합니다

사용자는 작은 버그 수정을 요청합니다. 에이전트는 파일 다섯 개의 서식을 바꾸고, 변수 이름을 변경하고, 공개 API를 수정합니다.

완화 방법:

Make the minimal change that fixes the issue. Do not perform opportunistic
refactors unless they are necessary for correctness.

하지만 diff 검토도 반드시 거치게 하세요. 마무리하기 전에 변경된 파일과 줄 수를 표시하세요:

git diff --stat
git diff -- apps/api/src/auth/session.ts

3. 에이전트가 오래된 컨텍스트를 신뢰합니다

오래 실행되는 세션에는 낡은 가정이 쌓입니다. 사용자가 외부에서 파일을 수정해 테스트가 이전과 다른 이유로 실패하는데도, 에이전트는 기존의 이해를 바탕으로 계속 작업합니다.

완화 방법:

• 파일이 변경되었을 가능성이 있다면 수정하기 전에 다시 읽으세요.
• 확인할 항목: git diff 패치를 적용하기 전에 실행하세요.
• 도구 출력을 대화 기억보다 최신 정보로 취급하세요.

4. 에이전트가 도구 실패를 감춥니다

셸 명령이 실패했는데도 에이전트는 성공한 것처럼 진행합니다.

완화 방법: 도구 결과는 구조화되어 있어야 하며 무시하기 어려워야 합니다.

{
  "tool": "run_shell",
  "command": "pnpm test auth",
  "exit_code": 1,
  "stdout": "...",
  "stderr": "Cannot find module '@repo/config'",
  "status": "failed"
}

그런 다음 에이전트에게 다음과 같이 지시하세요:

If a tool call fails, do not claim success. Diagnose the failure or clearly
report the blocker.

5. 에이전트가 컨텍스트에 비밀 정보를 기록합니다

에이전트가 다음 항목을 읽을 수 있다면: .env, 크래시 덤프 또는 프로덕션 설정, 요약이나 로그 또는 프롬프트에 비밀 정보를 실수로 포함할 수 있습니다.

완화 방법:

• 알려진 비밀 정보 파일은 기본적으로 차단하세요.
• 도구 출력에서 토큰으로 보이는 값을 가리세요.
• 비밀 정보가 포함된 경로에는 명시적인 사용자 승인을 요구하세요.

경로 정책 예시:

DENY_PATTERNS = [
    ".env",
    ".env.*",
    "**/secrets/**",
    "**/*.pem",
    "**/*.key",
]

def can_read(path):
    return not any(fnmatch(path, pattern) for pattern in DENY_PATTERNS)

모델에 비밀 정보를 유출하지 말라고 지시하는 것은 좋습니다. 모델이 불필요한 비밀 정보를 보지 못하게 하는 것은 더 좋습니다.

Claude API 에이전트 루프 설계

Claude API를 직접 사용해 개발한다면, 유용하면서도 가장 단순한 루프는 다음과 같습니다:

1. 시스템 및 개발자 지침을 전송합니다.
2. 사용자의 작업을 제공합니다.
3. Claude가 도구를 요청하게 합니다.
4. 런타임에서 도구를 실행합니다.
5. 도구 결과를 반환합니다.
6. 모델이 최종 답변을 생성할 때까지 반복합니다.

단순화한 요청 형식은 다음과 같습니다:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "system": "You are a coding agent. Make minimal, correct changes...",
  "messages": [
    {
      "role": "user",
      "content": "Fix the auth timeout bug and add a regression test."
    }
  ],
  "tools": [
    {
      "name": "read_file",
      "description": "Read a bounded section of a workspace file.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "start_line": { "type": "integer" },
          "limit": { "type": "integer" }
        },
        "required": ["path"]
      }
    }
  ]
}

도구 사용 응답의 개념적 형태는 다음과 같습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I’ll inspect the auth timeout path first."
    },
    {
      "type": "tool_use",
      "name": "read_file",
      "id": "toolu_123",
      "input": {
        "path": "apps/api/src/auth/session.ts",
        "start_line": 1,
        "limit": 220
      }
    }
  ]
}

그런 다음 런타임이 결과를 반환합니다:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_123",
      "content": "export function createSession(...) { ... }"
    }
  ]
}

정확한 SDK 문법은 클라이언트 버전에 따라 다르지만, 설계 원칙은 변하지 않습니다. Claude가 작업을 제안하고, 런타임이 이를 실행하거나 거부하며, 다음 모델 턴에서 그 결과를 받습니다.

이러한 분리가 시스템을 이해하기 쉽게 유지해 줍니다.

살펴볼 만한 Claude Code 명령과 설정

Claude Code를 직접 사용하지 않더라도 그 워크플로에서 유용한 제품 패턴을 얻을 수 있습니다.

일반적인 프로젝트 초기 설정:

claude
/init

이 과정은 프로젝트 지침을 생성하거나 업데이트하여 이후 세션이 저장소별 규칙을 이해할 수 있게 합니다.

실제 세션은 흔히 다음과 같은 모습입니다:

claude "Find why the billing webhook test is flaky. Do not edit files yet."
claude "Patch the smallest fix and run the focused test."
claude "Show me the diff and summarize remaining risks."

저는 이 방식이 조사, 변경, 검증을 분리한다는 점에서 마음에 듭니다. 에이전트 개발자는 이를 다음과 같은 모드로 구현할 수 있습니다:

{
  "mode": "investigate",
  "can_edit": false,
  "can_run_tests": true,
  "requires_confirmation_for": ["network", "delete", "install"]
}

그런 다음 모드를 명시적으로 전환하세요:

{
  "mode": "implement",
  "can_edit": true,
  "can_run_tests": true,
  "requires_confirmation_for": ["network", "delete", "install", "commit"]
}

중요한 것은 특정 명령 자체가 아니라 상호작용의 약속입니다. 사용자는 에이전트가 언제 읽기만 하는지, 언제 파일을 변경하는지, 언제 부수 효과가 있는 작업을 하려는지 알 수 있어야 합니다.

프롬프트 덤프가 쉽게 깨지는 이유

시스템 프롬프트와 모델 설정을 모은 GitHub 저장소가 인기를 얻은 것은 엔지니어들이 실제 도구에 어떤 지침이 주어지는지 자연스럽게 궁금해하기 때문입니다. 저도 그 매력을 이해합니다. 프롬프트를 읽으면 제품 설계의 지향점을 알 수 있습니다. 개발자가 어떤 위험을 우려하는지, 어떤 워크플로를 최적화하는지, 모델에 어떤 방식으로 이야기하는지가 드러납니다.

하지만 복사한 프롬프트는 여러 이유로 쉽게 제 기능을 잃습니다:

• 비공식 자료일 수 있습니다. 어떻게 추출되었는지, 전체 내용이 담겨 있는지 알 수 없을 수 있습니다.
• 오래된 내용일 수 있습니다. 에이전트 프롬프트는 모델, 도구, 제품 정책이 바뀌면 함께 바뀝니다.
• 드러나지 않은 런타임 동작에 의존합니다. 도구를 언급하는 프롬프트는 해당 도구의 구현이 없으면 쓸모가 없습니다.
• 제품별 절충점을 담고 있습니다. Claude Code의 제약은 여러분의 에이전트가 사용하는 위협 모델과 맞지 않을 수 있습니다.
• 잘못된 확신을 심어줄 수 있습니다. 잘 다듬어진 프롬프트가 권한을 강제해 주지는 않습니다.

이러한 자료는 의존 대상으로 삼지 말고 설계에 영감을 얻는 데 활용하세요.

더 좋은 연습은 이 지침이 어떤 문제를 해결하는지 묻는 것입니다. 그런 다음 자신의 기술 스택에서 프롬프트와 런타임의 지원을 모두 활용해 그 문제를 해결하세요.

실무 핵심 요점

• 다음 주제에 관한 Claude Code system prompt 대화는 복사해 붙여 넣을 기회가 아니라 아키텍처 논의로 다루세요.
• 일관되게 유지할 동작은 시스템/개발자 지침에, 저장소 규칙은 프로젝트 파일에, 작업 목표는 사용자 메시지에 넣으세요.
• 고위험 작업의 경계는 문장으로만 명시하지 말고 도구와 런타임 권한으로 강제하세요.
• 파괴적 작업, 네트워크 작업, 의존성 변경 작업 또는 프로덕션에 영향을 주는 작업에는 구체적인 확인을 요구하세요.
• 에이전트에 범위가 제한된 파일 접근, 빠른 검색, 원자적 패치 적용, 구조화된 도구 실패 정보를 제공하세요.
• 실제로 효과적인 반복 과정에 맞춰 최적화하세요. 살펴보고, 계획하고, 최소한으로 수정하고, 검증하고, 위험을 요약하세요.
• 복사한 프롬프트가 오래되었거나 불완전할 수 있다고 가정하고, 명시적인 기능과 명확한 실패 처리를 기반으로 견고한 에이전트 동작을 구축하세요.