하네스 5대 요소 +
Superpowers 풀스택 5단계

차시별 진행

5차시 | 하네스 엔지니어링 + 5대 요소

1도입 영상 (60초)

2하네스 엔지니어링이란?

"하네스(Harness)"는 원래 말의 마구(馬具)입니다. 천 마력 말도 마구 없이는 밭을 갈 수 없습니다. AI 에이전트도 똑같습니다 — 모델이 아무리 뛰어나도 "어떻게 일하라"는 시스템이 없으면 매번 다른 결과가 나옵니다. 그 시스템을 설계하는 기술이 하네스 엔지니어링입니다.

프롬프트 엔지니어링 (2023) → 컨텍스트 엔지니어링 (2025) → 하네스 엔지니어링 (2026)

핵심: 하네스 산출물(CLAUDE.md · 스킬 파일 · 훅 스크립트)은 전부 Git에 커밋되는 파일입니다. 팀원이 바뀌어도, 모델이 업그레이드되어도, 하네스는 남습니다.

3핵심 개념 | 하네스 5대 요소

4만화로 보는 5대 요소

셰프 식당 메타포 — 각 요소가 식당 운영의 어디에 해당하는지.

5대표 하네스 플러그인 (각 5+ 스킬)

5대 요소를 미리 묶어둔 오픈소스 플러그인. 오늘은 Superpowers만 설치하고, 나머지는 필요할 때 회사 환경에 맞게 골라 도입합니다.

회사 환경에서 외부 마켓 접근 제한 시 — 필요한 SKILL.md만 .github/skills/{name}/SKILL.md 또는 .claude/skills/{name}/SKILL.md에 직접 배치하면 동일 작동.

6실습 | context7 MCP + Superpowers 플러그인 설치

명령어를 외울 필요 없습니다. GitHub 주소를 그대로 던지면 AI가 알아서 설치합니다. Claude Code · Copilot CLI 양쪽 동일.

실습 1 — context7 MCP (공식 SDK 문서 조회)

"https://github.com/upstash/context7
이 MCP 설치해줘"

# AI가 자동 실행:
# claude mcp add context7 -- \
#   npx -y @upstash/context7-mcp@latest
# (Copilot은 copilot mcp add ...)

# 재시작 후
/mcp
# → context7 등록 확인

# Claude Code
claude mcp add context7 -- \
  npx -y @upstash/context7-mcp@latest

# Copilot CLI (동등)
copilot mcp add context7 -- \
  npx -y @upstash/context7-mcp@latest

테스트 쿼리 (양쪽 동일):

React Query v5의 useQuery 사용법을 최신 공식 문서에서 찾아줘.

실습 2 — Superpowers 플러그인 (코딩 워크플로우 4종)

"https://github.com/obra/superpowers
이 플러그인 마켓플레이스 추가하고
superpowers 설치해줘"

# AI가 자동 실행:
# /plugin marketplace add \
#   obra/superpowers-marketplace
# /plugin install \
#   superpowers@superpowers-marketplace

brainstorming
  └─ 새 기능 함께 고민

writing-plans
  └─ 3단계+ 구현 계획 작성

systematic-debugging
  └─ 4단계 구조화 디버깅

verification-before-completion
  └─ 완료 주장 전 검증

테스트 (Phase 1 시작 시 자연 발동):

"새 기능 만들기 전에 brainstorming 스킬로 같이 고민해보자"

7Superpowers 스킬 자연어 호출 예시

스킬은 활성화될 때만 로드되는 점진적 공개 — 매 세션 시작 시 메타데이터(~100 토큰)만 스캔, 호출 시점에만 본문(~5,000 토큰) 로드. 스킬 이름을 외울 필요 없습니다 — 상황을 그대로 말하면 AI가 적합한 스킬을 자동 활성화.

Claude Code · GitHub Copilot 용어 비교

같은 개념을 두 도구에서 어떻게 부르는지. 파일명·SKILL.md 형식·hook 이벤트명은 양쪽 동일(GitHub Agent Skills 표준).

핵심 메시지

• 회사 적용 1단계: 회사 repo에 AGENTS.md(또는 CLAUDE.md) 만들고 오늘 작성한 내용을 그대로 옮김 → Copilot이 인식.
• 회사 적용 2단계: skills/{name}/SKILL.md 폴더 구조로 오늘 만든 스킬 그대로 옮김 → Copilot도 동일하게 활성화.
• 차이점: 슬래시 명령 이름은 도구별로 다르나 개념·파일 구조·SKILL 사양은 동일.

6차시 | Superpowers로 POS 분석 앱 만들기 (풀스택 5단계)

1오늘 만들 것 미리보기

기본은 Superpowers 스킬. /codex (외부 OpenAI), /simplify (Anthropic 내장) 등 외부 검수 도구는 4단계 REFACTOR에서 참고용 팁으로만 다룹니다.

2POS 데이터 명세 (SAP IBP)

SAP Integrated Business Planning 표준 주요 지표 기반 9 컬럼 · 410건 (정상 400 + 이상 10 — 각 카테고리 2건씩):

