이 블로그는 AI 스킬로 운영된다 — Context Engineering 실전기

이 글도 AI가 썼다.

정확히 말하면, 사람이 주제를 정하고 방향을 잡으면 Claude Code가 리서치하고, 초안을 쓰고, 링크를 연결하고, SEO를 점검하고, 배포까지 한다. 핵심은 프롬프트가 아니라 스킬이다. .claude/skills/ 디렉터리에 있는 12개의 마크다운 파일이 에이전트의 행동을 결정한다.

이것이 바로 Context Engineering의 실전 적용이다.

Context Engineering, 다시 짚기

Context Engineering은 LLM에게 무엇을 알려줄지 설계하는 분야다. 프롬프트 엔지니어링이 "어떻게 물어볼까"에 집중한다면, Context Engineering은 "에이전트가 올바른 결정을 내리려면 어떤 정보가 필요한가"를 설계한다.

이 블로그에서는 그 정보를 **스킬(Skill)**이라는 단위로 관리한다. 각 스킬은 마크다운 파일 하나로, 에이전트가 특정 작업을 수행할 때 컨텍스트 윈도우에 로드된다.

12개 스킬의 전체 구조

블로그 운영에 필요한 모든 작업이 12개 스킬로 나뉘어 있다.

.claude/skills/
├── blog-writer/       # 글 작성 워크플로우
├── blog-review/       # 초안 품질 검토
├── zettelkasten/      # 글 간 연결 관리
├── seo/               # SEO 점수 측정/개선
├── pre-publish/       # 발행 전 링크 정리
├── transition-stage/  # 발행 단계 전환
├── publish/           # 배포
├── push/              # Git commit & push
├── project-guide/     # 프로젝트 아키텍처 레퍼런스
├── dev/               # 개발 서버/빌드/디버깅
├── styling/           # 디자인 시스템/Tailwind
└── add-page/          # 새 페이지 추가

이 스킬들은 역할에 따라 네 가지 그룹으로 묶인다.

blog-writer는 이 블로그의 핵심 스킬이다. 주제 기획(Phase 1)부터 최종 승인(Phase 8)까지 8단계 워크플로우를 정의한다. 글 유형(How-to, Listicle, Case Study, 비교, Ultimate Guide)에 따라 구조를 다르게 잡고, 주제가 넓으면 허브-스포크 클러스터로 쪼개는 판단 기준까지 포함한다. SEO 규칙(키워드 밀도, 역삼각형 구조), 톤 가이드, MDX 문법, References 작성 규칙이 모두 이 파일 안에 있다.

blog-review는 초안의 발행 가능성을 판단한다. 사실성(모델 버전, 가격, 벤치마크 등의 검증), 구조(소제목 계층, 문단 길이), SEO(메타데이터 품질), 링크 안정성(위키링크 대상 존재 여부)을 점검하고, 발견된 이슈를 High/Medium/Low 심각도로 분류한다. "쉬운 단어 우선" 원칙도 이 스킬이 적용한다.

지식 관리

글이 독립된 문서가 아니라 연결된 지식 네트워크가 되도록 관리한다.

zettelkasten은 위키링크([[slug]]), 백링크, 카테고리 색상, 지식 그래프를 관리한다. 새 글을 쓸 때 기존 글과의 연결 후보를 탐색하고, 양방향 링크를 삽입하고, 첫 번째 태그가 그래프 노드 색상을 결정하는 규칙을 적용한다.

seo는 자체 측정 스크립트(bun run measure:seo)를 사용해 글 단위 SEO 점수를 측정한다. canonical 태그, sitemap 포함 여부, description 길이, JSON-LD 구조화 데이터까지 체크하고, 감점 항목별 대응 방법을 안내한다.

발행 파이프라인

글이 완성된 후 실제로 세상에 나가기까지의 과정을 자동화한다.

pre-publish는 발행 직전 정리를 담당한다. 미발행 글을 가리키는 내부 링크를 제거하고, 기존 발행 글 1~3개에 역링크를 삽입하고, 빌드와 SEO를 검증한다.

