# @kri/create-next-app KRI 표준 Next.js 프로젝트 생성 CLI입니다. ## 사전 준비 사용자 npm 설정에서 `@kri` scope와 Gitea 토큰이 설정되어 있어야 합니다. ```ini @kri:registry=https://gitea.kric.com/api/packages/KRi/npm/ //gitea.kric.com/api/packages/KRi/npm/:_authToken=${GITEA_NPM_TOKEN} ``` ## 개발 ```powershell npm install npm run typecheck npm run build node .\dist\cli.js test-front --yes --skip-install ``` ## 사용 ```powershell npx @kri/create-next-app survey-front ``` 질문 없이 기본값으로 생성: ```powershell npx @kri/create-next-app survey-front --yes ``` 주요 옵션은 `--help`로 확인합니다. Agent Harness 관련 기본값과 옵션: ```text --project-type requested-project|internal-service|shared-service --agent-project-id 하네스 프로젝트 ID (기본: 프로젝트명 slug) --harness-root 중앙 Agent Harness 저장소 경로 --agent-registration 중앙 등록 범위 (기본 shared) --skip-agent-compose 하네스 자동 등록·합성·검증 생략 ``` `--yes` 사용 시 프로젝트 유형은 `requested-project`입니다. ## 생성 과정 1. 표준 템플릿 복사 2. Next.js 및 shadcn 호환 npm 의존성 설치(설치 시점의 실제 버전 범위로 기록) 3. `@kri/common@latest` 설치 후 exact 버전 기록 4. KRI UI Registry 9개 항목 설치 5. `cn` 버전을 설치된 `@kri/common`의 `cn` 의존성과 같은 exact 버전으로 동기화 6. TypeScript 검사 7. Next.js production build 8. Agent Harness 공유 등록, `AGENTS.md`/`CLAUDE.md` 합성 및 검증 UI Registry: `https://ui-registry.kric.com/r` ## Agent Harness 생성 프로젝트에는 `.agent/profile.yml`, 라우팅 전용 `.agent/project.md`, 상세 규칙용 `.agent/references/repository-rules.md`, `.gitattributes`가 항상 포함됩니다. 중앙 하네스는 다음 순서로 탐색합니다. 1. `--harness-root` 2. `KRI_AGENT_HARNESS_ROOT` 환경변수 3. 생성 경로의 상위 디렉터리 하네스를 발견하면 기본적으로 프로젝트를 공유 `workspace.yml`에 등록하고 `compose`, `verify`를 실행합니다. 일회성 로컬 등록은 `--agent-registration local`로 선택할 수 있습니다. 하네스를 찾지 못해도 프로젝트 생성은 완료되며, 이 경우 `.agent` 원본을 중앙 하네스에서 나중에 등록·합성해야 합니다. 중앙 저장소와 생성 프로젝트의 Git 커밋은 자동으로 수행하지 않습니다. ## 생성되는 환경 파일 `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.example`을 생성합니다. `.env.local`과 `.env`는 기본적으로 Git에서 제외되며, `.env.development`와 `.env.production`은 Jenkins 빌드에 사용할 수 있도록 추적 가능합니다. ## 호환성 정책 - 생성 프로젝트는 Node.js 22 이상이 필요합니다(`@kri/common`의 `cn` 의존성 요구 사항). - 의존성은 `latest`를 그대로 기록하지 않고, 설치 시점에 해석된 실제 버전 범위(예: `^19.2.1`)로 기록합니다. `--skip-install`로 생성하면 설치 전이므로 spec(`latest` 등)이 그대로 남습니다. - `@kri/common`은 프로젝트 생성 시점의 최신 버전을 설치하고 exact 버전으로 기록합니다. - `cn`은 `@kri/common`이 의존하는 버전을 읽어 같은 exact 버전으로 설치합니다. shadcn 기본 컴포넌트와 `@kri/common/ui`가 같은 `cn`을 사용해 중복 설치되지 않습니다. - Next.js 생태계 호환성을 위해 생성 프로젝트의 TypeScript는 최신 5.x, ESLint는 최신 9.x를 사용합니다. `eslint-config-next`에 포함된 일부 플러그인이 ESLint 10을 지원하지 않아 9.x를 유지합니다. - `@types/node`는 배포 서버 Node 메이저(24)에 맞춰 최신 24.x를 사용합니다. - shadcn 기본 컴포넌트가 사용하는 `class-variance-authority`, `lucide-react`를 기본 의존성에 포함합니다. 클래스 병합은 `clsx`·`tailwind-merge` 대신 `cn`을 사용합니다.