이상 5건 — elif chain 순서대로 검사 (한 row가 여러 카테고리 동시 매칭 안 되도록):

1. STOCK 음수 — STOCK < 0
2. SLS=0인데 PROM>0 — SLS == 0 AND PROM > 0
3. 재고 결품 직전 — SLS > STOCK AND STOCK >= 0
4. DC 판매 0 — DC_SLS == 0
5. PROM > SLS — PROM > SLS AND SLS > 0

3Phase 1 — PLAN (15분) | brainstorming 스킬

"새 기능 만들기 전에 같이 고민해보자"라고 말하면 brainstorming 스킬이 자동 활성화. 다지선다 인터뷰로 설계 의사결정.

"pos_data.csv (410건, SAP IBP 9컬럼)을 읽어
이상 10건을 elif chain으로 찾아 표 출력하는
미니 분석 앱을 만들고 싶어. 같이 설계해보자."

# brainstorming 스킬 자동 활성화
# → 다지선다 인터뷰:
#   Q1. 출력: CLI 표 / HTML 페이지 / JSON?
#   Q2. 검사: 단일 함수 / elif chain / dispatcher?
#   Q3. 런타임: 순수 파이썬 / pandas?

research.md
  └─ pos_data.csv 9컬럼 명세
  └─ 이상 5건 카테고리 분석

design.md
  └─ 다지선다 결정 결과
  └─ 함수 분해 설계
  └─ 의사 코드 골격

4Phase 2 — DEVELOP (30분) | writing-plans + 실제 코딩

"이 기능 구현 계획을 plan.md로 작성해줘"로 writing-plans 활성화. 태스크 분해 + 순서 + 체크포인트.

"plan.md를 todo 리스트로 변환하고 전부 구현해줘.
각 단계 완료 시 plan.md에 [x] 체크.
모든 작업 완료까지 멈추지 마.
any 타입 쓰지 마, 지속적으로 type-check 실행."

강사 시연 흐름:

• load_csv(path) — UTF-8 BOM 정합 + 9컬럼 파싱
• check_anomaly(row) — elif chain 5종 (위 명세 순서)
• main() — 410건 순회 + 정확히 10건 찾기 + 카테고리별 표 출력

5Phase 3 — VERIFY (10분) | verification-before-completion

"완료 주장 전 type-check · test · 실행 결과까지 다 확인해줘" → verification-before-completion 활성화.

# Claude가 자동 실행:
python -m mypy pos_analyzer.py    # type-check
python -m pytest tests/           # test
python pos_analyzer.py            # 실제 실행
# → 정확히 5건 출력 확인 (이상 1·2·3·4·5)

막혔을 때: "이 에러 어디서 나는지 모르겠어, 체계적으로 디버깅" → systematic-debugging 자동 발동 (가설 3+ 수립 → 검증 → 근본 원인 확정).

6Phase 4 — REFACTOR (20분) | requesting-code-review + 외부 검수 팁

"이 코드 독립 컨텍스트에서 리뷰해줘" → requesting-code-review 활성화. 메인 세션과 분리된 코드 리뷰 에이전트가 자동 호출 — 작업한 사람이 자기 자신을 리뷰하는 함정 회피.

winget install --id OpenAI.Codex -e

7Phase 5 — SECURITY (10분) | /security-review

Anthropic 공식 슬래시 명령. 코드의 보안 취약점(CSV 파싱 — path traversal, 입력 검증, 의존성 보안 등) 자동 점검.

/security-review

# Claude가 자동 분석:
# - CSV path 파라미터 검증
# - 사용자 입력 sanitize
# - 의존성 CVE 점검
# - 결과 요약 + 수정 권장

7차시 | 조직 맞춤 스킬 토론·제작

1POS팀 업무 흐름 — 어떤 작업이 스킬이 되는가

스킬 후보의 핵심 조건은 "같은 양식·같은 절차로 매번 반복되는 작업". 회사 룰은 CLAUDE.md, 도메인 패턴은 SKILL.md입니다.

2SKILL.md 작성 가이드

두 부분으로 구성 — frontmatter(메타데이터)와 body(절차).

---
name: pos-anomaly-check
description: POS CSV 이상 5종 (STOCK 음수, SLS=0 PROM>0 등)을 elif chain으로
  검사하고 표로 보고. "이상 탐지", "anomaly", "POS 검사" 언급 시 자동 발동.
---

# POS Anomaly Check

## 입력
- pos_data.csv (SAP IBP 9컬럼)
- 검사 기간 (default: 최근 5주)

## 절차
1. CSV 로드 (UTF-8 BOM)
2. elif chain으로 5종 검사 (순서 — 중복 매칭 방지):
   ① STOCK < 0
   ② SLS == 0 AND PROM > 0
   ③ SLS > STOCK AND STOCK >= 0
   ④ DC_SLS == 0
   ⑤ PROM > SLS AND SLS > 0
3. 케이스별 row 정렬 + 표 출력
4. 발견 0건 시 "정상" 보고

## 출력 형식
- 발견 건수
- 카테고리별 row (timestamp · SKU · LOCATION)
- 후속 조치 제안

