챗봇처럼 묻지 마세요: Claude를 시니어 엔지니어처럼 활용하는 방법

How to Use Claude Like a Senior Engineer, Not a Chatbot

한번 상상해 보세요. 여러분이 Claude에게 로그인 기능의 요구사항과 완료 조건을 전달합니다. Claude는 프로젝트의 CLAUDE.md에서 아키텍처 원칙과 검증 명령을 확인하고, 코드를 조사한 뒤 계획·구현·테스트를 차례로 수행합니다. 파일이 바뀔 때마다 Claude Code Hook이 포매터나 린터를 실행하고, 마지막에는 테스트 결과와 남은 위험을 함께 보고합니다 [1, 4].

마법처럼 보이시나요? 사실 이건 프롬프트를 기가 막히게 써서가 아니라, AI를 ‘답변하는 챗봇’이 아니라 ‘상태를 유지하는 에이전트’로 설계했기 때문에 가능한 일입니다.

혹시 Claude와 대화하다 보면 이런 느낌을 받은 적 없으신가요? “처음에는 똑똑하더니, 대화가 길어질수록 예전에 말한 규칙을 까먹네?”, “분명히 이렇게 짜달라고 했는데 왜 자꾸 엉뚱한 코드를 내놓지?”

이런 현상을 모두 모델의 지능 탓으로 돌리면 해결책을 놓칩니다. 요구사항이 모호하거나, 관련 없는 탐색 결과가 대화에 누적되거나, 실행 가능한 검증 수단이 없을 때도 결과는 쉽게 흔들립니다. 이 글에서는 Claude를 시니어 엔지니어처럼 활용하기 위한 ‘컨텍스트 관리와 검증 시스템’을 단계별로 구성해 봅니다.

대화가 길어질수록 왜 작업 품질이 흔들릴까?

Claude Code의 대화에는 메시지뿐 아니라 읽은 파일과 도구 실행 결과도 쌓입니다. 공식 모범 사례는 관련 없는 작업 사이에 /clear를 사용하고, 많은 파일을 읽는 조사는 별도 서브에이전트에 맡기라고 권합니다. 긴 세션에서 불필요한 정보가 누적되면 작업에 필요한 신호가 묻힐 수 있기 때문입니다 [1].

따라서 목표는 무조건 긴 대화를 유지하는 것이 아니라, 현재 결정에 필요한 정보만 남기는 것입니다. 같은 기능을 계속 다듬는 동안에는 기존 맥락이 유용하지만, 인증 버그를 끝낸 뒤 배포 스크립트로 넘어가는 것처럼 과제가 바뀌면 새 세션이 더 유리할 수 있습니다. 공식 문서도 서로 무관한 작업 사이의 /clear와 범위가 좁은 조사를 권장합니다 [1].

챗봇이 아니라 ‘상태를 가진 에이전트’로 바라보기

그동안 Claude를 어떻게 쓰셨나요? 아마 “이 코드 좀 리뷰해줘”, “이 기능 구현하는 코드 짜줘” 같은 방식으로 요청하고, 결과물을 받아 다시 수정하는 ‘질의응답’ 루프에 익숙하실 겁니다. 하지만 이건 Claude라는 강력한 도구를 10%만 쓰는 방식이에요.

Claude Code는 단순한 챗봇이 아닙니다. 파일을 읽고, 셸 명령을 실행하고, 변경 사항을 직접 적용하는 ‘에이전틱 코딩 환경(Agentic coding environment)’이죠 [1, 13].

이제 작업의 패러다임을 완전히 바꿔야 합니다. ‘코드 작성 $\rightarrow$ 리뷰 요청’이 아니라, ‘요구사항 기술 $\rightarrow$ AI의 계획 및 구현’으로 가야 해요.

“Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it.”

(직접 코드를 짜고 Claude에게 리뷰를 요청하는 대신, 원하는 것을 설명하면 Claude가 어떻게 구축할지 스스로 찾아냅니다.) [1]

여기서 중요한 건 AI에게 단순한 ‘답변’을 기대하는 게 아니라, 스스로 루프를 돌며 작업을 완결 지을 수 있는 ‘권한’과 ‘도구’를 주는 것입니다. “알아서 해줘”가 아니라, “이 도구들을 사용해서 이 기준을 만족할 때까지 루프를 돌아줘”라고 정의하는 것이 에이전틱 워크플로우의 핵심입니다.

정적 컨텍스트의 힘: CLAUDE.md로 지식 주입하기

