Branch: agent/ahp-system | Date: 2026-08-13 | Spec: spec.md
Input: Feature specification from /specs/001-harness-public-site/spec.md
Summary
개발자를 대상으로 하네스 엔지니어링의 개념·작업법·구성법, 5240lab 적용 근거, 개선 후 재판정과 코드-매뉴얼 통합 제작 과정을 설명하는 공개 사이트를 만든다. Next.js App Router의 서버 컴포넌트를 기본으로 사용하고, 사람이 선별한 근거를 빌드 전에 원본 파일과 대조해 공개용 스냅샷으로 생성한다. 런타임은 원본 저장소에 접근하지 않는다. standalone release를 사전 health 검증하고 원자적으로 전환하며, 외부 스모크 실패 시 직전 release로 복구한다.
Technical Context
Language/Version: TypeScript 5.9.x, Node.js 24.18.0
Primary Dependencies: Next.js 16.3.0, React 19.2.8, React DOM 19.2.8,
Lucide React; 개발 도구로 ESLint, tsx, Playwright, axe-core
Storage: 저장소 내 구조화 TypeScript 콘텐츠, 선별 evidence.json, 빌드 생성
공개 스냅샷. 런타임 데이터베이스 없음
Testing: Node test runner + tsx, React 서버 렌더 계약 테스트, Playwright 브라우저
검사, axe 접근성 검사, TypeScript, ESLint, Next.js production build, HTTP smoke
Target Platform: Nginx와 systemd가 있는 Linux 서버, 최신 데스크톱·모바일 브라우저
Project Type: 공개 읽기 전용 Next.js 웹 애플리케이션
Performance Goals: 네 핵심 경로의 사전 렌더 HTML 제공, 첫 HTML 200KB 이하,
핵심 콘텐츠가 보이는 로컬 브라우저 검사 2초 이내
Constraints: 한국어 단일 언어, 인증·DB·분석 없음, 런타임 저장소 접근 금지,
공개 안전 근거만 포함, JavaScript 없이 핵심 콘텐츠 사용 가능, 375~1440px 대응
Scale/Scope: 공개 경로 4개 + health/robots/sitemap/404, 하네스 계층 8개,
초기 근거 약 15~25개, 초기 개선 항목 약 8~12개
Constitution Check
GATE: Phase 0 이전 및 Phase 1 설계 후 재검토 — PASS.
- 근거 우선 — PASS: 원본 파일·행·발췌·공개 금지 패턴 검증을 빌드 차단 게이트로 두고 증거 유형과 확인 시각을 표시한다.
- 명세 선행 — PASS: 승인된 설계, spec, plan, tasks를 구현 전에 완성하고 명세 커밋 게이트에서 중단한다.
- 테스트 우선 — PASS: 근거 검증, 점수 계산, 렌더 계약과 사용자 흐름 테스트를 먼저 실패시킨 뒤 구현한다. 전체 verify와 브라우저 검사를 완료 조건으로 둔다.
- 매뉴얼 포함 — PASS:
/guide,README.md,docs/evidence-maintenance.md,docs/operations.md를 코드와 같은 작업·릴리스 게이트에서 검증한다. - 공개 경계 — PASS: 빌드 도구만 상대 경로로 워크스페이스를 읽고 런타임에는 공개 스냅샷만 포함한다. 민감 패턴은 빌드를 차단한다.
- 접근성 — PASS: 서버 HTML, skip link, 의미 구조, 키보드 필터, 상태 텍스트, 시스템 다크 모드와 reduced-motion을 설계에 포함한다.
- 배포 안전 — PASS: 버전별 standalone release, 후보 health, 원자적 전환, 외부 스모크와 자동 복구를 포함한다.
Phase 1 산출물 검토 후에도 새 런타임 저장소나 사용자 데이터가 없고, 모든 공개 데이터가 검증 스냅샷 경계를 통과하므로 헌법 준수 결과는 동일하게 PASS다.
Evidence and Manual Synchronization
- Evidence source boundary: 프로젝트 루트에서
../..로 해석되는 5240lab 워크스페이스만 허용하고, manifest에 명시된 POSIX 상대 경로만 읽는다. 심볼릭 링크 해석 후에도 경계 내부인지 재확인한다. - Evidence validation: 파일·양의 행 범위·기대 발췌 일치, 안정 ID 중복, 증거 유형, 날짜 형식, 절대 경로·자격 증명·토큰·개인정보 패턴을 검사한다. 실패하면 스냅샷과 빌드를 생성하지 않는다.
- Documentation impact: 공개
/guide, 개발자README.md, 근거 관리자docs/evidence-maintenance.md, 운영자docs/operations.md가 영향받는다. - Manual validation: 공개 가이드는 렌더 계약과 브라우저 링크 검사로, 저장소
매뉴얼은 명령·경로·health·롤백 절차 대조로 검증한다. 각 기능 작업은 매뉴얼 영향
또는
manual-impact: none을 task report에 남긴다. - Coordinated release: 코드·공개 가이드·저장소 매뉴얼을 한 release로 묶고 후보 release에서 네 경로와 health를 검사한다. 활성화 후 HTTPS 검사 실패 시 이전 release로 복구하고 배포 기록에 결과를 남긴다.
Project Structure
Documentation (this feature)
specs/001-harness-public-site/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│ ├── evidence-manifest.md
│ ├── maturity-assessment.md
│ └── public-routes.md
├── checklists/
│ └── requirements.md
└── tasks.md
Source Code (repository root)
app/
├── api/health/route.ts
├── guide/page.tsx
├── 5240lab/page.tsx
├── roadmap/page.tsx
├── layout.tsx
├── page.tsx
├── not-found.tsx
├── robots.ts
├── sitemap.ts
└── globals.css
components/
├── EvidenceExplorer.tsx
├── EvidenceCard.tsx
├── HarnessFlow.tsx
├── MaturityScore.tsx
├── SiteHeader.tsx
└── ui/
content/
├── evidence.json
├── generated/evidence.public.json
├── guide.ts
├── harness.ts
└── roadmap.ts
lib/
├── evidence-schema.ts
├── evidence.ts
├── maturity.ts
└── release.ts
scripts/
├── verify-evidence.ts
├── verify-content.ts
└── smoke.mjs
tests/
├── unit/
├── integration/
└── browser/
deploy/
├── build-release.sh
├── deploy.sh
├── harness.service
└── nginx.conf
docs/
├── evidence-maintenance.md
└── operations.md
README.md
Structure Decision: 단일 Next.js 애플리케이션 안에서 페이지·프레젠테이션
컴포넌트·구조화 콘텐츠·순수 검증 로직을 분리한다. 검증 스크립트는 빌드 시에만
워크스페이스 원본을 읽고 content/generated를 만든다. 페이지는 생성 스냅샷과
정적 콘텐츠만 import하므로 standalone 런타임의 파일 권한과 배포 경계가 단순하다.
Complexity Tracking
헌법 예외가 없으므로 기록할 위반 사항이 없다.