Anthropic이 알려주는 Claude를 활용한 프롬프트 작성 방법

Claude Code를 만든 Boris Cherny의 발표를 초보자도 이해하기 쉽게 정리했어요.

Claude Code를 잘 쓰는 사람은 프롬프트보다 ’작업 환경’을 설계해요

AI를 잘 사용하려면 멋진 프롬프트 문장을 외워야 한다고 생각하기 쉬워요. “전문가처럼 행동해 주세요”, “단계별로 생각해 주세요” 같은 표현을 더 정교하게 만들면 결과도 계속 좋아질 것 같아요.

하지만 Claude Code를 만든 Boris Cherny가 약 28분 동안 강조한 내용은 조금 달라요. Claude Code를 잘 쓰는 사람은 한 번의 프롬프트에 모든 것을 걸지 않아요. AI가 프로젝트를 이해할 수 있도록 맥락을 제공하고, 먼저 계획하게 하고, 결과를 스스로 확인할 수 있는 도구를 연결해요.

결국 중요한 것은 ’어떻게 질문할까?’보다 ’AI가 좋은 결과를 만들고 검증할 수 있는 작업 환경을 어떻게 구성할까?’에 가까워요.

이 글에서는 발표의 핵심을 6 가지 원칙으로 정리해 볼게요.

1. 처음부터 코드를 작성하게 하지 말고, 먼저 질문하게 해요

Claude Code를 처음 실행하면 무엇을 입력해야 할지 막막할 수 있어요. 기능을 만들어 달라고 해야 할지, 오류를 고쳐 달라고 해야 할지, 파일을 수정해 달라고 해야 할지 선택지가 너무 많기 때문이에요.

Boris가 가장 먼저 권하는 사용법은 의외로 단순해요.

코드를 수정하기 전에 코드베이스에 관해 질문해 보세요.

코드베이스란 하나의 앱이나 서비스를 구성하는 코드 전체를 뜻해요. 쇼핑몰을 예로 들면 회원가입, 상품 목록, 장바구니, 결제, 관리자 화면을 만드는 모든 파일이 하나의 코드베이스에 들어 있어요.

Claude Code에는 다음과 같이 물어볼 수 있어요.

이 프로젝트는 어떤 구조로 만들어졌나요?

처음 읽어야 할 파일 세 개를 골라 주세요.

이 함수는 어디에서 사용되나요?

사용자가 결제 버튼을 누르면 어떤 코드가 실행되나요?

이 기능과 연결된 테스트는 어디에 있나요?

이 함수의 인자가 이렇게 많아진 이유를 Git 기록에서 찾아 주세요.

이런 질문을 하면 Claude Code가 프로젝트의 파일을 탐색하고 서로의 관계를 따라가며 설명해요. 단순히 같은 단어를 검색하는 것보다, “이 코드가 왜 존재하고 실제로 어디에서 사용되는지”를 이해하는 데 도움이 돼요.

발표에 따르면 Anthropic은 신입 기술 인력의 온보딩에도 이 방식을 사용해요. 과거에는 코드베이스를 파악하는 데 2~3주가 걸렸지만, Claude Code를 이용한 질문·답변 방식으로 약 2~3일까지 줄었다고 해요.

초보자를 위한 설명: Git 기록은 왜 살펴보나요?

Git은 코드의 변경 이력을 저장하는 도구예요. 누가, 언제, 무엇을 바꿨는지 기록해요.

현재 코드만 보면 이상해 보이는 부분도 과거 기록을 살펴보면 이유를 알 수 있어요. 예를 들어 인자가 열다섯 개인 복잡한 함수가 처음부터 그렇게 만들어진 것이 아니라, 새로운 국가나 결제 방식을 지원하면서 하나씩 늘어났을 수 있어요.

Claude Code는 현재 코드만 설명하는 데서 그치지 않고 이런 변경 기록과 연결된 이슈까지 확인해 전체 맥락을 요약할 수 있어요.