그렇다면 매번 세션을 시작할 때마다 “우리 프로젝트는 이런 스택을 쓰고, 코딩 스타일은 이렇고, 아키텍처는 이래”라고 구구절절 설명해야 할까요? 당연히 아니죠. 새로 합류한 숙련된 개발자가 팀의 규칙을 빠르게 익힐 수 있도록 돕는 가이드 문서와 같은 역할이 있다면 어떨까요?

그 역할을 하는 것이 바로 CLAUDE.md 파일입니다 [2, 20]. 이 파일은 프로젝트의 코딩 표준, 워크플로우, 아키텍처 원칙을 세션에 제공하는 지속적 컨텍스트입니다. 다만 CLAUDE.md는 강제 정책 엔진이 아닙니다. 공식 문서도 결정론적으로 반드시 지켜야 할 규칙은 CLAUDE.md 문장만 믿지 말고 Hook이나 테스트로 집행하라고 설명합니다 [2, 4].

특히 반복되는 코드 리뷰 지적 사항이나, 프로젝트 특유의 까다로운 패턴을 여기에 기록해 두세요. 그러면 Claude는 이를 ‘학습된 상태’로 인식하고 일관성 있게 동작합니다 [2]. 여기에 ‘오토 메모리(Auto memory)’ 기능까지 결합하면, 사용자의 수정 사항과 선호도를 Claude가 스스로 기록하고 누적하는 시스템까지 구축할 수 있죠 [2].

실제로 제가 추천하는 CLAUDE.md 구성 예시입니다. 단순히 “잘 짜줘”가 아니라, 구체적인 ‘제약 조건’을 명시하는 게 포인트예요.

# Project Guide: User-Auth Service

## Tech Stack
- Language: TypeScript, Node.js
- Framework: NestJS, PostgreSQL (Prisma)
- Test: Jest

## Coding Standards
- Use Functional Programming patterns where possible.
- All business logic must reside in the `Service` layer, not `Controller`.
- Variable naming: use `camelCase` for variables and `PascalCase` for classes.
- Error Handling: Always use custom `AppError` class for business exceptions.

## Workflow & Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Deployment: Follow the guidelines in `/docs/deploy.md`

## Non-Negotiables (Critical)
- No `any` type allowed. Use `unknown` or define a proper interface.
- Every new API endpoint must have a corresponding `.spec.ts` test file.
- Database migrations must be reviewed by a human before applying to production.

이런 식으로 가이드라인을 구체화하면 Claude가 추측해야 할 범위가 줄어듭니다. 문서는 간결하고 구체적으로 유지하고, 상세 규격은 별도 문서에 둔 뒤 필요한 경로만 연결하는 편이 좋습니다 [2].

탐색 결과를 메인 컨텍스트에 쌓지 않기

대규모 저장소 조사에는 많은 파일 내용과 로그가 따라옵니다. 이 중 대부분은 최종 구현 때 다시 필요하지 않습니다. Claude Code의 서브에이전트는 메인 대화와 분리된 새 컨텍스트에서 작업하고 요약 결과를 반환하므로, 조사 과정의 소음을 메인 세션에 남기지 않는 데 적합합니다 [3].

예를 들어 한 세션에 모든 일을 몰아넣는 대신 다음처럼 역할을 나눌 수 있습니다.

1. 탐색: “인증 토큰 갱신 경로를 조사하되 파일은 수정하지 말고, 관련 파일·심볼·테스트·위험만 보고하라.” 2. 계획: 메인 세션에서 조사 근거를 검토하고 변경 범위와 완료 조건을 확정한다. 3. 구현: 확정한 한 가지 변경만 적용하고 지정된 테스트를 실행한다. 4. 검증: 별도 서브에이전트가 회귀 위험과 빠진 경계 조건을 검토한다.

서브에이전트가 항상 정답은 아닙니다. 계획부터 구현·테스트까지 같은 맥락을 반복해서 참조해야 하는 작은 변경은 메인 대화가 더 효율적입니다. 반면 결과가 장황하고 독립적인 조사, 도구 권한을 제한해야 하는 검토, 구현 후 별도 시각의 검증에는 격리가 효과적입니다 [3].

AI의 ‘확률’을 시스템의 ‘확신’으로 바꾸는 법

하지만 여기서 한 가지 짚고 갈게요. AI가 “다 된 것 같습니다!”라고 말하는 걸 100% 믿으시나요?

LLM은 기본적으로 ‘확률적’으로 다음 토큰을 예측하는 모델입니다. 프로덕션 코드에서 “아마 맞을 거예요”라는 확률은 매우 위험하죠. 그래서 우리는 AI의 ‘판단’이 아니라, 시스템적인 ‘결과’로 제어하는 ‘결정론적 제어’가 필요합니다.

