5240lab Harness

문서 / docs/superpowers/specs/2026-08-13-harness-website-design.md

5240lab 하네스 공개 사이트 설계

공개 사이트의 정보 구조와 네 경로를 정한 최초 설계.

1. 목적

harness.insapien.co.kr은 개발자에게 하네스 엔지니어링의 개념과 구성 방법을 설명하고, 5240lab에 실제 적용된 장치를 검증 가능한 근거와 함께 공개하는 한국어 사이트다. 개선 제안은 정적인 희망 목록이 아니라 기준선, 실행, 검증, 재판정을 연결한 운영 루프로 보여준다.

이 사이트가 말하는 하네스의 범위는 프롬프트나 코딩 자동화에 한정되지 않는다. 아이디어가 기능정의서와 기술계획을 거쳐 구현되고, 검증된 동작이 사용자·관리자· 운영자 매뉴얼에 반영되어 배포되는 전체 제작 프로세스를 포함한다.

2. 대상과 범위

  • 주 독자: AI 에이전트를 활용해 제품을 만드는 개발자와 기술 리더
  • 언어: v1은 한국어 단일 언어
  • 공개 수준: 상대 경로, 행 번호, 짧은 발췌와 검증 결과. 절대 경로·자격 증명· 비공개 원문 링크는 공개하지 않는다.
  • 프로젝트 위치: 이 저장소의 lcy_harness 프로젝트 루트
  • 공개 URL: https://harness.insapien.co.kr

포함

  1. 하네스의 정의, 역할, 계층과 단계별 구성법
  2. 하네스로 실제 일하는 10단계 플레이북
  3. 기능정의서·기술계획·작업목록의 작성 시점과 역할
  4. spec-kit과 Superpowers의 역할 분담 및 활용법
  5. 코드에서 매뉴얼까지 이어지는 문서 동기화 게이트
  6. 5240lab 적용 내용과 공개 가능한 근거
  7. 성숙도 단계, 100점 평가와 개선 전후 재판정
  8. 사이트 자체의 검증, 배포, 롤백과 운영 매뉴얼

제외

  • 저장소 실시간 스캔과 원본 파일의 런타임 제공
  • 로그인, 편집 UI, 데이터베이스
  • 비공개 GitHub 저장소 링크와 전체 코드 공개
  • 자동으로 5240lab 설정을 수정하는 기능
  • 영문 번역

3. 정보 구조

/

  • “모델보다 먼저, 일하는 환경을 설계합니다”라는 핵심 메시지
  • 구상 → 컨텍스트 → 설계·명세 → 구현 → 검증 → 매뉴얼 동기화 → 배포 → 피드백·재평가 흐름
  • 프롬프트 엔지니어링과 하네스 엔지니어링의 차이
  • 핵심 지표와 세부 페이지 진입 카드

/guide

  • 하네스로 일하는 10단계 플레이북
  • design.md → spec.md → plan.md → tasks.md 문서 타임라인
  • spec-kit은 “무엇을”, Superpowers는 “어떻게”를 통제한다는 역할 분담
  • brainstorming, systematic-debugging, test-driven-development, executing-plans, subagent-driven-development, verification-before-completion, finishing-a-development-branch 활용표
  • 최소 구성 → 팀 구성 → 운영 구성 레시피
  • 복사 가능한 요청 계약과 완료 체크리스트
  • 코드-매뉴얼 동기화 절차와 manual-impact: none 판정 규칙

/5240lab

  • 컨텍스트 주입, 스킬 라우팅, 명세, 작업 격리, 실행 가드, 테스트·평가, 배포, 매뉴얼 동기화의 적용 지도
  • 각 항목을 정책, 자동 강제, 실행 기록으로 분류
  • 상대 경로, 행 범위, 짧은 발췌, 확인 시각과 검증 상태
  • RED/GREEN 보고서, Oracle 읽기 전용 가드, 공유 DB 격리, 문서 감사, 신구 사이트 parity, 리버스 변경 감지 사례
  • 적용이 강한 영역과 선언 수준에 머문 영역을 구분

/roadmap

  • 계층별 현재 성숙도 L0~L4
  • 적용 범위, 강제력, 검증 가능성, 추적성, 운영 안전성의 총 100점 평가
  • 매뉴얼 동기화율, 기능-매뉴얼 추적성, 앱·매뉴얼 배포 동시성 지표
  • 개선 과제별 기준선, 목표, 검증 명령, 통과 조건, 근거, 재평가일
  • 즉시·단기·중기·장기 우선순위
  • 개선 전후 점수와 통과, 부분 통과, 실패 상태

4. 제작 프로세스

  1. 요청 계약: 목표, 범위, 완료 조건을 정한다.
  2. 브레인스토밍: 대안을 비교하고 설계를 승인한다.
  3. 기능 정의: spec.md에 기능과 수용 조건, 매뉴얼 영향을 기록한다.
  4. 기술 설계: plan.md, 데이터 모델, 인터페이스, 실패 처리를 작성한다.
  5. 작업 분해: tasks.md에 테스트, 구현, 매뉴얼과 배포를 같은 기능 아래 묶는다.
  6. 격리 구현: 프로젝트 경계 안에서 RED → GREEN → REFACTOR로 구현한다.
  7. 독립 검토: diff, 테스트 결과, 미검증 위험을 기록한다.
  8. 매뉴얼 동기화: 코드와 기존 매뉴얼을 대조하고 초안·검증·승인을 수행한다.
  9. 통합 배포: 앱과 매뉴얼 공개 경로를 함께 스모크 검사한다.
  10. 재평가: 근거와 운영 피드백으로 성숙도와 다음 과제를 갱신한다.

