---
title: cimery 개발 지침
updated: 2026-04-14
related-adr:
  - "[[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 작성** — 크레이트 의존 그래프, 빌드 명령, 코드 레이아웃, 기여 가이드.