Claude Code를 잘 쓰려면 “AI가 똑똑하다”보다 AI가 어디까지 볼 수 있고, 무엇을 실행할 수 있고, 어디서 멈춰야 하는지를 알아야 합니다.
Claude Code는 무엇을 보고 일하나요
Claude Code는 보통 아래 순서로 맥락을 봅니다.
| 맥락 | 쉬운 설명 |
|---|---|
| 현재 작업 폴더 | AI가 실제로 파일을 읽고 고칠 수 있는 범위 |
| README.md | 이 프로젝트가 무엇인지 알려주는 첫 설명서 |
| CLAUDE.md / AGENTS.md | 이 폴더에서 AI가 따라야 하는 작업 규칙 |
| docs/ | 기획서, 계획, 회의록, 작업 기록 |
| package.json | 어떤 명령으로 실행하고 검사하는지 |
| git 상태 | 어떤 파일이 이미 바뀌었는지 |
그래서 좋은 프로젝트는 “AI에게 말로 설명을 많이 한 프로젝트”가 아니라, 파일 안에 맥락이 잘 남아 있는 프로젝트입니다.
Claude Code가 쓰는 도구
도구 이름은 환경마다 조금씩 다르지만, 실제 역할은 비슷합니다.
| 역할 | 무엇을 하나요 |
|---|---|
| 파일 읽기 | 기존 구조와 규칙을 확인 |
| 파일 수정 | 실제 코드나 문서 변경 |
| 검색 | 필요한 함수, 문장, 파일 찾기 |
| 터미널 실행 | 테스트, 빌드, git 상태 확인 |
| 브라우저 확인 | 화면이 실제로 보이는지 확인 |
| 이미지/스크린샷 확인 | 화면 깨짐, 배치 문제 확인 |
중요한 것은 AI가 도구를 쓸 수 있다는 점이 아니라, 어떤 도구를 언제 써야 하는지 스스로 판단하게 만드는 것입니다.
권한과 승인
AI가 마음대로 다 하게 두면 빠르지만 위험합니다. 반대로 모든 것을 매번 물어보면 위임이 되지 않습니다.
그래서 작업을 맡길 때는 권한을 나눠야 합니다.
| 구분 | 예시 | AI가 해도 되나요 |
|---|---|---|
| 읽기 | 파일 읽기, 검색, 구조 파악 | 보통 가능 |
| 안전한 수정 | 새 문서 추가, 작은 문구 수정 | 가능 |
| 위험한 수정 | 대량 삭제, 설정 변경, 인증 정보 변경 | 먼저 물어봐야 함 |
| 외부 행동 | push, 배포, 메시지 전송, 결제 | 반드시 물어봐야 함 |
요청문:
이 작업을 하기 전에 권한을 나눠줘.
네가 바로 해도 되는 것, 내 확인이 필요한 것,
절대 하면 안 되는 것을 먼저 정리해줘.하네스는 무엇인가요
하네스(harness)는 AI가 일을 할 때 쓰는 실행틀입니다. 어렵게 생각하지 않아도 됩니다.
예를 들어 이런 것이 하네스입니다.
- 어떤 폴더를 작업 공간으로 볼지
- 어떤 명령어를 실행할 수 있는지
- 파일을 어디까지 수정할 수 있는지
- 브라우저나 GitHub 같은 외부 도구를 쓸 수 있는지
- 승인 없이 할 수 있는 일이 어디까지인지
같은 모델이라도 하네스가 다르면 일하는 방식이 달라집니다. Claude 확장, Codex 앱, Hermes 같은 도구가 다르게 느껴지는 이유도 여기 있습니다.
세션 기억보다 파일 기억
채팅 세션 안에서만 기억한 내용은 사라지기 쉽습니다. 진짜 위임을 하려면 중요한 맥락을 파일에 남겨야 합니다.
| 남길 것 | 어디에 남기나 |
|---|---|
| 프로젝트 목표 | README.md 또는 docs/기획서.md |
| 지금 할 일 | docs/계획.md 또는 TASKS.md |
| 작업 규칙 | CLAUDE.md 또는 AGENTS.md |
| 결정 이유 | docs/worklog/ |
| 반복 절차 | 스킬 또는 명령 문서 |
좋은 작업 요청의 기본형
목표:
[무엇이 되면 끝인지]
배경:
[왜 하는지, 누가 쓰는지]
범위:
[고칠 파일/고치면 안 되는 파일]
완료조건:
[눈으로 확인할 수 있는 결과]
검증:
[어떤 명령이나 화면으로 확인할지]
진행 방식:
먼저 기존 구조를 읽고,
재사용할 수 있는 것을 찾은 뒤,
수정 계획을 짧게 말하고,
작업 후 검증 결과를 보고해줘.이 형식을 매번 길게 쓸 필요는 없습니다. 다만 큰 작업일수록 이 틀에 가까워질수록 결과가 좋아집니다.
AI가 자꾸 대충 만들 때
AI가 기존 CSS를 무시하거나 새 구조를 막 만들면 보통 세 가지가 부족한 상태입니다.
- 기존 구조를 먼저 읽으라는 조건
- 재사용할 컴포넌트/스타일 후보를 찾으라는 조건
- 완료 후 화면 검증을 하라는 조건
요청문:
새로 만들기 전에 기존 컴포넌트와 스타일을 먼저 찾아줘.
재사용할 수 있는 것이 있으면 그것을 우선 써줘.
새 CSS나 새 구조를 만들 필요가 있으면 이유를 먼저 설명해줘.
작업 후에는 화면이 깨지지 않았는지 확인해줘.