이 원칙의 핵심

Claude Code를 처음 사용하는 사람에게 곧바로 코드를 맡기면 AI의 결과를 평가하기도 어려워요. 먼저 질문을 주고받으면 사용자는 Claude Code가 잘하는 일과 추가 설명이 필요한 일을 자연스럽게 파악할 수 있어요.

코딩 경험이 적은 사람에게도 좋은 시작점이에요. 코드를 직접 만들지 않더라도 기존 프로젝트를 읽고 설명받는 것만으로 충분한 가치를 얻을 수 있어요.

2. 큰 작업은 바로 실행하지 말고, 계획부터 확인해요

AI에게 다음과 같이 요청하고 싶을 때가 있어요.

회원가입부터 결제까지 전부 구현해 주세요.

Claude Code가 한 번에 완성할 수도 있어요. 하지만 결과가 사용자가 원한 방향과 완전히 다를 위험도 커요. 요청이 클수록 AI가 스스로 채워 넣어야 하는 빈칸이 많아지기 때문이에요.

Boris가 권하는 방법은 구현 전에 먼저 생각하게 하는 거예요.

아이디어를 몇 가지 제안하고 계획을 세워 주세요. 계획을 먼저 보여 주고, 제가 승인하기 전에는 코드를 수정하지 말아 주세요.

이 한 문장만으로도 사용자는 다음 내용을 미리 확인할 수 있어요.

AI가 문제를 제대로 이해했는지

어떤 파일을 수정하려는지

기존 기능에 영향을 줄 위험은 없는지

작업을 더 작은 단계로 나눌 수 있는지

완성된 결과를 어떻게 확인할 것인지

잘못된 계획은 몇 줄의 대화로 고칠 수 있어요. 하지만 잘못된 구현은 여러 파일을 되돌리고 다시 작성해야 할 수 있어요.

초보자를 위한 비유

집을 짓기 전에 설계도를 확인하는 것과 같아요. 방의 위치가 잘못된 상태에서 공사를 시작하면 수정 비용이 커져요. 설계도 단계에서는 선 몇 개만 바꾸면 돼요.

Claude Code의 계획도 같은 역할을 해요. 코드를 작성하기 전에 AI가 이해한 목표와 작업 순서를 확인하는 과정이에요.

좋은 요청에는 네 가지가 들어가요

계획을 요청할 때 다음 정보를 함께 주면 좋아요.

목적: 왜 이 작업이 필요한지 알려 줘요.

범위: 어디까지 바꾸고 어디는 건드리지 말아야 하는지 알려 줘요.

기준: 어떤 결과가 나오면 성공인지 알려 줘요.

확인 방법: 테스트, 화면 비교, 사람의 승인 중 무엇으로 검증할지 알려 줘요.

프롬프트를 길게 만드는 것 자체가 목적은 아니에요. AI가 추측해야 하는 중요한 빈칸을 줄이는 것이 목적이에요.

3. 지시만 주지 말고, 결과를 확인할 수 있는 도구를 줘요

Claude Code는 파일을 검색하고, 코드를 읽고, 파일을 수정하고, 터미널 명령을 실행할 수 있어요. 사용자가 각 도구의 사용 순서를 일일이 지시하지 않아도 목표에 맞게 조합할 수 있어요.

여기서 결과의 품질을 크게 바꾸는 요소가 있어요.

Claude Code가 자신의 작업을 확인할 수 있어야 해요.

예를 들어 웹 화면의 목업 이미지를 주고 구현해 달라고 하면 첫 결과도 꽤 괜찮을 수 있어요. 하지만 Claude Code가 완성된 화면의 스크린샷을 찍어 목업과 비교하고, 차이를 수정하고, 다시 스크린샷을 찍게 하면 결과가 훨씬 좋아질 수 있어요.

코드에서도 같은 원리가 적용돼요.

유닛 테스트로 작은 기능이 정확한지 확인해요.

