Skip to content

Commit e18d31b

Browse files
ikseong00ikseong00
committed
docs: consolidate verification harness
1 parent 19de17a commit e18d31b

6 files changed

Lines changed: 124 additions & 14 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,11 +33,5 @@ jobs:
3333
- name: Install dependencies
3434
run: pnpm install --frozen-lockfile
3535

36-
- name: Type check
37-
run: pnpm check
38-
39-
- name: Test
40-
run: pnpm test
41-
42-
- name: Build
43-
run: pnpm build
36+
- name: QA harness
37+
run: pnpm qa

‎CLAUDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ pnpm qa
4141
- `client/src/lib/analytics.ts`: GA4 이벤트
4242
- `docs/spelling-rules.md`: 현재 적용된 맞춤법 규칙
4343
- `RULE_UPDATE.md`: 룰 추가 기준
44+
- `HARNESS.md`: 로컬, CI, UI, 배포, 분석, 검색 노출 검증 기준
4445
- `DEPLOYMENT.md`: 배포 운영
4546

4647
## Product Rules
@@ -109,3 +110,4 @@ Then:
109110
3. Push `main`.
110111
4. Create a GitHub release tag.
111112
5. Confirm Vercel production URL responds.
113+
6. Check `HARNESS.md` for any extra UI, GA4, SEO, or deployment verification relevant to the change.

‎DEPLOYMENT.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
- GitHub `main` 브랜치에 push되면 Vercel Production 배포가 생성된다.
88
- PR 또는 `main`이 아닌 브랜치 push는 Vercel Preview 배포로 확인한다.
9-
- GitHub Actions는 배포를 직접 하지 않고 `pnpm check`, `pnpm test`, `pnpm build`만 확인한다.
9+
- GitHub Actions는 배포를 직접 하지 않고 `pnpm qa`로 타입 체크, 테스트, 빌드만 확인한다.
1010

1111
Vercel 공식 문서 기준으로 Git 저장소를 연결하면 브랜치 push마다 자동 배포가 생성되고, production branch의 최신 변경은 Production 배포가 된다.
1212

@@ -38,11 +38,11 @@ VITE_SITE_URL=https://example.com
3838
배포 전 로컬에서 다음 명령을 통과시킨다.
3939

4040
```bash
41-
pnpm check
42-
pnpm test
43-
pnpm build
41+
pnpm qa
4442
```
4543

44+
배포 뒤에는 `HARNESS.md`의 배포 하네스 기준으로 홈, `robots.txt`, `sitemap.xml`을 확인한다.
45+
4646
## 주의
4747

4848
- Vercel CLI가 로그인되어 있지 않은 로컬 환경에서는 프로젝트 연결을 자동으로 끝낼 수 없다.

