CLAUDE.md

이 워크스페이스에서 일할 때의 규칙. 구성과 빠른 시작은 README.md.

이 워크스페이스는 cob 커널에서 만들어졌다. 기능 SDK는 backend/<project_name>_client/lib/src/module/<기능>/protocol에 직접 생성한다. 기능별 client 패키지를 다시 만들지 않는다. 생성 명령은 tool/serverpod/cli.sh를 사용하며 unified: 경로 표지를 보존한다(생성기 유지보수). 기능은 feature(모듈)로 더하고, 모듈은 slots.yaml 의 자리에만 꽂는다. 커널 저장소(coco-de/kernel) 자체를 고치는 중이라면 KERNEL.md 를 먼저 읽을 것 — 커널에만 있는 규칙(포장 · 도너 흔적 · compose 계약 시험)이 거기 있고, 생성 프로젝트에는 그 파일이 없다.

반드시 지킬 것

1. 정체성은 지정 파일에만 (Identity-Free)

앱 이름 · 번들 ID · 조직 값은 identity.yaml 의 files 밖에 쓰지 않는다. 필요하면 참조한다:

자리 참조
Dart (앱) AppIdentity (shared/env_config)
Dart (서버) ServerIdentity (backend/demo_exchange_remittance_server/lib/src/server_identity.dart)
iOS · macOS $(APP_DISPLAY_NAME) · $(APP_BUNDLE_ID) (AppInfo.xcconfig)
Android identity.properties → applicationId · ${appName}

project_name(서버 · 클라이언트 패키지 이름)과 app_link_domain(유니버설 · 앱 링크)도 정체성 값이다. project_name 만은 import · 경로 · serverpod 생성물에 두루 들어가 지정 파일 제한이 없다(포장이 모든 파일에서 치환한다) — 대신 중립 이름 backend_* 와 카멜 표기를 게이트가 막는다.

Android namespace 와 Kotlin 패키지는 정체성과 무관한 고정값 app.shell 이다. 테스트 타깃 번들 ID 도 app.shell.RunnerTests 로 고정한다. 새 플랫폼 파일에 정체성이 꼭 들어가야 하면 identity.yaml 의 files 에 올린다.

2. 마커는 계약이다

slots.yaml 의 마커 문구는 cob 레지스트라가 문자열 그대로 찾는다. 문구를 바꾸거나 지우면 compose 가 멈춘다. 새 슬롯은 slots.yaml 에 선언하고 파일에 한 번만 둔다(check_slots.py).

3. 생성물은 커밋하고, 손대지 않는다

