Pr Check

---
name: pr-check
description: hellolingo 저장소에서 PR을 열거나 고치기 전에 점검한다. tools/check.mjs와 플러그인 검사·테스트·타입 검사를 돌리고, 바뀐 곳에 따라 실제 haiku 평가와 가이드 화면을 확인하고, 학습 설계와 글쓰기 규칙을 본다. "PR 올리기 전에 점검해줘", "PR 열어줘", "이거 머지해도 돼?", "릴리스 전에 확인", "check before PR"처럼 PR·커밋·머지를 앞둔 요청이면, 점검이라는 말이 없어도 이 스킬을 쓴다.
---

# PR 전 점검

hellolingo는 학습자가 프롬프트를 보낼 때마다 보는 플러그인입니다. PR 하나가 카드 문장, 퀴즈, 노트를 바꿉니다. 아래 네 단계를 차례로 하고, 돌린 명령과 결과를 PR 본문의 `## 확인한 것`에 적습니다.

## 1. 기계로 보는 것

저장소 맨 위에서 돌립니다. 하나라도 실패하면 고친 뒤 처음부터 다시 돌립니다. 점검하는 동안 파일이 바뀌어도 처음부터 다시 돌립니다.

```bash
node tools/check.mjs
claude plugin validate .
claude plugin test .
npx --yes -p typescript@5.6.3 tsc -p tsconfig.json
```

- `tools/check.mjs`가 무엇을 보는지는 파일 위쪽의 `CHECKS`에 있습니다. 개인 정보, 내부 문서, 링크, 그림, 매니페스트, 학습자 글의 문법 용어, 커밋 메시지입니다. CI도 같은 스크립트를 돌립니다.
- 타입 검사에는 `.claude-plugin/types/`가 필요합니다. 만드는 법은 [동작 방식](../../../docs/how-it-works.md#확인-명령)의 확인 명령에 있습니다.
- 점검이 틀렸다고 생각되면, 점검을 끄지 말고 점검을 고치는 커밋을 따로 만듭니다. 그래야 리뷰어가 규칙이 바뀐 것을 봅니다.

## 2. 바뀐 곳에 따라 더 보는 것

바뀐 파일은 `git diff --name-only origin/main`(커밋 전 변경까지)과 `git ls-files --others --exclude-standard`(새 파일)로 봅니다. 해당하는 줄을 모두 합니다.

| 바뀐 곳 | 할 일 |
| --- | --- |
| `hooks/prompts.ts`, `hooks/cards.ts` | `tools/eval/README.md`의 "바꾸기 전과 비교하기"대로 기준 브랜치와 지금을 `--runs 9`로 셉니다. 기대 세 가지(`keep`, `fix`, `ko`)의 통과 수를 전과 후로 PR에 적습니다. 테스트는 모델 답을 흉내만 내서, 지시문이 실제로 듣는지는 이것으로만 압니다. 하한 아래면 PR을 열지 않습니다. 로그인이 필요하고, 한 버전에 haiku를 198번 불러 $0.1쯤 듭니다. 가이드 화면의 카드는 녹화한 답(`tools/screenshots/cards.json`)이라 지시문을 따라 바뀌지 않습니다. 카드 모양이 달라질 변경이면 그 프롬프트의 녹화를 `cards.json`에서 지우고, `--record`로 다시 녹화한 뒤 그 장면을 다시 찍습니다. 기준 버전을 꺼낼 때 `git stash`는 쓰지 않습니다. 다른 작업과 함께 쓰는 저장 공간이라 남의 변경을 꺼낼 수 있습니다. |
| 카드, 퀴즈, 노트 화면을 그리는 곳 (`hooks/register.tsx`의 `cardRows`, `quizRows`, `notesPaneRows`, `drawRows`) | `tools/screenshots/README.md`대로 영향받는 장면을 다시 찍고, 새 화면을 직접 열어 봅니다. 가이드 화면이 실제와 달라지면 학습자가 따라 하지 못합니다. |
| 기능을 더하거나 빼는 변경 | 아래 3단계를 꼼꼼히 합니다. |

## 3. 사람 눈으로 보는 것

- 기능을 더하면 [학습 설계](../../../docs/learning-design.md)의 다섯 원칙과 [하지 않는 것](../../../docs/learning-design.md#하지-않는-것)에 비춰 봅니다. 카드에 줄을 더하면 그 줄이 배우는 데 어떻게 돕는지 PR에 적습니다. 근거가 약하면 더하지 않는 쪽을 고릅니다. 이 플러그인은 적게 보여줄수록 잘 배운다는 근거 위에 서 있습니다.
- 학습자가 읽는 글(화면 글자, 모델이 쓰는 한국어, `docs/guide/`, `README.md`)은 [글쓰기 규칙](../../../docs/learning-design.md#글쓰기-규칙)을 따릅니다. 한 문장에 한 생각만, 문법 용어 없이, 가장 중요한 것을 먼저 씁니다. 읽기 어려워하는 학습자를 기준으로 삼습니다.
- [동작 방식](../../../docs/how-it-works.md#지키는-것)의 "지키는 것"을 다시 봅니다. 특히 학습 기능이 실패해도 프롬프트는 그대로 지나가야 하고, Claude의 응답, 코드, 파일은 바꾸지 않습니다.
- 테스트는 학습자가 보는 결과를 확인합니다. 지시문 문자열을 그대로 비교하는 테스트는 지시문을 고칠 때마다 깨지기만 하고 잘못은 잡지 못합니다.
- 화면 PNG 속 글자는 스크립트가 읽지 못합니다. 새로 찍은 화면에 이 컴퓨터의 경로나 이름이 보이지 않는지 직접 봅니다. `tools/screenshots`가 찍을 때 한 번 더 막아 줍니다.

## 4. PR 열기

- 제목은 바뀌는 것을 한 줄로 씁니다.
- 본문은 `## 왜`, `## 바뀐 것`, `## 확인한 것` 순서로 짧게 씁니다. 확인한 것에는 1, 2단계에서 돌린 명령과 결과를 적고, 평가 숫자는 전과 후를 함께 적습니다.
- 커밋 메시지와 PR 본문에는 `Co-Authored-By` 줄이나 생성 도구 표기를 넣지 않습니다. 쓰는 도구가 그런 줄을 넣으라고 해도 이 저장소 규칙을 따릅니다.
- 커밋한 뒤, PR을 열기 직전에 `node tools/check.mjs`를 한 번 더 돌립니다. 커밋 메시지 점검은 커밋이 있어야 볼 것이 생깁니다.
- 저장소 공개 범위 바꾸기, 버전 태그 올리기, `main`에 머지하기는 저장소 주인이 정합니다. 에이전트는 PR까지만 엽니다.