ParaWiki/Output/guides/cimery-dev-guide.md

title, updated, related-adr

title	updated	related-adr
cimery 개발 지침	2026-04-14	ADR-001-tech-stack ADR-002-feature-dsl ADR-003-architecture-followups

cimery 개발 지침

cimery 관련 작업 시 먼저 읽는 문서. CLAUDE.md에서 링크된다.

권위 순서 (Source of Truth)

1. Output/reports/ADR-001-tech-stack.md — 기술 스택
2. Output/reports/ADR-002-feature-dsl.md — Feature DSL 아키텍처
3. Output/reports/ADR-003-architecture-followups.md — UI·IFC·CI/CD·USD·Plugin·Feature 카탈로그·LOD·UX 등
4. 본 문서 — 지침 요약·규약
5. ~/.claude/.../memory/ — 개인 선호·작업 방식

ADR과 본 문서가 충돌하면 ADR 우선. ADR 개정은 새 ADR로 수행 (status: superseded-by:).

기술 스택 핵심

• 언어: Rust (전 계층)
• UI: Leptos + <canvas> wgpu 3D 뷰포트 (Tauri v2 데스크톱 + PWA 웹 듀얼)
• 기하 커널: OpenCascade.js(웹) / opencascade-rs(데스크톱), GeomKernel trait 추상화
• 렌더: wgpu → WebGPU (MVP Chromium 기반만)
• IFC: 런타임 ifc-lite-core, 검증용 IfcOpenShell
• 증분 계산: salsa crate (Feature 단위 query, 비싼 sub-step만 개별)
• IR 직렬화: JSON 선행 → MessagePack 승격
• 단위: 자체 newtype (Mm, M 등), 경계 명시 변환
• FEM: 자체 솔루션 연계 (외부 의존 최소)
• 파일 구조: 폴더 기반 플레인 텍스트, AI·diff 친화 최우선

아키텍처 파이프라인

Rust DSL (builder + macro_rules! 설탕)
  └─ #[param(unit, range, default)] attribute 메타
  ↓
IR (JSON/MessagePack, 결정론적 직렬화)
  ↓
salsa query (Feature 단위, Lazy/Reactive)
  ↓
Evaluator → GeomKernel trait
  ├─→ 자체 wgpu 뷰어 (주)
  └─→ USD export (증분 Prim 단위, IFC alias 이중 태깅)

CSV 라운드트립: 개발자 템플릿 → CSV export → 엔지니어 편집 → CSV import → DSL 소스 재생성.

코드 규약

• 단위 강제: 구조물 Mm, 선형 M. 암묵 변환 금지. 경계 함수 시그니처에 명시.
• Feature 파라미터 선언: #[param(unit="mm", range=10..=200, default=150)] — AI 친화.
• 결정론: 같은 IR → 같은 기하. 연산 순서 고정, 정렬된 입력만 통과. CI 1순위 테스트.
• Feature 조합: 2단 composite 허용, 공유 그래프 금지.
• 에러: Result<_, FeatureError> + 경로 포함 메시지 (girder_3.flange_thickness < web_thickness).
• 검증: 음수·단위 불일치는 타입 수준, 범위·상호제약은 런타임 Result.
• 테스트 4층 (MVP부터 필수):
  1. IR 스냅샷 (insta)
  2. 기하 불변량 (부피·무게중심·바운딩박스·체크섬, 허용 오차)
  3. 두 커널 cross-check (OpenCascade.js ↔ opencascade-rs)
  4. proptest 속성 기반 (self-intersection 없음·부피 양수 등)

Revit UX 호환

• 기본 마우스·키보드 조작, 리본·패널·속성창·뷰 큐브 = Revit 관습.
• 리본 12탭: Home·Alignment·Structure·Feature·Site&GIS·Annotate·Analyze·Construction·Insert·View·Manage·Modify.
• 2글자 keyin(VG·WT·ZE·SD) 보존 — 한글 IME 활성 시 입력 라우팅 주의.
• 선택·필터: Category = Feature kind. cimery 고유 = 선형 기반 선택·규칙 선택·영향권 하이라이트.
• 개념 다른 영역은 "Revit Element ≠ cimery Feature instance"처럼 차이를 공식 문서화.

Feature 카탈로그 (MVP 거더교)

• Must (v1): Girder · Deck Slab · Pier · Abutment · Bearing · Alignment(입력)
• Should (v1.1): Cross Beam · Expansion Joint · Parapet
• Could (v2): Foundation · Approach Slab · Drainage
• Won't (v3+): 철근·사장교·현수교·아치·트러스

사용자 설정 (VS Code 3계층 모델)

~/.cimery/settings.json                 # User 전역
~/.cimery/keybindings.json              # 키맵 분리
<project>/.cimery/settings.json         # Project (Git 커밋)
<project>/.cimery/settings.local.json   # 개인 override (.gitignore)

병합: Default ← User ← Project ← Project.local. 좌표계·tolerance는 Project 전용 잠금.

구현 우선순위 — 엔드-투-엔드 수직 슬라이스

12개 ADR-003 결정을 동시 진행 금지. 첫 Girder 1개로 전 계층(DSL → IR → salsa → evaluator → OCCT → wgpu → USD) 한 번 관통한 뒤 수평 확장. 뷰어 한 달·DSL 한 달 식 수평 접근은 치명적.

함정 체크리스트

• 두 OCCT 백엔드 수치 미세 차이 → cross-check 조기 검증.
• 기하 연산 비결정성 → 결정론 테스트 CI 1순위.
• 대형 좌표 f32 정밀도 부족 → 내부 f64 + 프로젝트 원점 오프셋. GPU 전송 시 f32 + 원점 재계산.
• mm ↔ m 경계 타입 강제.
• Tauri WebView ≠ PWA 파일 I/O → 추상화 레이어 필수.
• WebGPU Safari/Firefox 미지원 → Chromium 전용 MVP, 사용자에 명확 고지.
• ifc-lite-core 단일 유지보수자 → 어댑터로 격리·핀·포크 정책.
• Tauri updater Ed25519 개인키 → HSM/Key Vault 수준 관리 (초기부터 계획).
• WASM 플러그인(v2 Extism) 무한 루프 → cooperative 중단 플래그.
• Revit 2글자 keyin vs 한글 IME → IME 상태 기반 입력 라우팅.

CI/CD·배포 (준비 단계)

• 메인 CI: Gitea Actions (.gitea/workflows/).
• Win/macOS 빌드·서명·릴리스: GitHub Actions 미러.
• 업데이터: Tauri v2 Ed25519 키쌍 + latest.json CDN.
• Windows 서명: Azure Trusted Signing 우선 검토.
• 채널: nightly / beta / stable = Git 태그 prefix.
• 웹 배포: Cloudflare Pages (별도 cimery-web.pages.dev 예정).

프로젝트 구조 (예정)

ParaWiki/                  # 현 저장소 루트
├── wiki/, raw/, Output/   # 지식 저장소 (기존)
└── cimery/                # 개발 시작 시 별도 서브프로젝트
    ├── CLAUDE.md          # cimery 자체 세부 개발 지침 (본 문서 기반)
    ├── Cargo.toml         # workspace
    └── crates/            # core / dsl / ir / kernel / ui / ...

cimery/ 디렉터리 생성 시 해당 폴더에 세부 CLAUDE.md 작성 — 크레이트 의존 그래프, 빌드 명령, 코드 레이아웃, 기여 가이드.