발표 자료 컨텍스트 2부 - 프롬프트와 CLAUDE.md

에이전트를 제대로 쓰는 법: 시스템 프롬프트와 CLAUDE.md

-규칙을 심는 시스템-
-질문을 던지는 사용자-
두 프롬프트의 역할만 구분해도 AI 활용이 달라집니다.

 

---

프롬프트에는 두 종류가 있습니다

AI와 대화할 때 프롬프트가 하나라고 생각하기 쉽습니다.

실제로는 두 가지입니다.

• 시스템 프롬프트 - 대화 시작 전에 미리 심어두는 규칙
• 사용자 프롬프트 - 우리가 직접 입력하는 질문과 요청

 

---

시스템 프롬프트: AI의 행동 규칙

시스템 프롬프트는 대화를 시작하기 전에 미리 설정해두는 지시문입니다.

• 사용자 눈에는 보이지 않습니다
• 대화 내내 고정된 규칙으로 유지됩니다
• 주로 서비스를 만드는 사람이 작성합니다

# 시스템 프롬프트 예시
- 항상 한국어로 답변하세요.
- 당신은 요리 전문가입니다.
- 정치적인 주제는 다루지 마세요.

 

아래는 제가 사용하는 학습 목적 시스템 프롬프트입니다.

#Role
당신은 실무 경력 20년차의 베테랑 풀스택 개발자입니다.

#Rules
- 응답은 마크다운 형태로 작성해주세요. 
- 질문에 대한 핵심만 요약하여 3줄 이내로 먼저 대답하고 이후 나머지 내용을 작성하세요.
- 개념 설명의 경우 예시를 함께 나열해주세요.
- 모르거나 애매한 부분이 있다면 필요한 정보를 물어보거나 모른다고 응답하세요.
- 모든 정보는 사실에 근거하여 말해주세요.
- 개발 지식의 경우 실무 적용 사례를 함께 제시해주세요. (good/bad Case)

#Tone And Manner
전문적이고 객관적인 어조를 유지하십시오. 감정적인 표현은 배제하고 사실에 기반하여 명확하게 답변하세요.

 

---

사용자 프롬프트: 실제 요청

우리가 AI에게 직접 입력하는 질문이나 요청입니다.

• 매번 자유롭게 바꿀 수 있습니다
• 시스템 규칙 안에서 처리됩니다

파스타 레시피 알려줘.

 

---

충돌하면 항상 규칙이 이깁니다

시스템 프롬프트와 사용자 프롬프트가 충돌하면 항상 시스템 프롬프트가 우선입니다.

시스템: "요리 전문가로만 답변하세요"
사용자: "주식 추천해줘"

→ AI: "저는 요리 전문가라 주식은 답변이 어렵습니다."

사용자 요청은 시스템 규칙의 울타리 안에서만 처리됩니다.

 

---

한눈에 비교

구분	시스템 프롬프트	사용자 프롬프트
누가 쓰나	서비스 제공자	사용자 본인
언제 쓰나	대화 시작 전	대화할 때마다
보이나	사용자에게 안 보임	직접 입력하므로 보임
바뀌나	거의 안 바뀜	매번 바뀜
역할	AI의 행동 규칙 설정	실제 요청 전달

 

---

시스템 프롬프트의 5가지 이점

1. 일관된 답변 품질

시스템 프롬프트 없이 "파이썬 코드 짜줘"를 입력하면 어떤 날은 설명 포함, 어떤 날은 코드만, 어떤 날은 다른 언어로 답변이 옵니다.

# 시스템 프롬프트
항상 코드 + 한 줄 설명. 언어는 파이썬만.

이 한 줄로 매번 동일한 형식과 품질이 보장됩니다.

2. 보안과 안전성

# 시스템 프롬프트
- 개인정보(전화번호, 주민번호 등)는 절대 노출하지 마세요.
- 욕설이나 폭력적 내용은 답변하지 마세요.

불특정 다수가 쓰는 서비스일수록 이런 안전장치가 필수입니다.

3. 비용 절감

AI는 입력한 글자 수만큼 비용이 발생합니다.

# 매번 반복 입력 (비용 낭비)
"당신은 요리 전문가입니다. 한국어로 답하세요.
레시피는 5단계로 정리하세요. 파스타 레시피 알려줘."

# 시스템 프롬프트에 저장 후 (효율적)
사용자: "파스타 레시피 알려줘"

4. 브랜드·서비스 정체성 유지

서비스 시스템 프롬프트 예시

서비스	시스템 프롬프트 예시
어린이 교육 앱	"쉬운 단어만 사용, 항상 긍정적인 어조 유지"
법률 상담	"단정적 법률 판단 금지, 전문가 상담 권유 포함"
글로벌 서비스	"사용자 언어를 감지해 동일한 언어로 답변"

5. 업무 자동화

# 이메일 요약 봇 시스템 프롬프트
입력된 이메일을 아래 형식으로 요약하세요.
- 발신자:
- 핵심 내용 (1~2줄):
- 필요한 조치:
- 긴급도: 높음 / 보통 / 낮음

사용자는 이메일 내용만 붙여넣으면 됩니다.

