Files
aio-01d4-stu/Lecture/FinalProject/Doc/agent-skills-final-project.html
T

669 lines
58 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Agent Skills로 최종 프로젝트 제대로 하기</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400..900&display=swap">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap">
<style>
section {
--ink: #121826;
--paper: #F6F4EE;
--paper2: #ECE7DC;
--accent: #D9692A;
--accent-text: #A94E16;
--accent-dark-text: #F2A46E;
--blue: #2B63C4;
--body: #3F4756;
--body-dark: #B9C2D3;
--line: #DCD4C3;
padding: 128px;
background: var(--paper);
color: var(--ink);
font-family: 'Noto Sans KR', 'Noto Sans CJK KR', Arial, sans-serif;
display: flex;
flex-direction: column;
box-sizing: border-box;
}
section.alt { background: var(--paper2); }
section.dark { background: var(--ink); color: #F3EFE6; }
.eyebrow { font-size: 24px; font-weight: 700; letter-spacing: 0.08em; color: var(--accent-text); margin: 0 0 16px; }
.dark .eyebrow { color: var(--accent-dark-text); }
.title { font-size: 60px; font-weight: 800; line-height: 1.18; margin: 0 0 48px; color: var(--ink); letter-spacing: -0.01em; }
.dark .title { color: #F3EFE6; }
.lead { font-size: 32px; line-height: 1.55; color: var(--body); margin: 0; }
.dark .lead { color: var(--body-dark); }
.note { font-size: 28px; line-height: 1.5; color: var(--body); margin: 0; }
.dark .note { color: var(--body-dark); }
.src { font-size: 24px; color: #6B7280; margin: 0; }
.dark .src { color: #8C97AB; }
.hl { color: var(--accent-text); font-weight: 700; }
.dark .hl { color: var(--accent-dark-text); }
.m { font-family: 'JetBrains Mono', 'Noto Sans KR', 'Noto Sans CJK KR', monospace; }
.row { display: flex; gap: 32px; }
.col { display: flex; flex-direction: column; gap: 24px; }
.grow { flex: 1; }
.push { margin-top: auto; }
.card { background: #FFFDF8; border: 2px solid var(--line); border-radius: 16px; padding: 32px; display: flex; flex-direction: column; gap: 12px; }
.alt .card { background: #FBF9F4; }
.dark .card { background: #1C2436; border-color: #2E3950; }
.card .card-title { font-size: 34px; font-weight: 800; line-height: 1.3; margin: 0; color: var(--ink); }
.dark .card .card-title { color: #F3EFE6; }
.card .card-text { font-size: 28px; line-height: 1.55; margin: 0; color: var(--body); }
.dark .card .card-text { color: var(--body-dark); }
.card .card-tag { font-size: 24px; font-weight: 700; margin: 0; color: var(--accent-text); }
.dark .card .card-tag { color: var(--accent-dark-text); }
.card .card-link { font-size: 28px; line-height: 1.5; margin: 0; color: var(--blue); font-weight: 600; }
.dark .card .card-link { color: #8DB4F5; }
.card.accent { border-color: var(--accent); }
.code { background: #0E131E; border-radius: 16px; padding: 32px 36px; display: flex; flex-direction: column; }
.code .ln { font-family: 'JetBrains Mono', 'Noto Sans KR', 'Noto Sans CJK KR', monospace; font-size: 26px; line-height: 1.6; color: #E9E4D8; margin: 0; white-space: pre; }
.code .cm { color: #8C97AB; }
.code .kw { color: #F2A46E; }
.code .st { color: #9CCB8B; }
.tbl { border-collapse: collapse; width: 100%; }
.tbl th { font-size: 26px; font-weight: 700; text-align: left; padding: 16px 20px; background: var(--ink); color: #F3EFE6; }
.tbl td { font-size: 28px; line-height: 1.45; padding: 14px 20px; border-bottom: 2px solid var(--line); vertical-align: top; color: var(--body); }
.tbl td.k { font-weight: 800; color: var(--ink); white-space: nowrap; }
.dark .tbl th { background: #2A3550; }
.dark .tbl td { border-bottom-color: #2E3950; color: var(--body-dark); }
.dark .tbl td.k { color: #F3EFE6; }
.stat { display: flex; flex-direction: column; gap: 8px; }
.stat .num { font-size: 96px; font-weight: 900; line-height: 1; margin: 0; color: var(--accent-dark-text); }
.stat .lbl { font-size: 32px; font-weight: 700; margin: 0; color: #F3EFE6; }
.stat .sub { font-size: 26px; margin: 0; color: var(--body-dark); }
.phase { flex: 1; border-radius: 16px; padding: 36px 24px; background: #FFFDF8; border: 2px solid var(--line); display: flex; flex-direction: column; gap: 10px; }
.phase .ph-en { font-size: 24px; font-weight: 800; letter-spacing: 0.08em; margin: 0; color: var(--accent-text); }
.phase .ph-ko { font-size: 44px; font-weight: 800; margin: 0; color: var(--ink); }
.phase .ph-cmd { font-family: 'JetBrains Mono', 'Noto Sans KR', 'Noto Sans CJK KR', monospace; font-size: 30px; font-weight: 600; margin: 0; color: var(--blue); }
.phase .ph-txt { font-size: 26px; line-height: 1.45; margin: 0; color: var(--body); }
.dark .phase { background: #1C2436; border-color: #2E3950; }
.dark .phase .ph-en { color: var(--accent-dark-text); }
.dark .phase .ph-ko { color: #F3EFE6; }
.dark .phase .ph-cmd { color: #8DB4F5; }
.dark .phase .ph-txt { color: var(--body-dark); }
.arrow { font-size: 40px; font-weight: 800; color: var(--accent); margin: 0; align-self: center; }
.numlist { display: flex; flex-direction: column; gap: 22px; }
.numitem { display: flex; gap: 28px; align-items: flex-start; }
.numitem .n { font-size: 44px; font-weight: 900; line-height: 1.1; color: var(--accent); margin: 0; width: 64px; flex: none; }
.numitem .t { font-size: 32px; font-weight: 800; line-height: 1.35; margin: 0; color: var(--ink); }
.numitem .d { font-size: 28px; line-height: 1.5; margin: 6px 0 0; color: var(--body); }
.dark .numitem .n { color: var(--accent-dark-text); }
.dark .numitem .t { color: #F3EFE6; }
.dark .numitem .d { color: var(--body-dark); }
.hero { font-size: 96px; font-weight: 900; line-height: 1.15; letter-spacing: -0.02em; margin: 0; color: #F3EFE6; }
.quote { font-size: 44px; font-weight: 800; line-height: 1.4; margin: 0; color: var(--ink); }
.bar { width: 120px; height: 10px; background: var(--accent); border-radius: 5px; }
@keyframes rise { from { opacity: 0; transform: translateY(24px); } }
.rise { animation: rise 0.6s cubic-bezier(0.2, 0.7, 0.2, 1) both; }
.d1 { animation-delay: 0.1s; }
.d2 { animation-delay: 0.2s; }
.d3 { animation-delay: 0.3s; }
.d4 { animation-delay: 0.4s; }
.d5 { animation-delay: 0.5s; }
.d6 { animation-delay: 0.6s; }
.tbl-sm th { font-size: 24px; }
.tbl-sm td { font-size: 24px; padding: 16px 20px; }
html, body { margin:0; background:#0B0F18; }
.deck section { width:1920px; height:1080px; position:relative; overflow:hidden; }
.deck section aside { display:none; }
.deck section h1, .deck section h2, .deck section h3, .deck section p, .deck section ul { margin-block-start:0; }
.deck section .push { margin-top:auto; }
@media screen {
body { overflow:hidden; height:100vh; }
.stage { position:fixed; inset:0; display:flex; align-items:center; justify-content:center; }
.deck { width:1920px; height:1080px; transform-origin:center center; position:relative; }
.deck section { position:absolute; inset:0; display:none; }
.deck section.on { display:flex; }
.hud { position:fixed; right:20px; bottom:16px; font:14px 'Noto Sans KR',sans-serif; color:#8C97AB; z-index:5; user-select:none; }
.hud button { background:#1C2436; color:#E9E4D8; border:1px solid #2E3950; border-radius:8px; padding:6px 12px; margin-left:6px; cursor:pointer; font:inherit; }
.notes { position:fixed; left:0; right:0; bottom:0; max-height:30vh; overflow:auto; background:rgba(14,19,30,.96); color:#E9E4D8; font:18px/1.6 'Noto Sans KR',sans-serif; padding:18px 28px 52px; display:none; z-index:4; }
.notes.show { display:block; }
}
@media print {
@page { size:1920px 1080px; margin:0; }
html, body { background:none; }
.hud, .notes { display:none !important; }
.deck section { display:flex !important; break-after:page; page-break-after:always; }
.deck section * { animation:none !important; }
}
</style>
</head>
<body>
<div class="stage"><div class="deck" id="deck">
<section id="cover" class="dark" data-transition="fade">
<p class="eyebrow rise">AIO 1기 · 최종 프로젝트 특강</p>
<h1 class="hero rise d1" style="margin-top:120px">Agent Skills로<br>최종 프로젝트 제대로 하기</h1>
<div class="bar rise d2" style="margin-top:56px"></div>
<p class="lead rise d3" style="margin-top:40px;width:1300px">addyosmani/agent-skills — 시니어 엔지니어의 작업 순서를 AI 코딩 에이전트에 입히는 방법</p>
<p class="src push">2026년 11월 · 출처: github.com/addyosmani/agent-skills</p>
<aside>오늘은 바이브 코딩을 ‘제대로’ 하기 위한 도구 하나를 소개합니다. Google의 Addy Osmani가 공개한 agent-skills입니다. 핵심은 새로운 기술이 아니라, AI 에이전트가 스펙·테스트·리뷰를 건너뛰지 못하게 하는 작업 절차입니다. 최종 프로젝트 5단계 산출물과 어떻게 연결되는지에 집중해서 보겠습니다.</aside>
</section>
<section id="problem">
<p class="eyebrow">왜 필요한가</p>
<h2 class="title">AI 코딩 에이전트는 가장 짧은 길로 ‘완료’합니다</h2>
<div class="row">
<div class="card grow rise d1"><p class="card-tag">빠뜨리는 것 ①</p><h3 class="card-title">스펙 없이 바로 코딩</h3><p class="card-text">요구사항 명세(FR/NFR)와 실제 구현이 따로 놀고, 발표 Q&amp;A에서 “왜 이렇게 만들었나”에 답하지 못합니다.</p></div>
<div class="card grow rise d2"><p class="card-tag">빠뜨리는 것 ②</p><h3 class="card-title">테스트는 “나중에”</h3><p class="card-text">Auto-Healing 시연과 통합 테스트 결과서를 쓸 때가 되어서야 깨진 곳이 한꺼번에 드러납니다.</p></div>
<div class="card grow rise d3"><p class="card-tag">빠뜨리는 것 ③</p><h3 class="card-title">리뷰·보안 점검 생략</h3><p class="card-text">API 키가 커밋되고, 승인 없이 위험한 도구가 실행되는 경로가 그대로 남습니다.</p></div>
</div>
<div class="card accent push rise d4" style="flex-direction:row;align-items:center;gap:32px"><p class="quote" style="font-size:36px">agent-skills는 이 빠진 단계를 에이전트가 <span class="hl">반드시 밟도록</span> 강제하는 워크플로우 모음입니다.</p></div>
<aside>Addy Osmani가 저장소와 블로그에서 밝힌 문제의식입니다. 에이전트는 기능은 만들지만 시니어가 당연히 하는 스펙, 테스트, 리뷰, 범위 관리를 건너뜁니다. 우리 평가 기준이 ‘문서 존재’가 아니라 ‘설계·구현·검증의 연결’이라는 점과 정확히 맞닿아 있습니다.</aside>
</section>
<section id="glance" class="dark">
<p class="eyebrow">한눈에 보기</p>
<h2 class="title">addyosmani/agent-skills 구성</h2>
<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:56px 48px">
<div class="stat rise d1"><p class="num">25</p><p class="lbl">스킬</p><p class="sub">생명주기 스킬 24개 + 라우팅 메타 스킬 1개</p></div>
<div class="stat rise d2"><p class="num">9</p><p class="lbl">슬래시 커맨드</p><p class="sub">/spec /plan /build /test /review /ship 등</p></div>
<div class="stat rise d3"><p class="num">4</p><p class="lbl">전문가 페르소나</p><p class="sub">코드 리뷰어 · 테스트 엔지니어 · 보안 감사 · 웹 성능 감사</p></div>
<div class="stat rise d4"><p class="num">70+</p><p class="lbl">지원 에이전트</p><p class="sub">Claude Code · Codex · Gemini CLI · Cursor · Copilot 등</p></div>
<div class="stat rise d5"><p class="num">MIT</p><p class="lbl">라이선스</p><p class="sub">자유롭게 복사·수정해 팀 전용으로 바꿔 쓸 수 있음</p></div>
<div class="stat rise d6"><p class="num">11.7만</p><p class="lbl">GitHub 스타</p><p class="sub">2026년 11월 기준, 포크 1.2만</p></div>
</div>
<p class="src push">출처: github.com/addyosmani/agent-skills README (2026-11-18 확인)</p>
<aside>숫자는 오늘 저장소에서 확인한 값입니다. 초기에는 스킬 19개, 커맨드 7개였는데 계속 늘어났습니다. 블로그나 다른 글에서 개수가 다르게 나오는 건 버전 차이 때문입니다. MIT 라이선스라서 팀 상황에 맞게 고쳐 쓰는 것이 오히려 권장됩니다.</aside>
</section>
<section id="what-skill">
<p class="eyebrow">스킬이란</p>
<h2 class="title">스킬 = 읽는 문서가 아니라 실행하는 절차</h2>
<div class="row grow">
<div class="col" style="width:640px;flex:none">
<div class="code rise d1">
<p class="ln"><span class="kw">skills/</span></p>
<p class="ln"> spec-driven-development/</p>
<p class="ln"> SKILL.md <span class="cm"># 진입점</span></p>
<p class="ln"><span class="kw">references/</span> <span class="cm"># 필요할 때만</span></p>
<p class="ln"><span class="kw">agents/</span> <span class="cm"># 페르소나</span></p>
</div>
<p class="note">SKILL.md는 frontmatter(이름·언제 쓰는지) + 단계별 절차 + 체크포인트 + 종료 조건으로 된 마크다운 파일입니다.</p>
</div>
<div style="display:grid;grid-template-columns:1fr 1fr;gap:24px;flex:1">
<div class="card rise d2"><p class="card-tag">Process, not prose</p><h3 class="card-title">절차형</h3><p class="card-text">설명문이 아니라 체크포인트와 종료 조건이 있는 단계별 워크플로우</p></div>
<div class="card rise d3"><p class="card-tag">Anti-rationalization</p><h3 class="card-title">핑계 차단표</h3><p class="card-text">에이전트가 단계를 건너뛸 때 대는 핑계와 반박을 미리 적어 둠</p></div>
<div class="card rise d4"><p class="card-tag">Verification</p><h3 class="card-title">증거로 끝남</h3><p class="card-text">통과한 테스트, 빌드 출력, 런타임 데이터 없이는 ‘완료’가 아님</p></div>
<div class="card rise d5"><p class="card-tag">Progressive disclosure</p><h3 class="card-title">필요한 것만 로드</h3><p class="card-text">메타 스킬이 지금 단계에 맞는 스킬만 불러와 컨텍스트를 아낌</p></div>
</div>
</div>
<aside>Osmani는 에세이형 가이드는 읽히고 무시되지만 단계형 워크플로우는 실행된다고 말합니다. 네 가지 원칙 중 수업에서 특히 강조할 것은 ‘증거로 끝남’입니다. 에이전트가 “다 됐습니다”라고 말하는 것만으로는 완료가 아닙니다.</aside>
</section>
<section id="lifecycle" class="alt">
<p class="eyebrow">워크플로우</p>
<h2 class="title">6단계 생명주기와 슬래시 커맨드</h2>
<div class="row" style="gap:12px;align-items:stretch">
<div class="phase rise d1"><p class="ph-en">DEFINE</p><p class="ph-ko">정의</p><p class="ph-cmd">/spec</p><p class="ph-txt">코드보다 스펙 먼저</p></div>
<p class="arrow">›</p>
<div class="phase rise d2"><p class="ph-en">PLAN</p><p class="ph-ko">계획</p><p class="ph-cmd">/plan</p><p class="ph-txt">작고 원자적인 작업</p></div>
<p class="arrow">›</p>
<div class="phase rise d3"><p class="ph-en">BUILD</p><p class="ph-ko">구현</p><p class="ph-cmd">/build</p><p class="ph-txt">한 번에 한 조각</p></div>
<p class="arrow">›</p>
<div class="phase rise d4"><p class="ph-en">VERIFY</p><p class="ph-ko">검증</p><p class="ph-cmd">/test</p><p class="ph-txt">테스트가 증거</p></div>
<p class="arrow">›</p>
<div class="phase rise d5"><p class="ph-en">REVIEW</p><p class="ph-ko">리뷰</p><p class="ph-cmd">/review</p><p class="ph-txt">코드 건강 개선</p></div>
<p class="arrow">›</p>
<div class="phase rise d6"><p class="ph-en">SHIP</p><p class="ph-ko">배포</p><p class="ph-cmd">/ship</p><p class="ph-txt">빠를수록 안전</p></div>
</div>
<div style="display:grid;grid-template-columns:1fr 1fr;gap:20px 48px;margin-top:56px">
<p class="note"><span class="m hl">/constraints</span> 품질 기준을 한 번 정하고 끝까지 강제</p>
<p class="note"><span class="m hl">/code-simplify</span> 영리함보다 명료함</p>
<p class="note"><span class="m hl">/webperf</span> 최적화 전에 먼저 측정</p>
<p class="note"><span class="m hl">/build auto</span> 계획 1회 승인 → 작업별 테스트·커밋 자동, 실패·위험 단계에선 멈춤</p>
</div>
<p class="note push">Claude Code에서는 <span class="m">/review</span>가 내장 명령과 겹치므로 <span class="m hl">/agent-skills:review</span>로 호출합니다. 커맨드 없이도 작업 내용에 따라 스킬이 자동 활성화됩니다.</p>
<aside>여섯 개 커맨드가 그대로 개발 순서입니다. 보조 커맨드 중 /constraints는 팀 품질 기준을 CONSTRAINTS.md로 고정하고, 에이전트가 검사를 끄거나 테스트를 건너뛰는 것을 잡아냅니다. /build auto는 편하지만, 처음에는 한 조각씩 직접 확인하는 것을 권합니다.</aside>
</section>
<section id="catalog">
<p class="eyebrow">스킬 카탈로그</p>
<h2 class="title" style="margin-bottom:32px">단계별 24개 스킬 — <span class="hl">굵은 글씨</span>가 최종 프로젝트 핵심</h2>
<table class="tbl">
<tr><th style="width:160px">단계</th><th>스킬</th></tr>
<tr><td class="k">정의</td><td class="m">interview-me · idea-refine · <b>spec-driven-development</b> · <b>constraint-driven-development</b></td></tr>
<tr><td class="k">계획</td><td class="m"><b>planning-and-task-breakdown</b></td></tr>
<tr><td class="k">구현</td><td class="m"><b>incremental-implementation</b> · <b>test-driven-development</b> · <b>context-engineering</b> · <b>source-driven-development</b> · doubt-driven-development · frontend-ui-engineering · <b>api-and-interface-design</b></td></tr>
<tr><td class="k">검증</td><td class="m">browser-testing-with-devtools · <b>debugging-and-error-recovery</b></td></tr>
<tr><td class="k">리뷰</td><td class="m"><b>code-review-and-quality</b> · code-simplification · <b>security-and-hardening</b> · performance-optimization</td></tr>
<tr><td class="k">배포</td><td class="m"><b>git-workflow-and-versioning</b> · <b>ci-cd-and-automation</b> · deprecation-and-migration · <b>documentation-and-adrs</b> · <b>observability-and-instrumentation</b> · shipping-and-launch</td></tr>
</table>
<p class="note push">+ 메타 스킬 <span class="m">using-agent-skills</span>: 들어온 작업을 알맞은 스킬로 연결하고 공통 규칙(요청받은 것만 건드린다 등)을 정의</p>
<aside>전부 외울 필요는 없습니다. 굵게 표시한 것이 우리 프로젝트 STEP 1~5에 직접 연결되는 스킬입니다. 프론트엔드나 웹 성능 쪽 스킬은 UI 담당자만 선택적으로 쓰면 됩니다.</aside>
</section>
<section id="install" class="dark">
<p class="eyebrow">설치</p>
<h2 class="title" style="margin-bottom:36px">설치 — 한눈에 보기 (도구별 자세한 사용법은 다음 장)</h2>
<div class="code rise d1">
<p class="ln"><span class="cm"># Claude Code (권장)</span></p>
<p class="ln">/plugin marketplace add addyosmani/agent-skills</p>
<p class="ln">/plugin install agent-skills@addy-agent-skills</p>
<p class="ln"><span class="cm"># Codex CLI (v0.122+)</span></p>
<p class="ln">codex plugin marketplace add addyosmani/agent-skills</p>
<p class="ln"><span class="cm"># Antigravity CLI</span></p>
<p class="ln">agy plugin install https://github.com/addyosmani/agent-skills.git</p>
</div>
<div class="row push" style="gap:24px">
<div class="card grow rise d2"><h3 class="card-title" style="font-size:32px">SSH 오류가 나면</h3><p class="card-text">marketplace add에 HTTPS 주소(…/agent-skills.git)를 넣기</p></div>
<div class="card grow rise d3"><h3 class="card-title" style="font-size:32px">Cursor · Gemini</h3><p class="card-text">Cursor는 .cursor/skills/에 복사, Gemini CLI는 gemini skills install</p></div>
<div class="card grow rise d4"><h3 class="card-title" style="font-size:32px">저장소 전체 설치</h3><p class="card-text">스킬 하나씩 npx로 깔면 공용 references/가 빠짐</p></div>
<div class="card grow rise d5"><h3 class="card-title" style="font-size:32px">설치 후 확인</h3><p class="card-text">/help로 /spec 등이 보이는지 먼저 확인</p></div>
</div>
<aside>팀 안에서 도구가 섞여도 괜찮지만, 설치 방식은 README 대로 통일하세요. 실제 사용 후기 중에는 설치 직후 커맨드가 보이지 않아 에이전트에게 커맨드를 프로젝트로 복사하라고 한 번 더 요청해야 했던 사례가 있습니다. 그래서 /help 확인을 첫 단계로 넣었습니다.</aside>
</section>
<section id="tool-claude">
<p class="eyebrow">도구별 사용법 ① · Claude Code</p>
<h2 class="title" style="margin-bottom:36px">플러그인으로 설치하고, 슬래시 커맨드로 단계를 진행</h2>
<div class="code rise d1">
<p class="ln"><span class="cm"># 1. 설치 — Claude Code 세션 안에서 입력</span></p>
<p class="ln">/plugin marketplace add addyosmani/agent-skills</p>
<p class="ln">/plugin install agent-skills@addy-agent-skills</p>
<p class="ln"><span class="cm"># 2. 확인 → 3. 단계별 실행</span></p>
<p class="ln">/help</p>
<p class="ln"><span class="kw">/spec</span> → <span class="kw">/plan</span> → <span class="kw">/build</span> → <span class="kw">/test</span> → <span class="kw">/agent-skills:review</span> → <span class="kw">/ship</span></p>
</div>
<div class="row push" style="gap:24px">
<div class="card grow rise d2"><h3 class="card-title" style="font-size:32px">/review 충돌</h3><p class="card-text">내장 /review와 겹치므로 /agent-skills:review로 호출</p></div>
<div class="card grow rise d3"><h3 class="card-title" style="font-size:32px">자동 활성화</h3><p class="card-text">커맨드 없이 “API 설계해줘”라고 해도 맞는 스킬이 붙음</p></div>
<div class="card grow rise d4"><h3 class="card-title" style="font-size:32px">페르소나</h3><p class="card-text">code-reviewer · test-engineer · security-auditor를 서브에이전트로 지정</p></div>
<div class="card grow rise d5"><h3 class="card-title" style="font-size:32px">CLAUDE.md</h3><p class="card-text">“커밋 전 pytest”, “스펙 승인 전 코딩 금지” 같은 팀 규칙</p></div>
</div>
<aside>Claude Code가 가장 완성도 높은 경로입니다. 플러그인에 슬래시 커맨드, 페르소나, 훅이 함께 들어 있습니다. 설치 직후 /help로 /spec 등이 보이는지 꼭 확인하세요. 로컬 클론으로 시험하려면 claude --plugin-dir 경로 옵션을 씁니다. 페르소나는 “security-auditor 서브에이전트로 이 PR 점검해줘”처럼 부르면 됩니다.</aside>
</section>
<section id="tool-codex" class="dark">
<p class="eyebrow">도구별 사용법 ② · Codex CLI</p>
<h2 class="title" style="margin-bottom:36px">플러그인으로 설치하고, <span class="m">@스킬이름</span>으로 호출</h2>
<div class="code rise d1">
<p class="ln"><span class="cm"># 1. 설치 — 터미널에서 (Codex CLI v0.122 이상)</span></p>
<p class="ln">codex plugin marketplace add addyosmani/agent-skills</p>
<p class="ln">codex plugin add agent-skills@agent-skills</p>
<p class="ln"><span class="cm"># 2. 새 Codex 세션을 열고 채팅에서 @로 호출</span></p>
<p class="ln"><span class="kw">@spec-driven-development</span> InfraCare AI 스펙을 써줘</p>
<p class="ln"><span class="kw">@planning-and-task-breakdown</span> 승인된 스펙으로 작업 분해</p>
<p class="ln"><span class="kw">@test-driven-development</span> T04부터 실패하는 테스트 먼저</p>
</div>
<div class="row push" style="gap:24px">
<div class="card grow rise d2"><h3 class="card-title" style="font-size:32px">슬래시 커맨드 없음</h3><p class="card-text">/spec 대신 @spec-driven-development가 공식 권장 방법</p></div>
<div class="card grow rise d3"><h3 class="card-title" style="font-size:32px">자동 선택</h3><p class="card-text">작업만 설명해도 Codex가 맞는 스킬을 고름</p></div>
<div class="card grow rise d4"><h3 class="card-title" style="font-size:32px">AGENTS.md</h3><p class="card-text">저장소 루트의 팀 규칙을 작업 전에 먼저 읽음</p></div>
<div class="card grow rise d5"><h3 class="card-title" style="font-size:32px">새 세션 필수</h3><p class="card-text">설치 후 세션을 새로 열어야 스킬이 인식됨</p></div>
</div>
<aside>Codex는 저장소 루트의 skills 폴더를 플러그인으로 그대로 읽습니다. 구버전에서는 codex marketplace add였으니 버전을 먼저 확인하세요. Codex에서 /spec이 안 된다는 질문이 GitHub 이슈로도 올라왔고, 답은 @spec-driven-development처럼 스킬 이름으로 부르는 것입니다. 팀 공통 규칙은 AGENTS.md에 적어 두세요.</aside>
</section>
<section id="tool-agy" class="alt">
<p class="eyebrow">도구별 사용법 ③ · Antigravity CLI (agy)</p>
<h2 class="title" style="margin-bottom:36px">agy 플러그인으로 설치하고, <span class="m">/agent-skills:스킬이름</span>으로 호출</h2>
<div class="code rise d1">
<p class="ln"><span class="cm"># 1. 설치 (Gemini CLI에 이미 깔았다면: agy plugin import gemini)</span></p>
<p class="ln">agy plugin install https://github.com/addyosmani/agent-skills.git</p>
<p class="ln"><span class="cm"># 2. 확인</span></p>
<p class="ln">agy plugin list</p>
<p class="ln"><span class="cm"># 3. 새 세션에서 /agent-skills: 를 입력하면 스킬 목록이 뜸</span></p>
<p class="ln"><span class="kw">/agent-skills:spec-driven-development</span></p>
<p class="ln"><span class="kw">/agent-skills:code-review-and-quality</span></p>
</div>
<div class="row push" style="gap:24px">
<div class="card grow rise d2"><h3 class="card-title" style="font-size:32px">/build가 안 될 때</h3><p class="card-text">짧은 커맨드가 “No matches”면 알려진 제한 → 스킬 이름으로 호출</p></div>
<div class="card grow rise d3"><h3 class="card-title" style="font-size:32px">페르소나</h3><p class="card-text">code-reviewer 등 서브에이전트가 등록됨, /agents에서 선택</p></div>
<div class="card grow rise d4"><h3 class="card-title" style="font-size:32px">AGENTS.md</h3><p class="card-text">작업 공간 루트에 두면 팀 계획 규칙을 따름</p></div>
<div class="card grow rise d5"><h3 class="card-title" style="font-size:32px">안전하게</h3><p class="card-text">agy --sandbox로 실행, 커밋 전 Ctrl+r로 변경 검토</p></div>
</div>
<aside>설치 위치는 ~/.gemini/config/plugins/agent-skills/입니다. agy 1.1.x 일부 버전에서는 /build 같은 짧은 커맨드가 보이지 않는데, 재설치로는 해결되지 않으니 /agent-skills: 뒤에 스킬 이름을 붙여 부르세요. --dangerously-skip-permissions 옵션은 승인을 건너뛰므로 실습 프로젝트에서는 쓰지 않는 것을 권합니다.</aside>
</section>
<section id="tool-cheatsheet">
<p class="eyebrow">도구별 사용법 · 한 장 정리</p>
<h2 class="title" style="margin-bottom:36px">같은 단계, 도구별 호출법</h2>
<table class="tbl tbl-sm">
<tr><th style="width:150px">단계</th><th style="width:300px">Claude Code</th><th style="width:500px">Codex CLI</th><th>Antigravity CLI</th></tr>
<tr><td class="k">정의</td><td class="m">/spec</td><td class="m">@spec-driven-development</td><td class="m">/agent-skills:spec-driven-development</td></tr>
<tr><td class="k">계획</td><td class="m">/plan</td><td class="m">@planning-and-task-breakdown</td><td class="m">/agent-skills:planning-and-task-breakdown</td></tr>
<tr><td class="k">구현</td><td class="m">/build</td><td class="m">@incremental-implementation</td><td class="m">/agent-skills:incremental-implementation</td></tr>
<tr><td class="k">검증</td><td class="m">/test</td><td class="m">@test-driven-development</td><td class="m">/agent-skills:test-driven-development</td></tr>
<tr><td class="k">리뷰</td><td class="m">/agent-skills:review</td><td class="m">@code-review-and-quality</td><td class="m">/agent-skills:code-review-and-quality</td></tr>
<tr><td class="k">배포</td><td class="m">/ship</td><td class="m">@shipping-and-launch</td><td class="m">/agent-skills:shipping-and-launch</td></tr>
</table>
<div class="card accent push"><p class="card-text" style="font-size:28px;color:var(--ink)">팀원마다 도구가 달라도 <b>같은 스킬</b>을 부르면 같은 절차가 돌아갑니다. 어느 도구든 이름이 기억나지 않으면 “follow spec-driven-development”처럼 말로 지시해도 됩니다.</p></div>
<aside>Codex와 Antigravity에는 Claude Code의 짧은 커맨드가 없거나 일부 버전에서 보이지 않습니다. 그래서 커맨드가 내부적으로 부르는 스킬 이름을 직접 쓰는 표입니다. /ship은 Claude Code에서 여러 페르소나를 함께 돌리지만, 다른 도구에서는 shipping-and-launch를 부른 뒤 페르소나를 따로 호출하세요.</aside>
</section>
<section id="mapping">
<p class="eyebrow">우리 프로젝트에 적용</p>
<h2 class="title" style="margin-bottom:32px">최종 프로젝트 5단계에 그대로 얹기</h2>
<table class="tbl">
<tr><th style="width:330px">단계</th><th style="width:640px">필수 산출물</th><th>쓰는 커맨드 · 스킬</th></tr>
<tr><td class="k">STEP 1 기획·설계</td><td>기획서(요구사항 명세), WBS</td><td class="m">/spec · interview-me · /plan</td></tr>
<tr><td class="k">STEP 2 API·FC</td><td>API 설계 문서, DB 스키마 설계서</td><td class="m">api-and-interface-design · /build · /test</td></tr>
<tr><td class="k">STEP 3 단일 에이전트</td><td>상태 전이 그래프 설계서, 자기 성찰 테스트 결과서</td><td class="m">context-engineering · source-driven · TDD</td></tr>
<tr><td class="k">STEP 4 협업·Healing</td><td>협업 아키텍처, AI 보안 가드레일, Auto-Healing 결과서</td><td class="m">debugging · security-and-hardening · doubt-driven</td></tr>
<tr><td class="k">STEP 5 최적화·배포</td><td>대화형 AI 웹 앱, 통합 테스트 결과서, 배포 아키텍처</td><td class="m">ci-cd · observability · /ship</td></tr>
</table>
<div class="card accent push"><p class="card-text" style="font-size:28px;color:var(--ink)">평가는 문서의 존재가 아니라 <b>설계 · 구현 · 검증의 연결</b>을 봅니다. 스킬을 쓰면 그 연결이 저장소 안에 <span class="hl">spec.md → tasks/todo.md → 테스트 → 리뷰 기록</span>으로 남습니다.</p></div>
<aside>매니저 가이드의 STEP 1~5 산출물 표에 스킬을 붙인 것입니다. 스킬이 산출물 문서를 대신 써 주는 건 아닙니다. 대신 문서에 들어갈 근거, 즉 승인된 스펙, 작업 목록, 테스트 결과, 리뷰 기록이 자연스럽게 쌓입니다.</aside>
</section>
<section id="spec" class="alt">
<p class="eyebrow">STEP 1 · 기획·설계</p>
<h2 class="title" style="margin-bottom:36px"><span class="m">/spec</span> — 코드 전에 PRD부터</h2>
<div class="row grow">
<div class="col" style="width:900px;flex:none">
<p class="note"><b>프롬프트 예시</b> (주요산출물 문서의 교육용 예시 서비스)</p>
<div class="code rise d1">
<p class="ln"><span class="kw">/spec</span></p>
<p class="ln">InfraCare AI: IT 운영자가 장애 접수→진단→</p>
<p class="ln">승인→복구→검증을 한 화면에서 처리하는</p>
<p class="ln">멀티 에이전트 서비스.</p>
<p class="ln">스택: FastAPI · LangGraph · Supabase · AWS</p>
<p class="ln">MVP: 장애 목록, AI 진단, 복구 승인, 이력</p>
<p class="ln">요구사항은 FR-xx / NFR-xx ID로 정리해줘.</p>
</div>
</div>
<div class="col grow">
<div class="card rise d2"><h3 class="card-title" style="font-size:32px">스펙의 6개 핵심 영역</h3><p class="card-text">목표 · 명령어 · 프로젝트 구조 · 코드 스타일 · 테스트 전략 · 경계(Boundaries)</p></div>
<div class="card rise d3"><h3 class="card-title" style="font-size:32px">경계는 3단계로</h3><p class="card-text"><b>Always</b> 커밋 전 pytest 실행<br><b>Ask First</b> DB 스키마 변경, 의존성 추가<br><b>Never</b> .env·API 키 커밋, 승인 없는 복구 실행</p></div>
</div>
</div>
<div class="card accent" style="margin-top:32px"><p class="card-text"><b>PRD</b> (Product Requirements Document, 제품 요구사항 문서) — 무엇을, 누구를 위해, 왜 만드는지와 ‘완료’의 기준을 코드보다 먼저 정리한 문서입니다. 우리 과정의 <b>기획서(요구사항 명세 포함)</b>에 해당합니다.</p></div>
<aside>/spec은 코드를 한 줄도 쓰기 전에 짧은 PRD를 씁니다. 공식 가이드는 이것을 가장 효과가 큰 습관이라고 부릅니다. 경계 3단계는 그대로 STEP 4 보안 가드레일 문서의 출발점이 됩니다. 범위가 모호하면 interview-me 스킬로 한 번에 한 질문씩 요구사항을 끌어내게 하세요.</aside>
</section>
<section id="gates" class="dark">
<p class="eyebrow">STEP 1 · 승인 게이트</p>
<h2 class="title">스펙은 ‘쓰고 바로 코딩’이 아니라 ‘승인 후 다음 단계’</h2>
<div class="row" style="gap:12px;align-items:stretch">
<div class="phase rise d1"><p class="ph-en">PHASE 0</p><p class="ph-ko" style="font-size:32px">범위 점검</p><p class="ph-txt">기능이 여러 개 묶였으면 모듈 지도부터 승인</p></div>
<p class="arrow">›</p>
<div class="phase rise d2"><p class="ph-en">PHASE 1</p><p class="ph-ko" style="font-size:32px">명세</p><p class="ph-txt">가정 목록과 스펙 작성 후 <b>멈추고</b> 승인 요청</p></div>
<p class="arrow">›</p>
<div class="phase rise d3"><p class="ph-en">PHASE 2</p><p class="ph-ko" style="font-size:32px">계획</p><p class="ph-txt m">tasks/plan.md</p></div>
<p class="arrow">›</p>
<div class="phase rise d4"><p class="ph-en">PHASE 3</p><p class="ph-ko" style="font-size:32px">작업</p><p class="ph-txt m">tasks/todo.md</p></div>
<p class="arrow">›</p>
<div class="phase rise d5"><p class="ph-en">PHASE 4</p><p class="ph-ko" style="font-size:32px">구현</p><p class="ph-txt">한 번에 한 작업씩</p></div>
</div>
<div class="row push" style="gap:32px">
<div class="card grow"><p class="card-tag">팀 운영 팁</p><p class="card-text">승인 = 팀장 + 담당자가 PR로 <span class="m">docs/spec.md</span>를 머지. 이것이 기획서 v1.0의 근거입니다.</p></div>
<div class="card grow"><p class="card-tag">살아있는 문서</p><p class="card-text">범위가 바뀌면 스펙부터 고쳐 커밋하고, PR에서 해당 스펙을 참조합니다.</p></div>
<div class="card grow"><p class="card-tag">위험 신호</p><p class="card-text">스펙을 쓴 같은 턴에 계획이나 코드까지 시작했다면 멈추세요.</p></div>
</div>
<aside>spec-driven-development 스킬은 각 단계마다 사람의 검토 게이트를 둡니다. 특히 스펙은 쓴 턴이 아니라 다음 턴에 승인받아야 한다고 명시합니다. 에이전트가 스펙을 쓰자마자 코딩으로 넘어가면 스킬이 제대로 동작하지 않는 것입니다.</aside>
</section>
<section id="plan">
<p class="eyebrow">STEP 1 · 작업 분해</p>
<h2 class="title" style="margin-bottom:36px"><span class="m">/plan</span> — WBS가 저절로 나오는 작업 목록</h2>
<div class="row grow">
<div class="code rise d1" style="width:1020px;flex:none">
<p class="ln"><span class="kw">## T03 진단 Agent 노드 구현</span></p>
<p class="ln">- 담당: AI / 선행: T02</p>
<p class="ln">- 수용 기준: 장애 ID → 원인·근거 로그·신뢰도 반환</p>
<p class="ln">- 검증: pytest tests/test_diagnosis.py 통과</p>
<p class="ln">- 파일: app/agents/diagnosis.py</p>
<p class="ln"> </p>
<p class="ln"><span class="kw">## T04 복구 승인 가드 (FR-03)</span></p>
<p class="ln">- 수용 기준: approval_id 없으면 403</p>
<p class="ln"> APPROVAL_REQUIRED</p>
<p class="ln">- 검증: test_recover_requires_approval</p>
</div>
<div class="col grow">
<div class="card rise d2"><h3 class="card-title" style="font-size:32px">WBS 표를 그대로 채움</h3><p class="card-text">ID · 담당 · 선행 · 산출물 열이 이미 들어 있습니다.</p></div>
<div class="card rise d3"><h3 class="card-title" style="font-size:32px">일일 기록이 쉬워짐</h3><p class="card-text">대시보드에는 “오늘 끝낸 T번호 + 검증 결과”만 적으면 됩니다.</p></div>
<div class="card rise d4"><h3 class="card-title" style="font-size:32px">한 작업 = 하루 이내</h3><p class="card-text">넘으면 다시 쪼갭니다.</p></div>
</div>
</div>
<aside>planning-and-task-breakdown 스킬은 각 작업에 수용 기준, 검증 단계, 파일 목록을 붙이고 의존 순서대로 정렬합니다. 이 형식이 우리 WBS 템플릿의 작업 계획표와 거의 같습니다. 대시보드 일일 기록과 연결하면 강사 피드백도 T번호 단위로 줄 수 있습니다.</aside>
</section>
<section id="build" class="alt">
<p class="eyebrow">STEP 2~3 · 구현과 검증</p>
<h2 class="title" style="margin-bottom:36px"><span class="m">/build</span> + <span class="m">/test</span> — 얇은 수직 조각, 테스트 먼저</h2>
<div class="row grow">
<div class="col" style="width:520px;flex:none">
<div class="card rise d1"><p class="card-tag">1 · RED</p><p class="card-text">실패하는 테스트를 쓰고 실제로 실패하는 것을 확인</p></div>
<div class="card rise d2"><p class="card-tag">2 · GREEN</p><p class="card-text">통과할 만큼만 최소한의 코드를 작성</p></div>
<div class="card rise d3"><p class="card-tag">3 · REFACTOR</p><p class="card-text">정리한 뒤 다시 통과 확인 → 작업 단위로 커밋</p></div>
</div>
<div class="col grow">
<div class="code rise d2">
<p class="ln"><span class="kw">def</span> test_recover_requires_approval(client, token):</p>
<p class="ln"> res = client.post(</p>
<p class="ln"> <span class="st">"/api/incidents/INC-104/recover"</span>,</p>
<p class="ln"> json={<span class="st">"strategy"</span>: <span class="st">"restart"</span>},</p>
<p class="ln"> headers={<span class="st">"Authorization"</span>: <span class="kw">f</span><span class="st">"Bearer {token}"</span>},</p>
<p class="ln"> )</p>
<p class="ln"> <span class="kw">assert</span> res.status_code == 403</p>
<p class="ln"> <span class="kw">assert</span> res.json()[<span class="st">"error"</span>][<span class="st">"code"</span>] \</p>
<p class="ln"> == <span class="st">"APPROVAL_REQUIRED"</span></p>
</div>
<p class="note">한 조각 = 라우터 + 서비스 + 테스트 + 커밋. 테스트 비율은 단위 80 / 통합 15 / E2E 5를 기준으로 삼습니다.</p>
</div>
</div>
<aside>incremental-implementation과 test-driven-development 스킬의 핵심입니다. 큰 기능을 한 번에 만들지 말고, 끝에서 끝까지 동작하는 얇은 조각을 하나씩 완성하고 커밋합니다. 예시는 주요산출물 문서의 복구 API 명세(승인 없으면 403)를 그대로 테스트로 옮긴 것입니다.</aside>
</section>
<section id="agents" class="dark">
<p class="eyebrow">STEP 3~4 · 에이전트와 Auto-Healing</p>
<h2 class="title" style="margin-bottom:40px">LangGraph 에이전트 단계에서 꺼내 쓰는 스킬</h2>
<div style="display:grid;grid-template-columns:1fr 1fr;gap:28px">
<div class="card rise d1"><p class="card-tag m">debugging-and-error-recovery</p><h3 class="card-title" style="font-size:32px">재현 → 위치 특정 → 축소 → 수정 → 재발 방지</h3><p class="card-link">→ Auto-Healing 결과서의 장애 주입·감지·복구·검증 로그 구조로 그대로 사용</p></div>
<div class="card rise d2"><p class="card-tag m">security-and-hardening</p><h3 class="card-title" style="font-size:32px">OWASP Top 10 · 시크릿 관리 · 3단계 경계</h3><p class="card-link">→ AI 보안 가드레일: 프롬프트 인젝션, 도구 권한, 승인 게이트 점검</p></div>
<div class="card rise d3"><p class="card-tag m">source-driven-development</p><h3 class="card-title" style="font-size:32px">공식 문서에 근거하고 출처를 남김</h3><p class="card-link">→ API가 자주 바뀌는 LangGraph·LangChain에서 옛 문법 환각 방지</p></div>
<div class="card rise d4"><p class="card-tag m">doubt-driven-development</p><h3 class="card-title" style="font-size:32px">중요한 결정을 새 컨텍스트에서 반박 검토</h3><p class="card-link">→ 상태 전이 그래프와 자기 성찰 루프의 종료 조건 점검</p></div>
</div>
<p class="note push"><span class="m hl">context-engineering</span> 규칙 파일(CLAUDE.md·AGENTS.md)·컨텍스트 묶기·MCP 연동으로 “필요한 정보를 필요한 때” 주는 법 — 에이전트 프롬프트 설계에도 그대로 적용됩니다.</p>
<aside>여기가 우리 과정의 차별점입니다. 디버깅 스킬의 다섯 단계는 Auto-Healing을 설계하는 틀로도 쓸 수 있습니다. 감지는 재현, 원인 분석은 위치 특정과 축소, 복구는 수정, 재발 방지는 가드에 해당합니다. LangGraph는 버전마다 API가 달라서 source-driven-development로 공식 문서 근거를 강제하는 것이 특히 효과적입니다.</aside>
</section>
<section id="review">
<p class="eyebrow">모든 STEP 공통 · 머지 전 품질 게이트</p>
<h2 class="title" style="margin-bottom:40px"><span class="m">/review</span> — 다섯 축으로 보고, 심각도를 붙인다</h2>
<div class="row grow">
<div class="col" style="width:760px;flex:none">
<table class="tbl">
<tr><th style="width:250px">리뷰 축</th><th>확인할 것</th></tr>
<tr><td class="k">정확성</td><td>요구사항 충족, 예외·경계 케이스, 테스트 충분성</td></tr>
<tr><td class="k">가독성·단순성</td><td>명확한 이름, 불필요한 복잡도 없음</td></tr>
<tr><td class="k">아키텍처</td><td>기존 패턴 준수, 결합도, 파일 크기</td></tr>
<tr><td class="k">보안</td><td>시크릿·입력 검증·인증, 외부 데이터 불신</td></tr>
<tr><td class="k">성능</td><td>N+1 없음, 목록 API 페이지네이션</td></tr>
</table>
</div>
<div class="col grow">
<div class="card rise d1"><h3 class="card-title" style="font-size:32px">심각도 라벨</h3><p class="card-text"><b>Critical</b> 머지 차단 · (라벨 없음) 필수 수정 · <b>Optional</b> 제안 · <b>Nit</b> 사소함 · <b>FYI</b> 참고</p></div>
<div class="card rise d2"><h3 class="card-title" style="font-size:32px">변경 크기</h3><p class="card-text">약 100줄이 이상적, 300줄은 한 가지 변경일 때만, 1000줄은 쪼개기</p></div>
<div class="card rise d3"><h3 class="card-title" style="font-size:32px">페르소나 활용</h3><p class="card-text">code-reviewer · test-engineer · security-auditor를 각각 따로 돌려 관점을 나눔</p></div>
</div>
</div>
<aside>code-review-and-quality 스킬은 테스트부터 읽고, 다섯 축으로 구현을 보고, 심각도 순으로 정리한 뒤, 작성자의 검증 근거를 확인합니다. 팀 규칙으로 “Critical이 하나라도 있으면 머지 금지”를 정하고, 리뷰 결과를 PR 코멘트로 남기면 통합 테스트 결과서와 결함 재검증 근거가 됩니다.</aside>
</section>
<section id="ship" class="alt">
<p class="eyebrow">STEP 5 · 최적화·배포</p>
<h2 class="title" style="margin-bottom:40px"><span class="m">/ship</span> — 배포는 체크리스트와 되돌리기 계획까지</h2>
<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px">
<div class="card rise d1"><p class="card-tag m">git-workflow-and-versioning</p><p class="card-text">트렁크 기반 개발, 원자적 커밋, 커밋을 세이브 포인트로</p></div>
<div class="card rise d2"><p class="card-tag m">ci-cd-and-automation</p><p class="card-text">Shift Left와 품질 게이트 파이프라인 → GitHub Actions에서 ruff·pytest 통과해야 머지</p></div>
<div class="card rise d3"><p class="card-tag m">observability-and-instrumentation</p><p class="card-text">구조화 로그, RED 지표, OpenTelemetry, 증상 기반 알림 → MLOps 모니터링</p></div>
<div class="card rise d4"><p class="card-tag m">shipping-and-launch</p><p class="card-text">출시 전 체크리스트, 단계적 롤아웃, 롤백 절차 → 배포 아키텍처 설계도</p></div>
<div class="card rise d5"><p class="card-tag m">documentation-and-adrs</p><p class="card-text">ADR로 ‘왜’를 기록 → 발표 Q&amp;A의 설계 근거</p></div>
<div class="card accent rise d6"><p class="card-tag">/ship이 하는 일</p><p class="card-text">전문가 페르소나에게 나눠 점검을 맡기고 <b>go / no-go</b> 판단을 돌려줌</p></div>
</div>
<aside>RED 지표는 Rate, Errors, Duration, 즉 요청 수, 오류율, 응답 시간입니다. 최종 시연 직전에 /ship을 돌려 no-go가 나오면 그 이유가 곧 우리가 고쳐야 할 목록입니다. ADR은 발표 때 “왜 이 구조를 택했나” 질문에 답하는 가장 좋은 준비물입니다.</aside>
</section>
<section id="excuses" class="dark">
<p class="eyebrow">핑계 차단표 (Anti-rationalization)</p>
<h2 class="title" style="margin-bottom:36px">에이전트도, 우리도 쓰는 핑계와 그 반박</h2>
<table class="tbl">
<tr><th style="width:620px">핑계</th><th>스킬에 적힌 반박</th></tr>
<tr><td class="k">“너무 간단해서 스펙은 필요 없어요”</td><td>수용 기준은 여전히 필요합니다. 다섯 줄이면 충분하지만 0줄은 안 됩니다.</td></tr>
<tr><td class="k">“테스트는 나중에 쓸게요”</td><td>‘나중’은 없습니다. 실패하는 테스트부터 씁니다.</td></tr>
<tr><td class="k">“테스트 통과했으니 배포하죠”</td><td>통과는 증거이지 증명이 아닙니다. 실제 동작, 사용자 화면, 사람이 diff를 읽었는지 확인합니다.</td></tr>
<tr><td class="k">“요구사항은 어차피 바뀌어요”</td><td>살아있는 스펙이 변경을 감당합니다. 낡은 스펙도 없는 것보다 낫습니다.</td></tr>
</table>
<div class="card accent push"><p class="card-tag">실습 · 10분</p><p class="card-text" style="font-size:28px">우리 팀이 실제로 써 온 핑계 3개와 반박을 <span class="m">CONSTRAINTS.md</span>에 적고 커밋하세요. Osmani도 팀 고유의 핑계를 직접 적어 두라고 권합니다.</p></div>
<aside>LLM은 그럴듯한 정당화를 만드는 데 능숙하기 때문에 반박을 미리 적어 두는 것입니다. 사람 팀원에게도 그대로 적용됩니다. 예를 들어 “시연 끝나고 테스트 고칠게요” 같은 말을 팀 규칙 파일에 박아 두면 에이전트와 팀원 모두 같은 기준을 보게 됩니다.</aside>
</section>
<section id="case-scrapingbee">
<p class="eyebrow">실제 사용 사례 ① · ScrapingBee 기술 블로그 (2026-08)</p>
<h2 class="title" style="margin-bottom:36px">같은 패턴으로 ‘우리 팀 전용 스킬’을 만들었다</h2>
<div class="row grow">
<div class="col" style="width:800px;flex:none">
<div class="card rise d1"><p class="card-tag">만든 것</p><p class="card-text">가장 저렴한 스크래핑 방법부터 시작하고, 근거가 있을 때만 단계를 올리는 스킬 — <span class="m">SKILL.md</span> + <span class="m">scripts/fetch.py</span>, <span class="m">extract.py</span></p></div>
<div class="card rise d2"><p class="card-tag">결과</p><p class="card-text"><b>정적 페이지</b>: 표준 라이브러리 스크래퍼로 해결, 크레딧 0<br><b>JS 페이지</b>: 정적 확인이 실패한 근거로 렌더링 단계로 승급<br>같은 스킬이 상황에 따라 <b>다른 결정</b>을 내림</p></div>
</div>
<div class="card grow rise d3">
<p class="card-tag">그들이 얻은 교훈</p>
<ul style="margin:0;padding-left:32px;display:flex;flex-direction:column;gap:12px">
<li class="card-text">SDK 버전부터 고정한다</li>
<li class="card-text">마켓플레이스 SSH 오류 → HTTPS</li>
<li class="card-text">200 응답이어도 차단 페이지일 수 있다 → 필드 검증</li>
<li class="card-text">스킬은 가이드일 뿐 보장이 아니다 → 테스트·린트와 함께</li>
<li class="card-text">컬렉션 전체보다 1~5개만 설치</li>
<li class="card-text">남이 만든 스킬은 설치 전 스크립트·훅까지 검토</li>
</ul>
</div>
</div>
<p class="note push"><b>우리 적용:</b> 팀 도메인의 외부 API 연동 규칙(공공 API 페일오버, 재시도 제한 등)을 팀 전용 SKILL.md로 만들어 두면 누가 에이전트를 돌려도 같은 방식으로 구현됩니다.</p>
<aside>ScrapingBee는 agent-skills를 계기로 자기 제품용 스킬을 직접 만들어 Codex로 실행해 봤습니다. 핵심 교훈은 스킬이 보장이 아니라 가이드라는 점, 그래서 테스트와 린트로 받쳐야 한다는 점입니다. 우리 팀도 공통 스킬 위에 팀 전용 스킬 하나를 얹는 것을 목표로 해 보세요.</aside>
</section>
<section id="case-community" class="alt">
<p class="eyebrow">실제 사용 사례 ② · 개발자 커뮤니티 반응 (Hacker News · GeekNews, 2026)</p>
<h2 class="title" style="margin-bottom:36px">현업 개발자들의 평가 — 좋은 점과 한계</h2>
<div class="row">
<div class="card grow rise d1">
<p class="card-tag">좋았다는 경험</p>
<ul style="margin:0;padding-left:32px;display:flex;flex-direction:column;gap:12px">
<li class="card-text">수년 걸릴 레거시 PHP 리팩터링을 한 달 안에 해냄</li>
<li class="card-text">스펙 기반 워크플로로 몇 달째 운영 중인 서비스에 기능을 꾸준히 추가</li>
<li class="card-text">코드베이스를 이미 이해하고 있으면 생성 코드 리뷰가 빠름</li>
</ul>
</div>
<div class="card grow rise d2">
<p class="card-tag">아쉬웠다는 경험</p>
<ul style="margin:0;padding-left:32px;display:flex;flex-direction:column;gap:12px">
<li class="card-text">지시 파일의 필수 규칙을 LLM이 빠뜨림 → 사람 리뷰가 유일한 확실한 검사</li>
<li class="card-text">스킬·MCP를 많이 올리면 토큰과 속도 손해</li>
<li class="card-text">효과를 A/B로 검증한 사례가 드묾</li>
</ul>
</div>
</div>
<div class="card accent push rise d3"><p class="quote" style="font-size:34px">“AI가 만들어낸 코드를 검토하고 이해하는 능력이 핵심”</p><p class="card-text">— GeekNews 댓글, 사내에서 바이브 코딩만으로 개발해 본 개발자. 공통 결론: <b>작고 집중된, 팀에 맞춘 스킬</b>이 가치 있다.</p></div>
<aside>균형 있게 보여 주려고 비판도 넣었습니다. Hacker News 토론에서는 ‘스네이크 오일’이라는 강한 비판도 있었습니다. 지시 파일의 규칙을 모델이 빠뜨릴 수 있다는 것이죠. 그래서 우리는 스킬을 권고로, CI와 사람 리뷰를 강제 장치로 씁니다. 여러분이 발표에서 자기 코드를 설명할 수 있어야 한다는 점과도 연결됩니다.</aside>
</section>
<section id="caution" class="dark">
<p class="eyebrow">주의사항</p>
<h2 class="title" style="margin-bottom:40px">우리 과정에 맞게 쓰는 5가지 원칙</h2>
<div class="numlist">
<div class="numitem rise d1"><p class="n">1</p><div><p class="t">다 깔지 말고 핵심부터</p><p class="d">/spec · /plan · /build · /test · /review로 시작. 공식 가이드도 24개를 한꺼번에 로드하지 말라고 권합니다.</p></div></div>
<div class="numitem rise d2"><p class="n">2</p><div><p class="t">웹 프론트엔드 편향 걸러 내기</p><p class="d">Core Web Vitals·브라우저 테스트 스킬은 UI 담당만. 백엔드·에이전트는 Python(pytest·ruff) 기준으로 읽습니다.</p></div></div>
<div class="numitem rise d3"><p class="n">3</p><div><p class="t">스킬은 권고, 강제는 CI</p><p class="d">모델은 규칙을 빠뜨릴 수 있습니다. 테스트·린트를 GitHub Actions 품질 게이트로 막아 두세요.</p></div></div>
<div class="numitem rise d4"><p class="n">4</p><div><p class="t">커맨드가 안 보이면 이름으로 부르기</p><p class="d">설치 후 /help로 확인하고, 안 되면 “follow spec-driven-development”처럼 스킬 이름으로 지시합니다.</p></div></div>
<div class="numitem rise d5"><p class="n">5</p><div><p class="t">내가 설명할 수 있는 코드만 머지</p><p class="d">최종 발표는 예외 대응, 한계, <b>개인 기여 설명</b>까지 평가합니다.</p></div></div>
</div>
<aside>agent-skills는 웹 성능 전문가가 만든 만큼 일부 스킬이 프론트엔드 쪽으로 기울어 있습니다. 우리 백엔드와 에이전트 코드는 Python이므로 원칙만 가져오고 도구는 pytest, ruff로 바꿔 읽으면 됩니다. 마지막 원칙이 가장 중요합니다.</aside>
</section>
<section id="roadmap">
<p class="eyebrow">도입 로드맵 (권장 예시 · 실제 마감은 대시보드 기준)</p>
<h2 class="title" style="margin-bottom:40px">8주 동안 이렇게 씁니다 — 지금 2주차부터</h2>
<div class="row" style="gap:12px;align-items:stretch">
<div class="phase rise d1"><p class="ph-en">1~2주</p><p class="ph-cmd" style="font-size:26px">/spec /plan</p><p class="ph-txt">기획서 · WBS</p></div>
<p class="arrow">›</p>
<div class="phase rise d2"><p class="ph-en">2~3주</p><p class="ph-cmd" style="font-size:26px">/build /test</p><p class="ph-txt">API 설계서 · DB 스키마 설계서</p></div>
<p class="arrow">›</p>
<div class="phase rise d3"><p class="ph-en">3~5주</p><p class="ph-cmd" style="font-size:26px">debugging security</p><p class="ph-txt">그래프 설계서 · 보안 가드레일 · Auto-Healing</p></div>
<p class="arrow">›</p>
<div class="phase rise d4"><p class="ph-en">5~6주</p><p class="ph-cmd" style="font-size:26px">/review</p><p class="ph-txt">통합 테스트 결과서 · 결함 재검증</p></div>
<p class="arrow">›</p>
<div class="phase rise d5"><p class="ph-en">7~8주</p><p class="ph-cmd" style="font-size:26px">/ship</p><p class="ph-txt">배포 아키텍처 · 모니터링 · 시연</p></div>
</div>
<div class="card push"><p class="card-text" style="font-size:28px;color:var(--ink)"><b>/review는 2주차부터 모든 PR에서 매번.</b> 단계 사이에 넘어갈 때마다 spec.md와 tasks/todo.md를 갱신하고, 그 변경 이력이 곧 중간·최종 발표의 ‘계획 대비 실적’ 근거가 됩니다.</p></div>
<aside>주차는 STEP 1~5 흐름에 맞춘 권장 예시입니다. 실제 마감은 대시보드의 통합 일정을 따르세요. 이미 기획서 초안이 있는 팀은 /spec에 기존 초안을 넣고 빠진 영역, 특히 경계와 테스트 전략을 채우게 하면 됩니다.</aside>
</section>
<section id="checklist" class="alt">
<p class="eyebrow">이번 주 할 일</p>
<h2 class="title" style="margin-bottom:40px">팀 체크리스트 6개</h2>
<div class="grow" style="display:grid;grid-template-columns:1fr 1fr;grid-template-rows:repeat(3,1fr);gap:28px 32px">
<div class="numitem card rise d1" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">1</p><div><p class="t">전원 같은 방식으로 설치</p><p class="d">/help로 커맨드가 보이는지 확인</p></div></div>
<div class="numitem card rise d2" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">2</p><div><p class="t">docs/spec.md 승인</p><p class="d">/spec 결과를 팀장이 PR로 리뷰·머지</p></div></div>
<div class="numitem card rise d3" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">3</p><div><p class="t">CONSTRAINTS.md 작성</p><p class="d">/constraints로 테스트·린트·금지 사항 확정</p></div></div>
<div class="numitem card rise d4" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">4</p><div><p class="t">tasks/todo.md ↔ WBS</p><p class="d">T번호를 대시보드 WBS·일일 기록과 맞춤</p></div></div>
<div class="numitem card rise d5" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">5</p><div><p class="t">PR 템플릿</p><p class="d">T번호 · 테스트 결과 · /review 심각도 라벨</p></div></div>
<div class="numitem card rise d6" style="flex-direction:row;align-items:center;padding:36px 40px"><p class="n">6</p><div><p class="t">첫 ADR 1건</p><p class="d">“LangGraph 상태를 왜 이렇게 나눴나”</p></div></div>
</div>
<aside>이번 주 금요일 회고 때 이 여섯 가지 중 몇 개를 했는지 대시보드 주간 회고에 적어 주세요. 다음 주 일일 피드백에서 spec.md와 tasks/todo.md 링크를 기준으로 코멘트하겠습니다.</aside>
</section>
<section id="closing" class="dark">
<p class="eyebrow">마무리</p>
<h1 class="hero rise d1" style="margin-top:96px;font-size:88px">AI가 짠 코드를<br>설명할 수 있는 팀이 이깁니다</h1>
<div class="bar rise d2" style="margin-top:56px"></div>
<div class="col push rise d3" style="gap:12px">
<p class="lead">저장소 · <span class="m">github.com/addyosmani/agent-skills</span></p>
<p class="lead">문서 · <span class="m">skills.addy.ie</span></p>
<p class="lead">저자 해설 · <span class="m">addyosmani.com/blog/agent-skills</span></p>
</div>
<aside>스킬은 에이전트를 더 똑똑하게 만드는 마법이 아니라, 우리가 이미 알고 있는 좋은 개발 습관을 매번 지키게 하는 장치입니다. 질문 받겠습니다.</aside>
</section>
</div></div>
<div class="notes" id="notes"></div>
<div class="hud"><span id="pos"></span>
<button id="prev" aria-label="이전">◀</button><button id="next" aria-label="다음">▶</button>
<button id="nbtn">노트(N)</button><button id="fbtn">전체화면(F)</button></div>
<script>
(function(){
const s=[...document.querySelectorAll('#deck > section')], deck=document.getElementById('deck');
const notes=document.getElementById('notes'), pos=document.getElementById('pos');
let i=Math.max(0,Math.min(s.length-1,(parseInt((location.hash.match(/slide-(\d+)/)||[])[1])||1)-1));
function fit(){const k=Math.min(innerWidth/1920,innerHeight/1080);deck.style.transform='scale('+k+')';}
function show(n){
i=Math.max(0,Math.min(s.length-1,n));
s.forEach((e,j)=>{e.classList.toggle('on',j===i);});
const el=s[i]; el.querySelectorAll('.rise').forEach(r=>{r.style.animation='none';r.offsetHeight;r.style.animation='';});
const a=el.querySelector('aside'); notes.textContent=a?a.textContent:'';
pos.textContent=(i+1)+' / '+s.length; history.replaceState(null,'','#slide-'+(i+1));
}
addEventListener('resize',fit); fit(); show(i);
addEventListener('keydown',e=>{
if(['ArrowRight','PageDown',' ','Enter'].includes(e.key)){e.preventDefault();show(i+1);}
else if(['ArrowLeft','PageUp','Backspace'].includes(e.key)){e.preventDefault();show(i-1);}
else if(e.key==='Home')show(0); else if(e.key==='End')show(s.length-1);
else if(e.key==='n'||e.key==='N')notes.classList.toggle('show');
else if(e.key==='f'||e.key==='F')toggleFs();
});
function toggleFs(){document.fullscreenElement?document.exitFullscreen():document.documentElement.requestFullscreen();}
document.getElementById('prev').onclick=()=>show(i-1);
document.getElementById('next').onclick=()=>show(i+1);
document.getElementById('nbtn').onclick=()=>notes.classList.toggle('show');
document.getElementById('fbtn').onclick=toggleFs;
document.querySelector('.stage').addEventListener('click',e=>{ if(e.clientX>innerWidth/2) show(i+1); else show(i-1); });
})();
</script>
</body>
</html>