# SEED Design 공통 기술 규칙 저장소 전체에 적용되는 코드·테스트·의존성·릴리스 규칙이다. 버전은 루트와 각 workspace의 `package.json`이 원천이다. ## TypeScript - 새 코드에 `any`, `as unknown`을 쓰지 않는다. Oxlint는 `typescript/no-explicit-any`를 경고 수준으로만 보고하므로 직접 지킨다. 기존 예외는 무관한 변경에서 일괄 정리하지 않는다. - 타입 import에는 `type` 키워드를 쓴다. - 정적 import가 기본이다. lazy loading, plugin 경계, 런타임 선택이 필요할 때만 동적 import를 쓴다. - 주석은 코드만으로 알 수 없는 워크어라운드·외부 제약에만 한국어로 남긴다. 변경 이유와 배경은 PR 본문에 쓴다. ## 테스트 작성 - 생성기·변환기가 만든 문자열은 조각(`toContain`)이 아니라 전체 일치로 검증한다. 조각 단언은 헤더나 행이 빠져도 통과한다. 배열 멤버십 검사에는 `toContain`이 맞다. - 생성물이 아니라 동작에 딸린 문구(오류 메시지, 로그, 안내 문장)는 검증하지 않는다. 문구를 고쳐도 동작은 그대로인데 테스트만 깨진다 → 실패는 `toThrow()`로 확인하고, 호출자가 실패 종류를 구분해야 하면 오류 코드나 클래스를 검증한다. - 생성물이나 외부 패키지 데이터를 유닛 테스트 입력으로 쓰지 않는다. 데이터가 바뀌면 검증 대상이 멀쩡해도 깨진다 → 순수 함수를 export해 합성 입력으로 검증한다. 실데이터를 지나는 테스트는 데이터에 묶이지 않는 파생값(섹션 목록 등)만 전체 일치로 본다. - 유닛 테스트에서 네트워크를 타지 않는다. 모듈 스코프에서 비동기 초기화를 시작하면 그 모듈을 import하는 모든 테스트가 요청을 보낸다 → 초기화를 함수 안으로 옮긴다. - `cleanup()`을 직접 호출하지 않는다. `bunfig.toml`의 `[test].preload`가 `scripts/happydom.ts`(DOM)와 `scripts/testing-library.ts`(jest-dom 매처, 전역 `afterEach(cleanup)`)를 이미 로드한다. ## 의존성 - `bunfig.toml`의 `minimumReleaseAge`가 3일이라 게시된 지 3일이 안 된 버전은 설치되지 않는다 → 더 오래된 버전을 고르거나, 꼭 필요하면 `minimumReleaseAgeExcludes`에 추가할지 사용자에게 묻는다. - `package.json`의 script·metadata를 바꾸기 전에 해당 패키지의 기존 구조와 릴리스 설정을 확인한다. ## 릴리스 - 사용자에게 보이는 변경(기능, 버그 수정, 스타일)에는 changeset이 필요하다. `.changeset/*.md`를 직접 쓰지 않고 `seed-change` Skill의 changeset 분기로 만든다. 문서 수정·내부 리팩터링만 있으면 필요 없다. - `bun version`과 `bun release`는 `.github/workflows/release-publish.yml`이 실행한다. 로컬에서는 changeset 작성까지만 한다. - PR snapshot 게시·확인은 `seed-snapshot-release` Skill을 따른다. snapshot은 Rootage CDN stable 포인터를 바꾸지 않는다. - `minor`·`major` → `dev` PR은 merge 버튼으로 합치지 않는다 → 쓰기 권한자가 `/ff-merge` 댓글을 남기면 `.github/workflows/ff-merge.yml`이 커밋·SHA를 유지한 채 `dev`를 fast-forward한다. ## Kapture workflow ownership Kapture 지원 브랜치와 빌드 명령은 `.github/workflows/kapture-capture.yml`에서 관리한다. 캐시 보관 기간은 `KAPTURE_CACHE_RETENTION_DAYS`, CLI 버전은 각 workflow의 `KAPTURE_CLI_VERSION`이며 설치된 adapter와 같은 버전인지 계약 테스트로 확인한다. Capture, Report, Publish, Approve는 실행 이벤트와 권한 경계가 달라 분리한다. CLI 전용 job은 Node.js 24와 npx를 사용하고, 저장소 설치·빌드와 계약 테스트에는 Bun을 사용한다. Publish의 `publish`와 Approve job은 PR 타임라인 댓글을 생성·갱신하므로 `pull-requests: write`와 `issues: write`를 부여한다. Capture의 모든 job은 read 권한만 사용하고, Publish의 `finalize`는 PR 읽기와 status 쓰기만 허용한다. 댓글 API의 403은 Capture 성공·리포트 배포 성공과 별개로 게시 실패를 만든다. Capture는 `opened`, `synchronize`, `reopened`에서만 실행한다. 제목·본문 수정의 `edited`는 새 Capture run을 만들지 않으므로 진행 중인 캡처나 최신 실행 소유권을 바꾸지 않는다. base 브랜치를 바꾼 경우 PR을 닫았다가 다시 열어 새 base/head 비교를 시작한다. Report는 이 Capture workflow의 `in_progress`·`completed` 이벤트만 처리한다. read-only `review-context`가 live PR·base를 검증한 뒤 PR별 큐에 들어간다. 조회 오류는 5초 간격으로 최대 3회 시도하고, 계속 실패하면 Report 실행을 실패시킨다. `ready=false`인 오래된 실행·지원하지 않는 PR은 재시도나 게시 없이 종료한다. 조회 실패가 지속되어 상태 마무리가 실행되지 않았다면 실패한 Report를 재실행한다. 큐를 소유한 caller가 Publish reusable workflow의 게시와 finalize 전체를 기다리며, 승인도 같은 PR 큐를 사용한다. 게시·finalize는 `--expected-pr-number`로 큐 대상을 다시 검증한다. Cloudflare secret 두 개만 reusable workflow에 전달한다. `workflow-tests` job이 `scripts/kapture-workflows.test.ts`를 실행한다. CLI·adapter 버전 일치, base의 정확한 checkout, cache miss 시 빌드 복귀와 현재 실행 artifact 게시, job별 권한·PR 큐·reusable workflow 경계를 검사한다. Capture 실행 시간·캐시 판정은 job summary와 별도 `kapture-execution-*` artifact에 보관한다. 취소되지 않은 실패 실행에서도 생성된 진단 파일을 업로드하며, 파일이 없으면 경고만 남기고 원래 캡처 실패를 유지한다. 시각 리포트·승인 digest에는 실행 진단을 섞지 않으며, stable head cache가 실제 export된 경우에만 게시한다. artifact 다운로드는 Node 24의 download-artifact v8로 digest 불일치를 실패 처리한다. Kapture의 `github restore-build`가 캐시 탐색·출처·archive digest·Storybook 파일 경계 검증과 복원을 담당한다. 별도 정책 checkout이나 SEED 캐시 스크립트는 없다. `cache-directory`가 비어 있으면 정확한 base를 빌드하고 검증한다. 복원 여부와 무관하게 선택된 빌드를 현재 실행의 base artifact로 게시한다. 재사용 artifact 게시 실패는 비교를 실패시키지 않으며, 보관 만료는 YAML의 retention 설정과 GitHub expired 상태를 따른다. 복원 후보는 같은 저장소의 성공한 실행이며 생산 PR이 머지되어야 한다. base/head workflow가 다르면 캐시 게시도 비활성화된다. 초기 도입이나 cache miss에는 새 빌드가 정상이며, 캡처 비교·시각 승인과는 별개다. 지원 브랜치·빌드 명령·보관 기간은 SEED가 소유한다. Kapture CLI와 adapter는 `0.15.2`로 함께 고정한다. 오류 없는 unstable 리포트는 쓰기 권한이 있는 리뷰어가 `/kapture approve --allow-unstable`로 전체 리포트를 예외 승인할 수 있다. 사유는 선택이며, 남기려면 명령 뒤에 한 줄 최대 1000자로 덧붙인다. 승인자와 전체 report digest는 항상 기록하고 입력한 사유만 안전하게 처리해 함께 남긴다. 원본 판정·repeat/self-diff PNG·validate exit 3·cache 제외는 유지한다. 캡처·비교 오류는 승인할 수 없다. 일반 시각 승인은 기존처럼 changed 리포트에만 적용한다. 버전이 다른 base/head adapter도 지원되는 protocol·캡처 계약이면 같은 CLI와 브라우저 환경에서 정상 비교한다. `--allow-adapter-upgrade`는 사용하지 않으며, 호환되지 않는 계약과 캡처 오류는 실패로 처리한다. 캡처 엔진·계약이 다른 캐시는 재사용하지 않는다. Report·승인은 기본 브랜치 `dev`의 workflow로 실행된다.