🗒️ 게시판

05. AI와 문서로 일한다 : 컨텍스트 엔지니어링

교시
5교시
선택
완료
시간
14:00~14:50
회차
1회차
⏰
5교시 · 14:00~14:50 쉬는 시간 14:50~15:00
🧭
이전 장에서 Claude Code를 처음 사용해봤다면, 이번엔 AI에게 어떻게 일을 시킬지, 그 사고방식을 정리합니다. 핵심은 단 하나, 문서로 소통한다는 것입니다.

1. 바이브코딩의 특장점 : AI와 문서로 일한다

바이브코딩에서는 AI와 마크다운 문서(.md)로 소통합니다. AI가 문서를 작성하고, 인간은 그 문서를 검토하며 지시하는 방식입니다.
문서 / 폴더
역할
설명
CLAUDE.md
프로젝트 규칙 (법전)
AI가 매번 읽는 설정 파일. 나의 작업 스타일과 규칙을 담음
MEMORY.md
AI의 장기 기억
대화가 끝나도 기억해야 할 정보를 저장. 다음 대화에서도 참고
SKILL.md
반복 업무 지침서 (Skill)
자주 하는 업무의 수행 방법을 저장. /스킬명으로 직접 호출하거나, 요청이 설명문과 맞으면 자동 발동
에이전트 파일 .claude/agents/이름.md
전문 AI 페르소나 (Agent)
한 가지 일만 맡는 서브에이전트를 정의. 메인 에이전트가 일을 맡기거나 @이름 으로 부름
BRD.md
비즈니스 요구사항 문서
"뭘 만들지?" : 목표, 범위, 이해관계자, 예산, 제약사항
PRD.md
제품 요구사항 문서
"어떻게 만들지?" : 핵심기능, UI 설계, 기술사양, 구현계획

비유로 보면 : 회사와 같습니다

파일
비유
왜 그렇게 보나
CLAUDE.md
회사 사규
이 폴더에서 일하는 모두가 매번 먼저 읽는 규칙
SKILL.md
업무 매뉴얼
반복하는 일을 어떤 순서로 하는지 적은 문서
에이전트 파일 (서브에이전트)
직원
한 가지 일을 맡아 하고 결과만 돌려주는 사람
메인 에이전트 (내 대화창의 클로드)
팀장
요청을 받아 매뉴얼대로 직원에게 일을 나눠 맡기는 사람
비유는 이해를 돕는 그림입니다. 실제로는 모두 폴더 안의 .md 파일이고, 클로드 코드가 이 파일들을 읽고 일합니다.

한눈에 보기 : 폴더 안에서 이렇게 생겼습니다

클로드 코드가 읽는 문서 3가지 : CLAUDE.md · SKILL.md · 에이전트 파일
클로드 코드가 읽는 문서 3가지 : CLAUDE.md · SKILL.md · 에이전트 파일
세 파일을 열어 보면 : 노란 줄이 클로드 코드가 먼저 보는 곳
세 파일을 열어 보면 : 노란 줄이 클로드 코드가 먼저 보는 곳
💡
기준은 CLAUDE.md, 순서는 SKILL.md, 나눠 맡기는 것은 에이전트 파일. 오늘은 CLAUDE.md(2교시 · 5교시)와 SKILL.md(6교시 「기획서 쓰자」)를 씁니다. 에이전트 파일은 2회차에 직접 만듭니다.

실제 예 : 강사가 만든 광고 리포트 에이전트

스킬과 서브에이전트가 실제로 어떻게 나뉘고 이어지는지 보여 줍니다. 2회차에 이 구조를 내 업무로 만듭니다.
광고 리포트 에이전트 구조 : 메인 에이전트 · 스킬 · 서브에이전트 2개와 사람 승인
광고 리포트 에이전트 구조 : 메인 에이전트 · 스킬 · 서브에이전트 2개와 사람 승인
메인 에이전트 · 스킬 · 서브에이전트 파일을 열어 보면
메인 에이전트 · 스킬 · 서브에이전트 파일을 열어 보면
📝
핵심 원칙 : 모든 문서 작성은 AI가 한다. AI가 문서로 보고하고, 인간은 문서 검토로 지시한다. 마크다운(.md)은 인간과 AI가 가장 효율적으로 소통할 수 있는 문서 형식입니다.

2. 컨텍스트 엔지니어링

🧩
바이브코딩에서는 프롬프트 엔지니어링을 기반으로 한 컨텍스트 엔지니어링이 가장 중요합니다.
컨텍스트(Context) = 맥락. AI에게 단순히 질문을 잘 하는 것(프롬프트 엔지니어링)을 넘어서, AI가 작업에 필요한 모든 맥락 정보를 체계적으로 제공하는 것이 컨텍스트 엔지니어링입니다.

LLM에게 전달해야 하는 정보

  • 시스템 지침 : "친절한 튜터처럼 행동해" 또는 "JSON만 출력해"와 같은 규칙
  • 사용자 프롬프트 : "이 기사를 요약해 줘"와 같은 특정 질문 또는 작업
  • 대화 기록 : 일관성을 유지하기 위한 이전 상호작용
  • 외부 데이터 : 모델에 제공되는 문서, 데이터베이스 또는 API 결과
  • 도구 : 웹 검색이나 파일 조작 같은 도구에 대한 접근
💡
사실 LLM을 잘 사용하고 있었던 유저는 이미 어느 정도 컨텍스트 엔지니어링을 하고 있었습니다. 요청 → 응답 결과 직접 실행 → 실행 결과를 LLM에 공유 → 다시 요청 이 과정 자체가 맥락을 쌓는 과정입니다.

우리 회사 업무 컨텍스트 자료