transition-stage는 publishStage 값을 안전하게 전환한다. draft → prepublish → published 순서를 강제하고, 링크 정책 위반이 있으면 전환을 중단한다. dry-run 모드로 미리 영향을 확인할 수 있다.

publish는 최종 배포를 수행한다. publishStage: published와 published: true로 전환하고, 변경 파일을 커밋하고, git push origin main으로 Vercel 자동 배포를 트리거한다.

push는 publish와 별개로, 글 이외의 일반 변경사항을 커밋하고 push하는 스킬이다.

개발 인프라

블로그 자체의 코드와 디자인을 다루는 스킬들이다.

project-guide는 프로젝트 전체의 아키텍처 레퍼런스다. 빌드 파이프라인(MDX → Velite → .velite/ JSON → Next.js SSG), 라우트 맵, 핵심 파일 역할, 테마 시스템, SEO 전략이 문서화되어 있다. 에이전트가 코드를 수정할 때 전체 구조를 이해한 상태에서 작업할 수 있게 한다.

dev는 개발 서버 실행, 빌드, 에러 해결을 안내한다. "Velite 스키마 에러가 났다"거나 "#site/content import가 안 된다" 같은 상황에서 원인과 해결법을 바로 제공한다.

styling은 디자인 시스템(색상 토큰, 폰트, 레이아웃 패턴)과 Tailwind CSS 사용법을 정의한다. 다크모드 구현 방식, 코드 블록 스타일, prose 설정까지 포함한다.

add-page는 새 페이지나 라우트를 추가하는 템플릿을 제공한다. generateMetadata 필수 포함, container mx-auto max-w-3xl 래퍼 사용, 한국어 UI 같은 규칙이 코드 예시와 함께 정리되어 있다.

하나의 글이 만들어지는 과정

이 스킬들이 실제로 어떻게 협업하는지, 이 글이 만들어진 과정을 따라가 보자.

사용자: "Context Engineering 실전기 글을 써줘"
                    ↓
            blog-writer 로드
     Phase 1: 주제 기획, 키워드 전략
     Phase 2: bun run new "제목" → MDX 파일 생성
     Phase 3: 아웃라인 설계
     Phase 4: 본문 작성 (project-guide 참조)
     Phase 5: 제목/메타 작성
                    ↓
            blog-review 로드
     사실 검증, 구조 점검, 용어 교정
                    ↓
            zettelkasten 로드
     기존 글 탐색 → 위키링크 삽입 계획
                    ↓
            pre-publish 로드
     내부 링크 정리, 역링크 삽입, 빌드 검증
                    ↓
            transition-stage 로드
     draft → prepublish → published 전환
                    ↓
            publish 로드
     git commit → git push → Vercel 자동 배포

사용자가 한 것은 주제를 정하고 피드백을 준 것뿐이다. 나머지는 스킬이 정의한 워크플로우를 에이전트가 실행한다.

왜 프롬프트가 아니라 스킬인가

"그냥 프롬프트를 잘 쓰면 되지 않나?"라고 생각할 수 있다. 차이는 세 가지다.

1. 재사용성

프롬프트는 매번 새로 써야 한다. 스킬은 한 번 만들면 계속 쓴다. "SEO 점검해줘"라고 말하면 seo 스킬이 로드되고, 동일한 절차가 적용된다. 10번째 글이든 100번째 글이든 품질이 일정하다.

2. 관심사 분리

하나의 거대한 시스템 프롬프트에 모든 규칙을 넣으면 컨텍스트 윈도우가 낭비된다. 스킬은 필요할 때만 로드된다. 글을 쓸 때는 blog-writer만, 배포할 때는 publish만 컨텍스트에 들어간다. 이것이 Context Engineering에서 말하는 **프로그레시브 디스클로저(Progressive Disclosure)**다.

3. 버전 관리

스킬은 마크다운 파일이다. Git으로 변경 이력을 추적하고, 규칙이 바뀌면 파일을 수정하면 된다. "References에는 공식 문서만 허용"이라는 규칙을 추가하고 싶으면 blog-writer의 SKILL.md를 한 줄 고치면 끝이다. 프롬프트를 기억에 의존해서 매번 반복할 필요가 없다.