‎HARNESS.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# 검증 하네스
2+
3+
이 문서는 `맏춤법 검사기`의 기능, UI, 배포, 검색 노출 상태를 확인할 때 쓰는 기준이다.
4+
5+
## 기본 하네스
6+
7+
로컬과 CI의 기본 검증 명령은 하나로 맞춘다.
8+
9+
```bash
10+
pnpm qa
11+
```
12+
13+
`pnpm qa`는 아래 명령을 순서대로 실행한다.
14+
15+
```bash
16+
pnpm check
17+
pnpm test
18+
pnpm build
19+
```
20+
21+
## 룰 하네스
22+
23+
맞춤법 룰을 추가하거나 수정할 때는 다음 파일을 함께 확인한다.
24+
25+
- `client/src/lib/reverseSpellCheck.ts`
26+
- `client/src/lib/reverseSpellCheck.fixtures.ts`
27+
- `client/src/lib/reverseSpellCheck.test.ts`
28+
- `docs/spelling-rules.md`
29+
- `RULE_UPDATE.md`
30+
31+
확인 기준:
32+
33+
- fixture가 실제로 바뀐 표현을 검증하는가
34+
- 오류 분류가 `맞춤법`, `띄어쓰기`, `표준어`, `외래어` 중 맞는 값인가
35+
- 문맥 없이 위험한 룰이 기본 룰로 들어가지 않았는가
36+
- 사용자를 불쾌하게 만들 수 있는 문장부호/띄어쓰기 장난이 들어가지 않았는가
37+
38+
## UI 하네스
39+
40+
UI를 바꾼 뒤에는 브라우저에서 주요 폭을 확인한다.
41+
42+
- 375
43+
- 768
44+
- 980
45+
- 1024
46+
- 1280
47+
- 1440
48+
49+
확인 항목:
50+
51+
- 콘솔 에러 0
52+
- 가로 overflow 0
53+
- 긴 한국어 문장 입력 시 카드와 버튼이 깨지지 않음
54+
- 결과 문장 안에서 밑줄/하이라이트가 보임
55+
- 복사, 공유, 이미지 저장 버튼의 `aria-label`/`title` 유지
56+
- `이것도 넣어줘` 팝업 열기/닫기/제출 플로우 정상
57+
- 모바일에서 `검사하기` 버튼이 불필요하게 늘어나지 않음
58+
59+
## 배포 하네스
60+
61+
`main`에 push하면 Vercel Production 배포가 생성된다. 배포 뒤 확인할 URL:
62+
63+
- `https://reverse-spell-checker.vercel.app/`
64+
- `https://reverse-spell-checker.vercel.app/robots.txt`
65+
- `https://reverse-spell-checker.vercel.app/sitemap.xml`
66+
67+
기준:
68+
69+
- 홈: `200 OK`
70+
- `robots.txt`: `sitemap.xml` 하나만 참조
71+
- `sitemap.xml`: `application/xml`, 홈 URL 1개 포함
72+
- `sitemap.txt`: 사용하지 않음
73+
74+
## 분석 하네스
75+
76+
GA4는 원문을 저장하지 않는다. 이벤트에는 길이, 분류, rule id처럼 비식별 신호만 보낸다.
77+
78+
핵심 이벤트:
79+
80+
- `page_view`
81+
- `input_start`
82+
- `check_submit`
83+
- `result_generated`
84+
- `rule_report_opened`
85+
- `rule_report_submitted`
86+
87+
주요 파라미터:
88+
89+
- `error_count`
90+
- `rule_count`
91+
- `categories`
92+
- `matched_rules`
93+
- `matched_rule_1` ... `matched_rule_5`
94+
- `char_count_bucket`
95+
96+
## 검색 노출 하네스
97+
98+
일반 웹페이지는 Google Indexing API 대상이 아니다. 검색 노출 관련 확인은 아래 순서로 한다.
99+
100+
1. Search Console URL 검사에서 홈 URL 확인
101+
2. 실제 URL 테스트
102+
3. 색인 생성 요청
103+
4. sitemap은 `sitemap.xml`만 제출
104+
5. 외부 링크는 GitHub README, GitHub Release, 소개글 등으로 만든다
105+
106+
기준:
107+
108+
- `index,follow` 유지
109+
- canonical이 대표 URL과 일치
110+
- `client/index.html`의 정적 fallback 본문에 제품명과 주요 케이스가 남아 있음
111+
- sitemap/robots를 반복 수정하지 않음

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ Vercel 설정:
7575

7676
- [맞춤법 룰 업데이트 기준](./RULE_UPDATE.md)
7777
- [현재 적용 규칙](./docs/spelling-rules.md)
78+
- [검증 하네스](./HARNESS.md)
7879
- [룰 후보 정리](./RULE_CANDIDATES.md)
7980
- [기능 명세](./SPEC.md)
8081
- [배포 운영](./DEPLOYMENT.md)

‎SPEC.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,16 +47,18 @@
4747

4848
## 검증 하네스
4949

50-
변경 후 가능한 한 아래를 실행한다.
50+
상세 기준은 `HARNESS.md`를 따른다. 기본 검증 명령은 아래 하나로 통일한다.
5151

5252
```bash
5353
pnpm qa
5454
```
5555

56-
개별 명령은 다음과 같다.
56+
`pnpm qa`는 타입 체크, 테스트, 프로덕션 빌드를 순서대로 실행한다.
5757

5858
```bash
5959
pnpm check
6060
pnpm test
6161
pnpm build
6262
```
63+
64+
UI 변경은 `pnpm qa`만으로 끝내지 않는다. 브라우저에서 주요 폭과 기본 입력/검사/복사/공유/이미지 저장 플로우를 확인한다.

0 commit comments

Comments
 (0)