통합 테스트로 여러 기능이 함께 잘 작동하는지 확인해요.

브라우저 자동화 도구로 버튼과 입력창이 정상적으로 동작하는지 확인해요.

오류 로그를 읽고 실패 원인을 찾게 해요.

앱 시뮬레이터의 화면을 캡처해 디자인과 비교하게 해요.

이처럼 작업하고, 결과를 확인하고, 문제를 수정한 뒤 다시 확인하는 구조를 피드백 루프라고 해요.

초보자를 위한 설명: 테스트가 무엇인가요?

테스트는 코드가 기대한 대로 작동하는지 자동으로 확인하는 검사예요.

계산기 앱에서 ’2 + 3은 5가 되어야 한다’는 규칙을 검사하는 것이 작은 테스트의 예예요. AI가 계산 기능을 수정한 뒤 테스트를 실행하면, 변경 때문에 기존 기능이 망가지지 않았는지 확인할 수 있어요.

사람이 글을 쓴 뒤 맞춤법 검사를 하는 것과 비슷해요. 초안을 잘 쓰는 능력도 중요하지만, 오류를 발견하고 고치는 과정이 있어야 최종 품질이 높아져요.

코딩이 아닌 작업에도 적용할 수 있어요

피드백 루프는 개발자만을 위한 개념이 아니에요.

글을 쓸 때는 문체 가이드와 체크리스트로 검토하게 해요.

데이터를 분석할 때는 계산 결과를 원본 데이터와 대조하게 해요.

발표 자료를 만들 때는 글자 수, 색상, 슬라이드 구조를 검사하게 해요.

번역할 때는 숫자, 고유명사, 누락된 문단을 원문과 비교하게 해요.

AI에게 “잘해 주세요”라고 말하는 것보다, 무엇을 기준으로 잘했는지 확인할 수 있게 만드는 편이 더 효과적이에요.

4. 반복해서 설명하는 내용은 CLAUDE.md에 적어 둬요

AI와 작업하다 보면 같은 설명을 반복하게 돼요.

이 프로젝트는 어떤 서비스를 만드는지

자주 사용하는 명령이 무엇인지

팀이 따르는 코드 스타일은 무엇인지

어떤 파일이 중요한지

절대로 변경하면 안 되는 영역은 어디인지

작업을 끝낸 뒤 무엇을 보고해야 하는지

Claude Code에서는 이런 정보를 CLAUDE.md라는 파일에 정리할 수 있어요. 프로젝트의 가장 바깥 폴더에 이 파일을 두면 Claude Code가 세션을 시작할 때 자동으로 참고해요.

쉽게 말하면 CLAUDE.md는 AI를 위한 프로젝트 안내서예요. 새 팀원이 들어왔을 때 보여 주는 온보딩 문서와 비슷해요.

예를 들어 다음과 같이 시작할 수 있어요.

이 프로젝트는 지역 커뮤니티의 모임을 관리하는 웹서비스예요.
화면 문구는 전문용어보다 쉬운 한국어를 사용해요.
코드를 수정하기 전에 관련 테스트를 먼저 찾아요.
큰 변경은 계획을 보여 주고 승인을 받은 뒤 진행해요.
작업을 마치면 변경한 파일과 실행한 테스트를 요약해요.

완벽한 문서를 한 번에 만들 필요는 없어요. Claude Code가 반복해서 실수하는 부분이나 팀원이 계속 설명하는 내용을 발견할 때마다 조금씩 추가하면 돼요.

길수록 좋은 문서는 아니에요

AI가 한 번에 참고할 수 있는 정보의 양에는 한계가 있어요. 이를 컨텍스트 창이라고 해요.

CLAUDE.md가 너무 길면 중요한 규칙이 수많은 설명 속에 묻힐 수 있어요. 매번 반드시 알아야 하는 내용을 짧고 구체적으로 적는 것이 좋아요.

