작업 범위: T013–T021
기준일: 2026-08-13 UTC
상태: DONE
manual-impact: affected
매뉴얼 영향
공개 사용자 매뉴얼인 /guide를 placeholder에서 실행 가능한 가이드로 교체했다.
하네스 정의, 문서 작성 시점, 열 단계 플레이북, spec-kit/Superpowers 역할 경계,
매뉴얼 완료 게이트와 시작·완료 템플릿을 서버 HTML로 제공한다. 랜딩 /도 이
작업법과 /guide, /5240lab, /roadmap 진입점을 함께 설명한다.
개발자 README.md, 근거 관리자 docs/evidence-maintenance.md, 운영자
docs/operations.md는 각각 T051, T033, T052 범위이므로 이 단계에서 선행 생성하지
않았다. 공개 가이드와 제품은 같은 Next.js 정적 빌드 산출물로 통합되었고 unit,
서버 렌더, typecheck, lint, build 검증을 함께 통과했다. 브라우저 스모크도
승인된 상위 실행 환경에서 키보드와 네 반응형 크기 계약을 모두 통과했다.
RED
구현 전에 콘텐츠, 서버 렌더, 브라우저 계약을 먼저 작성했다.
| 명령 | 결과 |
|---|---|
npm run test:unit -- tests/unit/guide-content.test.ts |
FAIL (exit 1) — Cannot find module '../../content/guide' |
node --import tsx tests/integration/guide-pages.test.tsx |
FAIL (exit 1), 0/3 — placeholder에 What/Why/How 제목, 가이드 목차와 <pre> 템플릿 부재 |
PLAYWRIGHT_BASE_URL=<로컬> npx playwright test tests/browser/guide.spec.ts --reporter=list |
BLOCKED before assertions — 5개 테스트를 찾았으나 Chromium launch에서 SIGTRAP |
브라우저 RED는 제품 계약의 실패로 해석하지 않았다. 설치된 Chromium headless shell이 프로세스를 시작한 직후 다음 인프라 오류로 종료되었기 때문이다.
[FATAL:content/browser/sandbox_host_linux.cc:41]
Check failed: . shutdown: Operation not permitted (1)
process did exit: exitCode=null, signal=SIGTRAP
GREEN
| 명령 | 결과 |
|---|---|
npm run test:unit |
PASS — 3/3 test files, guide content 계약 포함 |
npm run test:integration |
PASS — 3/3 test files, landing/guide SSR 계약 포함 |
npm run typecheck |
PASS |
npm run lint |
PASS |
npm run build |
PASS — /와 /guide 포함 4개 공개 경로 정적 사전 렌더 |
npx playwright test tests/browser/guide.spec.ts --list |
PASS — 키보드 1개와 375/768/1024/1440px 4개, 총 5개 수집 |
PLAYWRIGHT_BASE_URL=<로컬> npx playwright test tests/browser/guide.spec.ts --reporter=list |
BLOCKED — 5/5 모두 assertion 전 동일 Chromium sandbox host SIGTRAP |
npx playwright test tests/browser/guide.spec.ts (승인된 상위 실행) |
PASS — 5/5 (4.6s), 키보드 탐색과 375/768/1024/1440px layout·수평 overflow 계약 |
제한된 sandbox의 Chromium launch 실패는 프로덕트 실패가 아닌 실행 권한 제약으로 확인됐다. 같은 test file을 승인된 상위 환경에서 실행해 모든 assertion이 성공했으므로 브라우저 GREEN을 최종 검증 결과로 판정한다.
구현 결과
- 정확한 열 단계와 각 단계의 목적·산출물·통과 조건을 구조화했다.
design.md→spec.md→plan.md→tasks.md순서와 기능 정의가 설계 승인 후 구현 전에 작성된다는 계약을 명시했다.- spec-kit은 WHAT, Superpowers는 HOW라는 경계를 brainstorming, TDD, subagent-driven/executing-plans, verification-before-completion에 연결했다.
- 코드 동작 이후에도 공개·개발자·근거 관리자·운영자 매뉴얼 갱신 또는
manual-impact: none근거, 제품+매뉴얼 통합 릴리스와 스모크가 필요함을 완료 게이트로 제시했다. - 랜딩을 과장된 성과 수치 없이 What/Why/How와 세 상세 경로 중심으로 구성했다.
- 가이드에 로컬 목차, 의미 있는 제목 구조, 일반 텍스트
<pre>템플릿, 반응형 및 print-safe 규칙을 추가했다. 핵심 콘텐츠에 클라이언트 컴포넌트나 clipboard JS를 사용하지 않았다.
남은 우려와 task 상태
- T013–T021은 RED→GREEN 구현과 자동 검증을 모두 완료했다.
- 제한된 sandbox 내 Chromium은 sandbox host 권한 제약으로 실행할 수 없었지만, 승인된 실행으로 같은 5개 브라우저 계약을 모두 통과해 잔여 제품 우려는 없다.