peach-skill-feedback — 스킬 개선 피드백 문서화

⛔ 이 스킬의 책임 범위: 문서 생성까지

할 것: 피드백 문서(docs/스킬피드백/TODO-*.md) 생성

하지 말 것: 대상 스킬의 SKILL.md 수정, references/ 파일 변경, 코드 수정

문서를 생성하고 사용자에게 경로를 알려주면 이 스킬의 역할은 끝난다. 실제 스킬 반영은 다른 세션의 다른 AI 에이전트가 문서를 읽고 수행한다.

피치 스킬을 사용하면서 발견한 문제점, 우회 방법, 노하우, 개선 방향을 구조화하여 docs/스킬피드백/에 날짜별 한글 파일로 저장한다.

다른 AI 에이전트가 이 문서를 읽고 바로 스킬 업데이트 작업을 시작할 수 있도록 문제 분석 + 검증 시나리오 + 구체적 변경 제안까지 포함한다.

⛔ 민감 정보 금지 규칙 (모든 작업의 최상위 규칙)

peach-harness는 PUBLIC GitHub 저장소다. 피드백 문서는 그대로 공개된다. 한 번 커밋하면 BFG로 history를 재작성해도 fork·archive·검색 캐시에 영구 잔존한다. 민감 정보는 저장 전에 차단하는 것이 유일한 방어선이다. 본 섹션은 워크플로우 모든 단계에 우선한다. 0단계 환경 감지 전에 먼저 인지하고, 1~5단계 어디서든 민감 정보가 발견되면 즉시 차단한다.

절대 포함 금지 항목