스킬 하나의 구조

각 스킬 파일은 YAML frontmatter와 마크다운 본문으로 구성된다.

---
name: blog-writer
description: >
  블로그 글 작성의 전체 워크플로우.
  "블로그 글 작성", "포스트 작성" 같은 요청에 트리거.
user-invocable: true
argument-hint: [글 제목 또는 주제]
allowed-tools: Bash(bun *), Read, Edit, Write, Grep, Glob
---

name: 스킬 식별자
description: 에이전트가 어떤 요청에 이 스킬을 로드할지 결정하는 트리거 설명
user-invocable: 사용자가 /blog-writer 같은 슬래시 커맨드로 직접 호출 가능 여부
allowed-tools: 이 스킬이 사용할 수 있는 도구 목록

본문은 일반 마크다운이다. 체크리스트, 코드 예시, 테이블, 의사결정 트리 등 에이전트가 참조해야 할 모든 지식이 들어간다. 에이전트가 이 파일을 읽으면, 그 내용이 곧 에이전트의 행동 규칙이 된다.

직접 만들어보기

이 블로그의 스킬 구조를 참고해서 자신의 프로젝트에 적용할 수 있다. Claude Code 기준으로 설명하지만, 원리는 Cursor(.cursor/rules/)나 다른 AI 에이전트에도 동일하게 적용된다.

1단계: 반복 작업을 식별한다

매번 비슷한 요청을 하는 작업이 있다면, 그것이 스킬 후보다.

"PR 올리기 전에 항상 테스트 돌려줘" → test-runner 스킬
"커밋 메시지를 Conventional Commits로 써줘" → commit 스킬
"새 API 엔드포인트 추가할 때 이 구조를 따라줘" → api-template 스킬

2단계: 마크다운으로 규칙을 적는다

---
name: test-runner
description: >
  PR 전 테스트 실행. "테스트", "PR 준비", "검증" 요청에 트리거.
user-invocable: true
allowed-tools: Bash(bun test*)
---
 
# Test Runner
 
## 실행 순서
 
1. 변경된 파일과 관련된 테스트 파일을 찾는다
2. `bun test --filter <파일>` 으로 관련 테스트만 실행한다
3. 실패 시 원인을 분석하고 수정 제안을 한다
4. 전체 테스트를 돌려 회귀를 확인한다
 
## 규칙
 
- 테스트 없는 파일은 테스트 작성을 먼저 제안한다
- 커버리지 80% 미만이면 경고한다

3단계: 스킬 간 연결을 설계한다

하나의 스킬이 끝나면 다음 스킬로 이어지는 흐름을 만든다. 이 블로그에서는 blog-writer → blog-review → pre-publish → publish 순서가 그 예다. 각 스킬의 완료 조건이 다음 스킬의 시작 조건이 된다.

Context Engineering 원칙을 스킬에 주입하다

스킬 시스템이 12개로 성숙해지면서 새로운 문제가 드러났다. 긴 세션에서 에이전트가 앞쪽 결정(글 유형, 핵심 키워드, 톤)을 잊거나, bun run build 같은 도구 출력이 컨텍스트 윈도우를 잡아먹어 핵심 작업이 밀려나는 현상이다.

이 문제는 스킬의 내용이 부족해서가 아니라, 스킬이 컨텍스트 윈도우를 어떻게 관리할지 지시하지 않았기 때문에 발생했다. Context Engineering의 핵심 원칙 6가지를 기존 스킬에 주입하여 해결했다.

Lost-in-the-Middle 방지 → blog-writer Phase 4

LLM은 긴 컨텍스트의 중간부를 잘 기억하지 못한다. 8단계 워크플로우에서 Phase 4(본문 작성)에 도달하면 Phase 1(기획)의 결정이 이미 컨텍스트 중간에 묻혀 있다.

해결: Phase 4 시작 전에 핵심 결정(글 유형, 키워드, SEO 규칙, 톤)을 명시적으로 재확인하는 가드를 추가했다.

