6주차: 인스트럭션 튜닝

Phase 26주차중급강의일: 2026-04-07

이론 (Theory)

오늘의 학습 목표

개념 관점

“Sign” 메타포로 instruction tuning을 설명하고, 영구 컨텍스트(PROMPT.md / AGENTS.md)와 일시적 프롬프트의 역할 분리를 정리한다.

설계 관점

instruction layer를 mission / norms / pitfalls / examples 4구역으로 설계하고, 어떤 실패 패턴을 어떤 구역에서 흡수할지 결정한다.

구현 관점

프로젝트 PROMPT.md를 고도화해 반복 실수 1-2개를 명시적 금지 패턴으로 박제하고, 실패 → instruction 업데이트 사이클을 자동화한다.

운영 관점

instruction drift를 모니터링하고, 분기마다 instruction을 재검토 / 정리 / 삭제하는 “instruction housekeeping” 루틴을 제안한다.

왜 6주차에서 인스트럭션 튜닝이 중심인가

5주차에서 컨텍스트를 깨끗하게 유지하는 법을 배웠다 — auto-compaction, fresh context, 상태 파일. 하지만 컨텍스트가 깨끗해도, 에이전트가 같은 실수를 반복하면 소용이 없다.

이번 주의 핵심 질문: 에이전트의 행동을 모델 가중치 변경 없이 교정할 수 있는가?

답은 “인스트럭션 튜닝” — 모델을 바꾸지 않고 환경(instruction file)을 바꿔서 행동을 교정한다. 4주차 Ralph 루프의 AGENTS.md(누적 학습)가 수동적 기록이었다면, 이번 주의 PROMPT.md/CLAUDE.md 튜닝은 능동적 제약 설계다.

7주차(멀티에이전트)로 넘어가면 에이전트마다 다른 PROMPT.md와 퍼미션이 필요하다. 그 전에 단일 에이전트의 행동을 정밀하게 제어하는 기술을 먼저 익힌다.

---

인스트럭션 튜닝이란?

Ralph 루프에서 에이전트가 반복적인 실수를 하면, 모델 가중치를 재훈련하지 않고 PROMPT.md에 구체적이고 결정론적인 지시를 추가하여 행동을 교정한다.

Huntley의 "Sign" 메타포

어린이 놀이터 미끄럼틀 옆에 “올라가지 마시오” 경고판을 세우는 것과 같다. 미끄럼틀 자체(모델)를 재설계하는 대신, 환경에 명확한 지시(Sign)를 추가한다.

Sign Fatigue: 간판이 너무 많아지면 오히려 역효과가 난다. 놀이터에 30개의 경고판이 붙어 있으면 아이도 어른도 아무것도 읽지 않는다. PROMPT.md도 마찬가지 — 제약이 과다하면 에이전트가 핵심 지시를 놓친다. 그래서 **주기적으로 간판을 정리(tune)**해야 한다. 이것이 “인스트럭션 튜닝”의 진짜 의미 — 추가만이 아니라 정리와 우선순위 재조정을 포함한다.

인스트럭션 튜닝 프로세스

INSTRUCTION TUNING PROCESS

1. 반복 오류 패턴 식별

↓

2. 오류의 구체적 원인 분석

↓

3. 결정론적 제약 문구 작성

↓

4. PROMPT.md 영구 섹션에 추가

↓

5. 다음 루프에서 효과 검증

Claude Code 내부에서는...

인스트럭션 튜닝의 원리가 Claude Code의 Permission Model + 도구 필터링 + Instruction 계층에 그대로 구현되어 있다:

• CLAUDE.md 5레벨 계층 (2026년 확장):
  1. ~/.claude/CLAUDE.md — 사용자 전역 (모든 프로젝트 공통)
  2. ./CLAUDE.md — 프로젝트 루트 (git 공유, 팀 공통)
  3. ./CLAUDE.local.md — 개인 설정 (gitignore)
  4. 부모 디렉토리의 CLAUDE.md — 모노레포에서 상위 규칙 상속
  5. 자식 디렉토리의 CLAUDE.md — on-demand 로딩, 해당 디렉토리 작업 시에만
• @import 문법: @path/to/file로 외부 파일 참조. 예: @README.md, @docs/api-conventions.md
• Advisory vs Deterministic: CLAUDE.md는 advisory(~80% 준수). 100% 실행이 필요하면 Hook으로 구현해야 한다

도구를 숨기는 것(LLM이 존재를 모름)과 실행을 거부하는 것(알지만 차단)은 다른 보안 레이어다 — 방어심층(defense-in-depth).

→ 상세: 참고자료 > Claude Code 내부 구조

