2부 · 지침 (Instructions)

1. 지침 (Instructions) — 에이전트의 헌법

1.1 개념 — 지침은 무엇인가

• 에이전트가 모든 대화에서 항상 참조하는 최상위 규칙. 회사로 치면 헌법·취업규칙.
• 스킬(필요할 때 로드)과 달리 지침은 늘 켜져 있으므로, 길수록 모든 응답이 무거워지고 핵심이 묽어집니다(1부 3.2 attention budget).
• 따라서 지침에는 항상 지켜야 할 소수의 원칙만 담고, 상황별 디테일은 스킬로 내립니다.

1.2 어떻게 작성하나 — 6원칙

이번 데모를 만들며 검증한 작성 원칙입니다.

① “무엇을”만, “어떻게”는 맡긴다. 메이커는 목표·규칙만 쉬운 말로 적고, 코드·라이브러리·경로 같은 구현은 에이전트에 맡깁니다(1부 1.4 황금률).

❌ "pandas로 /app/uploads의 xlsx를 read_excel 후 groupby로 집계하고 print"
✅ "엑셀 숫자는 눈대중 말고 실제로 계산해서 정확한 값을 알려주세요"

② 일반 사용자가 읽을 수 있게. 대부분의 메이커는 개발자가 아닙니다. 디렉토리·함수명·전문용어를 빼고 업무 언어로 적습니다.

③ 단일 출처(Single Source of Truth) — 지침에 세부를 박지 마라. 세부 규칙(예: 브랜드 색상)을 지침과 스킬 양쪽에 적으면 에이전트가 “지침에 이미 있네” 하고 스킬을 건너뜁니다. 디자인·절차는 스킬에만 두고, 지침은 스킬을 가리키게합니다.

❌ 지침: "배경은 아이보리(#FBF6EC), 포인트는 마젠타(#C2185B)"
   → 에이전트가 색만 알고 템플릿·단색 폴백 규칙이 든 스킬을 안 봄

✅ 지침: "메일·보고서는 회사 디자인 규칙(메일·보고서 스킬)을 그대로 따르세요"
   → 색을 알려면 반드시 스킬을 열어야 함 → 템플릿·규칙까지 함께 따라옴

흔한 사고다. 색을 지침에 박아두면 에이전트가 색만 보고 스킬(템플릿·예외 처리 규칙)을 건너뛰어, 디자인이 부분적으로 깨지는 일이 생긴다(1.5 사례).

④ 비가역 행동에는 확인 게이트(HITL). 메일 발송·외부 전송처럼 되돌리기 어려운 작업은 반드시 사용자 확인 후 실행으로 못 박습니다(1부 10.2).

⑤ 가드레일은 부정형으로 명확히. “데이터에 없는 숫자를 만들지 않는다”, “승인 전 발송하지 않는다” 처럼 금지선을 분명히 적습니다.

⑥ 구조: 역할 → 작업별 규칙 → 가드레일. 짧은 섹션으로 끊어 스캔하기 쉽게 만듭니다.

1.3 좋은 지침 구조 (템플릿)

# [에이전트 이름] — 지침

[한 문단: 역할과 무엇을 도와주는지]

## [작업 A]를 할 때
- 규칙 (무엇을, 쉬운 말로)
- 세부는 스킬을 가리키기

## [작업 B]를 할 때 (비가역이면 "중요" 표시)
- 확인 게이트, 금지선

## 지킬 점 (가드레일)
- 항상/절대 규칙 3~5개

1.4 지침에 넣을 것 vs 스킬로 내릴 것

가장 자주 막히는 결정입니다. 기준은 “항상 필요한가, 가끔 필요한가”입니다.

지침에 넣을 것 (소수):

• 에이전트의 역할과 무엇을 도와주는지
• 항상 지켜야 할 가드레일(없는 숫자 만들지 않기 등)
• 비가역 행동의 확인 게이트(발송 전 승인)
• 세부가 필요한 작업은 “그 스킬을 따르라”는 포인터

지침에서 빼야 할 것 (→ 스킬로):

• 구체적 출력 형식·템플릿
• 색·폰트 같은 디자인 값
• 단계별 절차·도구 사용법
• 코드·라이브러리·경로 같은 구현

짚고 가기: 지침이 길어진다고 느끼면 십중팔구 어떻게(구현·형식)가 섞인 것이다. 그 부분을 스킬로 내리면 지침은 다시 가벼워지고, 에이전트는 작업할 때 해당 스킬을 펼쳐 더 정확히 따른다.

1.5 왜 단일 출처가 중요한가 — 디자인 깨짐 사례

세부를 지침에 중복으로 박으면 에이전트가 스킬을 건너뛰어 품질이 깨지는 일이 생깁니다. 대표적인 예가 HTML 메일 디자인입니다.

• 증상: 메일 헤더 글씨(흰색)가 안 보임.
• 표면 원인: 헤더 배경을 그라데이션(linear-gradient)만으로 칠해, 그라데이션 미지원 메일앱(Outlook 등)에서 배경이 사라지고 흰 글씨만 남음.
• 근본 원인: 색 값이 지침에 박혀 있어 에이전트가 스킬의 안전 규칙(“흰 글씨엔 단색 배경을 깐다”)을 펼쳐보지 않음.
• 교훈: 디자인을 스킬에만 두고 지침은 “스킬을 따르라”고만 했다면, 에이전트가 스킬을 열어 안전 규칙(bgcolor 단색)을 함께 적용했을 것.

반론 대응(FAQ): “지침에 다 적으면 더 확실하지 않나?” → 아니다. 다 적을수록 지침이 비대해져 핵심이 묽어지고(attention budget), 스킬을 우회해 오히려 품질이 떨어진다. 지침은 가리키고, 디테일은 스킬에.