Scratch Pad — 도구 출력 오프로드 → blog-writer Phase 7, pre-publish

bun run build의 전체 로그는 수백 줄이다. SEO 측정 결과도 JSON으로 수십 줄이 나온다. 이 출력을 전부 컨텍스트에 남기면 정작 중요한 글 내용과 수정 지시가 밀려난다.

해결: 도구 출력을 3-5줄 요약으로 압축하고, 상세 내용은 파일(docs/*.md)에 남겨두었다가 필요할 때만 다시 읽는 Scratch Pad 패턴을 적용했다.

앵커드 요약 → blog-writer Phase 8

Phase가 전환될 때마다 구조화된 진행 요약(세션 의도, 핵심 결정, 수정 파일, 다음 단계)을 생성하도록 했다. 컨텍스트가 압축되더라도 핵심 맥락이 보존된다.

Select — 리뷰 범위 분할 → blog-review Phase 2

리뷰를 한 번에 전부 수행하면 컨텍스트가 이슈 목록으로 가득 찬다. 사실성 → 구조 → SEO → 링크 순서로 범위를 분할하고, 각 범위의 결과를 요약한 후 다음으로 넘어가도록 변경했다.

Compress — 구조화된 리뷰 요약 → blog-review 출력 형식

리뷰 결과 앞에 1줄 요약(High N건 / Medium N건 / Low N건 → Verdict)을 추가했다. 사용자와 에이전트 모두 전체 상태를 즉시 파악할 수 있다.

Error Recovery Guidance → seo 에러 처리

SEO 도구 실패 시 에러 메시지만 남기는 대신, 원인 추정 → 복구 단계 → 대안 접근법을 구조화된 형식으로 보고하도록 했다.

변경 로그

스킬	변경 위치	CE 원칙	내용
blog-writer	Phase 4	Lost-in-the-Middle	핵심 결정 재확인 가드
blog-writer	Phase 7	Scratch Pad	도구 출력 요약 규칙
blog-writer	Phase 8	Anchored Summary	Phase 전환 시 진행 요약
blog-review	Phase 2	Select	리뷰 범위 분할 실행
blog-review	출력 형식	Compress	1줄 구조화 요약
pre-publish	Step 5	Scratch Pad	build/SEO 출력 최적화
seo	에러 처리	Error Recovery	에러+원인+복구+대안 형식

별도로 context-engineering 스킬을 새로 만들어 이 원칙들의 이론적 배경과 진단 도구를 집약했다. 이 스킬은 다른 스킬들이 참조하는 메타 스킬 역할을 한다.

얻은 것과 한계

얻은 것:

글 작성 시간이 크게 줄었다. 리서치와 초안 작성을 에이전트가 처리하고, 사람은 방향 설정과 품질 판단에 집중한다.
품질이 일정하다. SEO 규칙, 링크 정책, References 기준이 스킬에 고정되어 있어서 빠뜨리는 일이 없다.
규칙 변경이 쉽다. SKILL.md 파일 하나를 고치면 다음 글부터 바로 적용된다.

한계:

스킬 작성 자체에 시간이 든다. 처음 12개를 만드는 데 상당한 시행착오가 있었다.
에이전트가 스킬을 100% 따르지는 않는다. 특히 복잡한 판단이 필요한 부분(클러스터로 쪼갤지 단일 글로 갈지)에서는 사람의 개입이 필수다.
스킬이 많아지면 어떤 스킬이 언제 로드되는지 추적이 어려워진다.

마무리

Context Engineering은 거창한 이론이 아니다. "에이전트에게 필요한 정보를 구조화해서 제공하는 것"이 전부다. 이 블로그는 그걸 12개의 마크다운 파일로 실현했다.

AI 에이전트를 쓰고 있다면, 매번 같은 지시를 반복하는 대신 스킬로 만들어보자. 첫 번째 스킬을 만드는 순간, 프롬프트 엔지니어링과 Context Engineering의 차이를 체감하게 될 것이다.

Context Engineering의 이론적 배경과 오픈소스 스킬 레포에 대해서는 Context Engineering 오픈소스 스킬 레포 분석 글을 참고하자.