Files
game-fe-agent/html/fe-ai-reference-flow.html

795 lines
22 KiB
HTML

<!doctype html>
<html lang="ko">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>프론트엔드 작업 단계별 AI 참조 흐름도</title>
<style>
:root {
--navy: #17172b;
--blue: #0b63ce;
--blue-soft: #eaf4ff;
--purple: #5937b7;
--purple-soft: #f1ebff;
--green: #15975f;
--green-soft: #e8f8ef;
--orange: #d97706;
--orange-soft: #fff4dd;
--yellow: #f2b43f;
--yellow-soft: #fff8e6;
--red: #d94841;
--red-soft: #fff0f0;
--bg: #f5f7fb;
--card: #ffffff;
--line: #dce4ef;
--text: #1f2937;
--muted: #667085;
}
* {
box-sizing: border-box;
}
body {
margin: 0;
color: var(--text);
background: var(--bg);
font-family:
-apple-system,
BlinkMacSystemFont,
"Segoe UI",
"Noto Sans KR",
sans-serif;
line-height: 1.55;
}
.hero {
padding: 34px 44px 36px;
color: #fff;
background: var(--navy);
border-bottom: 4px solid #1677ff;
}
.hero .eyebrow {
margin: 0 0 8px;
color: #8d96b8;
font-size: 11px;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.hero h1 {
margin: 0 0 10px;
font-size: 27px;
font-weight: 900;
letter-spacing: -0.04em;
}
.hero p {
margin: 0;
color: #c2c8da;
font-size: 13px;
}
.container {
width: min(1180px, calc(100% - 56px));
margin: 28px auto 48px;
}
.card {
margin-bottom: 22px;
padding: 24px;
background: var(--card);
border: 1px solid var(--line);
border-radius: 8px;
box-shadow: 0 1px 2px rgba(15, 23, 42, 0.03);
}
.section-title {
display: flex;
align-items: center;
gap: 8px;
margin: 0 0 18px;
color: #315a9e;
font-size: 15px;
font-weight: 900;
letter-spacing: -0.02em;
}
.section-title::before {
content: "";
width: 4px;
height: 18px;
background: var(--blue);
border-radius: 999px;
}
.notice {
padding: 12px 16px;
margin-bottom: 16px;
color: #17436f;
font-size: 13px;
font-weight: 700;
background: var(--blue-soft);
border-left: 4px solid var(--blue);
border-radius: 4px;
}
.case-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 14px;
}
.case-box {
min-height: 126px;
padding: 18px;
border: 1px solid var(--line);
border-radius: 8px;
background: #fff;
}
.case-box.case1 {
border-color: #a8caff;
background: #f7fbff;
}
.case-box.case2 {
border-color: #c8b5ff;
background: #fbf8ff;
}
.case-label {
display: inline-block;
margin-bottom: 10px;
padding: 4px 11px;
color: #fff;
font-size: 12px;
font-weight: 900;
border-radius: 999px;
}
.case1 .case-label {
background: var(--blue);
}
.case2 .case-label {
background: var(--purple);
}
.case-box h3 {
margin: 0 0 8px;
font-size: 15px;
font-weight: 900;
}
.case-box p {
margin: 0;
color: #475467;
font-size: 13px;
}
table {
width: 100%;
border-collapse: collapse;
font-size: 13px;
border: 1px solid var(--line);
}
th,
td {
padding: 12px 14px;
text-align: left;
vertical-align: top;
border-right: 1px solid var(--line);
border-bottom: 1px solid var(--line);
}
th {
color: #344054;
font-weight: 900;
background: #eef4ff;
}
td:last-child,
th:last-child {
border-right: 0;
}
.path {
color: #c0392b;
font-family: "SFMono-Regular", Consolas, monospace;
font-size: 12px;
white-space: nowrap;
}
.load-badge {
display: inline-block;
padding: 3px 8px;
color: #915f00;
background: var(--yellow-soft);
border: 1px solid #e8bd54;
border-radius: 999px;
font-size: 11px;
font-weight: 900;
white-space: nowrap;
}
.load-badge.blue {
color: #0b4fa6;
background: var(--blue-soft);
border-color: #9ec3ff;
}
.quote {
padding: 12px 16px;
margin-bottom: 18px;
color: #0c55b0;
font-size: 14px;
font-weight: 700;
font-style: italic;
background: var(--blue-soft);
border-left: 4px solid var(--blue);
border-radius: 4px;
}
.quote.purple {
color: #4d2e91;
background: var(--purple-soft);
border-left-color: var(--purple);
}
.tree {
position: relative;
padding-left: 24px;
}
.tree::before {
content: "";
position: absolute;
top: 0;
bottom: 0;
left: 6px;
width: 2px;
background: #e4e7ec;
}
.tree-node {
position: relative;
margin: 0 0 16px;
padding: 14px 16px;
border: 1px solid var(--line);
border-radius: 8px;
background: #fff;
}
.tree-node::before {
content: "";
position: absolute;
top: 24px;
left: -18px;
width: 18px;
height: 2px;
background: #e4e7ec;
}
.tree-node:last-child {
margin-bottom: 0;
}
.node-head {
display: flex;
align-items: center;
gap: 8px;
margin-bottom: 10px;
font-weight: 900;
}
.round {
display: inline-flex;
align-items: center;
justify-content: center;
width: 24px;
height: 24px;
color: #fff;
font-size: 12px;
font-weight: 900;
background: var(--blue);
border-radius: 999px;
flex-shrink: 0;
}
.round.green {
background: var(--green);
}
.round.orange {
background: var(--orange);
}
.round.purple {
background: var(--purple);
}
.chip-row {
display: flex;
flex-wrap: wrap;
gap: 6px;
margin: 8px 0;
}
.chip {
display: inline-block;
padding: 4px 9px;
font-family: "SFMono-Regular", Consolas, monospace;
font-size: 11px;
border: 1px solid;
border-radius: 999px;
background: #fff;
}
.chip.yellow {
color: #8a5a00;
border-color: #e6b64e;
background: var(--yellow-soft);
}
.chip.green {
color: #087443;
border-color: #8bd3aa;
background: var(--green-soft);
}
.chip.blue {
color: #0b4fa6;
border-color: #9ec3ff;
background: var(--blue-soft);
}
.chip.purple {
color: #4d2e91;
border-color: #c6b6ff;
background: var(--purple-soft);
}
.chip.red {
color: #a33a34;
border-color: #e4a39f;
background: var(--red-soft);
}
.work-box {
margin-top: 10px;
padding: 12px 14px;
border-radius: 6px;
font-size: 12px;
}
.work-box.blue {
background: var(--blue-soft);
border-left: 4px solid var(--blue);
}
.work-box.green {
background: var(--green-soft);
border-left: 4px solid var(--green);
}
.work-box.yellow {
background: var(--yellow-soft);
border-left: 4px solid var(--yellow);
}
.work-box.red {
background: var(--red-soft);
border-left: 4px solid var(--red);
}
.work-box ul {
margin: 4px 0 0;
padding-left: 18px;
}
.case2-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 14px;
}
.stage-card {
padding: 16px;
border: 2px solid;
border-radius: 8px;
background: #fff;
}
.stage-card.purple {
border-color: var(--purple);
}
.stage-card.green {
border-color: var(--green);
}
.stage-card.orange {
border-color: var(--orange);
}
.stage-card.red {
border-color: var(--red);
}
.stage-card .stage-title {
display: flex;
align-items: center;
gap: 8px;
margin: 0 0 12px;
font-size: 15px;
font-weight: 900;
}
.example {
padding: 10px 12px;
margin-bottom: 12px;
font-size: 12px;
font-style: italic;
border-radius: 4px;
background: #f8f5ff;
color: #4d2e91;
}
.legend {
display: flex;
flex-wrap: wrap;
gap: 10px;
align-items: center;
padding: 12px 14px;
background: #fff;
border: 1px solid var(--line);
border-radius: 8px;
font-size: 12px;
}
.legend strong {
margin-right: 4px;
}
@media (max-width: 900px) {
.container {
width: calc(100% - 28px);
}
.hero {
padding: 28px 24px;
}
.case-grid,
.case2-grid {
grid-template-columns: 1fr;
}
table,
thead,
tbody,
tr,
th,
td {
display: block;
width: 100%;
}
thead {
display: none;
}
tr {
border-bottom: 1px solid var(--line);
}
td {
border-right: 0;
}
}
</style>
</head>
<body>
<header class="hero">
<p class="eyebrow">Frontend AI Guidelines — gameservice-fe-agent</p>
<h1>프론트엔드 작업 단계별 AI 참조 흐름도</h1>
<p>
프론트엔드 개발 요청 시 공통 지침(rules/)을 기반으로 Claude AI에게 업무를 위임할 때
어떤 파일을 언제 참조하는지 정리합니다.
</p>
</header>
<main class="container">
<!-- 작업 사례 -->
<section class="card">
<h2 class="section-title">실제 작업 사례 기준</h2>
<div class="notice">
예시: <strong>게임 카드 컴포넌트에 신규 출시 뱃지 추가 (Vue 3 + Nuxt)</strong>
</div>
<div class="case-grid">
<article class="case-box case1">
<span class="case-label">CASE 1</span>
<h3>자연어 업무 요청</h3>
<p>
AI가 claude-workflow.md에 따라 탐색 → 계획 → 구현 → 검증 순서로
전체 흐름을 주도하며 진행합니다. 모호한 부분은 질문합니다.
</p>
</article>
<article class="case-box case2">
<span class="case-label">CASE 2</span>
<h3>@rules 직접 지정 · 단계 분리</h3>
<p>
개발자가 각 작업 단계마다 필요한 rules/ 파일을 직접 지정하고
탐색 · 계획 · 구현 · 검증을 나누어 요청합니다.
</p>
</article>
</div>
</section>
<!-- 공통 자동 로드 -->
<section class="card">
<h2 class="section-title">공통 자동 로드 구조 — 모든 대화에서 항상 적용</h2>
<table>
<thead>
<tr>
<th style="width: 120px;">구분</th>
<th style="width: 280px;">파일</th>
<th>주요 내용</th>
<th style="width: 120px;">로드 시점</th>
</tr>
</thead>
<tbody>
<tr>
<td>공통 지침 진입점</td>
<td><span class="path">CLAUDE.md</span></td>
<td>rules/* 전체를 @import. 공통 지침 우선순위 및 skill 사용 안내</td>
<td><span class="load-badge blue">세션 1회</span></td>
</tr>
<tr>
<td>코딩 컨벤션</td>
<td><span class="path">rules/coding-conventions.md</span></td>
<td>포맷팅(스페이스 2칸·싱글 쿼터·세미콜론), 네이밍(camelCase·PascalCase), any 금지, import 순서</td>
<td><span class="load-badge">매 대화 턴</span></td>
</tr>
<tr>
<td>프레임워크 규칙</td>
<td><span class="path">rules/framework-rules.md</span></td>
<td>Vue 3 &lt;script setup lang="ts"&gt;, Pinia, useFetch, Tailwind 유틸리티 우선, clsx 조건부 클래스</td>
<td><span class="load-badge">매 대화 턴</span></td>
</tr>
<tr>
<td>커밋 / PR 규칙</td>
<td><span class="path">rules/commit-pr.md</span></td>
<td>Conventional Commits 형식, subject 50자·명령형, Squash merge, CI + 1인 승인 필수</td>
<td><span class="load-badge">매 대화 턴</span></td>
</tr>
<tr>
<td>작업 방식 지침</td>
<td><span class="path">rules/claude-workflow.md</span></td>
<td>탐색→계획→구현→검증 순서, 최소 변경 원칙, 모호 시 질문, 임의 기능 추가 금지</td>
<td><span class="load-badge">매 대화 턴</span></td>
</tr>
</tbody>
</table>
</section>
<!-- CASE 1 Tree -->
<section class="card">
<h2 class="section-title">CASE 1 자연어 업무 요청 — 자동 참조 흐름 (Tree)</h2>
<div class="quote">"게임 카드 컴포넌트에 신규 출시 뱃지 추가해줘."</div>
<div class="tree">
<article class="tree-node">
<div class="node-head"><span class="round">0</span>자동 로드</div>
<p>모든 대화 시작 시 CLAUDE.md와 rules/* 4개 파일을 자동으로 참조합니다.</p>
<div class="chip-row">
<span class="chip blue">CLAUDE.md</span>
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">framework-rules.md</span>
<span class="chip yellow">commit-pr.md</span>
<span class="chip yellow">claude-workflow.md</span>
</div>
</article>
<article class="tree-node">
<div class="node-head"><span class="round">1</span>요구사항 분석 — 모호한 부분 질문</div>
<p>claude-workflow.md 원칙에 따라 추측 대신 사용자에게 확인합니다.</p>
<div class="chip-row">
<span class="chip yellow">claude-workflow.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box yellow">
<strong>예상 질문</strong>
<ul>
<li>뱃지는 어떤 조건(출시일 기준 N일 이내 등)일 때 표시하나요?</li>
<li>뱃지 디자인은 기존 디자인 시스템 컴포넌트를 사용하나요?</li>
<li>GameCard 컴포넌트는 여러 페이지에서 공유 중인가요?</li>
</ul>
</div>
</article>
<article class="tree-node">
<div class="node-head"><span class="round">2</span>탐색 — 관련 파일 파악 · 유사 패턴 확인</div>
<p>GameCard 컴포넌트와 주변 컨벤션을 먼저 읽고 유사 뱃지 구현 패턴을 찾습니다.</p>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box blue">
<strong>탐색 항목</strong>
<ul>
<li>GameCard.vue 현재 구조 파악</li>
<li>기존 뱃지 컴포넌트(Badge.vue 등) 존재 여부 확인</li>
<li>props 타입 정의 위치 확인 (types/ 또는 도메인 types.ts)</li>
</ul>
</div>
</article>
<article class="tree-node">
<div class="node-head"><span class="round">3</span>계획 — 할 일 목록 작성 · 승인</div>
<p>변경 파일 목록과 구현 순서를 공유하고, 아키텍처 영향이 있으면 승인을 받습니다.</p>
<div class="chip-row">
<span class="chip yellow">claude-workflow.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box blue">
<strong>계획 산출물</strong>
<ul>
<li>GameCard.vue — isNew prop 추가, 뱃지 렌더링 조건 분기</li>
<li>types/game.ts — isNew: boolean 필드 추가</li>
<li>기존 뱃지 컴포넌트 재사용 or 인라인 처리 결정</li>
</ul>
</div>
</article>
<article class="tree-node">
<div class="node-head"><span class="round green">4</span>구현 — 코드 작성</div>
<p>계획에 따라 Vue 컴포넌트와 타입을 수정합니다. 요청 범위를 벗어나는 리팩토링은 하지 않습니다.</p>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box green">
<strong>구현 항목</strong>
<ul>
<li>defineProps&lt;T&gt;()에 isNew?: boolean 추가</li>
<li>Tailwind 유틸리티 클래스로 뱃지 스타일 적용</li>
<li>조건부 클래스에 clsx 사용, 200줄 초과 시 분리 검토</li>
</ul>
</div>
</article>
<article class="tree-node">
<div class="node-head"><span class="round orange">5</span>검증 — 린트 · 빌드 · 커밋 / PR 작성</div>
<p>타입체크와 빌드를 확인한 뒤 Conventional Commits 형식으로 커밋과 PR을 작성합니다.</p>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">commit-pr.md</span>
<span class="chip yellow">claude-workflow.md</span>
</div>
<div class="work-box red">
<strong>최종 산출물</strong>
<ul>
<li>lint / tsc / build 통과 확인</li>
<li>커밋: <code>feat(game-card): add new-release badge</code></li>
<li>PR 본문: 변경 사항·배경·테스트·체크리스트 작성</li>
</ul>
</div>
</article>
</div>
</section>
<!-- CASE 2 -->
<section class="card">
<h2 class="section-title">CASE 2 @rules 직접 지정 · 단계별 업무 요청 — 직접 참조 흐름 (Tree)</h2>
<div class="quote purple">
개발자가 각 작업 단계마다 필요한 rules/ 파일 또는 skill을 직접 지정해 요청합니다.
</div>
<div class="case2-grid">
<article class="stage-card purple">
<h3 class="stage-title"><span class="round purple">1</span>탐색 단계</h3>
<div class="example">"GameCard 컴포넌트 구조 파악해줘. @rules/framework-rules.md 참고해서"</div>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box green">
<strong>산출 내용</strong>
<ul>
<li>컴포넌트 파일 구조 및 props 정리</li>
<li>재사용 가능한 유사 패턴 목록</li>
<li>영향받는 파일 범위 파악</li>
</ul>
</div>
</article>
<article class="stage-card purple">
<h3 class="stage-title"><span class="round purple">2</span>계획 단계</h3>
<div class="example">"뱃지 추가 구현 계획 잡아줘. @rules/claude-workflow.md 참고해서"</div>
<div class="chip-row">
<span class="chip yellow">claude-workflow.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box green">
<strong>산출 내용</strong>
<ul>
<li>수정 파일 목록 및 변경 순서</li>
<li>아키텍처 영향 범위 정리</li>
<li>사용자 승인 필요 항목 명시</li>
</ul>
</div>
</article>
<article class="stage-card green">
<h3 class="stage-title"><span class="round green">3</span>구현 단계</h3>
<div class="example">"계획대로 구현해줘. @rules/coding-conventions.md @rules/framework-rules.md 참고해서"</div>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">framework-rules.md</span>
</div>
<div class="work-box green">
<strong>산출 내용</strong>
<ul>
<li>Vue 컴포넌트 코드 수정</li>
<li>TypeScript 타입 추가 · 수정</li>
<li>Tailwind 클래스 적용 및 clsx 처리</li>
</ul>
</div>
</article>
<article class="stage-card orange">
<h3 class="stage-title"><span class="round orange">4</span>검증 단계</h3>
<div class="example">"변경 코드 검증하고 커밋·PR 작성해줘. @rules/commit-pr.md 참고해서"</div>
<div class="chip-row">
<span class="chip yellow">coding-conventions.md</span>
<span class="chip yellow">commit-pr.md</span>
</div>
<div class="work-box red">
<strong>산출 내용</strong>
<ul>
<li>lint / tsc / build 통과 확인</li>
<li>Conventional Commits 커밋 메시지 작성</li>
<li>PR 템플릿(변경사항·배경·테스트·체크리스트) 작성</li>
</ul>
</div>
</article>
</div>
<div style="margin-top: 16px; padding: 12px 14px; background: var(--purple-soft); border-left: 4px solid var(--purple); border-radius: 4px; font-size: 13px; color: #4d2e91;">
<strong>Skill 활용 팁</strong> — 반복 업무는 스킬 명령으로 더 빠르게 처리할 수 있습니다.<br>
<span style="font-family: monospace; font-size: 12px;">
/conventional-commit &nbsp;·&nbsp; /verify-component-review &nbsp;·&nbsp; /plan-analyzer &nbsp;·&nbsp; /markup-edm
</span>
</div>
</section>
<!-- 범례 -->
<section class="card">
<h2 class="section-title">범례</h2>
<div class="legend">
<strong>공통 자동</strong>
<span class="chip blue">CLAUDE.md — 세션 1회 자동 로드</span>
<span class="chip yellow">rules/* — 매 대화 턴 자동 로드 (4개 파일)</span>
<span class="chip green">단계별 주요 참조 파일</span>
<span class="chip purple">@rules — 직접 지정 (CASE 2)</span>
<span class="chip red">검증 · 커밋 / PR 단계</span>
</div>
</section>
</main>
</body>
</html>