1. TECH STACK & PACKAGE MANAGEMENT
AI가 가장 실수하기 쉬운 '버전 범위'와 '의존성 전파' 문제를 원천 차단합니다.
-
Language & Core: 최신 안정 버전의 TypeScript를 전역적으로 사용하며, 모든 설정은 일관성을 유지합니다.
-
Monorepo: Turborepo를 사용합니다.
각 Task의inputs와outputs를 명확히 정의하여 캐시 효율을 극대화하며, Remote Cache 전략은 루트 README에 명시된 내용을 따릅니다. -
Package Manager: pnpm 필수.
pnpm-workspace.yaml을 통한 워크스페이스 관리를 수행합니다.- Phantom Dependency 금지: 직접 사용하지 않는 의존성에 대한 접근을 엄격히 차단하며, 필요한 모든 의존성은 해당 패키지에 명시적으로 선언해야 합니다.
-
Private Registry: 모든 내부 모듈은
http://192.168.0.6:4873을 통해 관리합니다.- 주의: Docker 내부 환경에서
localhost사용은 절대 불가합니다. 반드시 지정된 IP를 사용하십시오.
- 주의: Docker 내부 환경에서
-
Strict Versioning: 모든
package.json내 버전은 Exact Version
예: 1.2.3만 허용합니다.
^,~등 버전 범위를 나타내는 기호는 사용하지 않습니다. -
Lockfile:
pnpm-lock.yaml은 Immutable 상태로 관리하며, CI 및 런타임 환경에서 반드시 커밋된 상태를 유지해야 합니다. -
Root
.npmrcConfiguration:shamefully-hoist=false @{projectName}:registry=http://192.168.0.6:4873
2. ARCHITECTURE & MODULE BOUNDARY
비즈니스 로직과 프레임워크 코드를 철저히 분리하여 제품 중심의 설계를 강제합니다.
-
Directory Role:
packages/: Framework-agnostic.
특정 프레임워크에 종속되지 않는 순수 비즈니스 로직 및 라이브러리입니다. 의존성은 단방향으로만 흐르며, 순환 참조는 엄격히 금지됩니다.apps/: Wiring & Entry. 프레임워크 설정, 런타임 진입점, 모듈 조립만 수행합니다. 비즈니스 로직은 이곳에 작성하지 않습니다.
-
Directional Rule:
packages/는 절대apps/를 참조하거나 의존할 수 없습니다. -
Frontend (React + MUI):
- UI 라이브러리는 MUI로 고정합니다.
- MUI와 React 간의 호환성을 보장하기 위해 버전을 고정하며, 메이저 버전 업데이트 시 반드시 상호 호환성을 검증합니다.
-
Runtime Environment:
- Dev Mode: Vite 개발 서버를 사용하며, Backend와는 Proxy 설정을 통해 통신합니다.
- Prod Mode: Backend가 빌드된 정적 아티팩트를 직접 서빙하는 단일 서버 모드로 작동합니다.
- 모든 모드는 명시적 환경 변수로 구분하며, 암시적인 스위칭은 배제합니다.
-
Backend: 포트는 환경 변수(
10000–59999범위)를 통해서만 할당받으며, 코드 내 하드코딩을 금지합니다. -
Package Export: 모든 패키지의
package.json내main,module,types필드는 반드시 빌드 결과물인dist/경로를 가리켜야 합니다. -
Peer Dependencies: 패키지 내에서 사용하는 프레임워크 의존성은 직접 설치하지 않고
peerDependencies로 선언하여 중복 로드를 방지합니다.
3. CONTAINERIZATION
런타임의 일관성을 위해 로컬 스크립트보다 도커 환경을 우선시합니다.
-
Primary Runtime: 모든 실행 환경은 Docker로 단일화합니다.
-
Entry Point:
docker-compose.yml이 프로젝트 실행의 유일한 진입점입니다.
Compose의name은 프로젝트 명칭과 일치시킵니다. -
Configuration: 초기 기동 시
env_file, Named Volumes, Named Networks를 반드시 정의해야 합니다. -
pnpm in Docker:
--frozen-lockfile옵션을 사용하여 빌드 안정성을 확보하고,PNPM_HOME또는 볼륨 마운트를 통해 스토어 경로를 최적화합니다. -
Networking:
-
기본적으로 프로젝트 격리형 내부 네트워크를 사용합니다.
-
타 프로젝트와의 연동이 필요한 경우에만 외부 네트워크인
linker를 활용합니다.networks: linker: external: true -
사용 전 반드시
docker network create linker명령어가 README에 문서화되어야 합니다.
-
4. MODULE RESOLUTION RULES
모노레포 내 모듈 참조 방식을 단일화하여 런타임 오류를 방지합니다.
-
Workspace Import: 패키지 간 참조 시 반드시 워크스페이스 이름을 사용합니다
(예:@{projectName}/core) -
No Relative Paths:
packages/간의 상대 경로참조는 절대 금지됩니다. -
Resolution Sync:
tsconfig의paths설정은 실제 패키지 이름과 완벽히 일치해야 하며, 별도의 별칭(Alias) 없이도 Node.js 런타임에서 해석이 가능해야 합니다.
5. VERDACCIO CATALOG & VENDORING
중복 구현을 방지하고 검증된 모듈을 재사용하기 위한 엄격한 가이드입니다.
-
Pre-check: 기능 구현 전 반드시 카탈로그 서버(
http://192.168.0.6:48740)를 조회하여 기존 모듈 존재 여부를 확인합니다.- 조회 API:
/catalog,/catalog/search?q=,/catalog/:package
- 조회 API:
-
Vendoring Policy: 레지스트리에 등록된 카탈로그 모듈을 사용할 때는 직접 설치하는 대신,
packages/내부에 로컬 패키지 형태로 Vendoring하여 관리합니다. -
Versioning Rule: 카탈로그 모듈에서 파생된 버전은
x.y.z-{projectName}.n형식을 따르며, 명시적인 지시가 있을 때만 버전을 올립니다.
6. AI-FIRST DOCUMENTATION & TESTING
AI가 맥락을 파악하고 안정적으로 코드를 생성하도록 돕는 가이드입니다.
-
Documentation: 모든 패키지는
README.md와docs/폴더를 필수적으로 포함합니다.- AI가 읽고 즉시 코드 구조를 파악할 수 있도록 TSDoc 스타일의 주석과 아키텍처 다큐먼트를 작성합니다.
-
Testing Strategy: "코드가 아닌 제품을 관리한다"는 원칙하에 단위 테스트보다 인수 테스트 중심의 가이드를 제공합니다.
- 사용자 시나리오가 의도대로 작동하는지 검증하는 테스트 코드를 우선 작성하여 리팩토링 안정성을 확보합니다.
