AI 에이전트의 ‘SKILL.md’가 뚱뚱해질 때 생기는 비극과 해결책 (프롬프트 비대화의 함정)

“버그가 생길 때마다 지침을 한 줄씩 추가하다 보니, 어느새 시스템 프롬프트가 수백 줄이 되었습니다. 그런데 왜 AI는 말을 더 안 들을까요?”

AI 코딩 에이전트(Google Antigravity, Cursor, Claude Code, Windsurf 등)를 활용해 네이버 블로그 자동 포스팅, 뉴스 크롤러, 데이터 분석 등 실무 자동화 파이프라인을 구축하다 보면 누구나 반드시 마주치는 거대한 병목이 있습니다. 바로 시스템 규칙 파일인 SKILL.md 또는 시스템 프롬프트(System Prompt)의 비대화(Bloat) 현상입니다.

자동화 파이프라인에서 예외가 터질 때마다 “이것도 하지 마라”, “저것도 조심해라”라며 프롬프트에 금지 규칙을 한 줄씩 덧붙이다 보면, 처음에는 똑똑했던 AI 에이전트가 점차 엉뚱한 환각을 일으키고 기본 원칙조차 무시하는 상황이 발생합니다.

실제 엔지니어링 프로젝트를 운영하며 겪었던 생생한 경험을 바탕으로, 왜 SKILL.md가 비대해질수록 AI 모델의 성능이 저하되는지, 그리고 이를 해결하기 위한 결정론적 코드 가드레일 분리 아키텍처 전략을 상세히 정리해 드립니다.

1. 발단: 완벽을 추구하다 보니 늘어난 잔소리

자동화 시스템을 운영하다 보면 실제 운영 환경(Production)에서 수많은 예외 상황(Edge Case)과 에러를 마주하게 됩니다.

• 웹 크롤링 인코딩 파손: 해외 뉴스나 비표준 웹페이지를 크롤링할 때 EUC-KR, GBK 등 다양한 문자셋으로 인해 텍스트가 깨져 들어오는 문제
• 소프트 404(Soft 404) 현상: 서버가 실제로는 페이지가 없음에도 HTTP 200 정상 상태 코드와 함께 안내 문구만 띄우는 기만적 응답 문제
• 포맷 및 금지어 통제 실패: 블로그 본문에 특정 금지어(이모지, 한자, 지나치게 딱딱한 기자체 어투)가 무단으로 섞여 들어가는 문제
• 에디터 자동화 제어 오작동: 네이버 스마트에디터나 워드프레스 블록 에디터에서 볼드, 가운데 정렬, 단락 구분이 의도와 다르게 뒤틀리는 문제

이러한 문제가 발생할 때 개발자가 가장 빠르고 손쉽게 시도하는 해결책은 SKILL.md 파일에 금지 규칙과 예외 처리 지침을 즉시 텍스트로 추가하는 것입니다.

처음에는 한두 줄의 지침이 효과를 발휘하는 것처럼 보입니다. 하지만 지침이 100줄, 200줄, 500줄로 누적되는 순간 시스템은 걷잡을 수 없는 이상 동작을 시작하게 됩니다.

2. SKILL.md가 비대해지면 발생하는 주요 부작용 4가지

시스템 지침이 비대해지면 AI 에이전트의 실행 흐름은 다음과 같이 급격한 질적 저하를 겪게 됩니다.

[초기 상태] 간결한 목표 제시 ──> AI의 창의적이고 신속한 실행
           ▼ (예외 규칙 및 금지 조항 무한 누적)
[비대화 상태] 수백 줄의 제약 조건 ──> 토큰 낭비 + 주의력 분산 + 엉뚱한 환각(Hallucination)

(1) 컨텍스트 윈도우(토큰) 낭비와 응답 속도 저하

