init: company-haness 설계

2026-07-23 17:49:00 +09:00
parent 57d1bab894
commit f668d6a158
962 changed files with 98989 additions and 1 deletions
@@ -0,0 +1,78 @@
+brief-id: hyeonworks-vnext-v1-direction-input
+parent-workflow-id: hyeonworks-vnext-v1
+product-decision-id: EXEC-CEO-20260718T111108Z
+
+product-goal: >
+  개념명을 알고 있거나 실제 증상만 알고 있는 개발자가 자신에게 맞는 입구에서 시작해 동일한
+  Lost Update 학습 실험으로 합류하고, 상태 변화를 예측·관찰·비교·설명한 뒤 새로운 사례에 전이한다.
+  Hyeonworks는 실제 장애를 확정 진단하지 않으며 메커니즘 후보를 통제된 시나리오로 검증하게 한다.
+
+core-users:
+  primary:
+    who: "기술 정의를 읽었지만 내부 상태 변화와 인과를 설명하기 어려운 개발자"
+    context: "면접·설계·동시성 문제 학습에서 Lost Update가 왜 발생하는지 직접 확인하려 한다"
+    expertise: "코드와 기본 SQL은 읽지만 트랜잭션 스케줄과 격리 메커니즘은 부분적으로 안다"
+  secondary:
+    who: "예상과 다른 최종값을 관찰했지만 관련 개념명을 모르는 실무 개발자"
+    context: "검색 답을 적용하기 전에 어떤 메커니즘을 검증해야 하는지 학습하려 한다"
+
+core-tasks:
+  - id: choose-entry
+    task: "개념을 알고 있는지 증상만 알고 있는지에 따라 두 출발점 중 하나를 선택한다"
+  - id: orient-concept
+    task: "Concurrency → Transaction Isolation → Lost Update 관계와 학습 질문을 이해한다"
+  - id: orient-symptom
+    task: "기대 120·실제 70, 동시 실행, 동일 초기값 읽기 단서로 가능한 메커니즘을 좁힌다"
+  - id: merge-lab
+    task: "두 출발점 모두 tx-lost-update-01 Lab Brief에서 같은 목표와 가정을 확인한다"
+  - id: complete-loop
+    task: "Predict → Observe → Compare → Explain → Transfer를 키보드와 모바일로 완주한다"
+  - id: understand-boundary
+    task: "guided scenario와 실제 운영 장애 확정의 차이를 이해한다"
+
+information-density: >
+  첫 화면은 장황한 마케팅 랜딩이나 넓은 카탈로그가 아니라 선택 가능한 두 입구와 하나의 공통 학습
+  목적을 한 화면 안에서 이해시키는 학습 도구다. 실험 화면은 두 세션의 읽기·계산·쓰기 순서와 값 변화,
+  예측 대비 실제 결과, 인과 설명을 동시에 비교할 수 있는 중간~높은 밀도를 허용하되 모바일에서는
+  순차 정보로 재배치한다.
+
+required-accessibility:
+  - "WCAG AA 이상 텍스트·컨트롤 대비와 명시적 focus-visible"
+  - "360/768/1280px에서 가로 스크롤 없이 Transfer까지 완주"
+  - "Tab·Enter·Space만으로 진입 선택, 단서 공개, 예측, 단계 실행, 설명 제출 가능"
+  - "세션·충돌·정답 상태를 색뿐 아니라 텍스트·아이콘·형태로 구분"
+  - "실험 단계 변화는 aria-live로 알리고 focus를 예측 가능하게 유지"
+  - "prefers-reduced-motion에서 전환·강조 애니메이션 제거"
+
+brand-constraints: >
+  Hyeonworks는 정확한 사고를 돕는 기술 학습 도구다. 차분하지만 무미건조하지 않고, 사용자가 스스로
+  가설을 세우고 증거를 읽는 느낌을 준다. '두 입구, 하나의 Lab'을 명확히 하며, 증상 경로는 진단·원인
+  확정이 아니라 가능한 메커니즘을 좁히는 학습 시나리오로 표현한다. 한국어가 기본이며 코드·DB 용어는
+  원어를 병기한다.
+
+avoid-cliches:
+  - "보라색 SaaS 그라디언트, 유리 효과, 의미 없는 KPI 카드"
+  - "네온 초록 터미널·해커 미학·과도한 경고색"
+  - "탐정 사건 파일·경찰 테이프처럼 실제 incident 진단 제품으로 오인시키는 은유"
+  - "완성 콘텐츠 하나를 거대한 기술 지도나 클릭 가능한 가짜 카탈로그로 부풀리는 화면"
+  - "두 진입마다 별도 디자인 시스템·진행 상태·설명 콘텐츠를 만드는 구조"
+  - "드래그 전용 타임라인과 색만으로 구분하는 세션 상태"
+
+representative-screen-requirement:
+  id: dual-entry-shared-lab
+  kind: first-entry
+  description: >
+    한 제품 안에 '개념을 알고 있어요'와 '증상만 알고 있어요' 두 출발점을 명확히 보여주고,
+    두 경로 모두 동일한 Lost Update Lab으로 연결된다는 사실을 첫 화면에서 이해시키는 대표 화면.
+    Concurrency → Transaction Isolation → Lost Update의 짧은 경로, 증상 요약, guided scenario 경계,
+    공통 학습 루프, 하나의 활성 콘텐츠와 준비 중 roadmap을 포함한다.
+  must-support-states: [default, keyboard-focus, compact-mobile, reduced-motion]
+
+tech-platform-constraints:
+  runtime: "새 browser-local 정적 애플리케이션; architecture 단계에서 stack 재확정"
+  state-model: "single scenario registry + pure deterministic reducer; Date.now/Math.random/network 결과 금지"
+  shared-core: "두 entryMode는 orientation 메타데이터일 뿐 합류 후 reducer와 콘텐츠를 분기하지 않음"
+  navigation: "정적 호스팅 안전 route; 실제 학습 route와 개발용 검증 route 분리"
+  dependency: "필요 최소 의존성; 범용 state-machine·diagram 프레임워크 금지"
+  render-gate: "production build + 실제 browser DOM/keyboard + 360/768/1280 render"
+  trust-gate: "guided scenario 가정·한계와 '검증할 후보 메커니즘' 표현을 모든 증상 경로에 유지"
@@ -0,0 +1,101 @@
+boundary-id: hyeonworks-vnext-v2-ground-boundary
+workflow-id: hyeonworks-vnext-v2
+stage: discovery
+declared-by: HUMAN-001
+declared-at: '2026-07-20'
+posture: "문제 공간 고정, 해결 공간 개방 (category redefinition 허용, 무제한 재정의는 아님)"
+
+fixed-problem-space:
+  target-user: >-
+    복잡한 시스템 동작을 정적 문서만으로 이해하기 어렵거나, 증상·결과를 내부 상태 변화와
+    인과관계에 연결하기 어려운 개발자.
+  out-of-scope-forever:
+    - 실제 장애 확정(운영 incident 진단 제품으로 확장 금지)
+    - 운영 로그 분석
+    - 원격 DB 연결
+    - AI 자동 진단
+  invariants-to-preserve:
+    - 인과적 정확성
+    - 증거 정직성(LIVE vs RULE-DERIVED 등 실행 근거와 파생 추론의 구분)
+    - 접근성
+    - 모바일 사용성
+
+open-solution-space:
+  description: >-
+    아래 항목은 v1이 확정했으나 이번 discovery에서 재검토 대상이다. hard constraint로 상속하지 않고
+    'prior decisions under review / baseline for comparison'으로만 취급한다. 새 근거에서 다시
+    우세할 때만 유지한다.
+  under-review:
+    - "제품 규정: Technology Atlas / Transaction Learning Lab"
+    - "Lost Update 단일 주제"
+    - "depth-before-breadth"
+    - "카탈로그형 확장"
+    - "개념/증상 dual-entry"
+    - "Predict→Observe→Compare→Explain→Transfer 고정 루프"
+    - "콘텐츠 모델"
+    - "반복 방문 가치"
+    - "배포 및 향후 유료 가치"
+  baseline-refs:
+    - path: hyeonworks/completion-records/hyeonworks-vnext-v1/EXEC-CEO-20260718T111108Z.report.yaml
+      note: >-
+        v1 executive-decision-packet(OPT-DUAL-PORTAL 선택). baseline이며 계승할 결정이 아니다.
+        자체 dissent 2건("Dual Portal이 두 제품처럼 보이면 선택 근거가 사라진다", "사용자 실측 전에는
+        두 카드가 시작률을 높이는지 알 수 없다")은 이번 사이클의 반증 대상이다.
+    - path: hyeonworks/app/dist/index.html
+      note: v1 released 실물. 현행 대안(status quo)으로서 비교 기준.
+
+mandated-option-set:
+  count: "3~4 (초과 금지)"
+  required:
+    - id: OPT-A-DEPTH-FIRST
+      label: Depth-first flagship
+      thesis: 대표 메커니즘 하나의 학습 깊이·상호작용·피드백·전이를 강화
+    - id: OPT-B-BREADTH-CATALOG
+      label: Breadth-first structured catalog
+      thesis: 일관된 taxonomy 아래 여러 메커니즘을 탐색·학습하는 제품
+    - id: OPT-C-CATEGORY-REDEF
+      label: Category redefinition
+      thesis: 현재 제품 카테고리를 열고 사용자 문제에 적합한 제품 형태를 재정의
+  conditional:
+    - id: OPT-D-STAGED
+      label: Staged strategy
+      admission-rule: >-
+        조사 근거에서 **독립적으로 도출될 경우에만** 추가한다. A와 B를 절충했다는 이유만으로
+        hybrid를 기본 추천하지 않는다. 근거 없이 등장하면 반려 대상이다.
+
+per-option-required-fields:
+  - target user와 painful job
+  - 제품 카테고리와 핵심 가치
+  - 범위 및 콘텐츠 확장 단위
+  - 현재 대안과 실명 경쟁·대체재
+  - 차별화 가설
+  - 학습성과 가설
+  - 유입·반복 방문·수익 가설
+  - 기술·콘텐츠·운영 비용
+  - solo-operability 평가
+  - 주요 trade-off
+  - evidence refs
+  - unresolved assumptions
+  - kill criteria
+  - revisit conditions
+
+evidence-protocol:
+  shared-evidence-pack: >-
+    market/user/competition 근거는 **하나의 공통 pack**으로 만든다. 각 렌즈는 동일한 옵션 집합을
+    그 pack 위에서 평가한다. 옵션별 별도 중복 조사를 하지 않는다.
+  external-evidence-required: >-
+    v1 부모 workflow는 외부 근거가 0건이었다(사내 아티팩트 3건만). 이번 pack은 실명 경쟁·대체재와
+    실제 URL을 포함해야 한다. 사내 근거만으로는 불충분하다.
+  grading: >-
+    실측 데이터 없으면 E2 상한·confidence Med 이하. 외부 URL은 E2 이하. company-context가
+    provisional이므로 회사 문맥 인용은 E2/Med 상한.
+
+non-goals-this-stage:
+  - 옵션 선택·수렴 (→ /decide)
+  - information architecture
+  - wireframe
+  - 시각 방향(색·타이포·메타포)
+  - 디자인 시스템
+  - 프로토타입
+  - 구현
+  - 하나의 안을 옹호하는 서술