같은 원리를 회사 업무에 적용하면, AI에게 제공할 맥락은 곧 우리 회사의 업무 문서입니다. 해운 업무 기준으로는 다음과 같은 자료가 컨텍스트가 됩니다.
  • 운임표(Tariff) : 구간, 컨테이너 타입별 운임 기준
  • C/P 계약 양식 : 용선계약 표준 조항과 용어
  • 선복 스케줄 : 선명, 항차, ETD/ETA, 마감 정보
  • 항차 정산서 양식 : 정산 항목과 계정 구조
  • 해운 용어집 : 사내 약어, 전문용어 정의
  • B/L, D/O 표준 양식 : 선적서류 필수 기재 항목
이 자료를 작업 폴더에 두고 "이 파일을 읽고 해줘"라고 하거나 CLAUDE.md에 @파일명으로 등록하면 Claude Code가 읽고 작업합니다. 매번 자동으로 읽히는 것은 CLAUDE.md뿐입니다. 오늘 실습에는 실제 회사 자료를 넣지 않습니다.

3. 실습 : 내 업무 맥락 문서 만들기

📍
어디에 치나요 : VS Code에서 서울_바이브코딩 폴더를 열고, 아래 터미널에 claude를 입력해 클로드 코드를 켭니다. 이번 실습의 문장은 모두 클로드 코드 입력 칸에 넣습니다. claude.ai가 아닙니다.
0️⃣
먼저 맥락 없이 한 번 시켜 보기
아래 문장을 보내고, 나온 결과를 눈으로 봐 둡니다. 끝에서 같은 문장을 다시 보내 비교합니다.
Plain Text
이번 주 내 업무 주간 보고 틀을 만들어줘.
→ 내 업무를 모르니 어느 회사에나 맞는 일반적인 틀이 나옵니다.
1️⃣
인터뷰로 맥락 문서 만들기
[ ] 두 곳(기업 · 부서 · 직무, 내 이름)만 바꿔 그대로 붙여 넣습니다. 이름은 띄어쓰기 없이 씁니다 (예 : 홍길동).
Plain Text
나는 [기업·부서·직무]를 맡고 있어.
앞으로 AI에게 일을 시킬 때 매번 처음부터 설명하지 않도록,
내 업무 맥락을 정리한 문서를 너와 함께 만들려고 해.

진행 방식:

1. 네가 나를 인터뷰해줘. 질문은 한 번에 하나씩, 6개까지 해줘.
   질문마다 내가 답하기 쉽게 보기나 예시를 2~3개 붙여줘.

2. 아래 다섯 가지가 채워지면 인터뷰를 끝내줘.
   - 우리 팀이 하는 일과 그 중 내가 맡은 역할
   - 매주·매월 반복하는 대표 업무 5개
   - 각 업무에 쓰는 데이터와 파일이 어디에 있는지
   - 내 역할과 업무에서 가장 중요하게 지켜야 하는 것 (예 : 마감, 정확도, 안전)
   - 우리 팀에서만 쓰는 용어와 약어

3. 마지막으로 이 업무들을 AI에게 맡길 때 검토해야 할 위험을 세 가지로 정리해줘.
   내가 놓친 것이 있으면 네가 먼저 짚어줘.
   각 위험마다 "무엇이 잘못될 수 있는지"와 "무엇을 확인하면 막을 수 있는지"를 같이 써줘.

4. 정리가 끝나면 "[내 이름]_업무_맥락.md" 파일로 저장해줘.

5. 실제 고객명·인사 정보·거래 조건은 넣지 마. 유형으로만 적어줘.
2️⃣
저장한 문서를 클로드 코드가 매번 읽게 등록하기
  • CLAUDE.md는 대화를 시작할 때마다 읽히는 파일입니다. 그 안에 @파일명 한 줄을 적어 두면 그 파일도 함께 읽힙니다
  • 아래 한 줄을 입력하면 클로드 코드가 등록을 대신합니다
Plain Text
방금 저장한 [내 이름]_업무_맥락.md를 앞으로 모든 작업에서 먼저 읽도록 CLAUDE.md 문서를 만들어줘
✅
등록 확인 : 맥락 전과 후 비교하기
  • /clear로 새 대화를 열고, 0️⃣에서 보냈던 문장을 그대로 다시 보냅니다 : "이번 주 내 업무 주간 보고 틀을 만들어줘."
  • 내 반복 업무 · 우리 팀 용어 · 쓰는 파일이 들어간 틀이 나오면 등록된 것입니다. 0️⃣ 결과와 무엇이 달라졌는지 비교해 봅니다
  • 이것이 컨텍스트 엔지니어링입니다. 질문은 같은데, 맥락이 있으니 결과가 달라집니다
  • 이 문서는 클로드 코드를 실행한 작업 폴더(서울_바이브코딩)에서만 읽힙니다. 다음 시간에도 같은 폴더에서 시작합니다
3️⃣
만든 문서 2개를 직접 열어 보기
  • VS Code 왼쪽 탐색기에서 [내 이름]_업무_맥락.md를 누릅니다. 인터뷰에서 답한 내용이 문서로 정리돼 있습니다
  • 같은 곳에서 CLAUDE.md를 누릅니다. 2교시에 넣은 규칙 아래에 @[내 이름]_업무_맥락.md 한 줄이 보이면 됩니다
  • 보기 좋게 보려면 파일을 연 채로 Ctrl + Shift + V를 누릅니다 (미리보기)
  • 틀린 내용이 있으면 직접 고치고 저장(Ctrl + S)하거나, 클로드 코드에게 "업무 맥락 문서의 반복 업무 3번을 이렇게 고쳐줘"라고 말합니다
→ AI가 쓴 문서를 사람이 읽고 고치는 것, 이것이 「AI와 문서로 일한다」의 마지막 단계입니다.