5240lab Harness Website Constitution

Core Principles

I. 근거가 주장보다 먼저다

사이트가 5240lab의 적용 상태를 설명할 때 모든 실질 주장은 검증 가능한 근거를 가져야 한다. 근거는 공개가 허용된 상대 경로, 행 범위, 짧은 발췌, 검증 시각과 판정 상태를 포함해야 한다. 정책 문서, 자동 강제 장치, 실행 기록을 서로 다른 증거 유형으로 표시해야 하며, 확인하지 못한 내용을 적용 완료로 표현해서는 안 된다.

II. 명세와 승인 게이트가 구현을 선행한다

모든 기능은 승인된 설계와 spec.md, plan.md, tasks.md에서 시작해야 한다. 설계 승인 전에는 코드를 작성하지 않고, 명세 승인 게이트 전에는 구현을 시작하지 않는다. 요청 범위와 완료 조건을 바꾸는 결정은 관련 문서에 먼저 반영하고 사용자 승인을 받아야 한다.

III. 테스트 우선과 실제 검증 (NON-NEGOTIABLE)

행동 변경은 실패하는 자동화 테스트를 먼저 확인하고 RED → GREEN → REFACTOR 순서로 구현해야 한다. 완료 여부는 설명이나 예상이 아니라 실제 테스트, 정적 검사, 프로덕션 빌드, 브라우저 검사와 배포 후 스모크 결과로 판정한다. 수행하지 못한 검증은 성공으로 간주하지 않고 이유와 남은 위험을 기록해야 한다.

IV. 매뉴얼은 제품의 일부다

기능정의서에는 매뉴얼 영향 여부를 반드시 기록하고, 작업 목록은 코드와 매뉴얼 변경을 같은 기능 아래 추적해야 한다. 사용자·관리자·운영자에게 영향을 주는 변경은 매뉴얼 초안, 기능과의 정합성 검증, 공개 경로 확인까지 마쳐야 완료로 판정한다. 영향이 없는 경우에도 manual-impact: none과 근거를 남겨야 한다. 프로그램과 매뉴얼은 동일한 릴리스 준비 게이트에서 승인해야 한다.

V. 공개 경계와 최소 권한

웹 런타임은 원본 5240lab 저장소를 직접 읽어서는 안 되며 빌드 시 검증된 공개용 스냅샷만 사용해야 한다. 절대 서버 경로, 자격 증명, 토큰, 개인 식별 정보와 운영 비밀은 빌드 단계에서 차단한다. 근거 수집기는 허용된 워크스페이스 경계 안의 명시된 파일만 읽고, 배포 서비스는 필요한 파일과 네트워크 권한만 가져야 한다.

VI. 접근 가능한 점진적 공개

핵심 설명과 근거는 JavaScript 없이도 읽을 수 있는 서버 렌더링 HTML로 제공해야 한다. 키보드 탐색, 순차적인 제목 구조, 보이는 포커스, 충분한 명도 대비와 prefers-reduced-motion을 지원해야 한다. 375px부터 1440px까지 정보 손실 없이 동작하고, 상호작용은 설명을 보조하되 콘텐츠 접근의 전제가 되어서는 안 된다.

기술 및 운영 제약

• 프로젝트는 <프로젝트 루트> 경계 안에서 독립적으로 구현하고 형제 프로젝트의 사용자 변경을 수정하거나 스테이징하지 않는다.
• 공개 사이트는 한국어 개발자 독자를 우선하며 /, /guide, /5240lab, /roadmap, /docs 다섯 개의 안정적인 경로를 제공한다. /docs는 매니페스트에 선언한 문서만 공개하며, 빌드 시 검증된 스냅샷만 런타임에 전달한다.
• 구조화된 콘텐츠와 표현 컴포넌트를 분리하고, 근거 스키마와 성숙도 계산은 UI 없이 독립적으로 테스트할 수 있어야 한다.
• 새 런타임 데이터베이스와 사용자 인증은 v1 범위에 포함하지 않는다.
• 배포는 버전별 release, 사전 health 검사, 원자적 활성 release 전환과 실패 시 직전 release 복구 절차를 가져야 한다.
• 도메인은 harness.insapien.co.kr이며 HTTPS, 보안 헤더, 외부 URL 스모크를 릴리스 완료 조건으로 사용한다.

개발 워크플로와 품질 게이트

1. 브레인스토밍에서 대안을 비교하고 사용자에게 설계 승인을 받는다.
2. 기능정의서에 사용자 시나리오, 수용 조건, 공개 범위와 매뉴얼 영향을 기록한다.
3. 기술계획에 근거 데이터 흐름, 실패 처리, 접근성, 배포·롤백과 매뉴얼 검증을 포함한다.
4. 작업목록은 테스트를 구현보다 앞에 배치하고 기능별 매뉴얼 작업을 포함한다.
5. 명세 산출물의 범위와 검증 기준을 승인받기 전에는 구현하지 않는다.
6. 구현은 최소 관련 테스트의 RED → GREEN 기록과 독립 검토 증거를 남긴다.
7. 완료 전 verify 전체 게이트, 접근성·반응형 브라우저 검사와 매뉴얼 정합성 검사를 수행한다.
8. 새 release를 사전 검증하고 HTTPS 배포 후 네 경로와 health endpoint를 스모크 검사한다. 실패하면 직전 release로 복구하고 결과를 기록한다.
9. 개선 과제는 기준선 → 실행 → 검증 → 근거 등록 → 성숙도 재평가 순서로 닫는다.
10. 명세와 구현은 각각 별도의 사용자 커밋 승인 게이트를 통과해야 한다.

Governance

이 헌법은 프로젝트 내 다른 개발 관행보다 우선한다. 원칙을 변경하려면 변경 이유, 영향을 받는 템플릿·기능·매뉴얼과 마이그레이션 방법을 문서화하고 사용자 승인을 받아야 한다. 원칙 제거나 의미 변경은 MAJOR, 필수 원칙·게이트 추가는 MINOR, 의미를 바꾸지 않는 명확화는 PATCH 버전으로 올린다. 모든 계획과 완료 검토는 헌법 준수 여부를 명시하고, 예외는 plan.md의 Complexity Tracking에 근거와 대안을 기록해야 한다.

Version: 1.0.0 | Ratified: 2026-08-13 | Last Amended: 2026-08-13