PROMPT.md 고도화 예시

# [영구 제약 — 절대 무시하지 말 것]

## ⚠️ 알려진 함정 (Instructional Tuning)

### 1. 존재하지 않는 함수 호출 금지
- `utils.parse_json()`은 이 프로젝트에 없음
- 반드시 `json.loads()`를 직접 사용할 것
- 추가일: 2026-04-02 (루프 #47에서 반복 오류 발생)

### 2. 테스트 없이 커밋 금지
- `git commit` 전 반드시 `pytest tests/ -q` 통과 필수
- CI가 실패하면 자동 rollback됨

### 3. 타입 힌트 필수
- 모든 함수는 Python 타입 힌트 포함
- `def add(a, b):` → `def add(a: int, b: int) -> int:`

---

# [현재 태스크]
...

Instruction 파일 설계 원칙 — 2,500개 레포에서 배운 교훈

GitHub Blog의 2,500개 오픈소스 레포 분석(2026)과 ETH Zurich의 AGENTbench 연구가 instruction 파일의 성공 요인과 안티패턴을 실증적으로 밝혀냈다.

성공하는 instruction 파일의 5요소

1. 실행 가능한 명령을 앞에 — pnpm test --coverage 같은 구체적 명령(플래그 포함)을 파일 상단에 배치
2. 산문보다 코드 예시 — “타입 안전하게 작성하라”보다 def add(a: int, b: int) -> int: 예시가 효과적
3. 명확한 경계 — 절대 건드리면 안 되는 파일/디렉토리를 명시
4. 구체적 스택 버전 — “Python 사용”이 아니라 “Python 3.12, FastAPI 0.115, Pydantic v2”
5. 6대 영역 커버 — 빌드 명령, 테스트, 프로젝트 구조, 코딩 스타일, git 워크플로우, 금지 사항

3-tier Boundary System

Tier	의미	예시
Always Do	매번 반드시 실행	”커밋 전 pytest 실행”, “타입 힌트 필수”
Ask First	실행 전 확인 요청	”DB 스키마 변경 시 사람에게 확인”, “외부 API 키 수정 시 확인”
Never Do	절대 금지	”.env 파일 커밋 금지”, “main 브랜치 직접 푸시 금지”

ETH Zurich 연구: LLM이 생성한 instruction 파일은 해롭다

ETH Zurich AGENTbench 연구(2026)의 핵심 발견:

• LLM이 자동 생성한 AGENTS.md: 성공률 ~3% 감소, 비용 20%+ 증가
• 인간이 직접 작성한 AGENTS.md: 성공률 ~4% 증가, 비용 ~19% 증가

왜? LLM이 생성한 파일은 “아키텍처 개요”나 “저장소 구조” 같은 일반적 정보를 나열하는데, 에이전트는 이 정보를 따르느라 불필요한 탐색을 수행한다. 인간이 작성한 파일은 “추론만으로 알 수 없는 정보”(비표준 빌드 명령, 숨겨진 제약, 도메인 규칙)만 포함하므로 효과적이다.

원칙: claude나 codex로 instruction 파일을 자동 생성하지 말라. 반드시 인간이 직접, “이것 없이는 에이전트가 실수할 정보”만 작성하라.

CLAUDE.md 200줄의 법칙

CLAUDE.md는 매 세션, 매 턴마다 시스템 프롬프트에 주입된다. 따라서 토큰 예산이 있다:

• 시스템 프롬프트가 이미 ~50개 instruction을 차지
• 사용자 instruction budget: ~150-200개 (약 200줄)
• 이 예산을 초과하면 에이전트가 핵심 지시를 무시하기 시작

Pruning 테스트: 각 줄에 대해 “이걸 빼면 Claude가 실수하나?” 자문하라. 아니면 삭제.

포함해야 할 것: 빌드/테스트 명령, 비표준 코딩 규칙, 아키텍처 결정 사항, 금지 목록 제외해야 할 것: 표준 언어 규칙(린터가 처리), 자주 변하는 정보, 긴 튜토리얼

Skills — Progressive Disclosure 패턴

200줄 제한을 해결하면서 도메인 지식을 활용하는 방법이 Skills다:

저장소	로딩 시점	용도
CLAUDE.md	매 세션 자동	프로젝트 공통 규칙 (200줄 이하)
.claude/skills/*.md	관련 태스크일 때 on-demand	도메인 특화 지식

예: API 컨벤션, 배포 절차, DB 마이그레이션 규칙 등은 매번 로딩할 필요 없다. .claude/skills/ 디렉토리에 분리하면 필요할 때만 로딩되어 토큰을 절약하면서도 전문 지식을 활용할 수 있다.

SkillReducer 연구(arXiv:2603.29919)는 도구 설명을 48% 압축했을 때 오히려 품질이 2.8% 향상되는 “less-is-more” 효과를 발견했다. 정보를 줄이면 에이전트가 핵심에 집중한다.

---

인스트럭션 효과 측정

지표	측정 방법
반복 오류율	동일 오류 발생 횟수 / 전체 루프 수
평균 루프 횟수	태스크 완료까지 필요한 루프 수
컨텍스트 효율	불필요한 탐색에 낭비되는 토큰 비율

출력 스타일과 인지 모드 — 제로 설정 인스트럭션 튜닝

PROMPT.md에 제약을 추가하는 것은 맞춤 간판을 설치하는 것과 같다. 반면 Claude Code의 **출력 스타일(Output Styles)**은 에이전트에 미리 내장된 모드 전환 스위치다. 설정 비용 없이 에이전트의 행동 패턴을 바꿀 수 있다.

핵심 통찰: 출력 스타일은 톤을 바꾸는 것이 아니라 인지 모드를 바꾼다. 같은 태스크를 주더라도 스타일에 따라 에이전트가 문제에 접근하는 방식 자체가 달라진다.

Explanatory

claude --output-style explanatory "이 함수의 에러 핸들링을 개선해줘"

에이전트가 코드를 수정하면서 왜 이렇게 바꾸는지 이유를 설명한다. PR에 reasoning이 이미 포함되므로 리뷰어가 결정만 검증하면 된다.

적합 상황: 팀 온보딩, 주니어 엔지니어의 낯선 코드베이스 작업, 코드 리뷰 시간 단축이 필요할 때

Learning

claude --output-style learning "이 함수의 에러 핸들링을 개선해줘"

에이전트가 직접 수정하는 대신 단계별로 가이드하며, 학습자가 스스로 변경하도록 유도한다. 코칭 모드.

적합 상황: 교육 목적, 이 과목의 실습처럼 학생이 원리를 이해해야 할 때

Concise

claude --output-style concise "이 함수의 에러 핸들링을 개선해줘"

최소한의 설명으로 코드 변경만 출력한다. 숙련 개발자가 빠르게 결과만 필요할 때.

적합 상황: 반복 작업, 린트 수정, 명확한 패턴 적용

Boris Cherny의 팀은 주니어 엔지니어가 낯선 서비스에서 작업할 때 Explanatory를 기본값으로 설정한다. 결과: PR 리뷰 시간이 단축되었다 — 코드에 reasoning이 이미 붙어 있으므로 리뷰어가 결정을 재구성할 필요가 없다.

Effort Levels — 추론 깊이 조절

출력 스타일이 방향을 바꾼다면, effort level은 깊이를 조절한다.

Level	용도	비용	예시
low	단순 조회, 타입 확인	최소	claude --effort low "이 함수의 반환 타입?"
medium	일반적인 코드 수정	보통	claude --effort medium "테스트 추가"
high	아키텍처 설계, 복잡한 디버깅	높음	claude --effort high "비동기 리팩터링 설계"
max	최대 추론 깊이 (지원 모델 한정)	최대 (10x+)	claude --effort max "보안 취약점 분석"

Ralph 루프에서 effort level의 실전 활용: 루프 초반(탐색 단계)에는 low로 빠르게 시도하고, 핵심 구현 단계에서 high로 전환하면 토큰 비용을 최적화할 수 있다.

ultrathink 키워드

프롬프트에 “ultrathink”를 포함하면 해당 턴만 high effort가 트리거된다. 세션 전체 설정을 바꾸지 않고 특정 질문에만 깊은 추론을 적용할 때 유용하다. Skill이나 Subagent의 YAML frontmatter에서도 effort를 오버라이드할 수 있다.

Custom Output Style — 프로젝트별 인지 모드

내장 스타일(Explanatory/Learning/Concise)로 부족하면 커스텀 스타일을 만들 수 있다:

# 새 커스텀 스타일 생성
claude /output-style:new

생성된 Markdown 파일의 frontmatter에서 keep-coding-instructions: true/false로 기존 코딩 지시를 유지할지 완전 교체할지 제어한다. 이것은 PROMPT.md보다 더 깊은 레벨의 인스트럭션 튜닝 — 시스템 프롬프트의 코딩 관련 부분 자체를 교체한다.

PROMPT.md 튜닝 vs 출력 스타일 — 언제 무엇을 쓰는가

항목	PROMPT.md 인스트럭션 튜닝	출력 스타일 + Effort Level
설정 비용	높음 — 오류 분석 → 문구 작성 → 효과 검증	제로 — CLI 플래그 하나
커스터마이징	무한 — 프로젝트 고유 제약 자유 기술	제한적 — 프리셋 목록에서 선택
지속성	영구 — 파일에 기록, git 추적	세션 단위 — 매번 지정 필요
Sign 메타포	현장에서 직접 세운 맞춤 간판	공장에서 미리 설치된 모드 전환 스위치
적합 상황	프로젝트 고유의 반복 오류 교정	범용적 행동 패턴 변경

두 접근은 보완 관계다

출력 스타일로 에이전트의 기본 행동 패턴을 설정하고, PROMPT.md로 프로젝트 고유 제약을 추가한다. 예: Explanatory 모드 + “pytest 실패 시 에러 메시지를 AGENTS.md에 기록할 것” — 범용 인지 모드 위에 프로젝트 규칙을 겹쳐 쌓는다.

Hooks — CLAUDE.md의 한계를 넘는 결정론적 시행

CLAUDE.md는 advisory — 약 80% 확률로 따른다. 100% 시행이 필요하면 Hook을 사용한다.

Hook은 도구 호출, 세션 이벤트 등에 셸 명령/HTTP/LLM 판단을 트리거하는 자동화 메커니즘이다. ~/.claude/settings.json 또는 프로젝트 .claude/settings.json에 정의한다.

4종 핸들러

타입	동작	용도
command	셸 명령 실행	auto-format, 린트 체크, 로그 기록
http	HTTP endpoint POST	외부 서비스 알림, CI 트리거
prompt	LLM(Haiku)에 판단 위임	”태스크 완료 여부” 자동 판단
agent	Subagent가 파일 읽기/명령 실행	”테스트 통과 여부” 복합 검증

실전 예시: PostToolUse로 자동 포맷팅

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "command": "npx prettier --write $CLAUDE_FILE_PATH"
    }]
  }
}

이 Hook은 Claude가 파일을 쓸 때마다 Prettier를 자동 실행한다. CLAUDE.md에 “Prettier 형식을 따르라”고 쓰는 것보다 100% 확실하다.

Stop Hook으로 Ralph 루프 자동 완료 검증

{
  "hooks": {
    "Stop": [{
      "type": "prompt",
      "prompt": "모든 태스크가 완료되었는가? fix_plan.md에서 미완료 항목을 확인하라.",
      "model": "haiku"
    }]
  }
}

prompt 타입 Hook은 Haiku 모델에 판단을 위임한다. "ok": false를 반환하면 에이전트가 계속 작업한다. Ralph 루프의 수동 검증을 자동화하는 핵심 패턴이다.

Hook의 보안 규칙

• PreToolUse Hook의 deny가 permission rule의 allow보다 항상 우선 — Hook은 제약을 강화할 수 있지만 완화할 수 없다
• if 필드(v2.1.85+)로 특정 패턴만 매칭: "if": "Bash(git *)" → git 명령에만 트리거
• Hook은 사용자의 settings.json에서만 정의 가능 — 에이전트가 스스로 Hook을 수정할 수 없다

Markdown-SSOT Skill Runtime

Agent OS Runtime은 CLAUDE.md/PROMPT.md 패턴을 SKILL.md로 일반화한다. skill frontmatter에는 triggers, allowed-tools, schema_version을 두고, runtime은 이를 skill_frontmatter_v1로 검증한 뒤 tool scope를 제한한다. 즉, instruction tuning은 “좋은 문구”에서 끝나지 않고 Markdown-SSOT + hook-gated policy로 실행 가능해진다.

---

도구별 Instruction 파일 비교

Instruction 파일은 모든 AI 코딩 도구의 공통 패턴이지만, 구현은 도구마다 다르다:

도구	파일	계층	특이점
Claude Code	CLAUDE.md	5레벨 + Skills	@import, advisory(~80%), Hook으로 보완
Cursor	.cursor/rules/	디렉토리 기반	.cursorrules에서 이전, glob 패턴 매칭
Windsurf	.windsurf/rules/	디렉토리 기반	Cascade 엔진이 자동 맥락 탐지
Codex CLI	AGENTS.md	도구 중립	60,000+ 레포 채택, 25+ 에이전트 호환
GitHub Copilot	.github/copilot-instructions.md	단일 파일	VS Code 3-tier 메모리와 결합

cross-tool 호환의 한계

모든 도구가 Markdown 기반이지만, 서로의 파일을 읽지 않는다. CLAUDE.md는 Claude Code만, .cursorrules는 Cursor만 읽는다. 이것이 AGENTS.md(도구 중립)가 등장한 배경이다 — 어떤 도구든 읽을 수 있는 공통 형식.

---

강의 중 토론 질문

1. CLAUDE.md에 “테스트 없이 커밋하지 마라”라고 쓰는 것과 Hook으로 PreToolUse: Bash(git commit*) → pytest 실행을 강제하는 것의 차이는? 어느 쪽이 더 효과적이고, 왜?
2. ETH Zurich 연구에서 LLM이 생성한 instruction 파일이 오히려 해로운 이유를 설명하라. “아키텍처 개요를 넣으면 도움이 될 것 같은데 왜 안 되는가?”
3. Sign Fatigue는 어떤 시점에서 발생하는가? PROMPT.md가 몇 줄을 넘으면 효과가 역전되기 시작할 것으로 예상하는가? SkillReducer 연구와 연결하여 논하라.
4. 출력 스타일(Explanatory/Learning/Concise)은 에이전트의 인지 모드를 바꾼다고 했다. “인지 모드를 바꾼다”는 것이 기술적으로 무슨 의미인가? 시스템 프롬프트의 어떤 부분이 변경되는 것인가?
5. 7주차 멀티에이전트에서 에이전트마다 다른 PROMPT.md를 주어야 한다면, 공통 부분과 역할별 부분을 어떻게 분리 설계할 것인가?

---

실습 (Practicum)

오늘 실습의 목표

반복 오류를 분석하여 결정론적 제약을 설계하고, A/B 테스트로 효과를 정량 측정한다. Lab 06에서 전체 파이프라인을 구현한다.

1. 오류 패턴 분석

   이전 랩의 실행 로그를 log_analyzer.py(Lab 06 참조)로 분석하여 반복 오류 상위 5개를 추출한다.

2. 3-tier Boundary 설계

   추출된 오류를 Always Do / Ask First / Never Do로 분류하고, PROMPT.md에 구조화된 인스트럭션 섹션을 추가한다.

3. Hook 설정

   Never Do 항목 중 하나를 PreToolUse Hook으로 구현하여 100% 시행을 보장한다. settings.json에 추가.

4. A/B 테스트

   동일한 태스크를 인스트럭션 추가 전/후로 실행하여 루프 횟수, 토큰 사용량, 반복 오류율을 비교한다. Lab 06의 ab_test.py를 활용.

5. Lab 06 연결

   위 실험 결과를 바탕으로 Lab 06의 4개 요구사항(분석 보고서, PROMPT.md, 비교 실험, 그래프)을 완성한다.

과제 (Assignment)

Lab 06: 인스트럭션 튜닝 실습

제출 마감: 2026-04-14 23:59

요구사항:

1. 반복 오류 분석 보고서 (최소 3가지 패턴, 3-tier 분류 포함)
2. 고도화된 PROMPT.md (인스트럭션 섹션 + Always Do / Never Do 구조)
3. 튜닝 전/후 비교 실험 결과 (A/B 테스트)
4. 인스트럭션 효과 정량 측정 그래프

---

핵심 정리

1. 인스트럭션 튜닝 = 간판 설치 + 정리: 추가만이 아니라 Sign Fatigue를 방지하기 위한 정리와 우선순위 재조정 포함
2. LLM으로 instruction 파일을 생성하지 마라: ETH Zurich 연구 — 성공률 3% 감소, 비용 20% 증가. 인간이 “추론만으로 알 수 없는 정보”만 직접 작성
3. CLAUDE.md 200줄 이하: instruction budget ~150-200개. Pruning 테스트로 불필요한 줄 제거
4. Skills로 분리: 도메인 지식은 .claude/skills/에 on-demand 로딩. SkillReducer의 less-is-more 효과
5. Advisory vs Deterministic: CLAUDE.md(~80% 준수) + Hook(100% 시행). 중요도에 따라 레벨 선택
6. 5레벨 계층: 전역 → 프로젝트 → 로컬 → 부모 디렉토리 → 자식 디렉토리. 가장 가까운 것이 우선

더 읽을거리

• How to Write a Great agents.md — GitHub Blog — 2,500개 레포 분석, 성공 5요소
• ETH Zurich AGENTbench — InfoQ — LLM 생성 instruction 파일의 역효과 연구
• Claude Code Hooks Guide — 24종 이벤트, 4종 핸들러 공식 문서
• SkillReducer (arXiv:2603.29919) — 도구 설명 48% 압축 시 품질 2.8% 향상
• Agentic Coding — MIT Missing Semester — instruction files, skills, subagents를 다루는 MIT 정규 강의