Feature Specification: 5240lab 하네스 공개 사이트

Feature Branch: agent/ahp-system Created: 2026-08-13 Status: Draft Input: harness.insapien.co.kr에서 하네스 엔지니어링의 개념·작업법·구성법, 5240lab 적용 근거, 개선과 재판정 방법, 구상부터 구현·매뉴얼 반영까지의 제작 프로세스를 개발자에게 공개한다.

User Scenarios & Testing (mandatory)

User Story 1 - 하네스로 일하는 방법 이해 (Priority: P1)

AI 에이전트를 활용하는 개발자는 하네스가 무엇이고 프롬프트 엔지니어링과 어떻게 다른지 이해한 뒤, 요청에서 설계·기능정의·구현·검증·매뉴얼·배포·재평가까지의 작업 순서를 자신의 프로젝트에 적용하고 싶다.

Why this priority: 적용 방법을 이해하지 못하면 근거와 로드맵도 단순한 사례 목록에 그치므로 사이트의 가장 중요한 사용자 가치다.

Independent Test: /guide만 방문한 개발자가 기능정의서의 작성 시점, spec-kit과 Superpowers의 역할 차이, 매뉴얼 완료 게이트를 찾아 설명하고 작업 시작 템플릿을 사용할 수 있으면 독립적으로 가치를 제공한다.

Acceptance Scenarios:

1. Given 하네스를 처음 접한 개발자, When 랜딩과 가이드를 읽으면, Then 하네스의 정의·역할·구성 계층과 전체 제작 흐름을 확인할 수 있다.
2. Given 새 기능을 시작하려는 개발자, When 문서 타임라인을 확인하면, Then design.md, spec.md, plan.md, tasks.md의 작성 순서와 목적을 구분할 수 있다.
3. Given Superpowers를 사용하려는 개발자, When 활용 절을 읽으면, Then 주요 스킬을 작업 단계, 산출물, 승인 게이트와 연결할 수 있다.
4. Given 기능 구현을 마친 개발자, When 완료 체크리스트를 사용하면, Then 매뉴얼 영향 판정·반영·검증과 통합 배포가 완료 조건임을 확인할 수 있다.
5. Given 다른 도구를 쓰는 개발자, When Superpowers 절을 읽으면, Then 도구가 없어도 동일한 원칙을 수동 하네스로 재현하는 방법을 알 수 있다.

User Story 2 - 5240lab 적용 근거 검토 (Priority: P2)

기술 리더나 개발자는 5240lab이 하네스를 실제로 어떻게 적용했는지 살펴보고, 문서화된 정책과 코드로 강제되는 장치, 실제 실행 기록을 구분해 신뢰도를 판단하고 싶다.

Why this priority: 공개 사이트의 차별점은 일반적인 설명이 아니라 검증 가능한 현장 근거에 있다.

Independent Test: /5240lab만 방문해 계층과 증거 유형을 필터링하고, 각 카드의 상대 경로·행 범위·발췌·확인 시각·검증 상태를 확인할 수 있으면 독립적으로 가치를 제공한다.

Acceptance Scenarios:

1. Given 적용 현황을 조사하는 개발자, When 계층 지도를 탐색하면, Then 컨텍스트·오케스트레이션·명세·격리·가드·검증·배포·매뉴얼 동기화의 적용 내용을 볼 수 있다.
2. Given 근거의 강제력을 구분하려는 사용자, When 증거 카드를 보면, Then 정책, 자동 강제, 실행 기록 유형을 식별할 수 있다.
3. Given 오래되거나 잘못된 근거, When 공개 빌드를 준비하면, Then 사이트가 해당 근거를 확인됨으로 공개하지 않고 빌드를 차단한다.
4. Given 민감한 문자열이나 허용 경계 밖 경로, When 근거를 등록하면, Then 공개 스냅샷에 포함되지 않고 오류 원인을 확인할 수 있다.
5. Given 매뉴얼 제작 하네스를 조사하는 사용자, When 문서화 근거를 보면, Then 리버스 감지·독립 감사·신구 문서 동등성 검증 사례를 확인할 수 있다.

User Story 3 - 개선 실행과 재판정 (Priority: P3)