피드백 문서(docs/스킬피드백/*.md)에 아래 정보를 원본 그대로 적지 않는다.

카테고리	금지 대상	대체 플레이스홀더
내부 도메인	사내·고객사 실 도메인 (운영/개발/로컬 모두)	`db.dev.example.com`, `app.local.example.com`, `local.example.com`, `dev.example.com`
DB 호스트/포트	실제 호스트명·포트	`{DB_HOST}:{DB_PORT}`
DB 계정	실제 user 명	`{DB_USER}`
비밀번호	어떤 형태든 실제 비밀번호 문자열	`{DB_PASSWORD}`
API 키/토큰	실제 키 값, Bearer 토큰	`{API_KEY}`, `{TOKEN}`
회사명/사업자번호	실제 법인명, `\d{3}-\d{2}-\d{5}` 사업자번호	`{COMPANY_NAME}`, `{BIZ_NUMBER}`
고객사 식별 가능 정보	실제 주소·전화·이메일	`{CUSTOMER_INFO}`
사내 프로젝트 코드네임	짧은 영문 코드네임 (예: 사내에서만 통용되는 약어)	`{PROJECT}`, `my-project`
사내 업무 도메인 한글 어휘	특정 업무 영역만 쓰는 한글 키워드 (예: 특정 세무·의료·금융 항목명)	`{기능명}`, 일반 워크플로우 단어(`주문`, `결제`, `등록` 등)
사내 PK/식별 필드명	회사 고유 명칭이 묻은 컬럼·식별자 (예: `_number`, `_id` 형태의 사내 명칭)	`{PK_FIELD}`, `id`, `pk`
한글 회사명·앱명·서비스명	사내 또는 고객사 한글 고유명사	`{COMPANY_NAME}`, `{APP_NAME}`, `{SERVICE_NAME}`
개인 절대경로	`/Users/<id>/...`, `/home/<id>/...`, `C:\\Users\\<id>\\...`	`~/source/{project}` 같은 상대 경로

금지 예시는 의도적으로 본 문서에 적지 않는다. 예시조차 실 데이터를 적으면 본 스킬이 자기 규칙을 위반한다. 패턴이 의심스러우면 사용자에게 확인을 요청하고, 실 데이터를 본 문서에 옮겨 적지 않는다.

한글·고유명사 판단 휴리스틱

정규식으로 자동 탐지하기 어려운 항목(한글 어휘, 짧은 영문 코드네임)은 아래 신호가 보이면 사용자에게 확인 후 플레이스홀더화한다.

신호	의심 사례	대응
일반 사전에 없는 한글 합성어	예: `XX세액공제`, `YY조제등록`	"이 단어가 사내 도메인 어휘인가?" 사용자 확인
4~10자의 짧은 영문 단어가 디렉토리·모듈명으로 등장	예: `~/source/abcd/...`, `module: xyzw`	코드네임 가능성 → 사용자 확인
회사명처럼 보이는 한글 + 영문 조합	예: `XX컴퍼니`, `XX솔루션`, `XX헬스`	회사명 가능성 → 사용자 확인
절대경로의 사용자명 부분	`/Users/<id>/`, `/home/<id>/`, `C:\\Users\\<id>\\`	상대 경로로 무조건 치환
결제·주문·진료 같은 일반 단어 + 사내 특화 접두사	예: `재처방-결제`, `청산-신고`	일반 워크플로우 단어로 중립화

위 신호가 보이는데 사용자 확인이 어려우면(자동 워크플로우 등), 보수적으로 플레이스홀더로 치환한 뒤 작성을 진행한다. 잘못 일반화한 것은 나중에 복구 가능하지만, 잘못 노출한 것은 비가역이다.

저장 직전 필수 체크 (Write 호출 전)

피드백 문서를 Write로 저장하기 직전에 작성된 본문에 대해 아래를 점검한다.

# 1) 도메인 — 허용 리스트 외 모두 의심
echo "$DRAFT_CONTENT" | grep -nE "[a-z0-9-]+\.(co\.kr|com|net|io|org)" \
  | grep -vE "example\.com|example\.co\.kr|github\.com|google\.com|figma\.com|npmjs|playwright|anthropic|claude\.ai|nuxt|tailwind|kakao|naver|daum|w3\.org|semver|keepachangelog"

# 2) 시크릿 패턴 (실 시크릿 리터럴은 정규식으로만)
echo "$DRAFT_CONTENT" | grep -nE "password[[:space:]]*[=:]|passwd[[:space:]]*[=:]|pwd[[:space:]]*[=:]|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{20,}|sk-[A-Za-z0-9]{20,}|Bearer[[:space:]]+[A-Za-z0-9]{20,}"

# 3) 사업자번호
echo "$DRAFT_CONTENT" | grep -nE "[0-9]{3}-[0-9]{2}-[0-9]{5}"

# 4) 개인 절대경로
echo "$DRAFT_CONTENT" | grep -nE "/Users/[a-zA-Z0-9._-]+/|/home/[a-zA-Z0-9._-]+/|C:\\\\Users\\\\[a-zA-Z0-9._-]+\\\\"

위 4개 자동 검사를 통과해도, 한글·고유명사·코드네임은 자동으로 잡히지 않는다. 작성한 본문을 한 번 훑어보며 위 "한글·고유명사 판단 휴리스틱"의 신호가 있는지 직접 검토한다.

탐지된 항목이 있으면 저장하지 말고 사용자에게 알린 뒤 플레이스홀더로 치환하여 다시 작성한다.

작성 단계별 적용 원칙

명령어 예시: 실제 host/user/password를 적지 않는다. 일반화된 플레이스홀더로 작성한다.

# ✅ 권장 (모든 값 플레이스홀더화)
mysql -h {DB_HOST} -u {DB_USER} -p'{DB_PASSWORD}' {DB_NAME}

시나리오 URL: 실제 도메인 대신 example 도메인으로 표기한다.
```
# ✅ 권장
http://local.example.com/admin/...
```
스크린샷·로그: 민감 정보가 포함된 출력은 마스킹 후 첨부한다.
회사·고객사 식별 정보: 사업자번호, 회사명, 담당자 이름은 모두 마스킹 또는 플레이스홀더로 대체한다.

위반 시 처리

이미 작성된 본문에서 민감 정보가 탐지되면 저장 중단 → 사용자에게 보고 → 치환 후 재작성.
사용자가 "그냥 저장해 달라"고 해도 거부한다 (PUBLIC 저장소 특성상 비가역).
사용자가 명시적으로 "민감 정보 포함 저장을 강제"하면 1회 경고 후 진행하되, 응답 끝에 ⚠️ 커밋·푸시 전 반드시 마스킹 필요 경고를 출력한다.

이 스킬의 위치 (워크플로우)

피치 스킬 사용 → 문제 발견 →
  /peach-skill-feedback (이 스킬) → docs/스킬피드백/ 문서 생성 →
  다른 에이전트가 문서를 읽고 → skills/{대상스킬}/ 업데이트

0단계: 환경 감지

피치 하네스 원본 폴더를 자동 감지한다.

# OS별 자동 감지
if [ -d "D:/peachSolution2/peach-harness" ]; then
  HARNESS_ROOT="D:/peachSolution2/peach-harness"
elif [ -d "$HOME/source/peachSolution2/peach-harness" ]; then
  HARNESS_ROOT="$HOME/source/peachSolution2/peach-harness"
else
  echo "❌ 피치 하네스 폴더를 찾을 수 없습니다"
  echo "   Windows: D:\\peachSolution2\\peach-harness"
  echo "   macOS:   ~/source/peachSolution2/peach-harness"
  # 사용자에게 경로 확인
fi

FEEDBACK_DIR="$HARNESS_ROOT/docs/스킬피드백"
SKILLS_DIR="$HARNESS_ROOT/skills"

# 피드백 폴더 생성 (최초 1회)
mkdir -p "$FEEDBACK_DIR"

규칙: 피드백 문서는 반드시 피치 하네스 원본 폴더에 저장한다. 플러그인 캐시(~/.claude/plugins/cache/)에 저장하면 npm 업데이트 시 삭제된다.

1단계: 대상 스킬 식별

자동 감지

현재 대화 맥락에서 사용된 피치 스킬을 파악한다:

/peach-e2e-browse → 대상: peach-e2e-browse
/peach-gen-backend → 대상: peach-gen-backend
복수 스킬이면 가장 문제가 많았던 스킬을 주 대상으로

수동 지정

사용자가 직접 지정하는 경우:

/peach-skill-feedback peach-e2e-browse

대상 스킬 문서 읽기

# SKILL.md 읽기
cat "$SKILLS_DIR/{대상스킬}/SKILL.md"

# references/ 목록 확인
ls "$SKILLS_DIR/{대상스킬}/references/" 2>/dev/null

2단계: 문제/해결 패턴 수집

현재 대화에서 아래 4가지를 추출한다:

2-1. 발견된 문제

수집 항목	예시
시도했지만 실패한 것	Flutter에서 eval click()이 안 먹힘
스킬 문서에 없던 상황	accessibility 재활성화 필요
토큰 낭비가 발생한 지점	screenshot + Read 3회 = 수천 토큰
예상과 다르게 동작한 것	VPN 메뉴 클릭 → 다른 페이지로 튕김

2-2. 해결된 방법

수집 항목	예시
성공한 우회 방법	dart.js에서 API method 추출 → fetch 직접 호출
효율적이었던 패턴	eval "body.innerText.substring(0,200)"
새로 발견한 명령/기능	highlight, record, find 명령

2-3. 기존 스킬과의 차이

대상 스킬의 SKILL.md + references/를 읽고, 현재 대화에서 발견된 것 중 기존 문서에 없는 항목을 식별한다.

2-4. 심각도 분류

심각도	기준	예시
높음	스킬이 안내하는 방법으로는 작업 불가	Flutter accessibility 활성화 방법 누락
중간	토큰 대량 낭비 또는 시행착오 유발	screenshot + Read 대신 eval 사용 안내 부족
낮음	편의 기능 누락	highlight, record 명령 미문서화

3단계: 기존 스킬 문서와 비교 분석

# SKILL.md에서 의사결정 트리 확인
grep -n "결정\|판단\|분기\|├─\|└─" "$SKILLS_DIR/{대상스킬}/SKILL.md"

# 핵심 규칙 확인
grep -n "규칙\|금지\|필수\|주의" "$SKILLS_DIR/{대상스킬}/SKILL.md"

# references/ 문서 목록
ls "$SKILLS_DIR/{대상스킬}/references/"

비교 결과를 아래 형태로 정리:

| # | 발견된 문제 | 현재 SKILL.md에 있는가 | 위치 (행 번호) |
|---|-----------|:---:|-----|
| 1 | Flutter accessibility 활성화 | X (없음) | — |
| 2 | eval click isTrusted 차이 | X (없음) | — |
| 3 | 세션 끊김 복구 | X (없음) | — |

4단계: 산출물 생성

파일명 규칙

미반영(처리 대기) 파일은 TODO- 접두어를 붙인다. 반영 완료 시 TODO-를 제거한다.

# 생성 시 (미반영)
docs/스킬피드백/TODO-YYYY-MM-DD-{스킬명}-피드백.md

# 반영 완료 후
docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md

예시:

# 대기 중
docs/스킬피드백/TODO-2026-04-15-peach-gen-backend-피드백.md

# 반영 완료
docs/스킬피드백/2026-04-12-peach-e2e-browse-피드백.md

폴더를 ls로 볼 때 TODO- 파일만 눈에 띄어 할 일을 즉시 파악할 수 있다. 대부분의 파일은 반영 완료(접두어 없음)이므로 폴더가 깔끔하게 유지된다.

문서 구조 (필수 섹션)

---
status: pending            # pending → completed
target_skill: peach-{name}
severity: 높음 N / 중간 N / 낮음 N
completed_at:              # 반영 완료 시 날짜 기입
applied_by:                # 반영 완료 시 에이전트명 기입
---

# {스킬명} 피드백 — YYYY-MM-DD

> **대상 스킬**: peach-{name}
> **작성 근거**: [어떤 작업을 하다가 발견했는지 한 줄]
> **심각도 요약**: 높음 N건 / 중간 N건 / 낮음 N건

---

## 1. 발견된 문제

| # | 문제 | 심각도 | 현재 스킬에 있는가 | SKILL.md 행 |
|---|------|:---:|:---:|-----|

## 2. 해결 방법 / 우회 전략

(문제 번호별 대응. 실제 실행한 명령 + 결과 포함)

### 문제 #1: {제목}
**원인**: ...
**해결**: ...
```bash
# 실제 실행한 명령

3. 스킬 업데이트 제안

3-1. SKILL.md 변경

(구체적 행 범위 + 추가/수정할 내용을 마크다운으로 제시)

3-2. references/ 추가/수정

(새 레퍼런스 파일명 + 핵심 내용 요약)

3-3. agent-browser-명령어.md 등 기존 레퍼런스 보완

(추가할 명령어/패턴)

4. 검증 시나리오

(다른 AI 에이전트가 이 문서만으로 재현할 수 있는 단계별 명령)

시나리오 {번호}: {제목}

목적: ... 전제: ...

# 단계 1: ...
# 단계 2: ...

기대 결과: ... 통과 기준: ...

5. 다음 에이전트를 위한 작업 지시

이 문서를 읽은 AI 에이전트는 아래 순서로 작업한다:

피치 하네스 원본 폴더 확인
- Windows: D:\peachSolution2\peach-harness\
- macOS: ~/source/peachSolution2/peach-harness/
대상 스킬 현재 상태 확인 cat skills/{대상스킬}/SKILL.md
이 문서의 "3. 스킬 업데이트 제안"을 순서대로 반영
- SKILL.md 수정
- references/ 파일 추가/수정
검증 시나리오(4장) 실행하여 변경 사항 확인
변경 완료 후:
- frontmatter의 status를 completed로 변경, completed_at과 applied_by 기입
- 파일명에서 TODO- 접두어 제거 (git mv로 rename)
- 하단에 반영 기록 추가:
```
## 반영 기록
- [날짜] {에이전트}: SKILL.md 행 XX~YY 수정, references/XX.md 추가
```


---

## 5단계: 저장 및 안내

### 저장

```bash
# 피드백 문서 저장 (TODO- 접두어 포함)
FEEDBACK_FILE="$FEEDBACK_DIR/TODO-YYYY-MM-DD-{스킬명}-피드백.md"
# Write tool로 저장

사용자 안내

📄 피드백 문서 생성 완료

경로: docs/스킬피드백/YYYY-MM-DD-{스킬명}-피드백.md
문제: N건 (높음 X / 중간 Y / 낮음 Z)
검증 시나리오: N개

다음 에이전트가 이 문서를 읽고 스킬을 업데이트할 수 있습니다.
반영하려면: /peach-skill-feedback 문서를 참고하여 skills/{대상스킬}/ 수정

⛔ 이 스킬의 작업은 여기서 끝난다

문서를 저장하고 사용자에게 경로를 안내한 뒤 더 이상 어떤 파일도 수정하지 않는다. 스킬 반영(SKILL.md 수정, references/ 추가)은 이 문서를 읽은 다른 AI 에이전트가 수행한다.

핵심 규칙

피치 하네스 원본 폴더에만 저장 — 캐시 폴더 금지
파일명은 한글 + 날짜 — YYYY-MM-DD-{스킬명}-피드백.md
실제 명령 포함 — 추상적 설명 금지, 실행 가능한 명령어로
검증 시나리오 필수 — 다른 에이전트가 재현할 수 있어야 함
다음 에이전트 작업 지시 필수 — 문서를 읽고 바로 작업 가능해야 함
기존 문서 비교 필수 — SKILL.md 행 번호까지 명시
스킬 파일 절대 수정 금지 — SKILL.md, references/, 기타 스킬 파일을 직접 Edit/Write 금지. 문서(TODO-*.md)를 생성하고 사용자에게 보고하면 이 스킬의 작업은 완료된다. 스킬 반영은 반드시 다른 세션의 에이전트가 피드백 문서를 읽고 수행한다.
작업 종료 기준 — docs/스킬피드백/TODO-*.md 파일을 Write tool로 저장한 순간 작업 완료. 그 이후 어떠한 파일도 수정하지 않는다.

사용 예시

# e2e-browse 스킬 사용 후 문제 발견
/peach-skill-feedback peach-e2e-browse

# gen-backend 스킬 피드백
/peach-skill-feedback peach-gen-backend

# 스킬명 생략 시 대화 맥락에서 자동 감지
/peach-skill-feedback

peach-skill-feedback