AI 에이전트는 사용자와 대화를 주고받거나 도구(Tool)를 실행하는 매 턴(Turn)마다 SKILL.md 전체 문서를 컨텍스트에 포함하여 읽습니다. 규칙 문서가 수천 토큰으로 비대해지면 매 호출마다 막대한 기본 토큰이 소모되어 API 비용이 기하급수적으로 증가하며, 모델의 연산량이 늘어나 응답 지연 시간(Latency)이 현저하게 길어집니다.

(2) 주의 집중도(Attention) 분산과 환각(Hallucination) 유발

대규모 언어 모델(LLM)의 주의 집중 메커니즘(Attention Mechanism)은 유한한 자원입니다. 수백 개의 규칙이 한꺼번에 쏟아지면 모델은 어떤 규칙이 최우선 핵심이고 어떤 규칙이 부차적인 보조 조건인지 우선순위를 혼동하게 됩니다. 결과적으로 “실제 크롤링된 URL을 1:1로 원본 그대로 보존하라”는 가장 기초적인 규칙을 망각하고, 문맥을 맞추기 위해 가상의 URL이나 조작된 파라미터를 그럴듯하게 날조하는 치명적인 환각이 발생합니다.

(3) 규칙 간의 상충과 모델의 오버피팅(Overfitting)

지침이 방대해질수록 규칙 상호 간에 미세한 논리적 모순이 발생합니다. 예를 들어 “본문은 친근한 대화체로 작성하라”는 스타일 지침과 “원문의 사실관계와 고유명사는 단 1자도 왜곡하거나 생략하지 마라”는 정확도 지침이 충돌할 때, AI는 어느 장단에 맞춰야 할지 혼란에 빠집니다. 결국 극단적으로 안전한 단답형 답변만 내놓거나, 부자연스럽고 경직된 문장을 양산하게 됩니다.

(4) 프롬프트 레거시화와 유지보수 불가능 상태

시간이 지나면 개발자 본인도 SKILL.md의 어떤 위치에 어떤 규칙이 적혀 있는지 파악하기 어려워집니다. 특정 버그를 잡기 위해 지침 한 줄을 수정했을 때 다른 핵심 기능이 연쇄적으로 오작동할까 두려워 프롬프트에 손을 대지 못하는 전형적인 레거시 코드의 늪에 빠지게 됩니다.

3. 해결책: 프롬프트로 기도하지 말고 코드로 가드레일을 쳐라

프롬프트 비대화의 비극을 끝내기 위한 근본적인 해결책은 프롬프트(자연어 지침)와 코드(결정론적 프로그램)의 역할을 아키텍처 레벨에서 명확히 분리하는 것입니다.

AI에게 “절대 실수하지 마”라고 자연어로 빌고 기도하는 대신, 실수가 불가능하도록 물리적인 코드 가드레일(Guardrails)을 설치해야 합니다.

4. 실전 리팩토링 3단계 전략

1단계: 검증(Validation)을 코드 단으로 완전 이관

AI 에이전트에게 “깨진 링크를 선택하지 마라”, “본문 길이가 짧은 기사는 제외하라”고 프롬프트로 당부하는 방식을 중단해야 합니다. 대신 데이터 파이프라인 중간에 독립적인 검증 모듈(Validator)을 배치하여, 코드가 물리적으로 404 응답과 비정상 데이터를 사전에 걸러내도록 만듭니다.

// 잘못된 방식: AI에게 404를 거르라고 프롬프트로 부탁하기
// 올바른 방식: 코드가 직접 렌더링 검증 후 통과된 데이터만 AI에게 전달

export async function verifyArticleUrl(url: string): Promise<VerifiedArticle> {
  const res = await fetch(url);
  const html = await res.text();
  
  // 소프트 404 및 본문 길이 기계적 검증
  if (html.includes("페이지를 찾을 수 없습니다") || html.length < 500) {
    return { isLive: false }; // AI가 개입할 여지 없이 코드가 차단
  }
  return { isLive: true };
}

