브라우저 검증 규정 작업 가이드 반영 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 헌법이 이미 요구하는 브라우저 검증을 공개 /guide의 게이트·완료 템플릿과 저장소 AGENTS.md 규칙 블록에 명문화해, 읽는 사람이 그것을 빠뜨릴 수 없게 만든다.

Architecture: 새 섹션·새 검증 장치를 만들지 않는다. content/guide.ts의 executionDetails 두 gate 문자열과 completionTemplate 한 줄을 고치고(단위 테스트가 내용을 요구하도록 RED를 먼저 세운다), AGENTS.md에 실행 규칙 블록을 신설한 뒤 README.md가 그 블록을 단일 출처로 가리킨다. gate 문자열은 content/journey.ts:35의 gateForStep을 통해 /docs에도 그대로 흐르므로 두 화면의 어투가 갈라지지 않는다.

Tech Stack: TypeScript 5.9.x, Node.js 24.18.0, Next.js 16.3.0, node:test + tsx(단위·통합), Playwright 1.62.1 + @axe-core/playwright(브라우저)

Global Constraints

• 설계 문서: docs/superpowers/specs/2026-08-19-playwright-work-guide-design.md
• 작업 저장소는 워크스페이스 바로 아래의 lcy_harness다. lcy_try/lcy_harness의 사본을 건드리지 않는다.
• 공개 /guide의 gate·템플릿 문구는 도구 중립으로 쓴다. "Playwright"라는 이름은 content/guide.ts에 넣지 않는다.
• guideSections, stageDocuments, documentAnchorByStage는 건드리지 않는다. 섹션 수는 다섯 그대로다.
• .specify/memory/constitution.md, .specify/templates/*, scripts/verify-manual.mjs는 이번 범위 밖이다.
• 런타임 dependencies는 next, react, react-dom 셋 그대로 유지한다.
• 문서 어디에도 npm run dev 다음 줄에 npm run test:browser를 적지 않는다. scripts/verify-manual.mjs:115의 blocking browser sequence 검사가 빌드를 실패시킨다.
• 커밋 메시지는 저장소 관행대로 한국어 한 줄 요약을 쓴다(feat(harness):, docs(harness):).

File Structure

Task 1이 공개 콘텐츠와 그 테스트를, Task 2가 저장소 규칙 문서를, Task 3이 매뉴얼 정합성과 전체 검증을 닫는다. 리뷰어는 각각을 따로 반려할 수 있다.

Task 1: 공개 /guide의 게이트와 완료 템플릿에 브라우저 검증을 세운다

Files:

• Modify: content/guide.ts:176, content/guide.ts:191, content/guide.ts:360-375
• Test: tests/unit/guide-content.test.ts

Interfaces:

• Consumes: content/harness.ts의 workflowSteps(10단계, id 순서 고정). executionDetails는 이 배열과 인덱스로 짝지어져 workflowPlaybook이 된다 — 배열 길이나 순서를 바꾸면 안 된다.

• Produces: workflowPlaybook[5].gate와 workflowPlaybook[8].gate의 새 문자열, completionTemplate의 새 줄. content/journey.ts의 gateForStep("isolated-implementation")·gateForStep("integrated-deployment")가 이 문자열을 그대로 읽어 /docs에 낸다.

• [ ] Step 1: 실패하는 테스트를 쓴다

tests/unit/guide-content.test.ts의 마지막 it(...) 블록 뒤, 파일을 닫는 }); 앞에 아래 두 검사를 넣는다.

  it("구현과 릴리스 게이트가 실제 브라우저 검증을 요구한다", () => {
    const implementation = workflowPlaybook.find((step) => step.id === "isolated-implementation");
    const release = workflowPlaybook.find((step) => step.id === "integrated-deployment");

    assert.ok(implementation, "isolated-implementation 단계가 없습니다.");
    assert.ok(release, "integrated-deployment 단계가 없습니다.");
    assert.match(implementation.gate, /브라우저/u);
    assert.match(release.gate, /브라우저/u);
  });

  it("완료 템플릿이 브라우저 검사 결과를 묻는다", () => {
    assert.match(completionTemplate, /브라우저 검사 명령 \/ 결과/u);
  });

workflowPlaybook과 completionTemplate은 이 파일 4~13행에서 이미 import되어 있으므로 import 문은 건드리지 않는다.

• [ ] Step 2: RED를 확인한다

Run: npm run test:unit Expected: FAIL — 새 검사 두 건이 실패한다. 게이트 쪽은 현재 문자열에 "브라우저"가 없어 AssertionError, 템플릿 쪽도 같은 이유로 실패한다. 기존 검사는 모두 통과한다.

• [ ] Step 3: 게이트 두 개를 고친다

content/guide.ts:176(구현 단계, purpose가 "변경 경계를 격리하고 RED→GREEN→REFACTOR로 구현한다."인 항목):

    gate: "관련 테스트가 실패 이유를 증명한 뒤 통과하고, 화면 동작을 바꿨다면 실제 브라우저 검사도 같은 근거를 남긴다.",

content/guide.ts:191(9단계 "통합 배포", purpose가 "제품과 매뉴얼을 한 후보로 검증하고 함께 활성화한다."인 항목):

    gate: "접근성·반응형 브라우저 검사와 후보·활성 경로 스모크가 모두 통과했다.",

• [ ] Step 4: 완료 템플릿에 한 줄을 더한다

content/guide.ts의 completionTemplate에서 "완료 증거" 블록을 아래로 바꾼다. REFACTOR 후 회귀 검사 다음, 독립 검토 결과 앞이다.

export const completionTemplate = `완료 증거 (RED → GREEN → REFACTOR):
- RED 명령 / 예상 실패:
- GREEN 명령 / 통과 결과:
- REFACTOR 후 회귀 검사:
- 브라우저 검사 명령 / 결과(접근성·반응형):
- 독립 검토 결과:

나머지 블록(매뉴얼 게이트, 릴리스)은 그대로 둔다.

• [ ] Step 5: GREEN을 확인한다

Run: npm run test:unit Expected: PASS — 새 검사 두 건 포함 전부 통과

• [ ] Step 6: 회귀와 정적 검사를 돌린다

Run: npm run test && npm run typecheck && npm run lint Expected: PASS — 통합 테스트의 /docs 게이트 대조를 포함해 실패 0

• [ ] Step 7: 화면에서 확인한다

Run: npx playwright test tests/browser/guide.spec.ts tests/browser/docs.spec.ts --reporter=line Expected: PASS — 이 명령이 자체 개발 서버를 띄운다. 앞에서 npm run dev를 따로 실행하지 않는다.

• [ ] Step 8: 커밋

git add content/guide.ts tests/unit/guide-content.test.ts
git commit -m "feat(harness): 구현·릴리스 게이트와 완료 템플릿에 브라우저 검증을 세운다"

Task 2: AGENTS.md에 브라우저 검증 규칙을 명문화한다

Files:

• Modify: AGENTS.md
• Modify: README.md:59

Interfaces:

• Consumes: playwright.config.ts의 webServer·PLAYWRIGHT_BASE_URL 동작, package.json의 test:browser·verify script, scripts/verify-manual.mjs:115의 blocking browser sequence 검사, tests/browser/responsive.spec.ts:4의 뷰포트 배열.

• Produces: AGENTS.md의 ## 브라우저 검증 규칙 절. 이후 README.md와 작업 보고서가 규칙 원문 대신 이 절을 가리킨다.

• [ ] Step 1: 규칙 블록을 넣는다

AGENTS.md의 다음 줄부터, 앞에 아래를 넣는다. 자동 생성 블록 안에 넣지 않는다 — next dev가 그 블록을 다시 쓰기 때문에 사라진다.

## 브라우저 검증 규칙

헌법 원칙 III와 개발 워크플로 7항이 요구하는 브라우저 검사의 실행 규칙이다.

1. 브라우저 검사는 `npm run test:browser` 하나로 실행한다. 대상은 `tests/browser/`뿐이다.
2. 앞에 `npm run dev`를 따로 띄우지 않는다. Playwright가 자체 `webServer`로 개발 서버를
   올리고 내린다. 문서에 `npm run dev` 다음 줄로 브라우저 명령을 적으면
   `npm run verify:manual`이 `blocking browser sequence`로 빌드를 실패시킨다.
3. 이미 떠 있는 서버나 배포 후보·공개 URL을 검사할 때만 `PLAYWRIGHT_BASE_URL`을 지정한다.
   이때는 `webServer`가 비활성이므로 서버 기동은 실행자 책임이다.
4. 화면 동작·레이아웃·타이포그래피를 바꾸면 375/768/1024/1440px 매트릭스와
   axe(WCAG 2.1 A/AA) 검사를 함께 돌린다. `heading-order`는 A/AA 밖의 best-practice
   규칙이므로 별도 검사로 유지한다.
5. `npm run verify`에는 브라우저 검사가 들어 있지 않다. 완료 판정 전에 따로 실행하고
   결과를 `docs/verification-report.md`에 건수와 함께 남긴다.
6. 빠른 RED/GREEN은 특정 스펙 파일만 좁혀 돌려도 되지만, 완료 판정은 production build 뒤
   전체 브라우저 검사로 한다.

• [ ] Step 2: README에서 규칙 블록을 가리킨다

README.md의 "검증 명령" 절, npm run verify를 설명하는 문단(58~59행) 바로 다음에 빈 줄을 두고 아래 한 줄을 넣는다.

마크다운 링크 문법을 쓰지 않는다 — 계획서·보고서가 이 줄을 인용할 때 상대 링크가 깨진 것으로 잡히기 때문이다. 절 이름을 본문으로 가리킨다.

브라우저 검사의 실행 규칙(자체 서버, `PLAYWRIGHT_BASE_URL`, 뷰포트 매트릭스, 결과 기록)은
저장소 루트 `AGENTS.md`의 「브라우저 검증 규칙」 절을 단일 출처로 따른다.

• [ ] Step 3: 매뉴얼 계약 검사를 돌린다

Run: npm run verify:manual Expected: PASS — commands, relative links, routes, public URLs, leak checks 전부 통과. AGENTS.md 상대 링크가 실재하고, 새 문서 어디에도 blocking browser sequence가 없어야 한다.

• [ ] Step 4: 통합 테스트를 돌린다

Run: npm run test:integration Expected: PASS — 매뉴얼 계약 통합 테스트 실패 0

• [ ] Step 5: 커밋

git add AGENTS.md README.md
git commit -m "docs(harness): 브라우저 검증 실행 규칙을 AGENTS.md에 세운다"

Task 3: 매뉴얼 영향을 기록하고 완료 게이트를 통과시킨다

Files:

• Modify: docs/manual-impact.md
• Modify: docs/verification-report.md

Interfaces:

• Consumes: Task 1·2의 변경 전체.

• Produces: 이번 변경의 manual-impact: affected 기록과 실행 증거. 후속 릴리스 판정이 이 표와 보고서를 근거로 삼는다.

• [ ] Step 1: 매뉴얼 영향표에 행을 더한다

docs/manual-impact.md의 표 마지막 행(DNS/TLS와 외부 공개) 다음에 아래 행을 넣는다.

| 브라우저 검증 규정 | 구현·릴리스 게이트와 완료 템플릿에 브라우저 검증 반영 | `AGENTS.md` 규칙 블록과 연결 한 줄 | 영향 없음 — 근거 선별 계약 불변 | 영향 없음 — 배포·incident 절차 불변 | 검증 완료 |

• [ ] Step 2: 전체 게이트를 돌린다

Run: npm run verify Expected: PASS — test, typecheck, lint, 모든 validator, build와 격리된 deployment contract 전부 통과

• [ ] Step 3: 브라우저 검사 전체를 돌린다

Run: npm run test:browser Expected: PASS — Chromium 전 건 통과. 실패가 나오면 고치기 전에 실패 내용을 그대로 기록한다.

• [ ] Step 4: 검증 보고서에 결과를 남긴다

docs/verification-report.md 끝에 아래 절을 더한다. 표의 결과 칸은 Step 2·3에서 실제로 나온 값으로 채운다 — 예상값을 미리 적지 않는다.

## 2026-08-19 브라우저 검증 규정 반영

| 검증 | 결과 |
|---|---|
| `npm run verify` | (실행 결과) |
| `npm run test:browser` | (실행 결과, 통과 건수) |

공개 `/guide`의 구현·릴리스 게이트와 완료 템플릿이 브라우저 검증을 요구하고,
`AGENTS.md`가 그 실행 규칙의 단일 출처가 되었다. 게이트 문자열은 `gateForStep`을 통해
`/docs`에도 같은 문구로 나간다.

• [ ] Step 5: 커밋

git add docs/manual-impact.md docs/verification-report.md
git commit -m "docs(harness): 브라우저 검증 규정 반영의 매뉴얼 영향과 실행 증거를 남긴다"