poc

name	poc
description	시간이 촉박한 상황(고객 데모, 내부 시연, PoC)에서 최소 구현 TODO + 데모 시나리오 + 기술 부채 추적을 생성합니다.
when_to_use	데모 준비, 시연 최소 구현, 급하게 보여줘야 해, PoC 계획. 정식 구현 플랜은 implan.
allowed-tools	Read, Write, Glob, Grep, Bash

외부-가시 문서: rules/external-doc.md 10원칙 준수. 데모 시나리오와 결과 전달 문서는 의사결정자와 이해관계자에 노출. 내부 경로 금지, What > How, 단계별 효과는 그 시점 기준.

역할

시간 촉박한 상황(고객 데모, 내부 시연, PoC 검증)에서 빠르게 동작하는 결과물 생성 지원:

1. 요구사항에서 "반드시 동작해야 하는 것"과 "이번에 안 만들어도 되는 것" 분리
2. 기존 기능 영향 범위 사전 체크
3. 최소 구현 TODO 생성 (하드코딩, 더미, 최소 연결 허용)
4. 데모 시나리오 스크립트
5. 임시 처리 추적 후 /todo로 본구현 전환

핵심 원칙: PoC/MVP는 "완성"이 아니라 "검증". 모든 TODO에 두 가지 판단:

• 진짜로 만든다 (없으면 데모 불가)
• 가짜로 만든다 (하드코딩/더미/스킵)

톤: 스코프를 좁히는 실무 관점.

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	일반 SW 관점으로만 진행 (Tier 1)
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
PRD/SRS	.local.claude/prd/, .local.claude/srs/	선택	PoC 목적과 성공 기준을 사용자에게 직접 질문
이전 PoC	.local.claude/poc/	선택	유사 PoC 재사용 불가, 처음부터 구성

다른 스킬과의 경계

질문	담당	이 스킬에서
"시간 촉박한 검증용 최소 구현 TODO, 데모 시나리오, 기술 부채"	이 스킬	✓ 핵심 (검증 우선, 폐기 가능 전제)
"제품 요구사항, 범위, 성공 지표 정의"	/prd	다루지 않음 (이 스킬은 검증 스코프만, 완전한 요구사항은 prd)
"기술 요구사항과 설계 명세"	/srs	다루지 않음 (PoC 는 명세가 아니라 빠른 검증)
"본구현 개발 작업 분해(Outside-In)"	/todo	다루지 않음 (PoC 기술 부채를 /todo 입력으로 전환)
"확정 기능의 시연용 데모와 발표 자료"	/spec-demo	다루지 않음 (PoC 는 미확정 가설 검증, spec-demo 는 확정 스펙 시연)

프로젝트 컨텍스트 (필수, PoC 작성 전 read)

다음 파일이 존재하면 우선 read 하여 회사, 제품, 기술 스택, 금지 사항을 파악:

• CLAUDE.md (자동 로드, 빌드, 실행, 금지, 컨벤션)
• bot/INDEX.md 또는 .local.claude/INDEX.md (사실 카탈로그)
• .local.claude/customers/{고객사}.md (데모 대상, 있을 시)

코드베이스 참조

코드베이스를 직접 읽고 검증하여 영향 범위 체크를 실제 코드 기반으로 수행.

문서	경로	용도
프로젝트 규칙	CLAUDE.md	금지사항, 컨벤션. PoC에서도 반드시 준수
아키텍처	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	요청 흐름, 모듈 매핑, 이벤트 흐름
모듈 상세	.local.claude/modules/{name}.md	서비스, 테이블, 이벤트. 영향 범위 확인
고객사 프로필	.local.claude/customers/{고객사}.md	데모 대상 고객의 Pain Point, 기대 수준, 커스터마이징 현황

핵심: 기존 코드 수정 시 반드시 실제 파일을 Read/Grep으로 확인

• 수정할 파일의 다른 기능 참조 여부 확인
• 기존 메서드/쿼리를 다른 곳에서 사용하는지 Grep
• 테이블 수정 시 해당 테이블 참조하는 다른 Mapper 확인

입력 처리

파일 경로가 제공된 경우 ($ARGUMENTS):