프론트매터 필수 필드:

• name — 스킬 식별자 (kebab-case)
• description — 자동 발동 트리거. AI가 이 텍스트만 보고 스킬 발동 판단

description은 "언제 발동하는지"가 명확해야 — "OO 언급 시 자동 발동" 같은 패턴 권장.

회사 환경 저장 위치 (GitHub Agent Skills 표준 — 파일 형식 양쪽 동일):

3그룹 토의 + SKILL.md 작성 (자유 그룹 3~4명) | 25분

3~4명 자유 그룹. 모르는 분들끼리도 OK. 아모레퍼시픽 + 도시바코리아 직원 시각으로:

1. 업무 인벤토리 (5분) — 우리 팀이 매주·매일 반복하는 작업 5개 나열
2. 스킬 후보 1개 선정 (5분) — 가장 시간이 많이 소요되는 작업
3. SKILL.md 작성 (15분) — frontmatter + 절차 + 출력 형식

4발표 + 상호 피드백 | 20분

조별로 작성한 SKILL.md를 자유롭게 공유하고, 다른 조의 아이디어를 듣습니다. 시간은 조 수에 맞춰 유연하게 — 깊이 있는 토론이 나오면 그쪽이 우선.

8차시 | QMD · LLM 위키 · 지식그래프 · AI-Ops 안내

1QMD 재정리 (어제 설치한 도구)

QMD (Quick Markdown DB)는 로컬 마크다운 폴더 전체를 임베딩·인덱싱해서 의미·키워드 검색을 즉시 제공하는 로컬 도구. 어제 1차시에 설치 완료. 본 강의에선 추후 활용법만 안내합니다.

추후 활용:

• 새 세션 시작 시 — "이전에 OO 관련 작업 있었나?" → qmd search로 자동 회상
• 중복 작업 방지 — 새 기획서 작성 전 유사 자료 검색
• 리서치 순서 — 사내 자료 1차 → 외부 검색 2차 (Tier 게이트)

2LLM 위키 — 자기 복제 운영 메모리

"RAG는 매번 검색해서 답을 만든다. LLM 위키는 지식이 쌓여서 답이 더 좋아진다." — Andrej Karpathy의 LLM Wiki 패턴.

3계층 구조 (Karpathy 패턴):

raw    — 불변 원자료 (대화 기록, 프로젝트 메모, 회고)
wiki   — AI 소유 마크다운 (요약 · 엔티티 · 상호 링크)
schema — 운영 규칙 (CLAUDE.md, lint 정책)

3가지 작업:

• ingest — 새 raw → wiki 페이지 · 엔티티 생성/갱신
• query — 위키만 읽고 답변 합성
• lint — 끊긴 링크 · 중복 개념 · 낡은 규칙 정리

핵심 원칙 — Gold In, Gold Out: "모으기만 하면 쓰레기통. 내 생각이 붙어야 지식이 됩니다." 목적 있는 수집만이 골드 데이터.

3무료 지식그래프 도구 8선 (학생 선택 가이드)

모두 오픈소스. LLM 호출 여부 · POS 환경 적합도 기준 비교:

4QMD 리서치 장점 (LLM 위키와의 연결)

QMD는 LLM 위키 운영의 인덱싱·검색 레이어. 위키를 쌓아도 빠르게 못 찾으면 무용지물. QMD가 그 검색을 1초로 제공합니다.

• 증분 인덱싱 — 새 파일 추가 시 변경분만 임베딩 (전체 재계산 X)
• 로컬 임베딩 — 사내 자료가 외부 API에 노출 X (보안)
• 스코어 게이트 — 0.9 이상 강한 매칭만 자동 회상 → 노이즈 차단
• 다국어 — bge-m3 모델이 한국어·영어 동시 처리

QMD 운영 흐름 — 새 자료 추가 → qmd update (인덱싱) → qmd search "쿼리" (검색). 회사 환경 적용 시 사내 위키·세션 로그·기획서 폴더를 대상으로 지정.

5전통 POS → AI-Ops 전환 5단계 로드맵

오늘 배운 5요소(CLAUDE.md · MCP · Skills · Hooks · Memory)를 POS 운영·개발 조직에 단계적으로 적용하면 어떤 변화가 가능한지.

POS 도메인 고려 사항:

• 결제 정확성 100% — AI 자동화는 보조 영역부터, 결제 본 함수는 사람 승인 후
• 24/7 영업 환경 — 배포 윈도우 제한, 점진적 롤아웃 필수
• 매장 네트워크 분산 — 단말 다양성 · 오프라인 대응 고려
• PCI-DSS 등 보안 규제 — 민감 정보 격리 · 로그 보존

다운로드

CSV 1개만 받으시면 됩니다. 모든 코드는 강사 시연 + 수강생이 본인 AI 도구(Copilot)에게 직접 생성 요청 — Phase 1·2 실습 본질.

• pos_data.csv
  SAP IBP 표준 9컬럼 · 205건 (정상 200 + 이상 5) · 5주 분량 · UTF-8 BOM (Excel 한글 호환)
  받기