브라우저 검증 규정을 작업 가이드에 세우는 설계

작성일: 2026-08-19 상태: 사용자 승인(공개 가이드는 기존 단계 게이트 보강, 저장소는 AGENTS.md 규칙 블록)

배경

브라우저 검증은 이 프로젝트에서 선택지가 아니다. 헌법 원칙 III는 완료 판정을 "실제 테스트, 정적 검사, 프로덕션 빌드, 브라우저 검사와 배포 후 스모크 결과"로 하고, 개발 워크플로 7항은 완료 전 "접근성·반응형 브라우저 검사"를 요구한다.

그런데 그 요구가 사람이 실제로 읽는 두 자리에는 없다.

• 공개 /guide의 작업 순서와 완료 템플릿은 RED/GREEN/회귀와 스모크만 묻는다. content/guide.ts 전체에 "브라우저"라는 말이 한 번도 없다. 템플릿이 묻지 않으면 빠뜨려도 빈칸이 항의하지 않는다.
• 저장소 AGENTS.md는 spec-kit 안내와 Next.js 자동 생성 블록뿐이다. Playwright 실행 규칙은 README.md 두 줄, playwright.config.ts, scripts/verify-manual.mjs의 검사 하나에 흩어져 있어, 에이전트가 규칙을 어기기 전까지는 규칙의 존재를 모른다.

실제로 그 규칙 중 하나는 이미 한 번 깨졌다. quickstart가 blocking npm run dev 다음에 브라우저 명령을 두었고, 명세 리뷰에서 잡혀 회귀 검사(verify-manual.mjs의 blocking browser sequence)가 생겼다. 규칙이 적히지 않은 자리에서 같은 종류의 실수가 반복된다.

관점

같은 규정을 두 독자에게 각자의 말로 세운다.

• 공개 /guide는 순서와 게이트를 판다. 도구 이름이 아니라 "언제 무엇을 통과해야 하는가"가 상품이다. 그러므로 게이트 문구는 도구 중립으로 쓰고, Playwright라는 이름은 도구를 이미 밝히고 있는 자리(workLayers, 저장소 문서)에만 둔다.
• 저장소 AGENTS.md는 실행 규칙을 판다. 에이전트가 명령을 치기 직전에 읽는 자리이므로 명령, 금지 패턴, 환경변수, 매트릭스, 기록 의무를 구체적으로 적는다.

새 섹션이나 새 검증 장치는 만들지 않는다. 이미 있는 요구를 빠뜨릴 수 없게 만드는 것이 목적이고, 그 이상은 이번 범위가 아니다.

범위

포함:

• content/guide.ts — executionDetails의 구현·릴리스 단계 gate 문구, completionTemplate
• AGENTS.md — 브라우저 검증 규칙 블록 신설
• README.md — 검증 명령 절에서 규칙 블록으로 연결
• docs/manual-impact.md — 매뉴얼 영향 기록

제외:

• .specify/memory/constitution.md 개정. 원칙 III와 워크플로 7항에 이미 브라우저 검사가 있으므로 개정할 것이 없다.
• .specify/templates/* 슬롯 추가.
• scripts/verify-manual.mjs 신규 검사. 문서화가 먼저이고, 강제는 규칙이 실제로 흔들릴 때 붙인다.
• /guide에 "검증 층" 새 섹션 신설. 섹션 수를 늘리지 않는다.

공개 /guide 변경

executionDetails의 두 단계 gate를 보강한다.

completionTemplate의 "완료 증거" 블록에 한 줄을 더한다.

- 브라우저 검사 명령 / 결과(접근성·반응형):

위치는 REFACTOR 후 회귀 검사 다음, 독립 검토 결과 앞이다. 회귀까지 끝난 뒤 화면을 확인하고, 그 결과를 들고 검토로 넘어가는 실제 순서와 같다.

documentAnchorByStage, guideSections, 문서 슬롯은 건드리지 않는다. /docs의 gateForStep이 같은 리터럴을 끌어가므로 gate 문구 변경은 /docs에도 자동 반영된다 — 이것은 의도한 결과이며, 두 화면의 어투가 갈라지지 않는다.

AGENTS.md 규칙 블록

SPECKIT 블록 다음, `` 앞에 ## 브라우저 검증 규칙을 세운다. 자동 생성 블록 사이에 끼우지 않는 이유는 next dev가 그 블록을 다시 쓰기 때문이다.

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 뒤 전체 브라우저 검사로 한다.

README.md의 "검증 명령" 절 끝에 한 줄을 더해 이 블록을 규칙의 단일 출처로 가리킨다.

검증

• RED: tests/unit/guide-content.test.ts에 두 검사를 먼저 붙인다. 구현·릴리스 단계의 gate가 브라우저 검사를 요구하는지, completionTemplate이 브라우저 검사 줄을 담는지다. 지금 이 파일은 gate가 비지 않았는지만 보고(37행) 템플릿은 RED/GREEN·manual-impact· 통합 릴리스만 확인한다(130~132행) — 내용까지 요구하는 검사는 없다.
• GREEN: npm run test, npm run typecheck, npm run lint
• 화면: npx playwright test tests/browser/guide.spec.ts tests/browser/docs.spec.ts
• 완료: npm run build 뒤 npm run test:browser 전체. 이 설계 자체가 요구하는 절차를 이 변경에도 그대로 적용한다.

매뉴얼 영향

manual-impact: affected. 공개 가이드(/guide)와 개발자 매뉴얼(AGENTS.md, README.md)이 같은 변경으로 함께 바뀐다. docs/manual-impact.md를 갱신하고 제품과 매뉴얼을 한 후보로 검증한다. 운영·근거 매뉴얼은 영향 없음 — 배포 절차와 근거 스키마를 건드리지 않는다.

남은 위험

• 헌법의 기술 제약은 프로젝트 경로를 워크스페이스의 lcy_try/lcy_harness로 적고 있으나 현재 작업 저장소는 워크스페이스 바로 아래의 lcy_harness다. 이번 범위 밖이므로 고치지 않고 후속 과제로 남긴다.
• 규칙을 문서에만 두므로 문서에서 규칙이 사라지는 것은 자동으로 잡히지 않는다. 규칙이 실제로 흔들리면 verify-manual.mjs 검사 추가를 후속으로 검토한다.