하네스 운영자는 현재 성숙도를 확인하고, 개선 과제를 실행한 뒤 같은 기준으로 다시 측정해 실제로 강제력과 안전성이 높아졌는지 판정하고 싶다.

Why this priority: 설명과 근거가 갖춰진 뒤 하네스를 지속적으로 개선하는 운영 루프를 완성한다.

Independent Test: /roadmap만 방문해 L0~L4와 100점 평가를 이해하고, 개선 항목의 기준선·목표·검증·판정·근거·재평가일을 확인하며 전후 결과를 비교할 수 있으면 독립적으로 가치를 제공한다.

Acceptance Scenarios:

1. Given 현재 상태를 검토하는 운영자, When 성숙도 화면을 보면, Then 각 계층의 단계와 총점, 산정 기준, 확인 시점을 볼 수 있다.
2. Given 개선 과제를 선택한 운영자, When 상세 내용을 열면, Then 기준선, 기대 효과, 난이도, 검증 방법과 완료 조건을 확인할 수 있다.
3. Given 개선 검증 결과, When 재평가 데이터가 등록되면, Then 이전·현재 점수와 통과, 부분 통과, 실패 판정을 비교할 수 있다.
4. Given 검증을 수행하지 못한 항목, When 상태가 표시되면, Then 성공으로 오인되지 않고 미검증 이유와 남은 위험을 볼 수 있다.
5. Given 매뉴얼 동기화 개선, When 재평가하면, Then 영향 판정률, 기능-매뉴얼 추적성, 통합 배포 결과를 근거로 판단한다.

Edge Cases

• 원본 파일은 존재하지만 지정 행이 이동하거나 발췌문이 바뀐 경우 빌드를 실패시키고 안정 ID와 실패 이유를 보고한다.
• 발췌문 주변에 공개 금지 문자열이 있으면 짧은 발췌라도 공개하지 않는다.
• 같은 근거 ID나 개선 ID가 중복되면 어느 항목도 임의로 덮어쓰지 않는다.
• 근거가 0건인 계층은 적용 완료처럼 보이지 않는 명시적인 빈 상태를 제공한다.
• JavaScript가 꺼지거나 클라이언트 상호작용이 실패해도 핵심 설명과 전체 근거는 읽을 수 있다.
• 점수 입력이 허용 범위를 벗어나거나 가중치 합계가 100이 아니면 평가를 생성하지 않는다.
• 개선 후 점수가 낮아진 경우에도 음수 변화를 숨기지 않고 원인과 함께 표시한다.
• 매뉴얼 영향이 없다고 판정한 기능은 manual-impact: none과 근거가 없으면 완료로 표시하지 않는다.
• 공개 URL의 일부 경로가 실패하면 전체 배포를 성공으로 판정하지 않는다.
• 작은 화면, 확대, 긴 한국어 경로에서도 카드와 코드 발췌가 가로로 페이지를 밀어내지 않는다.

Requirements (mandatory)

Functional Requirements