이렇게 검증 로직을 코드로 분리하면 AI는 이미 완벽하게 정제된 데이터만 전달받으므로, 불필요한 규칙을 기억할 필요 없이 고품질 텍스트 생성에만 온전히 집중할 수 있습니다.

2단계: SKILL.md의 모듈화 및 단일 책임 원칙 적용

프로젝트의 모든 작업 규칙을 하나의 단일 파일에 몰아넣지 않고, 소프트웨어 공학의 단일 책임 원칙(Single Responsibility Principle)에 따라 관심사별로 분리합니다.

• crawling-rules.md: 기사 수집 대상 도메인 및 타겟 카테고리 정의
• writing-style.md: 블로그 플랫폼 맞춤형 문체 및 어조 가이드
• editor-actions.md: Playwright 브라우저 조작 및 자동화 매뉴얼

작업 단계에 따라 필요한 지침 파일만 선택적으로 로드하여 컨텍스트에 주입함으로써 토큰 낭비를 줄이고 모델의 집중도를 극대화할 수 있습니다.

현재 SKILL.md 파일의 크기가 너무 커져서 에이전트의 효율성과 유지보수성이 떨어집니다. 
베스트 프랙티스 방법론에 따라 SKILL.md를 핵심 오케스트레이터로 경량화하고, 세부 규칙들은 references/ 폴더 아래의 전문 마크다운 문서로 분리해 주세요.

[요청 사항]
1. references/ 폴더를 생성하고 역할을 다음과 같이 분리하여 새 .md 파일을 작성해 주세요:
   - references/content-rules.md : 본문 작성 규칙, 글자 수, 문체, 번역 주체 명시, 금지어/이모지 배제, SEO 규칙
   - references/crawler-validator.md : 기사 수집/필터링 조건, 실시간 URL 유효성 검수, 인코딩/Soft-404 방지 규칙
   - references/naver-automation.md : 플레이라이트 브라우저 제어, 스마트에디터 서식/볼드 입력, 쇼핑커넥트 연동 규칙

2. 메인 SKILL.md 파일 리팩토링:
   - 전체적인 실행 워크플로우와 단계별 트리거 요약만 남겨 슬림하게 정리해 주세요.
   - 각 단계마다 세부 규칙이 필요할 때 위 references/ 문서들을 참조하도록 명확한 파일 링크와 경로를 연결해 주세요.
   - 불필요하게 중복된 설명은 제거해 주세요.

분리 작업 완료 후 새로 구성된 파일 구조와 변경 요약을 정리해 주세요.
  

3단계: 행동 원칙(Principle) 위주의 지침 다이어트

SKILL.md에는 복잡한 예외 처리 코드나 조건 분기를 서술하지 않고, 에이전트가 지켜야 할 핵심 가치관과 절대적 금기 사항(Negative Constraints)만 간결한 불릿 포인트로 유지합니다. 지침이 짧고 명확할수록 모델의 규칙 준수율(Instruction Following Rate)은 비약적으로 향상됩니다.

5. 요약 및 마무리

AI 에이전트 시스템을 처음 설계할 때는 프롬프트를 길고 상세하게 작성할수록 에이전트가 더 완벽하게 동작할 것이라는 착각에 빠지기 쉽습니다. 하지만 시스템이 고도화될수록 진정한 아키텍처 역량은 “프롬프트를 얼마나 과감하게 깎아내고, 그 자리에 단단한 결정론적 코드를 채워 넣는가”에서 판가름 납니다.

• AI 모델의 역할: 맥락 이해, 창의적 문장 구성, 자연스러운 톤 조율
• 프로그램 코드의 역할: 데이터 유효성 검증, 에러 차단, 하드 린팅, 무결성 보장

확률에 의존하는 프롬프트와 확실성을 보장하는 코드 가드레일이 각자의 영역에서 조화를 이룰 때, 비로소 사람의 추가적인 개입 없이 24시간 안정적으로 구동되는 진정한 무인 자동화 에이전트를 완성할 수 있습니다.