생성물 다시 만들기
shared/i10n/lib/src/translations/*.g.dart cd shared/i10n && dart run slang
feature/<domain>/{app,console}/lib/src/i18n/*.g.dart tool/feature_modules flutter-codegen (기능 소유 slang)
backend/demo_exchange_remittance_server/lib/src/generated/** · backend/demo_exchange_remittance_client/lib/src/protocol/** · test/integration/test_tools/ tool/serverpod/cli.sh generate
**/*.g.dart(go_router_builder) · test/src/bdd/*.widget_test.dart(co_bdd) tool/bdd/generate.sh
골든 기준 이미지 test/golden/goldens/** CI(조직 셀프호스트 macOS 러너) — 커밋 메시지 [update-goldens] 로 push

커밋하지 않는 생성물: envied 의 shared/env_config/lib/src/env/*.g.dart(난독화 값) — tool/dev/write_env.sh.

CI 가 생성기를 다시 돌려 작업 트리가 그대로인지 본다. 생성물에 dart format 을 돌리지 말 것 — 생성기 출력과 달라져 CI 가 빨개진다. 포맷은 생성물을 뺀 파일에만 한다(CI 의 포맷 단계 참고). co_bdd 생성물 (*.widget_test.dart · *.patrol_test.dart)은 co-package a66629f(#101)부터 생성기가 format 된 바이트로 내므로 CI 포맷 검사에 포함된다 — 맞지 않으면 손으로 고치지 말고 tool/bdd/generate.sh 로 다시 만든다.

번역 접근자는 JSON 키 그대로 snake_case 다(key_case: snake). 기존 모듈 코드가 그 표기를 쓰므로 바꾸지 않는다. 기본 로케일 밖은 지연 로딩이라 테스트에서는 await locale.build() 로 읽는다(위젯 테스트의 가짜 시계 안에서는 끝나지 않으니 setUpAll(LocaleSettings.instance.loadAllLocales) 뒤 getTranslations).

번역은 11개 로케일 전부(ko en zh-Hans ja de fr es pt it ru ar — 데모 표준 S-18). 키를 더하면 모든 로케일에 더하고 python3 tool/i18n/check_parity.py --strict 로 확인한다(게이트). 새 글자(한자 · 아랍 문자 등)가 들면 tool/gates/check_locale_fallback_font.py 가 알려 준다 — tool/fonts/build_locale_fallback.py 로 글꼴을 다시 만든다.

4. 화면 · 파일 · 라우트 규약 (게이트가 막는다)

5. 비밀은 저장소 밖

앱 환경변수 shared/env_config/.env.<flavor> 는 커밋하지 않는다(.env.example 만) — tool/dev/write_env.sh 가 만든다. 키 목록 · 우선순위는 shared/env_config/KEYS.md. backend/demo_exchange_remittance_server/config/passwords.yaml 도 커밋하지 않는다. 로컬·CI 는 tool/dev/write_passwords.sh 로 만들고, 운영은 같은 키를 SERVERPOD_PASSWORD_<키> 환경변수로 넣는다. 서버가 부팅 때 읽는 키는 그 스크립트 주석에 있다.

명령

flutter pub get
tool/dev/write_env.sh                     # .env.<flavor> + envied 생성(처음 한 번 · 키를 바꾼 뒤)
dart analyze --fatal-infos
tool/gates/check_all.sh
tool/feature_modules check
tool/serverpod/cli.sh generate            # 모듈 → 호스트 DAG
tool/feature_modules flutter-codegen      # slang · 모든 workspace 생성기

# 테스트 — 루트 workspace 의 모든 패키지 (서버는 내장 Postgres — write_passwords.sh 먼저)
tool/dev/test_all.sh          # SKIP_SERVER=1 이면 서버 제외

(cd app/app && flutter build web --no-wasm-dry-run --dart-define=FLAVOR=production)
bash tool/pages/build.sh                  # Pages 사이트 → build/pages/
(cd tool/pages/smoke && npm ci && node smoke.mjs --base https://<Pages 주소>/<저장소>/ --local-root ../../../build/pages)
python3 tool/i18n/check_parity.py --strict  # 11개 로케일 번역 패리티

tool/bdd/generate.sh                      # .feature · @TypedGoRoute 생성물
tool/golden/capture.sh && tool/golden/gallery.sh   # 골든 캡처 → build/golden-gallery/index.html
python3 tool/serverpod/profile.py show    # serverpod 버전 · 프로필

알아 둘 것

CI

워크플로: ci.yml(게이트 · 생성물 · 분석 · 테스트 · 웹 · 백엔드 통합 · Android) · golden.yml(골든) · pages.yml(6표면 빌드 · 배포 · 공개 스모크). 무엇을 언제 도는지는 각 파일 머리 주석.

러너는 조직 셀프호스트 macOS 러너뿐이다(#637 S6 — 비용: 호스티드 Linux 분이 조직 Actions 청구의 대부분). 모든 잡이 runs-on: [self-hosted, macOS, ARM64, flutter](Docker 가 필요한 잡은 docker 추가) — ubuntu-latest 를 다시 쓰지 말 것. 러너(Default 그룹 · M2 Ultra 9 · M4 Max 8)는 coui · unibook · good-teacher · cocode 와 함께 쓰고 한 기계에서 여러 잡이 동시에 돈다. 그래서:

이벤트 CI Golden Pages
PR 변경 범위로 가른다(문서만이면 계약 게이트 만, Android 는 네이티브 · 의존성 변경 때만) 골든 (compare) 사이트 빌드(배포 전 스모크 포함)
main push 전부(변경 범위 판정 없음 · Android 포함) 골든 (compare) 사이트 빌드 → 배포 (GitHub Pages) → 공개 스모크
workflow_dispatch evidence=true(기본) 전부(false 면 Android 만 뺀다) 골든 (compare) 빌드 · 배포 · 공개 스모크(false 면 빌드만)
[update-goldens] 커밋(main 밖 브랜치) · dispatch update_goldens=true(main 밖 브랜치) — 골든 (update) — 기준 이미지를 다시 만들어 그 브랜치에 커밋 —

main push · dispatch 의 run 은 서로 취소하지 않는다(PR 만 새 push 가 앞선 run 을 취소한다).

CI 증거 게이트 ↔ 잡 이름

데모 증거 대장(#637)은 게이트마다 (run, 잡 이름)을 적고, main HEAD 와 같은 SHA 의 성공한 run 안에서 그 이름의 잡 하나가 성공했는지만 본다(PR run · 다른 SHA 는 인정하지 않는다). 그래서 main push 에서 위 표대로 전부 돌고, 같은 SHA 를 다시 돌릴 때는 gh workflow run ci.yml --ref main -f evidence=true(golden.yml · pages.yml 도 같은 입력). 잡 이름은 고정이다 — 정본은 tool/ci/evidence_jobs.json, 이름 · matrix 레그를 바꾸면 이 표와 함께 바꾼다 (tool/gates/check_evidence_jobs.py 가 어긋남 · 중복 · 식이 남은 이름을 막는다).

게이트 워크플로 잡 이름(문자열 그대로) 무엇 · 대장 조건
fr CI FR 대조 (fr) PRD §7 FR/AC 고정 스냅샷(tool/fr/prd_snapshot.json — 본문 sha256) ↔ 대조표(tool/fr/coverage.json)의 테스트를 이 잡이 직접 돌려 묶인 테스트 하나하나의 통과를 같은 실행에서 확인(tool/gates/check_fr_coverage.py --run). 누락 · skip · 빈 본문 · TODO · 미실행 · 실패는 실패
unit CI 검증 (tests-1) (+ 검증 (tests-2) · 검증 (tests-modules)) 모든 패키지 테스트(패키지 라운드로빈 샤드) · 기능 서버 단위(TZ=UTC) — run 전체 성공이 다른 샤드를 보증
widget CI 검증 (tests-1) (+ 검증 (tests-2)) 같은 샤드의 위젯 테스트(실제 mount · 서버 모드 셸 · 데모 초기화)
golden Golden 골든 (compare) 셀프호스트 macOS 러너 렌더러 기준 비교 — 대장은 mode=compare 만 인정(골든 (update) 는 증거가 아니다)
widgetbook CI 검증 (widgetbook) Widgetbook 패키지 테스트(TEST_SUITE=widgetbook) — 웹 산출물은 사이트 빌드 의 /widgetbook/
bdd CI 검증 (bdd) co_bdd widget 시나리오(TEST_SUITE=bdd) — 생성물 최신은 검증 (generated)
patrol CI Patrol (chrome) 실행 앱 여정 — co_bdd *.patrol_test.dart(PRD §20 10편 · 시나리오 29)를 patrol CLI 가 Chrome(Playwright)에서 돈다. device: chrome
locale Pages 언어 전환 (locale) 같은 커밋 배포본의 업무 화면(A-03) iframe 실시간 전환 ko → en → ja → ar → ko · 빠른 연속 · 다크 — 다시 불러오지 않고 UI 문구 · 표시 데이터(B) · lang/dir 이 바뀌고 마지막 언어만 남는다 + ?lang=ar&theme=dark 첫 프레임(runtime localOnly)
backend CI 백엔드 통합 (server · PostgreSQL) (+ 검증 (tests-server)) 생성 SDK → 호스트 dispatcher → 기능 모듈 → PostgreSQL(잡 안의 docker 컨테이너, runtime server) + 계약 동등성(localOnly ≡ 생성 SDK 저장소). 내장 Postgres 판은 tests-server
surfaces Pages 사이트 빌드 6표면(랜딩 · app · console · widgetbook · golden · docs) 빌드 · 산출물 확인 + 배포 전 스모크 · 자격 증명 검사
smoke Pages 공개 스모크 같은 커밋(pages-commit) 배포본의 6표면 · 첫 프레임 전 상태 · iframe 전환 · 업무 화면 딥 링크(업무 네트워크 0 · runtime localOnly)

그 밖의 고정 이름: 변경 범위 · 계약 게이트 · 번들 모듈 → 호스트 코드 생성 · 검증 (generated) · 검증 (analyze) · 검증 (web) · Android 빌드 (debug) · 배포 (GitHub Pages).

커밋

한국어 Conventional Commits + gitmoji: <type>(<scope>): <gitmoji> <설명>. 예: feat(app): ✨ 부트스트랩 단계 마커 추가, fix(gates): 🐛 정체성 게이트가 바이너리를 읽던 문제.