• FR-001: 사이트는 /, /guide, /5240lab, /roadmap 네 개의 안정적인 공개 경로를 제공해야 한다.
• FR-002: 랜딩은 하네스의 정의, 역할, 프롬프트 엔지니어링과의 차이, 전체 제작 흐름과 각 상세 페이지 진입점을 제공해야 한다.
• FR-003: 전체 제작 흐름은 구상, 컨텍스트, 설계·명세, 구현, 검증, 매뉴얼 동기화, 배포, 피드백·재평가를 포함해야 한다.
• FR-004: 가이드는 요청 계약부터 재평가까지의 실행 가능한 10단계 플레이북을 제공해야 한다.
• FR-005: 가이드는 기능정의서와 설계·계획·작업 문서의 작성 시점, 목적과 승인 게이트를 설명해야 한다.
• FR-006: 가이드는 spec-kit과 Superpowers의 역할을 구분하고 주요 Superpowers 작업 규율을 단계·산출물·게이트와 연결해야 한다.
• FR-007: 가이드는 복사 가능한 작업 시작 템플릿과 완료 체크리스트를 제공해야 한다.
• FR-008: 가이드는 기능의 매뉴얼 영향 판정, 초안, 정합성 검증, 승인, 통합 배포와 영향 없음 기록 방법을 설명해야 한다.
• FR-009: 적용 현황은 5240lab 하네스를 명시된 계층으로 분류하고 각 계층의 설명과 근거를 제공해야 한다.
• FR-010: 모든 근거는 안정 ID, 증거 유형, 공개 상대 경로, 행 범위, 짧은 발췌, 요약, 확인 시각과 검증 상태를 가져야 한다.
• FR-011: 근거 유형은 최소한 정책, 자동 강제, 실행 기록을 구분해야 한다.
• FR-012: 사용자는 계층과 증거 유형으로 근거를 좁혀 볼 수 있어야 하며, 필터 없이도 모든 근거에 접근할 수 있어야 한다.
• FR-013: 공개 준비 과정은 허용된 워크스페이스 내부의 명시된 파일만 읽어야 한다.
• FR-014: 공개 준비 과정은 파일·행 범위·기대 발췌 일치 여부를 검증하고 하나라도 실패하면 공개 빌드를 차단해야 한다.
• FR-015: 공개 준비 과정은 비밀 값, 자격 증명, 절대 서버 경로와 개인 식별 패턴이 탐지된 근거를 차단해야 한다.
• FR-016: 공개 사이트 실행 중에는 원본 5240lab 저장소를 읽지 않고 검증된 공개용 스냅샷만 사용해야 한다.
• FR-017: 로드맵은 L0 미구성, L1 문서화, L2 자동 강제, L3 결과 측정, L4 지속 개선을 정의해야 한다.
• FR-018: 로드맵은 적용 범위, 강제력, 검증 가능성, 추적성, 운영 안전성을 합산한 100점 평가와 산정 기준을 제공해야 한다.
• FR-019: 개선 항목은 기준선, 목표, 기대 효과, 난이도, 검증 방법, 통과 조건, 상태, 근거와 재평가일을 가져야 한다.
• FR-020: 개선 결과는 이전·현재 평가와 점수 차이를 표시하고 통과, 부분 통과, 실패를 구분해야 한다.
• FR-021: 수행하지 못한 검증은 부분 통과 또는 미검증으로 표시하고 이유와 남은 위험을 공개해야 한다.
• FR-022: 매뉴얼 개선은 영향 판정률, 기능-매뉴얼 추적성, 정합성 검증과 앱· 매뉴얼 통합 배포 결과로 재판정해야 한다.
• FR-023: 모든 핵심 설명과 근거는 클라이언트 스크립트 없이도 읽을 수 있어야 한다.
• FR-024: 사이트는 키보드 탐색, 건너뛰기 링크, 순차적인 제목, 보이는 포커스, 상태 텍스트와 동작 감소 설정을 지원해야 한다.
• FR-025: 사이트는 375px부터 1440px까지 정보 손실과 가로 페이지 넘침 없이 사용할 수 있어야 한다.
• FR-026: 사이트는 라이트·다크 모드에서 동일한 정보와 구분 가능한 상태를 제공해야 한다.
• FR-027: 공개 페이지는 현재 근거 검증일과 사이트 릴리스 식별자를 표시해야 한다.
• FR-028: 잘못된 경로는 사이트 탐색으로 돌아갈 수 있는 명확한 404 응답을 제공해야 한다.
• FR-029: 배포는 새 릴리스를 활성화하기 전 내부 상태를 검증하고, 활성화 후 공개 경로 검증 실패 시 직전 정상 릴리스로 복구해야 한다.
• FR-030: 배포 기록은 릴리스 식별자, 검증 결과, 근거 확인 시각, 활성 릴리스와 롤백 결과를 남겨야 한다.

Key Entities

• Evidence Item: 5240lab 적용 주장을 뒷받침하는 공개 가능한 근거. 안정 ID, 계층, 유형, 경로, 행 범위, 발췌, 요약과 검증 메타데이터를 가진다.
• Harness Layer: 하네스를 구성하는 책임 영역. 설명, 작업 단계와 관련 근거를 묶는다.
• Maturity Assessment: 특정 시점의 계층별 L0~L4, 평가 축 점수, 총점과 근거.
• Improvement Item: 기준선에서 목표 상태로 이동하기 위한 과제와 검증·판정 정보.
• Reassessment: 개선 후 동일 기준으로 측정한 결과, 점수 변화와 남은 위험.
• Workflow Step: 하네스로 일하는 순서, 담당 역할, 입력·출력 문서와 통과 게이트.
• Manual Impact Record: 기능이 영향을 주는 사용자·관리자·운영·개발자 문서와 반영·검증 상태 또는 영향 없음 근거.
• Release Record: 배포 대상, 검증 결과, 활성 상태와 롤백 결과를 설명하는 기록.

