클로드 코드를 잘 쓰려면 명령을 화려하게 만드는 것보다 작업의 끝을 분명하게 정해야 합니다. 무엇을 바꿀지, 어디까지 손댈지, 완료 여부를 어떻게 확인할지를 먼저 알려주면 결과가 크게 안정됩니다. 핵심은 한 번에 정답을 받는 프롬프트가 아니라 읽기 → 계획 → 실행 → 검증이 이어지는 작업 구조입니다.
Claude Code는 질문에 답하고 멈추는 일반 채팅창과 다릅니다. 프로젝트 파일을 읽고, 코드를 수정하고, 명령어를 실행하며, 테스트 결과를 보고 다시 고칠 수 있는 작업 환경입니다. 이 차이를 이해하면 “코드 하나 만들어 줘”보다 훨씬 정확한 요청을 만들 수 있습니다.
일반 챗봇은 복사해 붙여 넣은 코드만 봅니다. 클로드 코드는 사용자가 허용한 범위에서 프로젝트 구조, 기존 코드, 테스트 명령, 변경 이력까지 살펴볼 수 있습니다. 그래서 새 코드를 처음부터 쓰게 하기보다, 현재 프로젝트가 이미 쓰는 방식을 찾아서 이어 달라고 요청하는 편이 낫습니다.
예를 들어 “로그인 기능을 만들어 줘”라고만 쓰면 선택지가 너무 많습니다. 어느 폴더를 써야 하는지, 기존 인증 흐름이 있는지, 테스트 방식은 무엇인지 알 수 없기 때문입니다. 다음처럼 시작하면 방향이 달라집니다.
먼저 이 프로젝트의 인증 관련 파일과 테스트를 읽으십시오.
현재 로그인 흐름, 재사용할 함수, 바꾸면 안 되는 범위를 정리하십시오.
아직 코드는 수정하지 말고 조사 결과만 보고하십시오.
이 요청은 클로드 코드가 성급하게 새 구조를 만드는 일을 줄여줍니다. 공식 권장 흐름도 복잡한 작업에서는 탐색과 계획을 구현보다 앞에 둡니다.
읽기 단계가 끝나면 재사용할 기존 코드와 새로 만들 부분을 나눠 달라고 요청하십시오. 그래야 비슷한 함수나 설정 파일이 중복으로 생기는 일을 막을 수 있습니다.
클로드 코드 사용법에서 가장 실용적인 원칙은 네 단계를 섞지 않는 것입니다.
| 단계 | 요청할 내용 | 확인할 결과 |
|---|---|---|
| 탐색 | 관련 파일과 기존 패턴 읽기 | 현재 구조와 원인 |
| 계획 | 수정 파일과 순서 정리 | 범위와 위험 |
| 실행 | 승인한 계획대로 최소 변경 | 실제 변경 내용 |
| 검증 | 테스트, 빌드, 화면 확인 | 성공 또는 남은 실패 |
파일이 여러 개 바뀌거나 낯선 프로젝트라면 Plan Mode가 유용합니다. Plan Mode는 소스 파일을 고치기 전에 읽고 조사하는 용도입니다. 반대로 오탈자 수정이나 로그 한 줄 추가처럼 변경 범위가 분명하면 계획 단계를 길게 잡을 필요가 없습니다.
중요한 것은 단계의 개수가 아니라, 문제를 충분히 읽기도 전에 코드부터 쓰지 않게 만드는 것입니다. “분석만 하십시오”, “수정 전에 계획을 보고하십시오”, “승인한 범위만 구현하십시오”라는 문장이 좋은 브레이크가 됩니다.
긴 프롬프트가 좋은 프롬프트는 아닙니다. 아래 네 가지가 들어가면 짧아도 강합니다.
아래 문장은 거의 모든 수정 작업에 적용할 수 있습니다.
목표: 로그인 세션 만료 뒤에도 사용자가 다시 로그인하지 않게 하십시오.
범위: src/auth와 관련 테스트만 수정하십시오.
제약: 새 패키지를 추가하지 말고 기존 토큰 갱신 방식을 재사용하십시오.
검증: 실패를 재현하는 테스트를 먼저 만든 뒤, 수정 후 해당 테스트와 전체 타입 검사를 통과시키십시오.
“예쁘게 바꿔 줘”, “오류를 고쳐 줘”처럼 완료 모습을 확인하기 어려운 요청은 왕복 대화를 늘립니다. 화면 작업이라면 기준 이미지를 주고, 버그라면 오류 메시지와 재현 순서를 주고, 데이터 작업이라면 기대 출력 예시를 함께 주는 편이 좋습니다.
요청을 보낸 뒤에는 클로드 코드가 이해한 목표와 완료 조건을 한 번 되짚게 하십시오. 작업 방향이 다르면 파일을 수정하기 전에 바로 고칠 수 있어 비용이 적습니다.
CLAUDE.md는 클로드 코드가 세션을 시작할 때 읽는 프로젝트 안내서입니다. 빌드 명령, 테스트 방법, 폴더 책임, 코딩 규칙, 반복해서 틀리는 주의사항처럼 매번 필요한 내용만 적습니다. 처음이라면 프로젝트 폴더에서 /init으로 초안을 만든 뒤 실제 프로젝트에 맞게 다듬을 수 있습니다.
길다고 좋은 문서는 아닙니다. 공식 문서는 한 파일을 가급적 200줄 아래로 간결하게 유지하라고 안내합니다. 소스만 읽어도 알 수 있는 설명, 자주 바뀌는 정보, 긴 튜토리얼은 덜어내야 중요한 규칙이 묻히지 않습니다. 특정 작업에서만 필요한 절차는 Skill로, 반드시 정해진 시점에 실행해야 하는 검사는 Hook으로 분리하는 편이 맞습니다.
검증 조건은 더 중요합니다. 테스트, 린트, 빌드, 스크린샷 비교, 예상 출력 중 하나라도 클로드 코드가 직접 확인할 수 있어야 합니다. “수정했습니다”라는 설명이 아니라, 실제 명령 결과가 통과했는지를 완료 기준으로 삼아야 합니다.
작업이 끝났다고 판단하기 전에 관련 테스트와 빌드를 실행하십시오.
화면을 바꿨다면 모바일 너비에서도 스크린샷을 확인하십시오.
실패가 남으면 완료라고 말하지 말고 원인과 다음 조치를 보고하십시오.
클로드 코드는 읽기, 파일 수정, 명령 실행을 어디까지 자동 허용할지 선택할 수 있습니다. 처음 사용하는 프로젝트나 민감한 저장소에서는 기본 모드 또는 Plan Mode가 안전합니다. 변경 내용을 계속 살펴보면서 속도를 높이고 싶다면 편집 자동 허용 모드를 검토할 수 있습니다.
권한 확인을 모두 건너뛰는 방식은 편해 보이지만 일반 작업의 기본값으로 두면 안 됩니다. 공식 문서도 권한 우회를 격리된 컨테이너나 가상 머신 같은 제한된 환경에만 권합니다. 삭제, 외부 전송, 배포, 결제, 운영 데이터 변경처럼 실패 비용이 큰 작업은 사람이 마지막 경계를 잡아야 합니다.
좋은 권한 설정은 모든 것을 허용하는 것이 아닙니다. 자주 실행하는 테스트와 린트처럼 안전한 명령만 허용하고, 외부 시스템이나 민감한 파일은 계속 확인받는 방식이 현실적입니다.
클로드 코드의 대화에는 메시지, 읽은 파일, 명령 출력, 프로젝트 지침이 함께 쌓입니다. 한 세션에서 로그인 버그를 고치다가 디자인을 바꾸고 다시 배포 문제로 돌아오면 관련 없는 정보가 섞입니다. 답이 흔들리기 시작하는 이유가 모델보다 세션의 혼잡일 때도 많습니다.
서로 다른 작업으로 넘어갈 때는 /clear로 새로 시작하는 편이 좋습니다. 이전 작업을 계속해야 한다면 claude --continue 또는 claude --resume을 쓸 수 있습니다. 방향이 틀어졌다면 /rewind나 Esc 두 번으로 이전 체크포인트를 선택할 수 있습니다.
같은 문제를 두 번 넘게 고쳐 설명했는데도 계속 빗나간다면, 긴 대화를 붙잡고 있기보다 지금까지 알게 된 조건을 짧은 새 요청으로 정리하는 편이 낫습니다. 하나의 세션에는 하나의 중심 작업. 이 원칙만 지켜도 체감 품질이 달라집니다.
작업 이름을 붙여 두는 것도 좋습니다. claude --resume에서 찾기 쉬운 이름을 정하면 여러 프로젝트를 오갈 때 이전 맥락을 다시 찾는 시간을 줄일 수 있습니다.
처음부터 모든 확장 기능을 설정할 필요는 없습니다. 같은 요청을 자주 복사한다면 Skill을 만들고, 편집 뒤 린트처럼 반드시 실행해야 하는 절차는 Hook으로 고정합니다. 외부 서비스나 데이터베이스에 접근해야 할 때는 MCP 연결을 검토합니다.
Subagent는 큰 코드베이스 조사나 별도 검토처럼 메인 대화를 어지럽히기 쉬운 작업에 어울립니다. 한 에이전트가 구현하고 다른 에이전트가 검토하게 하면 작성 과정의 선입견에서 조금 떨어진 결과를 받을 수 있습니다. 다만 작은 수정까지 여러 에이전트로 나누면 조정 비용이 더 커질 수 있습니다.
순서는 단순합니다. 먼저 한 세션에서 잘 되는 작업 방식을 찾고, 반복되는 부분만 규칙과 도구로 옮깁니다. 자동화는 좋은 작업 습관을 확대할 때 힘을 냅니다.
아래 예시는 정답 문구라기보다 요청의 뼈대입니다. 대괄호로 표시한 자료를 실제 파일, 오류 메시지, 화면 기준으로 바꾸면 됩니다. 한 번에 모든 예시를 붙이지 말고 현재 작업과 맞는 하나만 골라 범위와 검증 조건을 구체화하십시오.
프롬프트를 실행한 뒤에는 클로드 코드가 어떤 파일을 읽었는지, 무엇을 바꿨는지, 어떤 검사를 통과했는지를 확인하십시오. 설명이 그럴듯해도 검증 명령이 실행되지 않았다면 완료된 작업으로 보지 않는 편이 안전합니다.
각 예시의 첫 요청은 조사 범위를 좁히고, 두 번째 요청은 변경 범위를 고정하며, 마지막 문장은 검증 방법을 정합니다. 프로젝트 이름이나 기술 용어를 많이 적는 것보다 이 세 역할이 빠지지 않게 쓰는 편이 중요합니다. 결과가 기대와 다르면 막연히 “다시”라고 하지 말고, 달랐던 지점과 유지할 부분을 나눠 알려주십시오.
이 프로젝트의 핵심 진입점, 주요 폴더 책임, 실행 및 테스트 명령을 조사하십시오.
README만 요약하지 말고 실제 설정 파일과 대표 구현을 확인하십시오.
코드는 수정하지 마십시오.
마지막에 제가 먼저 알아야 할 위험 요소 세 가지만 보고하십시오.
아래 오류를 재현한 뒤 증상이 아니라 원인을 찾으십시오.
관련 파일과 최근 변경 이력을 먼저 확인하십시오.
실패하는 테스트를 만들고, 요청 범위 안에서 최소한으로 수정하십시오.
수정 후 테스트와 빌드를 실행하고 결과를 명령 단위로 보고하십시오.
[오류 메시지와 재현 순서]
첨부한 기준 화면과 현재 화면을 비교하십시오.
기존 컴포넌트와 디자인 토큰을 먼저 확인하고 같은 패턴을 따르십시오.
데스크톱과 모바일 화면을 구현한 뒤 각각 스크린샷으로 비교하십시오.
차이가 남으면 목록을 만들고 다시 수정한 뒤 최종 화면을 보고하십시오.
처음에는 명령어를 많이 외우기보다 자주 막히는 지점을 해결하는 질문부터 익히면 됩니다. 아래 세 질문은 비개발자가 시작할 때도 자주 마주치는 문제입니다. 기능 이름보다 작업 범위와 확인 방법을 먼저 말하는 습관이 더 오래 갑니다.
가능합니다. 다만 코드 문법보다 목표, 범위, 위험, 완료 조건을 설명하는 능력이 필요합니다. 운영 환경에 올리거나 고객 데이터를 다루는 일은 테스트 결과와 변경 내용을 사람이 이해한 뒤 진행해야 합니다.
프로젝트 실행 명령, 테스트 명령, 수정 금지 영역, 꼭 재사용할 기존 모듈, 커밋 전 검사부터 적으면 됩니다. 한 번 틀린 모든 일을 기록하기보다 같은 실수가 반복될 때 짧고 확인 가능한 규칙을 추가하는 편이 좋습니다.
작업 범위를 파일이나 폴더로 제한하고, 먼저 읽은 뒤 계획만 보고하게 하십시오. 이미 여러 번 빗나갔다면 /clear 후 목표·범위·제약·검증 네 칸으로 새 요청을 만드는 편이 빠릅니다.
클로드 코드를 잘 사용하는 방법은 결국 “AI에게 얼마나 많이 맡길까”보다 “무엇을 확인할 수 있게 만들까”에 가깝습니다. 작게 맡기고, 직접 검증하게 하고, 통과한 작업만 다음 단계로 넘기십시오.
※ 참고: Claude Code 공식 Best Practices, CLAUDE.md와 메모리 공식 문서, Permission Mode 공식 문서, Common Workflows 공식 문서