create-verification-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# create-verification-skill

진지한 프로젝트에는 실제 앱을 구동해 동작을 증명하는 스크립트화된 방법이 필요하다: 실행하고, 유저처럼 기능을 태우고, 증거를 남기는 것. 이 스킬은 그것을 레포 맞춤 프로젝트 로컬 스킬(`<repo>/.pi/skills/verify-<app>/`)로 생성한다. 생성물의 독자는 사람이 아니라 **이 앱을 처음 보는 다음 에이전트**다. 작업 중간에 cold read된다는 전제로 쓴다.

## 1. 사용자 말고 레포를 인터뷰한다

아래를 코드베이스에서 답하고, 관찰 불가능한 것만 사용자에게 묻는다:

- **Surface**: 유저가 실제로 만지는 게 뭔가? 웹 UI, CLI/TUI, API, 라이브러리? 여럿이면 주력 하나를 고르고 나머지를 기록한다.
- **Run**: 로컬에서 어떻게 시작하나? 레포 자체의 문서화된 dev 명령(package scripts, Makefile, README)을 우선한다. 포트, env, seed 데이터, 인증을 기록한다.
- **Drive**: 에이전트가 프로그램적으로 어떻게 조작하나? 기존 하네스(Playwright/Cypress 스펙, curl 가능한 엔드포인트, 디버그 포트)를 먼저 찾고, 없으면 일반 레시피를 고른다: 웹은 브라우저/CDP, CLI/TUI는 `tmux-terminal` helper, 서비스는 HTTP. CLI/TUI 경로는 먼저 helper의 `doctor`를 실행하고, 실패하면 ordinary bash를 PTY처럼 가장하지 말고 해당 검증 surface가 지원되지 않는다고 보고한다. 유한 비대화형 준비 명령은 `bash_async`를 사용한다.
- **Observe**: 어떤 증거를 잡을 수 있나? 스크린샷, 터미널 기록, 응답 바디, 로그, exit code, DB 상태.
- **Isolate**: 두 인스턴스가 나란히 뜰 수 있나(포트, 데이터 dir)? 안 되면 생성 스킬에 명시한다. 공유 인스턴스 이중 구동 거부가 사용자 세션 오염보다 낫다.

체크아웃이 그대로 빌드·기동되지 않으면 생성 전에 먼저 고치거나 정확히 보고한다. 깨진 베이스로 쓴 스킬은 틀린 절차를 가르친다.

## 2. 스킬 생성

`<repo>/.pi/skills/verify-<app>/SKILL.md`를 작성한다. frontmatter는 `name: verify-<app>`과 앱·surface·사용 시점을 담은 `description` 필수 (description이 없으면 Pi가 로딩하지 않는다). 각 섹션은 인터뷰에서 실제로 찾은 내용으로 채운다. 플레이스홀더 금지:

- **Launch**: 검증용 기동 명령과 준비 완료 판별법(로그 라인, 포트 응답, 프롬프트). teardown 포함. 단명 CLI는 서버 유지가 없으니 launch = 1회 빌드 후 각 drive를 격리된 PTY/tmux 세션에서 시작.
- **Doctor**: "이 인스턴스를 구동할 가치가 있나?"를 답하는 읽기 전용 체크 하나. 프로세스 생존, 버전, 포트 소유, 인증 유효성.
- **Drive**: 이 레포의 실제 셀렉터·명령으로 쓴 하네스 레시피. 좌표·탭 순서보다 안정적 핸들(ARIA 라벨, data 속성, 프롬프트 문자열, 라우트 경로)을 우선.
- **Evidence**: 증거로 뭘 어디에 남기는지. 기준: 내부 setter·테스트 전용 엔드포인트가 아니라 실제 유저 경로를 태운다. 최종 화면만이 아니라 액션과 결과 상태를 잡는다. 보이는 것과 함께 부수효과(쓰인 파일, insert된 행, 발송된 메시지)를 확인한다. dry-run은 이름을 믿지 말고 실제로 뭘 건너뛰는지 관찰로 확인한다.
- **Cleanup**: 실행이 만든 인스턴스만 정리한다. 프로세스 이름으로 kill하지 말고 직접 시작한 것만 죽인다. **증거는 절대 지우지 않는다.** 증거 보존 위치를 스킬에 명시한다.
- **Helpers**: 스킬이 싣는 스크립트는 실행 가능해야 하고 호출법이 본문에 나온다.

cross-harness 공유가 필요하면 `<repo>/.agents/skills/verify-<app>/`에 둔다 (이 위치는 `SKILL.md` 있는 디렉터리만 인식됨).

## 3. Feature map 시드

`verify-<app>/features/README.md`(인덱스)와 유저 대면 기능당 파일 하나를 만든다. 라우트·명령·메뉴·문서에서 식별한 상위 3~5개로 시작한다. 각 파일은 유저 관점에서 답한다:

```markdown
# <기능명>

## Sub-features
## How to get to it (user POV)
## Driving it with <harness>
## Gotchas
```

이 맵이 레포의 유지되는 검증 소스다. 맵에 다른 진입점이 있는데 편한 진입점 하나만 태운 증명은 불완전하다.

## 4. 생성한 스킬을 넘기기 전에 증명한다

생성한 스킬의 지시를 스스로 end-to-end 1회 실행한다: launch → doctor → 맵의 기능 **하나** drive → 증거 캡처 → cleanup. cleanup 후 증거가 명시된 위치에 남아 있는지 확인한다. 증거를 먹어치우는 cleanup은 이 단계 실패다. 실패한 iteration마다 생성된 cleanup을 돌려 프로세스·포트가 방치되지 않게 한다.

**한 번도 실행되지 않은 생성 스킬은 draft지 deliverable이 아니다.**

## 5. 유지보수

앱이 바뀌면 feature map이 낡는다. 유지보수 요청("verify 스킬 갱신해줘")을 받으면: 맵의 각 기능을 현재 소스와 대조하고, 라이브 1회 실행으로 확인한 뒤 스킬을 갱신한다. 단, **문서를 고쳐서 제품 버그를 숨기지 않는다.** 실행이 실패하면 그것은 맵의 오류이거나 제품 버그이고, 후자면 보고한다.

From Jonghakseo/my-pi, MIT.

More from Jonghakseo/my-pi