Documentation Impact (mandatory)

• Affected audiences: 하네스 사이트 독자, 사이트 개발자, 배포·운영 담당자.
• Affected manuals/paths: 공개 /guide가 사용자 매뉴얼 역할을 하고, 프로젝트 README.md와 배포 런북이 개발·운영 매뉴얼 역할을 한다.
• Required evidence: 네 공개 경로의 내용·링크·반응형 화면, 근거 검증 결과, health·배포·롤백 명령과 실제 스모크 결과.
• Release condition: 공개 가이드와 개발·운영 매뉴얼이 구현과 일치하고, 제품과 매뉴얼 경로의 통합 검증이 모두 통과해야 한다.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 처음 방문한 개발자가 3분 안에 하네스의 정의와 전체 제작 흐름을 찾고, 기능정의서가 구현 전에 작성된다는 점을 식별할 수 있다.
• SC-002: 가이드의 모든 작업 단계가 입력, 산출물 또는 통과 조건 중 최소 하나와 연결되고, 문서 타임라인의 네 문서가 각각 고유한 목적을 제공한다.
• SC-003: 공개된 근거의 100%가 빌드 시 파일·행·발췌 검증을 통과하고 공개 금지 패턴 탐지 건수가 0이다.
• SC-004: 사용자가 2번 이하의 조작으로 원하는 계층 또는 증거 유형의 근거만 확인할 수 있으며, 필터를 초기화해 전체 목록으로 돌아갈 수 있다.
• SC-005: 모든 개선 항목이 기준선, 검증 방법과 완료 조건을 가지며, 재평가된 항목은 이전·현재 점수와 판정 근거를 빠짐없이 제공한다.
• SC-006: 핵심 콘텐츠와 근거의 100%를 클라이언트 스크립트 없이 읽을 수 있다.
• SC-007: 375px, 768px, 1024px, 1440px에서 네 경로의 핵심 콘텐츠 손실과 수평 페이지 넘침이 0건이다.
• SC-008: 키보드만으로 전체 탐색과 모든 필터·공개/접기 동작을 완료할 수 있고, 자동 접근성 검사에서 심각 또는 중대 위반이 0건이다.
• SC-009: 새 배포는 네 공개 경로, 상태 확인, 정적 자산과 404 검사를 모두 통과하며, 실패를 주입한 배포 연습에서 직전 정상 릴리스가 복구된다.
• SC-010: 기능-매뉴얼 영향 판정률이 100%이고, 영향 있음 기능은 관련 매뉴얼의 정합성·링크·공개 경로 검증을 모두 통과한다.

Assumptions

• 공개 사이트는 인증 없이 읽을 수 있고 검색 엔진 색인을 허용한다.
• v1 콘텐츠는 사람이 선별하며 자동 스캔은 선별된 근거의 유효성만 검증한다.
• 근거 원본은 빌드가 실행되는 5240lab 워크스페이스에서 접근할 수 있다.
• 공개 근거는 5240lab 내부의 비공개 구현을 재구성할 수 없도록 짧고 제한적으로 제공한다.
• 초기 평가와 로드맵은 2026-08-13 조사 결과를 기준선으로 사용한다.
• 사이트는 읽기 중심이며 서버 측 사용자 데이터와 장기 저장소가 필요하지 않다.
• 초기 배포 서버에는 Nginx, systemd, Node.js와 TLS 발급 환경이 준비되어 있다.
• 브라우저 화면 캡처는 설명이 복잡한 흐름과 반응형 검증 증거에만 사용한다.

Out of Scope

• 저장소 전체를 실시간 분석하거나 외부 사용자가 근거 경로를 입력하는 기능
• 사이트에서 5240lab 설정·코드·성숙도 데이터를 수정하는 기능
• 로그인, 댓글, 문의, 분석 추적과 사용자 데이터 저장
• GitHub 원문 연결, 전체 코드 발췌와 절대 서버 경로 공개
• 영문판, 다국어 번역과 CMS 편집 화면