기능 완료의 정의는 “코드가 동작함”이 아니다. 검증된 동작이 필요한 매뉴얼에 반영되고 사용자가 접근할 수 있을 때 완료된다. 매뉴얼 영향이 없으면 생략이 아니라 manual-impact: none과 판정 근거를 남긴다.

5. 기술 아키텍처

Next.js App Router를 사용한다. 페이지는 서버 컴포넌트를 기본으로 하고 필터, 접기와 같은 최소 상호작용만 클라이언트 경계로 둔다. 콘텐츠는 구조화된 TypeScript 데이터와 사람이 선별한 evidence.json으로 관리한다.

빌드 전 검증기는 워크스페이스 내부의 허용된 상대 경로만 해석한다. 파일과 행 범위, 발췌문 일치 여부를 확인하고 비밀 값, 절대 서버 경로와 개인 정보를 탐지한다. 모든 근거가 통과하면 공개용 스냅샷을 생성한다. 웹 런타임은 이 스냅샷만 번들에 포함하며 원본 저장소를 읽지 않는다.

curated evidence.json
        |
        v
source boundary + excerpt + secret validation
        |
        v
generated public evidence snapshot
        |
        v
Next.js server-rendered pages

6. 시각 설계

선택된 방향은 “System Atlas”다. 밝고 정밀한 개발자 포털 인상으로 계층 지도, 근거 카드와 성숙도 지표를 균형 있게 보여준다.

  • 기본 배경: 차가운 회백색, 흰 표면, 짙은 남색 텍스트
  • 강조색: 인디고/보라. 성공은 녹색, 부분 통과는 황색, 실패는 적색
  • 제목: IBM Plex Sans 계열, 기술 레이블과 경로: JetBrains Mono 계열
  • 큰 제목과 충분한 여백, 4/8px 간격 체계, 얕은 테두리와 제한된 그림자
  • 라이트 모드가 기본이며 시스템 다크 모드를 동등한 의미 토큰으로 제공
  • SVG 선형 아이콘만 사용하고 장식용 이모지는 사용하지 않는다.
  • 모든 동작은 키보드로 가능하고 포커스가 보이며 reduced-motion을 지원한다.

7. 근거 모델과 공개 안전성

근거 항목은 안정 ID, 제목, 계층, 증거 유형, 공개 상대 경로, 행 범위, 기대 발췌, 요약, 검증 상태와 검증일을 가진다. 검증기는 다음 조건에서 빌드를 실패시킨다.

  • 파일 또는 행 범위가 존재하지 않음
  • 기대 발췌와 실제 원문이 다름
  • 경로가 허용된 워크스페이스 경계를 벗어남
  • 자격 증명, 토큰, 이메일·개인정보 또는 절대 서버 경로 패턴 발견
  • 미검증 항목이 확인됨으로 표시됨

8. 성숙도와 개선 판정

  • L0 미구성
  • L1 문서화
  • L2 자동 강제
  • L3 결과 측정
  • L4 지속 개선

각 개선은 기준선 → 실행 → 검증 → 근거 등록 → 재평가 상태를 가진다. 구성 파일이 존재한다는 이유만으로 자동 강제로 판정하지 않는다. 예를 들어 CI는 실패 테스트가 보호 브랜치 병합을 실제로 차단한 증거가 있어야 L2 이상이다.

9. 오류 처리와 검증

  • 근거 오류와 민감정보 탐지는 빌드 차단 오류다.
  • 수행하지 않은 검증은 부분 통과와 이유를 표시한다.
  • JavaScript 실패 시에도 핵심 콘텐츠는 HTML로 읽을 수 있어야 한다.
  • 네 경로, 404, health, 정적 자산을 배포 전후에 검사한다.
  • 375, 768, 1024, 1440px과 키보드·reduced-motion을 브라우저에서 검증한다.

10. 배포와 롤백

standalone 빌드를 커밋별 release 디렉터리에 보관한다. 새 release를 임시 포트에서 실행해 health를 확인한 뒤에만 current 링크를 원자적으로 전환한다. systemd 재시작 후 https://harness.insapien.co.kr 외부 스모크가 실패하면 직전 release로 복구한다. Nginx는 HTTPS와 보안 헤더를 담당한다. 배포 보고서에는 커밋, 검증 결과, 근거 확인 시각, 활성 release와 롤백 결과를 기록한다.

11. 설계 승인 기록

  • 대상: 개발자 중심
  • 언어: 한국어
  • 근거 갱신: 사람이 선별하고 빌드가 원본을 검증
  • 공개 수준: 상대 경로·행 번호·짧은 발췌
  • 프레임워크: Next.js
  • 정보 구조: 4개 경로
  • 시각 방향: System Atlas
  • 개선 판정: L0~L4 + 100점 + 개선 전후 증거
  • 제작 범위: 구상부터 구현, 매뉴얼 동기화, 통합 배포와 재평가까지
  • 사용자 최종 승인: 2026-08-13