매번 포맷 지시를 반복할 필요가 없습니다.

 

시스템 프롬프트는 AI를 "아무나"에서 우리 서비스 전문가로 바꿔주는 설계도입니다.

 

---

CLAUDE.md: AI는 왜 자꾸 까먹을까요

시스템 프롬프트 개념을 이해했다면 이제 에이전트 환경에서의 문제를 살펴볼 필요가 있습니다.

AI는 기억하지 못합니다.

대화창이 열려 있을 때는 100만 줄의 코드를 또렷이 기억하지만,

창을 닫으면 다음 세션은 다시 0부터 시작합니다.

한 번 대화가 끝나면 방금 나눈 이야기를 모두 잊어버립니다.

 

이 문제를 해결하는 두 가지 장치가 있습니다.

• CLAUDE.md - 내가 직접 적어두는 지침서
• 자동 메모리 - AI가 스스로 적는 노트

 

---

CLAUDE.md

한 번 적어두면 모든 대화 시작 때 자동으로 불러오는 메모입니다.

Claude Code 기준으로 프로젝트 폴더에 CLAUDE.md 파일을 두면,

에이전트가 작업을 시작할 때마다 이 파일을 읽고 시작합니다.

매번 같은 설명을 복붙하는 수고가 사라집니다.

 

시스템 프롬프트와의 차이를 정리하면 아래와 같습니다.

구분	CLAUDE.md	시스템 프롬프트
누가 쓰나	사용자	사용자 혹은 프로그램 내장
언제 쓰나	대화 시작 전	대화 시작 전
어디에	작업 폴더 내부	에이전트 환경에서 별도 설정
쓰는 내용	코드 구조, 작업 규칙 등	역할, 정책, 제약 등

 

---

어디에 두면 되나요

위에서 아래로, 넓은 범위에서 좁은 범위 순으로 불러옵니다.

위치	파일명	적용 범위
홈 디렉토리	~/.claude/CLAUDE.md	모든 프로젝트에 적용
프로젝트 루트	프로젝트/CLAUDE.md	팀이 함께 쓰는 규칙
내 PC 전용	CLAUDE.local.md	나만 보는 설정 (공유 안 됨)
폴더별	src/api/CLAUDE.md	해당 폴더에서만 로드

높은 계층의 파일이 우선순위를 가집니다.

 

---

이렇게 적으면 됩니다

# 우리 팀 규칙
- 함수는 30줄 이하로 작성
- 새 파일 만들기 전 확인받기
- 빌드: npm run build

# 자세한 코드 스타일은
@rules/style.md 참고

팀 규칙, 빌드 명령어, 다른 규칙 파일 불러오기까지 한 곳에 정리할 수 있습니다.

 

---

언제 적어두면 좋을까요

1. 같은 실수를 또 할 때 - AI가 반복해서 틀리는 패턴 발견 시
2. 꼭 알아야 할 걸 발견했을 때 - 프로젝트 특수 규칙, 제약 조건
3. 매번 같은 설명을 반복할 때 - 반복 입력이 3번 이상이면 파일로
4. 새 팀원에게 필요한 맥락 - 온보딩 문서처럼 활용

 

---

잘 쓰는 법 3가지

1. 짧게 쓰기

지침이 많아지면 오히려 무시당합니다.

200줄 이하로 유지하고 꼭 필요한 것만 남깁니다.

2. 구체적으로 쓰기

# 모호하게 (❌)
깔끔한 코드를 작성해주세요
테스트를 잘 작성해주세요

# 구체적으로 (✓)
함수는 30줄 이하로 작성
테스트는 모듈 단위로 작성
새 파일 만들기 전 확인받기

3. 처음부터 완벽하게 쓰지 않기

비대해졌다면 지우고 처음부터 시작합니다.

에이전트가 규칙을 벗어날 때마다 하나씩 추가하는 방식이 가장 효율적입니다.

 

---

커지면 rules/로 나눕니다

지침이 길어지면 주제별 파일로 쪼개서 .claude/rules/ 폴더에 둡니다.

.claude/
├─ CLAUDE.md        # 주 지침
└─ rules/
   ├─ code-style.md
   ├─ testing.md
   └─ security.md

rules 파일에 paths를 지정하면 해당 파일을 작업할 때만 자동으로 로드됩니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙
- 입력값을 항상 검증
- 표준 오류 형식 사용
- OpenAPI 주석 포함

src/api/users.ts를 수정할 때만 이 규칙이 켜집니다.

토큰도 아끼고, 맥락도 깔끔하게 유지됩니다.

 

---

정리

개념	한 줄 요약
시스템 프롬프트	AI를 "아무나"에서 전문가로 바꾸는 설계도
CLAUDE.md	에이전트가 매번 읽는 짧고 구체적인 메모

 

시스템 프롬프트로 AI의 역할과 제약을 잡고, CLAUDE.md로 프로젝트 맥락을 주입합니다.

이 두 가지만 제대로 써도 에이전트 활용 효율이 눈에 띄게 달라집니다.

CLAUDE.md는 AI에게 매번 건네는 짧고 구체적인 메모입니다. 짧게, 구체적으로, 완벽하지 않아도 OK.