프로젝트 안에 웹, 모바일 앱, 서버 코드가 함께 있다면 각 폴더에 별도의 CLAUDE.md를 둘 수도 있어요. Claude Code가 특정 폴더에서 작업할 때 그 영역의 규칙만 추가로 참고하게 할 수 있어요.

개인 규칙과 팀 규칙을 구분해요

팀 전체가 따라야 하는 규칙은 프로젝트와 함께 공유해요. 개인이 선호하는 문체나 도구는 개인 설정으로 관리해요. 회사 전체에 강제로 적용해야 하는 보안 규칙은 조직 정책으로 관리할 수 있어요.

이렇게 범위를 구분하면 개인 취향이 팀 규칙처럼 강제되거나, 중요한 보안 규칙이 개인의 선택으로 해제되는 문제를 줄일 수 있어요.

5. AI 전용 도구를 새로 만들기 전에, 팀이 이미 쓰는 도구를 연결해요

Claude Code는 터미널 명령과 MCP를 통해 외부 도구를 사용할 수 있어요.

CLI는 버튼 대신 명령어로 사용하는 프로그램이에요. 팀이 이미 배포, 데이터 조회, 테스트에 사용하는 CLI가 있다면 Claude Code에도 그 사용법을 알려 줄 수 있어요. 사용법을 모를 때는 도움말 명령을 먼저 실행하게 할 수도 있어요.

MCP는 Model Context Protocol의 약자예요. AI가 외부 도구와 데이터에 일정한 방식으로 연결되도록 돕는 규격이에요.

스마트폰의 공통 충전 규격을 떠올리면 이해하기 쉬워요. 기기마다 연결 방식이 모두 다르면 케이블을 매번 새로 만들어야 해요. 공통 규격이 있으면 같은 방식으로 여러 기기를 연결할 수 있어요. MCP는 AI와 외부 도구 사이에서 비슷한 역할을 해요.

MCP를 통해 다음과 같은 도구에 연결할 수 있어요.

회사의 데이터베이스

문서 검색 시스템

브라우저 자동화 도구

이슈 관리 도구

사내 API

중요한 점은 연결 자체가 아니라 팀이 검증해서 이미 사용하고 있는 도구를 AI도 활용하게 하는 것이에요.

예를 들어 Anthropic의 앱 저장소에는 Puppeteer MCP 서버 설정이 공유되어 있다고 해요. Puppeteer는 프로그램이 웹 브라우저를 자동으로 조작하고 스크린샷을 찍게 하는 도구예요. 팀원과 Claude Code가 같은 설정을 사용하므로 각자 도구를 처음부터 설치하고 설명할 필요가 줄어들어요.

권한은 편리함과 안전을 함께 고려해요

Claude Code가 도구를 사용할 수 있다고 해서 모든 권한을 열어 주는 것이 좋은 것은 아니에요.

자주 사용하는 안전한 읽기 명령은 자동으로 승인할 수 있어요. 반면 파일 삭제, 외부 전송, 배포, 결제처럼 영향이 큰 행동은 사람이 확인하는 편이 안전해요.

발표 후 질의응답에서도 Boris는 Claude Code를 만들 때 Bash 명령의 안전성을 확보하는 일이 특히 어려웠다고 설명해요. 모든 명령을 사람이 승인하면 불편하고, 모든 명령을 자동 승인하면 위험하기 때문이에요.

그래서 읽기 전용 명령을 구분하고, 명령을 실행하기 전에 위험을 분석하고, 허용 목록과 차단 목록을 여러 수준에서 관리하는 방식을 사용해요.

초보자라면 다음 원칙만 기억해도 좋아요.

이해하지 못한 명령은 실행 전에 설명을 요청해요.

삭제와 배포는 자동 승인하지 않아요.

민감한 데이터가 외부로 전송되는지 확인해요.

중요한 프로젝트는 Git으로 변경 이력을 남겨요.

AI가 만든 결과도 테스트와 사람의 검토를 거쳐요.

