5240lab Harness

문서 / README.md

5240lab Harness 공개 사이트

저장소 개요와 개발·검증 명령.

하네스 엔지니어링의 작업 원리, 5240lab 적용 근거와 개선 로드맵을 공개하는 읽기 전용 Next.js 사이트다. 공개 기준 URL은 https://harness.insapien.co.kr이며 안정 페이지는 /, /guide, /5240lab, /roadmap이다.

이 애플리케이션에는 데이터베이스, 로그인·권한 기능, 사용자 분석이 없다. 런타임 서버는 5240lab 저장소나 원본 근거 파일을 읽지 않고, 빌드 전에 검증해 생성한 content/generated/evidence.public.json만 사용한다.

개발 환경과 실행

Node.js 24.x와 npm이 필요하다. 저장소 루트에서 다음을 실행한다.

npm install
npm run dev

개발 서버는 기본적으로 <로컬>에서 열린다. 환경 변수는 선택 사항이며 .env.example에 공개 가능한 이름과 기본값만 있다. HARNESS_RELEASE_ID를 설정하지 않으면 content/release.json의 정적 release ID를 사용한다. 실제 비밀이나 운영 자격 증명을 환경 예제 또는 문서에 넣지 않는다.

콘텐츠 구조

  • content/site.ts: 공개 URL과 네 안정 경로
  • content/harness.ts: 여덟 하네스 계층과 열 단계 작업 흐름
  • content/guide.ts: 가이드 섹션, 문서 타임라인과 작업 템플릿
  • content/layers.ts: 5240lab 계층별 적용 상태와 한계
  • content/evidence.json: 빌드 시 원본과 대조할 비공개 선별 manifest
  • content/generated/evidence.public.json: 런타임이 사용하는 공개 안전 snapshot
  • content/roadmap.ts: 기준선, 개선 과제, 검증 조건과 재판정 예시
  • content/release.json: 정적 release 및 근거 검증 날짜

근거를 추가하거나 행·발췌를 갱신할 때는 근거 관리 가이드를 따른다. content/generated/evidence.public.json은 직접 편집하지 않는다.

검증 명령

변경 범위에 맞는 작은 명령부터 실행하고 완료 전 전체 게이트를 실행한다.

npm test
npm run typecheck
npm run lint
npm run verify:evidence
npm run verify:content
npm run verify:manual
npm run build
npm run test:browser
npm run verify

npm run test:browser는 Playwright 브라우저가 필요하며, 명령이 자체 개발 서버를 시작한다. 이미 실행 중인 서버나 공개 후보를 검사하려면 PLAYWRIGHT_BASE_URL에 기준 URL을 설정한다. npm run build는 근거, 전체 콘텐츠, 매뉴얼 계약을 먼저 검증하고 Next.js production build와 standalone 런타임 경계 검사를 수행한다. npm run verify는 test, typecheck, lint, 모든 validator, build와 격리된 deployment contract를 포함한다.

로컬 release와 배포 상태

Phase 8의 versioned standalone packaging, 후보 health와 내부 smoke, 원자적 current 전환, 외부 smoke 실패 시 이전 release 복구를 구현·검증했다. 2026-08-14에 systemd/Nginx, DNS/TLS와 공개 URL smoke를 완료했으며 활성 운영 release는 harness-20260814-0b665e7-r2다. 재현 명령과 권한, incident 절차는 운영 매뉴얼, 실행 증거는 배포 보고서에 있다.

기여 흐름

  1. specs/001-harness-public-site/tasks.md의 작업과 기대 동작을 확인한다.
  2. 동작을 바꾸기 전에 실패하는 테스트를 추가하고 RED 이유를 기록한다.
  3. 최소 구현으로 GREEN을 만든 뒤 회귀 검사와 정적 검사를 실행한다.
  4. /guide, 이 README, 근거 관리 가이드, 운영 매뉴얼에 미치는 영향을 판정한다.
  5. 영향이 있으면 코드와 매뉴얼을 함께 수정한다. 영향이 없으면 작업 보고서에 manual-impact: none과 구체적인 이유를 남긴다.
  6. 매뉴얼 영향표를 갱신하고 제품과 매뉴얼을 같은 후보로 검증한다.

기능 완료는 코드 GREEN만 뜻하지 않는다. 최신 자동 검사, 매뉴얼 정합성, 해당하는 배포 스모크가 모두 있어야 한다. T064 외부 배포와 T068 제품·매뉴얼 통합 검증은 완료했다. 로컬 확인 순서는 quickstart, 운영 인터페이스와 사고 대응은 운영 매뉴얼을 참고한다.