Skip to content

operatingModel.md

Latest commit

 

History

History
58 lines (44 loc) · 5.71 KB

operatingModel.md

File metadata and controls

58 lines (44 loc) · 5.71 KB
Raw

운영 모델 - 정보 구조, 아이디어 수명주기, 개발 원칙

pyproc 크기에 맞춘 운영 체계다(2026-07-11). 규칙은 가능한 한 "본문 + 기계 가드"를 짝짓는다: 본문은 이 트리에, 기계 가드는 .githooks와 tests/run.mjs에 산다.

1. 정보 구조

층 위치 담는 것 판정 질문
강행규칙 루트 CLAUDE.md (로컬 규칙 문서, git 미추적) 위반 시 즉시 이력 오염·계약 파손이 나는 규칙만, 짧게. 각 규칙은 상세 문서를 가리킨다 "어기면 즉시 손상인가?"
지속 문서 docs/ 제품 방향, 패키지 계약, 레퍼런스, 반복되는 운영 정책 "다음 릴리즈에서도 계속 유효한가?"
실행 정본 src/, tests/, package entrypoints 현재 동작, 공개 표면, 증거, 아직 실패하는 경계 "지금 코드와 게이트가 무엇을 실제로 보장하는가?"
역사 git history 끝난 계획, 대안 비교, 변경 이유와 그 시점의 증거 "과거에 왜 이 결정을 했는가?"
로컬 메모리 저장소 밖(git 미추적) 세션 간 약속·행동 규약. 레포에서 도출 가능한 내용은 복제하지 않는다 위 어디에도 둘 수 없는 개인 작업 연속성인가?

2. 아이디어 수명주기 (attempts -> contract -> src/tests -> history)

아이디어
  └─ tests/attempts/<카테고리>/     개념증명. 브라우저 실측으로 졸업 게이트 통과까지
       └─ docs/의 해당 계약         지속될 제품·소비·운영 결정을 갱신
            └─ src/ + tests/        구현과 실행 증거를 같은 변경에서 승격
                 └─ git history     완료된 변경과 결정 이유를 보존
  • 신규 능력은 src 직행 금지. 반드시 tests/attempts/<카테고리>/에서 시작한다. 규칙: tests/attempts/README.md.
  • 카테고리는 막무가내로 만들지 않는다. 진짜 질문(가설 + 성공 기준)이 생겼을 때만 개설하고, 개설했으면 그 안에서 파일로 결과를 쌓아 졸업 게이트가 판정날 때까지 운영한다(졸업 또는 명시적 폐기).
  • 지속되는 결정만 docs로 승격한다. 제품 방향은 docs/product/vision.md, 실제와 계약의 열린 차이는 docs/operations/contractReality.md, 소비 표면은 docs/usage/, 함수 계약은 docs/reference/가 소유한다. 일회성 작업 계획을 새 영구 트리로 만들지 않는다.
  • src는 승격된 코드만. 레이어 = 폴더(순위 정본: CONTRIBUTING.md 3항), import는 아래로만, 교차 관심사는 능력 계약 뒤에.
  • 완료 기록은 git history다. 현재 문서는 현재 계약만 말한다. 과거 계획이나 삭제된 구조를 되살리지 않고, 필요하면 관련 파일의 git log --follow와 커밋 diff에서 당시 결정을 찾는다.

3. 메모리 운영

로컬 메모리는 저장소 밖에 살고 git이 추적하지 않는다. 운영 원칙:

  • 인덱스 1파일 + 토픽 파일. 인덱스는 라우팅만 하고 본문을 담지 않는다. 토픽 파일은 종류 접두어(feedback/project/reference)로 구분한다.
  • 포인터 원칙. 레포 문서·코드·git 이력에서 도출 가능한 내용은 메모리에 복제하지 않는다. 이미 근본 문서가 있으면 포인터만 둔다.
  • 중복 자가 점검. 새 항목을 넣기 전 "근본 문서에 있는가?"를 묻고, 중복을 발견하면 근본 문서로 통합하고 메모리를 축약한다.
  • 레포가 정본. 메모리는 세션 간 연속성 장치일 뿐이다. 현재 상태는 docs, src/, tests/가 함께 말하고 과거 상태는 git history가 보존한다.

4. 개발 원칙 (모든 개발의 기본기)

  1. 폴더 구조 기획이 먼저다. 코드를 쓰기 전에 어느 레이어·어느 폴더에 사는지부터 정한다. 구조가 어색하면 코드를 밀어넣지 말고 구조를 고친다.
  2. 클린코드 + 잘 정립된 모듈화. 책임별 분리, 공개 표면은 index.js 한 곳, deep-path import 금지(공개 subpath export만 사용).
  3. 덕지덕지 금지. 특수 케이스·플래그·패치 누적으로 기능을 만들지 않는다. 강함은 쌓아서가 아니라 깎아서 나온다. 붙이기 전에 "이건 구조 문제 아닌가?"를 먼저 묻는다.
  4. 바닥부터 다진다. 검증 안 된 추측 위에 쌓지 않는다. 실측(브라우저) -> 계약 -> 구현 순서. 계약과 실제가 어긋나면 계약 실태 표에 먼저 기록한다.
  5. 정공법. 일부러 얇게 만들거나 우회하지 않는다. 막히면 우회 대신 tests/attempts/ 또는 계약 실태 표에 막힌 지점을 기록하고 정면으로 푼다.

5. 기계 가드 목록

가드 위치 차단하는 것
commit-msg .githooks/commit-msg 커밋 메시지의 도구·생성 흔적
pre-commit .githooks/pre-commit 스테이징된 *.md/*.js의 em dash(U+2014)
pre-push / reference-transaction .githooks/ non-main 브랜치 생성·푸시, 그리고 구조 게이트가 RED인 트리의 게시(커밋 메시지의 검증 줄은 주장이라 푸시에서 다시 판정한다)
구조 게이트 tests/run.mjs 공개 표면·타입 커버리지 누락, em dash, 깨진 상대 링크, attempts와 docs 계약 위반
런타임 게이트 tests/browser/run.mjs 공개 표면의 실제 브라우저 동작 회귀(부팅, 리액티브 실행 경계 계약, 스냅샷-fork, map 병렬). headless Chromium 자동 실행, 의존성 0

클론 후 git config core.hooksPath .githooks로 훅을 활성화한다.