6. 익숙해진 뒤에는 자동화와 병렬 작업으로 확장해요

앞의 다섯 가지가 기본기라면, SDK와 여러 세션 운영은 고급 활용에 가까워요.

Claude Code SDK를 사용하면 사람이 터미널에서 직접 요청하지 않아도 다른 프로그램이 Claude Code에 프롬프트를 보내고 결과를 받을 수 있어요.

결과를 JSON처럼 프로그램이 읽기 쉬운 형식으로 받을 수도 있어요. 이를 CI, 오류 대응, 로그 분석, 반복 업무 자동화에 연결할 수 있어요.

예를 들어 AI 커뮤니티 운영 도구가 매주 다음 작업을 자동으로 하게 만들 수 있어요.

일주일 동안 올라온 질문을 모아요.

비슷한 질문끼리 분류해요.

초보자가 어려워한 용어를 추출해요.

다음 주 학습 주제를 구조화된 데이터로 정리해요.

운영자가 검토할 초안을 만들어요.

파워 유저들은 여러 Claude Code 세션을 동시에 실행하기도 해요.

한 세션은 로그인 오류를 조사해요.

다른 세션은 모바일 화면을 수정해요.

또 다른 세션은 부족한 테스트를 작성해요.

서로 독립적인 작업이라면 병렬로 처리해 시간을 줄일 수 있어요. Git worktree를 사용하면 같은 프로젝트에서 여러 작업 공간을 분리할 수 있어요.

다만 여러 세션이 같은 파일을 동시에 수정하면 충돌할 수 있어요. 작업 범위를 분명하게 나누고, 각 결과를 합치기 전에 사람이 확인해야 해요.

초보자는 여기서 시작하지 않아도 괜찮아요

여러 세션과 SDK는 강력하지만 기본기가 없으면 복잡성만 커질 수 있어요.

먼저 한 세션에서 다음 흐름을 안정적으로 만드는 것이 좋아요.

프로젝트에 관해 질문해요.

계획을 확인해요.

작은 작업을 맡겨요.

테스트나 체크리스트로 결과를 검증해요.

반복되는 규칙을 CLAUDE.md에 기록해요.

이 흐름이 익숙해진 뒤 자동화와 병렬 작업으로 확장하면 돼요.

좋은 프롬프트보다 좋은 작업 구조가 오래가요

이 발표의 핵심은 “효과가 좋은 마법의 프롬프트를 외우세요”가 아니에요.

Claude Code가 좋은 결과를 만들려면 네 가지가 필요해요.

맥락: 이 프로젝트가 무엇이고 어떤 규칙을 따르는지 알려 줘요.

계획: 큰 작업은 실행 전에 접근 방식을 확인해요.

도구: 필요한 정보와 행동 수단을 연결해요.

검증: 테스트와 화면 비교로 결과를 확인하게 해요.

AI를 잘 활용하는 사람은 모든 일을 AI에게 넘기지 않아요. 사람은 목표, 제한 조건, 품질 기준을 정해요. AI는 탐색, 초안 작성, 반복 실행, 자동 검증을 맡아요. 중요한 결정과 최종 책임은 사람이 가져가요.

AI 커뮤니티의 참여자 수준이 제각각이라면 모두에게 같은 고급 기능을 가르칠 필요도 없어요.

처음 사용하는 사람은 기존 문서와 코드에 질문하는 것부터 시작해요.

조금 익숙한 사람은 계획을 받고 작은 수정을 맡겨요.

실무자는 CLAUDE.md와 테스트를 연결해 반복 가능한 작업 흐름을 만들어요.

고급 사용자는 MCP, SDK, 여러 세션으로 팀의 업무를 자동화해요.

좋은 AI 활용은 한 번의 놀라운 답변을 얻는 기술이 아니에요. AI가 반복해서 괜찮은 결과를 내도록 맥락과 검증 구조를 설계하는 기술에 더 가까워요.