이때 사용하는 것이 바로 ‘훅(Hooks)’입니다 [4]. Hook은 도구 실행 전후나 세션 종료 같은 수명 주기 이벤트에 연결하는 자동 처리 장치입니다. 예컨대 PostToolUse에서 Edit|Write만 골라 포매터를 실행할 수 있습니다. 테스트 전체 실행은 비용이 크므로 매 파일 수정 때가 아니라 작업 완료 조건에 명시하거나 별도 검증 단계로 두는 편이 실용적입니다.

“Give Claude a check it can run: tests, a build, a screenshot to compare. It’s the difference between a session you watch and one you walk away from.”

(Claude가 실행할 수 있는 검증 수단—테스트, 빌드, 비교 스크린샷—을 제공하세요. 그것이 여러분이 계속 지켜봐야 하는 세션과, 믿고 자리를 비울 수 있는 세션의 차이를 만듭니다.) [1]

보안과 자율성의 균형에는 샌드박싱도 도움이 됩니다. 파일 시스템과 네트워크 경계를 제한하면 명령 실행의 영향 범위를 줄이고, 경계 안에서 반복되는 작업의 권한 요청을 줄일 수 있습니다 [5, 9]. 다만 샌드박스는 입력 검증, 비밀정보 관리, 코드 리뷰를 대신하지 않습니다.

다만, AI가 셸 명령을 실행하고 파일을 직접 수정하는 에이전틱 도구를 사용할 때는 각별한 주의가 필요합니다. 샌드박싱 환경을 구축하여 시스템 영향을 최소화하고, AI가 제안한 변경 사항이나 실행하려는 명령어를 반드시 사람이 최종 검토하는 단계를 거쳐야 보안 사고를 예방할 수 있습니다 [5, 9].

아래는 Claude Code 공식 스키마에 맞춘 실행 가능한 예시입니다. 프로젝트 루트의 .claude/settings.json에 넣으면 Edit 또는 Write 도구가 성공한 직후, Hook 입력 JSON에서 수정 파일 경로를 꺼내 Prettier를 실행합니다. 이 Bash 예시는 jq와 프로젝트의 Prettier 설치가 필요합니다 [4].

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

설정 뒤에는 /hooks에서 등록 여부를 확인하고, 임시 파일을 한 번 수정해 실제 실행 결과를 검증합니다. Hook이 있다고 해서 작업 완료가 자동 보장되지는 않습니다. 프롬프트의 완료 조건에 npm test, npm run build, 변경 파일 목록, 실패한 검증과 그 이유를 명시해야 합니다.

바로 적용할 수 있는 완료 조건

시니어 엔지니어형 요청은 구현 방법을 장황하게 지시하기보다 경계와 증거를 명확히 합니다. 다음 템플릿은 작은 기능 작업에 바로 사용할 수 있습니다.

목표: 로그인 실패 횟수 제한을 추가한다.
범위: auth service와 해당 테스트만 수정한다. DB 스키마는 변경하지 않는다.
먼저: 관련 흐름과 기존 테스트를 조사하고 5단계 이내 계획을 제시한다.
검증: npm test -- auth, npm run lint, npm run build를 실행한다.
완료 보고: 변경 파일, 핵심 설계 선택, 검증 결과, 남은 위험을 구분해 적는다.
금지: 검증하지 않은 성공을 주장하거나 관련 없는 리팩터링을 하지 않는다.

이 구조의 핵심은 “잘 만들어 달라”가 아니라 성공을 판정할 수 있는 관찰 가능한 증거를 제공하는 것입니다. 테스트가 없다면 재현 명령, 예상 출력, 전후 스크린샷처럼 작업에 맞는 검증 장치를 먼저 만드세요 [1].

결국 Claude를 시니어 엔지니어처럼 활용한다는 것은 모델의 자신감에 의존하는 것이 아니라, 작업 범위와 완료 조건, 깨끗한 컨텍스트, 독립된 조사, 실행 가능한 검증을 설계하는 일입니다. CLAUDE.md는 공통 지식을 제공하고, 서브에이전트는 조사 소음을 격리하며, Hook과 테스트는 말이 아닌 결과로 규칙을 확인합니다. 이 구조가 갖춰져야 Claude는 단순한 답변기를 넘어 검증 가능한 엔지니어링 작업자가 됩니다.

참고 자료

• [1] Claude Code Best Practices
• [2] How Claude remembers your project
• [3] Create custom subagents
• [4] Automate workflows with hooks
• [5] Claude Code security
• [9] Claude Code sandboxing
• [13] 39 Claude Code Best Practices: A Guide for Engineering Teams
• [20] Claude Code Tutorial: Build a Senior Engineer System with CLAUDE.md