1. Read로 파일을 읽는다
2. SRS/요구사항/메모 등 어떤 형태든 분석하여 프로세스 시작

파일 경로가 없는 경우: "요구사항이나 상황 설명 파일 경로를 전달해주세요. 예: /poc path/to/requirements.md 또는 여기에 직접 상황을 설명해주셔도 됩니다."

프로세스

1단계: 상황 파악 & 구체화

필수 파악 항목:

• 데드라인: 언제까지? (오늘 중, 내일, 2~3일, 1주일)
• 대상: 누구에게? (고객사, 경영진, 내부 팀, 투자자)
• 목적: 무엇을 검증/확인?
• 기존 코드 영향: 신규인지, 기존 위에 올리는 건지?

애매할 때 추가 질문 (최대 4개):

상황	질문	이유
구체적 화면이 없음	데모에서 실제로 클릭하면서 보여줄 화면이 어디?	스코프 컷 기준이 됨
"동작하게"의 범위 불명확	데이터 저장까지? 화면에 보이기만?	구현 깊이 결정
대상의 기대 수준 불명확	기술 아는 분? 클릭해보고 싶어할 분?	클릭 가능 범위 결정
데모 후 코드 운명 불명확	버리나요, 살려서 이어 개발?	컨벤션 준수 수준 결정
어떤 데이터를 보여줄지 불명확	데모용 데이터 예시가 있나요?	시드 데이터 범위

Step 0: 멈추고 생각하기 (PoC를 만들기 전에)

[1M 활용] 다음을 단일 메시지에서 병렬 호출:

• Read: $ARGUMENTS 입력, CLAUDE.md, 관련 PRD .local.claude/projects/*/PRD-*.md, SRS .local.claude/projects/*/SRS-*.md
• Glob: .local.claude/modules/*.md, .local.claude/customers/*.md (데모 대상 고객)
• Read: bot/INDEX.md 또는 .local.claude/ONBOARDING.md

1) 문제 검증: PoC로 검증하려는 게 진짜 핵심인가?

• "왜 이 PoC가 필요한가?" 요청자가 "이거 만들어서 보여줘"라고 했지만, 진짜 검증하고 싶은 게 뭔가? PoC의 목적(What)이 명확하지 않으면 만들어도 "이게 아닌데"가 됨.
• 이미 답이 나와있지 않나? 기존 코드에서 동작 확인, 문서/스크린샷으로 증명 가능하면 코드를 안 짜도 됨.
• 검증해야 할 가설이 명확한가? "뭘 보여줄지"가 아니라 "뭘 검증할지"가 먼저. 가설이 없는 PoC는 삽질.

2) 접근 방식 검증: 새로 만들어야 하나?

• 기존 화면으로 안 되나? 기존 프로젝트 화면을 시연하고 "여기에 ~를 추가하면 됩니다"로 충분한가?
• 데모 범위가 과한가? "완성도 높은 PoC"는 모순. 5개 화면보다 1개 화면 동작이 더 설득력 있을 수 있음.
• 목업/와이어프레임으로 안 되나? 코드 없이 디자인만으로 검증 가능한 건 아닌가?

1)에서 "이미 답 있음" 또는 "가설 불명확"이면 PoC 없이 해결. 2)에서 더 가벼운 방법이 있으면 그것을 먼저 제시.

3) 데모 성공 기준: "이것만 되면 성공" PoC 착수 전에 명확히 정의:

• 데모에서 이 1가지가 동작하면 PoC 성공이다: [정의]
• 이것 외의 것은 부수적. 없어도 데모는 성공

2단계: 스코프 컷 (가장 중요)

[치명적] Must Demo: 데모에서 반드시 동작. 이것 없으면 시연 불가능. [참고] Fake OK: 동작하는 것처럼 보이면 됨. 하드코딩, 더미 데이터, 시드 데이터 허용. [미정] Skip: 이번에 아예 안 만듦. 데모에서 말로 설명하거나 건너뜀.

판단 기준:

• 데모에서 클릭/조작할 부분? 그렇다면 [치명적] or [참고]
• 데모에서 말로 설명할 부분? 그렇다면 [미정]
• 에러 나면 데모 깨지나? 그렇다면 [치명적] (최소 방어)
• 데이터 비어있으면 어색한가? 그렇다면 [참고] (시드 데이터)

애매할 때:

• [치명적] vs [참고]: "실제로 클릭해서 보여줄 건가요?"
• [참고] vs [미정]: "화면에 없으면 어색한가요?"
• [치명적] 항목이 너무 많으면: "데드라인에 현실적으로 어렵습니다. [참고]로 내릴 수 있는 항목?"

스코프 컷 결과를 보여준 뒤 사용자가 등급 조정 가능.

3단계: 기존 기능 영향 체크

[1M 활용] 서브 분할 없이 메인에서 직접 다중 파일 동시 로드 후 교차:

• 로드: 수정 대상 Service/DAO/Controller/Mapper, 해당 메서드/쿼리를 참조하는 다른 파일들 (Grep로 수집 후 전부 Read)
• 대조: 같은 메서드, 쿼리, 테이블을 쓰는 다른 기능 감지, 기존 고객사 운영에 영향 주는 지점 탐지

기존 코드 수정 시 실제 코드를 Glob/Grep/Read로 확인:

• 수정 파일에서 다른 기능이 같은 메서드/쿼리 사용하는지
• 이 수정이 기존 고객사 운영에 영향을 주는지
• 영향 있으면 경고 + 안전한 대안 (별도 엔드포인트, 분기 처리)

안전 장치:

• 기존 로직 수정: if 분기로 기존 동작 보존 + 새 로직 추가
• 새 엔드포인트: 기존 URL 충돌 확인
• DB 수정: 기존 컬럼 변경 대신 새 컬럼 추가 (nullable)
• 프론트 수정: 기존 이벤트 바인딩 보존

롤백 계획:

• Feature 브랜치에서만 작업 (develop 머지 보류)
• 기존 코드 수정 최소화, 새 파일 추가 위주

4단계: 최소 구현 TODO 생성

• [치명적] 항목은 실제 구현 TODO
• [참고] 항목은 "하드코딩으로 처리" TODO
• [미정] 항목은 TODO에 포함하지 않되 기술 부채에 기록
• PoC에서도 프로젝트 금지 사항 (CLAUDE.md) 반드시 준수
• 하드코딩은 // TODO: [PoC] 하드코딩 → 실제 구현으로 교체 주석 필수

5단계: 데모 시나리오 스크립트

시연 시 따라갈 수 있는 단계별 스크립트:

• 각 Step: 내레이션 + 동작 + 예상 결과 + 주의사항
• 금지 구역 (클릭하면 안 되는 곳) 반드시 포함
• Q&A 대비 (예상 질문 + 답변 가이드)

6단계: 기술 부채 & 본구현 전환

• 임시 처리 항목 목록 (방법 + 본구현 작업 + 우선순위)
• [미정] Skip 항목 목록
• /todo 스킬에 바로 입력할 수 있는 형태로 본구현 전환 요약 생성

출력 구조

스코프 컷

## 스코프 컷: [기능명]

**데드라인**: YYYY-MM-DD (N일 남음)
**대상**: 고객사명 / 내부 / 투자자
**목적**: 무엇을 검증하려는지

### [치명적] Must Demo (반드시 동작)
각 항목에 "왜 필수인지" 한 줄.

### [참고] Fake OK (동작하는 것처럼 보이면 됨)
각 항목에 "어떻게 가짜로 만들지" 한 줄.

### [미정] Skip (이번에 안 만듦)
각 항목에 "데모에서 어떻게 넘기는지" 한 줄.

영향 체크

## 기존 기능 영향 체크

### 수정 대상 파일
| 파일 | 수정 내용 | 다른 기능 영향 | 위험도 |

### 안전 장치
- 기존 로직 보존 방법
- 롤백 계획

PoC TODO

## [기능명] PoC TODO 리스트

**모드**: PoC / MVP / 긴급 데모
**데드라인**: YYYY-MM-DD
**예상 작업 시간**: N시간
**브랜치**: Feature/#NNN (develop 머지 보류)

### TODO-NN: {제목} [치명적/참고]
**파일**: {실제 경로}
**작업**: 구체적 내용
**임시 처리**: 하드코딩/더미 부분과 이유
**확인**: 완료 후 확인할 것

[OK] Phase 확인: 데모 가능 상태

데모 시나리오

## 데모 시나리오: [기능명]

**소요 시간**: 약 N분
**사전 준비**: 시드 데이터, 로그인 등

### Step N: {화면/동작}
**내레이션**: "~를 보여드리겠습니다."
**동작**: 클릭/입력 내용
**예상 결과**: 화면에 보이는 것
**주의**: 건드리면 안 되는 곳

### 금지 구역
- 클릭하면 에러/빈 화면이 나오는 곳

### Q&A 대비
| 예상 질문 | 답변 가이드 |

기술 부채

## 기술 부채 목록

### 임시 처리 항목
| # | 항목 | 임시 처리 방법 | 본구현 시 작업 | 우선순위 |

### [미정] Skip 항목
| # | 항목 | 본구현 시 작업 | 우선순위 |

### 본구현 전환 (/todo 스킬 입력용)
기능명, 현재 상태, 임시/미구현 항목 나열 후 `/todo`에 붙여넣기

파일 저장

Frontmatter (CONTRACT 7-2절 표준): category: project-docs, retention: project-end, harvest_targets: [modules/*.md]

PoC 산출물(스코프 컷 + TODO + 데모 시나리오 + 기술 부채)을 하나의 마크다운 파일로 저장한다.

프로젝트 연관 판단

1. $ARGUMENTS에 프로젝트명이 있으면 해당 프로젝트
2. 입력 파일이 projects/{name}/ 하위이면 해당 프로젝트
3. ls .local.claude/projects/로 기존 프로젝트 확인 후 관련 있으면 해당 프로젝트
4. 어디에도 해당 안 되면 독립 저장

이전 스킬 파일 참조

• 같은 프로젝트에 PRD, SRS가 있으면 Read로 읽어 스코프 컷에 반영

저장 경로

• 프로젝트 관련: .local.claude/projects/{project-name}/POC-{기능명}.md
• 독립적: .local.claude/poc/YYYY-MM-DD-{기능명}.md
• 디렉터리 없으면 mkdir -p로 생성

저장 시점

• 전체 산출물(스코프 컷~기술 부채) 생성 완료 시 저장
• 저장 후 파일 경로 안내

제약조건

• 외부-가시 문서 공통 원칙 준수: rules/external-doc.md (가독성 5 + 정직성 5). 데모 시나리오와 결과 전달 문서는 외부 독자에 노출될 수 있음.
• PoC에서도 프로젝트 금지 사항 (CLAUDE.md) 반드시 준수. 급해도 컨벤션을 어기지 않음.
• 하드코딩은 허용하되, // TODO: [PoC] 주석 필수.
• 기존 코드 수정 최소화. 새 파일 추가 위주로 롤백 용이하게.
• 기존 기능 장애 가능성 있는 수정 시 영향 체크에서 반드시 경고.
• 데모 시나리오에 금지 구역 필수 포함.
• 예상 작업 시간을 TODO 상단에 명시.
• 기술 부채에 우선순위(높음/중간/낮음) 매겨 본구현 가이드.
• 본구현 전환 섹션은 /todo 스킬에 바로 입력할 수 있는 형태로 생성.

검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.

이 스킬의 고유 실패 시나리오

[사용자 개입 필요] 성공 기준 모호

• 신호: "일단 돌려보자" 수준으로, 검증하려는 가설과 합격 기준이 Step 0 에서 나오지 않음
• 대응: Step 0 에서 성공 기준 3가지(가설 / 측정 지표 / 합격선) 선택 강제 + 미입력 시 POC 진행 중단

[환경/규모] 기존 코드 수정 범위가 5 파일 이상

• 신호: POC 를 위해 건드리는 기존 코드가 5개 파일 초과되어 본구현과의 경계 모호
• 대응: 분기 패턴(feature flag, 별도 브랜치, 샌드박스 디렉터리) 권장 + "POC 는 폐기 가능해야 함 (본구현 코드 오염 방지)" 경고