30 KiB
KRI Development Base Instructions
This document defines the shared working rules for KRI development repositories. Keep project-specific facts and commands in the project profile and project rules.
Instruction Resolution
Apply repository instructions in this order:
- Base rules
- Project-type rules
- Technology-stack rules
- Shared consumer contracts
- Project-specific rules
- The explicitly approved task scope
Later and more specific instructions may override earlier general instructions only within their stated scope.
- Apply a shared consumer contract only when
.agent/profile.ymldeclares it. - Do not silently resolve a material instruction conflict. Report the conflicting rules and request a decision before changing files.
- Rules involving destructive actions, credentials, external systems, production, deployment, databases, or Git publication require explicit authorization even when a later rule is less restrictive.
Communication
- Respond to the user in Korean unless the user requests another language.
- Keep code identifiers, commands, paths, protocol names, and external API terms in their original form.
- Follow the repository's existing language conventions for code comments and user-facing messages.
- Lead with the result or decision, then provide only the detail needed to verify it.
- Do not create or retain a full session transcript.
Work Authorization
- The default workflow is discussion first and explicit execution approval second.
- During discussion, perform only read-only investigation needed to understand the task and propose a concrete plan, unless the user prohibits inspection.
- Read-only investigation may include file inspection, code search, encoding checks,
git status,git diff,git log, and sanitized official-documentation lookup. - Before execution approval, do not edit files, install dependencies, run builds or tests, start services, connect to databases, or change local or external state.
- Before requesting approval, describe the intended scope, affected areas, validation plan, and material risks.
- Treat approval as limited to the presented scope. Pause and discuss again if the work materially expands.
- If the user explicitly requests immediate execution without prior discussion, the discussion gate may be skipped for the stated scope.
- Fast-track authorization does not implicitly authorize protected operations such as destructive commands, production changes, deployments, database mutations, Git publication, or external messages.
Local Development Environment
- Primary OS: Windows 11.
- Primary shell: PowerShell.
- Use Git Bash only when the repository already depends on Bash or POSIX shell behavior.
- Prefer repository-provided wrappers and scripts over globally installed commands.
- Do not assume that GNU utilities, WSL, Docker, or a Unix-compatible shell are available unless the project profile confirms them.
- Detect Java, Node.js, .NET, Python, package-manager, and database-tool versions from repository configuration.
- Do not install or modify global toolchains as part of a project task.
Preferred human-facing tools:
-
Classic ASP: Visual Studio Code
-
Java and Spring Boot: IntelliJ IDEA
-
C# and .NET: JetBrains Rider
-
JavaScript, TypeScript, and Next.js: JetBrains WebStorm
-
Python: JetBrains PyCharm
-
Microsoft SQL Server: SQL Server Management Studio
-
Other databases: JetBrains DataGrip
-
These preferences do not authorize launching or controlling a GUI application.
-
Prefer IDE-independent commands that can also run in CI.
-
Do not modify global IDE settings.
-
Do not create or modify
.idea,.vscode, workspace, or run-configuration files unless the approved task requires it. -
Preserve existing shared IDE configuration when it is already tracked.
PowerShell and Path Safety
- Quote paths containing spaces, brackets, parentheses, Korean characters, or PowerShell metacharacters.
- Prefer
-LiteralPathwhen operating on an exact filesystem path. - Use project-relative paths in committed configuration and documentation. Do not commit machine-specific paths such as
D:\_____Dev\.... - Do not pass filesystem targets between PowerShell,
cmd.exe, and Bash for destructive or recursive operations. - Keep a filesystem operation within one shell from target resolution through execution.
- Before a recursive delete or move, resolve and verify every absolute target.
- Never use a drive root, workspace root, user profile, unresolved variable, wildcard, or broad glob as a recursive delete target.
- Prefer recoverable operations when practical.
Change Discipline
- Preserve all existing user changes, including uncommitted and untracked work.
- Keep changes minimal but complete for the approved objective.
- Avoid unrelated cleanup, formatting, renaming, dependency upgrades, and architectural refactoring.
- Do not overwrite or revert unrelated changes.
- Stop and report when the requested change overlaps existing work in a way that cannot be handled safely.
- Prefer changing an authoritative source over editing generated output.
- Treat files marked as generated as read-only unless regeneration is part of the approved plan.
- Do not edit vendored dependencies, build outputs, caches, or generated clients unless explicitly required.
- Do not regenerate a broad set of files for a narrow change without first explaining the expected output scope.
Text Encoding and Korean Content Safety
- Treat the existing file encoding, BOM state, and line-ending style as part of the file's contract.
- Preserve Korean comments, user-facing messages, error messages, identifiers, and documentation exactly unless the task explicitly requires changing them.
- Do not assume that garbled terminal output means the file itself is corrupted. Verify bytes and encoding before modifying suspicious text.
- Before editing an existing text file, determine its current encoding and BOM state when repository configuration does not already guarantee them.
- Do not convert encoding, add or remove a BOM, or normalize line endings as a side effect of an unrelated change.
- Avoid whole-file rewrites for small changes.
- Do not rewrite source files through
Get-Content | Set-Content,Out-File, shell redirection, or another method whose encoding behavior is implicit. - Do not use a patching or formatting tool on a non-UTF-8 file unless it is known to preserve that file's encoding.
- Treat a console display problem and an on-disk encoding problem as separate issues.
- After editing Korean text, inspect the diff for replacement characters (
<EFBFBD>), mojibake, unexpected escapes, BOM changes, and unrelated line-ending changes. - Run
.agent/tools/check-encoding.ps1when it is available and the change touches Korean text or a non-default encoding. - If encoding cannot be identified confidently, stop before writing and report the affected file and evidence.
- For a new text file, follow repository configuration. If no rule exists, use UTF-8 without BOM.
Git Safety
- Use
git status,git diff, andgit logfor read-only investigation. - Do not run
commit,push,pull,fetch,merge,rebase,reset,checkout,switch,stash,clean,tag, or force operations unless that specific operation is explicitly approved. - Source-edit approval does not include commit or push approval.
- Never amend an existing commit unless explicitly requested.
- Before an approved commit, show the intended files, validation results, and proposed commit message.
- Never push directly to a protected branch unless the user names the target branch and explicitly authorizes the push.
Dependencies and External Actions
- Use the package manager, lockfile, and toolchain already selected by the repository.
- Do not install global packages.
- Do not add, remove, or upgrade a dependency unless it was included in the approved plan.
- Pause for approval if an unplanned dependency becomes necessary.
- Keep lockfiles synchronized with approved dependency changes.
- Do not deploy, publish packages, create releases, send messages or email, call business APIs, or modify external services unless explicitly requested.
- Never upload proprietary source code, internal documents, credentials, customer data, or database contents to an external service.
- Remove secrets and unnecessary internal identifiers from external search queries.
Database Safety
- Treat writing or reviewing SQL as source code separately from executing SQL against a database.
- SQL files, migrations, schema proposals, and query drafts may be created within an approved source-change scope.
- Do not connect to a shared, staging, or production database without explicit authorization for that environment.
- Read-only queries against a non-local database also require authorization because results may contain sensitive data.
- Do not execute DDL, DML, stored procedures, migrations, administrative commands, or data-correction scripts against a non-disposable database without separate authorization for the exact target and operation.
- Source-change approval does not authorize migration execution.
- Use a disposable local or test database for approved validation only after verifying its identity and disposable nature.
- Never place credentials, connection strings, or sensitive query results in source files, logs, generated documents, or chat output.
Secrets and Sensitive Data
- Never add credentials, tokens, passwords, private keys, connection strings, session identifiers, or production data to source control.
- Read sensitive files only when the approved task requires it and no safer source exists.
- Prefer inspecting configuration keys and schemas without displaying secret values.
- Never echo secrets into terminal output, chat responses, logs, diffs, generated documents, test fixtures, or screenshots.
- Redact sensitive values when reporting errors or command output.
- If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action.
- Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized.
Validation
- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands.
- Include intended validation in the discussion-phase plan.
- After approved changes, run the narrowest relevant validation first, then broader checks when appropriate.
- Limit formatting to files within the approved scope.
- Do not run tests that require a shared database, production service, paid external API, or sensitive data unless separately authorized.
- Do not claim that a check passed unless it was executed successfully.
- If a check cannot be run, state the exact reason.
- Distinguish a current-change failure from a pre-existing failure or an undetermined failure.
- Do not fix unrelated failures without expanding the approved scope.
- Inspect the worktree after validation for unexpected generated files, formatting churn, encoding changes, or lockfile changes.
Artifacts and Session Records
- Do not create full-session transcripts, automatic HTML copies, analysis reports, or extra documentation unless explicitly requested.
- Store durable information in the repository's existing documentation structure.
- Do not place generated reports or temporary analysis files in the repository root.
- Remove task-specific temporary files created by the current task after validation when removal is safe.
Completion Report
When implementation is complete, report in Korean:
-
what changed and why;
-
the main affected files or components;
-
validation commands actually executed and their results;
-
checks not executed and the reason;
-
remaining risks, assumptions, or follow-up work;
-
database, deployment, dependency, encoding, and compatibility impact when applicable.
-
Do not report completion while required validation is failing or known encoding corruption is unresolved.
-
Keep the report concise and do not include a full session transcript.
Requested Project Rules
- Treat the approved requirements, acceptance criteria, and recorded decisions as the primary scope boundary.
- Do not infer a requirement solely from a file name, folder date, or apparently newer document.
- When requirements conflict, report the exact sources and request a decision.
- Preserve original customer, partner, and planning documents as read-only evidence unless document editing is explicitly approved.
- Summarize durable implementation requirements inside the repository rather than relying only on files outside the repository.
- Do not expand the deliverable with speculative features, infrastructure, or architectural changes.
- Record material assumptions and unresolved decisions in the project-specific rules or existing project documentation.
- Define observable acceptance criteria before implementation.
- Treat separately managed Frontend and Backend repositories as independent deliverables with a coordinated contract.
- Protect customer, partner, survey, and field data as sensitive information.
- Keep handoff, operation, configuration, and validation instructions usable by the requesting team.
- Report deviations from the requested scope and obtain approval before proceeding.
TypeScript
- Treat the repository's current TypeScript version,
tsconfigfiles, module system, path aliases, and package manager as authoritative. - Preserve or strengthen existing strictness. Do not weaken compiler options or hide errors with broad
any,@ts-ignore, or unsafe assertions. - Prefer narrow domain types, discriminated unions, and explicit boundary types over duplicated or overly generic shapes.
- Validate untrusted runtime input even when a compile-time type exists.
- Keep imports, exports, aliases, and generated-code boundaries consistent with the repository.
- Do not introduce a JavaScript-to-TypeScript conversion outside the approved scope.
- Run the repository's focused type-check, lint, test, and build commands as applicable.
React
- Treat the current React version, component style, state management, routing, styling, and test approach as authoritative.
- Do not perform unrelated class-to-hook, JavaScript-to-TypeScript, state-library, styling-system, or React-to-Next.js migrations.
- Keep components focused and follow the repository's established split between presentation, state, data access, and side effects.
- Keep effects dependency-correct and clean up subscriptions, timers, listeners, and in-flight work where applicable.
- Use stable semantic keys and preserve accessibility, loading, empty, error, disabled, and success states.
- Preserve public component props and shared UI contracts unless a coordinated breaking change is explicitly approved.
- Treat any planned Next.js migration as a separate policy and task; the current React application remains authoritative until that migration slice is approved.
Next.js
- Treat the repository's current Next.js and React versions, routing model, rendering model, and package manager as authoritative.
- Preserve server and client component boundaries. Add
use clientonly when browser APIs, state, effects, or client-only libraries require it. - Keep secrets, privileged data access, and server-only modules out of client bundles.
- Preserve established route, layout, middleware, authentication, authorization, caching, revalidation, and error-handling conventions.
- Validate request parameters, payloads, headers, cookies, and external responses at runtime.
- Do not create new frontend TypeScript type or interface names ending in
DtoorDTO. Use domain- or purpose-specific names such asUser,UserInput,UserRequest, orUserResponse; do not rename existing types solely to enforce this rule outside the approved scope. - Use the approved KRI frontend and UI contracts when the project profile includes them; do not copy shared implementations into an application.
- Avoid incidental routing-model or rendering-strategy migrations.
- Run the repository's focused lint, type-check, test, and production build commands as applicable.
KriFrontCommon Consumer Contract
Package Usage
- Consume this contract through the published
@kri/commonpackage and only through entry points declared in itspackage.jsonexportsmap. - Use the package root for runtime-neutral object, URL, date, string, and shared type utilities.
- Use a focused subpath such as
@kri/common/http,@kri/common/browser,@kri/common/server,@kri/common/security,@kri/common/hooks,@kri/common/query,@kri/common/config,@kri/common/jotai, or@kri/common/noti-hubfor the corresponding capability. - Do not import from
@kri/common/src/*,@kri/common/dist/*, or another undeclared deep path. - Do not copy or fork a shared utility locally merely to avoid using an available public entry point. Propose a backward-compatible library addition when the shared contract is genuinely missing.
Runtime and Optional Integrations
- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary.
- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point.
- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper.
- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value.
- Prefer named public exports and retain the consumer project's current module system and bundler conventions.
React Compiler and Manual Memoization
createKriNextConfigenablesreactCompiler: trueunless the project overrides it; confirm the effective configuration.- When enabled, rely on React Compiler instead of adding
useMemo,useCallback, orReact.memoas a routine performance precaution. - Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem.
- Preserve existing memoization unless approved and verified for removal. Use
"use memo"or"use no memo"only for a documented compiler boundary.
Project Instruction Budget
- Keep
.agent/project.mdat or below 8 KiB (8,192 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schemas, endpoint inventories, examples, and temporary issue history to linked project documentation, and keep concise read-routing instructions here.
Change Safety
- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes.
- Review release notes and the actual affected API before upgrading. Run the consumer's focused type-check, test, and build commands after an upgrade.
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.
KriUiRegistry Consumer Contract
UI Component Selection
When implementing or changing frontend UI, use this order:
- Reuse an existing shared component in the project when it already meets the requirement.
- Prefer an approved component from KriUiRegistry.
- Otherwise, prefer a suitable shadcn/ui component.
- Create a new custom component only when the preceding options cannot meet the requirement without an unsafe or misleading adaptation.
Installation and Ownership
- Inspect the registry item and its dependencies before installation. Use the shadcn CLI with the approved registry endpoint under
https://ui-registry.kric.com/r/instead of copying files fromdist/rmanually. kri-data-tableuses the TanStack Table v8 API. Keep@tanstack/react-tablewithin the supported^8.21.3range and do not upgrade it to v9 until KriUiRegistry provides an explicitly migrated component contract.- Respect the consumer project's component aliases, target paths, package manager, styling system, React version, and existing design tokens.
- The shadcn workflow copies component source into the consumer repository. After installation, treat that copy as project-owned code; do not assume registry updates propagate automatically.
- Do not overwrite an existing project component without reviewing the diff and confirming that local behavior and accessibility are preserved.
- Keep package and lockfile changes produced by an installation within the approved scope.
Adaptation and Verification
- Adapt business data and application behavior outside the shared component when possible. Avoid embedding project-specific API, route, authentication, or environment logic into a reusable component.
- Preserve the installed component's public props, accessibility, keyboard behavior, responsive layout, and loading, empty, error, and disabled states unless the task explicitly changes them.
- If the registry lacks a generally reusable capability, propose it in KriUiRegistry; do not modify that repository unless it is explicitly in scope.
- Run the consumer repository's focused type-check, lint, tests, and build after installation or upgrade.
Generated Next.js Repository Rules
- This frontend application was generated by
@kri/create-next-app. - Keep the generated Next.js routing, server/client boundary, authentication, environment, state, query, and application-shell conventions unless an approved task changes them.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not create new TypeScript type or interface names ending in
DtoorDTO. - Consume shared frontend behavior from
@kri/commonand the KRI UI Registry instead of copying provider implementations into this repository. AGENTS.mdandCLAUDE.mdare central-harness generated outputs. Never edit them directly; update.agent/profile.ymlor.agent/project.mdand recompose.- Run
npm run typecheckandnpm run buildafter relevant source or configuration changes.
Survey Dashboard Data Schema (source: public/tmp-doc/테이블 스키마.xlsx)
Use these backend table/column names as the source of truth for frontend type, variable, and component naming (e.g. TanStack Query keys, DTO-free response types, prop names) so terminology stays consistent between frontend and backend.
t_wave(분기/회차):wave_cd(PK, 예:2601= 2026년 1분기),year,wave,label(예: "1분기 재생에너지"),is_open.wave_cd인코딩: 연도 뒤 2자리 + 분기 2자리(zero-padded), 예: 2026년 1분기 →2601.
t_wave_info(조사 개요 항목, "조사 목적" 등):wave_info_idx(PK),wave_cd(FK),wave_info_order,wave_info_title,wave_info_content.t_survey(조사 대상군: 일반국민/전문가):wave_cd+survey_cd(PK),survey_order,survey_title(예: "일반국민 전화조사"),survey_alias(예: "일반국민").t_survey_item(조사 개요 세부 항목: 조사대상/조사지역/조사방법/조사기간/표본규모/표본오차):survey_item_idx(PK),wave_cd+survey_cd(FK),survey_item_order,survey_item_title,survey_item_content.t_file(결과보고서/인포그래픽 다운로드):file_idx(PK),wave_cd(FK),file_order,file_title,file_type(예: "PDF"),file_name.t_part(Ⅰ~Ⅳ 대분류):wave_cd+part_cd(PK),part_order,part_title(예: "Ⅰ. 에너지 및 재생에너지 정책").t_part_item(문항, 예: "1 재생에너지 중심의 에너지 전환 정책 평가"):wave_cd+part_cd+part_item_cd(PK),part_item_order,part_item_title,chart_type(예: "bar"),part_item_comment(각주 텍스트).t_part_item_sub(문항 아래 서브 그룹, 예: 3-1의 "확대 이유"/"감소 이유"):wave_cd+part_cd+part_item_cd+part_item_sub_cd(PK),part_item_sub_title.t_part_item_base(응답 모집단 N/보조 문구):part_item_base_idx(PK),wave_cd+part_cd+part_item_cd+survey_cd+part_item_sub_cd(nullable, FK),base_count(예: 1640),base_pre_text/base_post_text(nullable).t_part_item_data(차트 데이터 값): PK 컬럼명이t_part_item_data_idx로 다른 테이블과 달리 테이블명 접두사가 붙어 있음(스키마 내 유일한 예외 — 연동 코드 작성 시 오탈자로 오인하지 말 것).wave_cd+part_cd+part_item_cd+survey_cd+part_item_sub_cd(nullable, FK),part_item_data_order,part_item_data_label(예: "매우 잘하고 있다"),part_item_data_value(decimal(14,10), 예:39.9— 퍼센트 값으로 추정).- 계층 구조:
t_wave→ (t_wave_info|t_survey→t_survey_item|t_file|t_part→t_part_item→ (t_part_item_sub,t_part_item_base,t_part_item_data)). - 복합키 패턴: 대부분 상위 테이블의 코드 컬럼(
wave_cd,part_cd,part_item_cd,survey_cd,part_item_sub_cd)을 그대로 이어받는 자연복합키. 별도 대리키(_idx)는t_wave_info,t_survey_item,t_file,t_part_item_base,t_part_item_data에만 존재.
Backend API Integration (epolicy-dash-back, http://localhost:6107, OpenAPI at /v3/api-docs)
백엔드 연동이 완료되어 위 "프론트엔드 명명과의 정합성" 문제는 해소됨 — 영문 slug 라우팅(survey.data.ts/menu.data.ts)을 전부 제거하고 실제 waveCd/partCd 기반 동적 라우트와 API 응답 데이터로 완전히 교체했다.
- 라우트:
/dashboard/[waveCd](조사 개요),/dashboard/[waveCd]/[partCd](Part 상세, 하위 문항은#item-{partItemCd}앵커). 루트/는GET /waves를 서버에서 조회해 접근 가능한 첫 Wave로 리다이렉트한다. - 헤더 분기탭·좌측 메뉴는 하드코딩 config가 아니라
GET /waves(헤더)와GET /waves/{waveCd}(사이드바,parts[].items[])를 그대로 데이터 소스로 사용한다 (AppMainLayout.tsx). 새 분기/Part/문항이 추가돼도 프론트 코드 변경이 필요 없다. - BFF 프록시 패턴: 브라우저 →
src/app/api/waves/[[...slug]]/route.ts(GET 전용, CUD 없음) →createServerApi()(httpOnly 쿠키의 accessToken을 Bearer로 자동 첨부) → 실제 백엔드.example리소스와 동일한 패턴이며, 신규 리소스 추가 시 이 구조를 그대로 복제하면 된다. userContext/ctx쿼리파라미터: Swagger상 로그인/로그아웃/Wave API에 필수 파라미터로 보이지만, 실제로는 서버가 인증 헤더에서 자동으로 채우는 값이다 (curl로 직접 검증함 — 파라미터 없이 호출해도 정상 동작). 프론트에서 절대 수동으로 구성해 보내면 안 된다(클라이언트가 자기userRole을 조작할 수 있게 되는 보안 문제).- Wave 접근 정책:
GET /waves는accessible플래그와 함께 모든 Wave를 반환한다 — 헤더 탭은accessible=false면disabled처리만 하고 숨기지 않는다. Wave/Part 상세 API는 비공개 접근 시403 WAVE_ACCESS_DENIED를 반환하며,nextApi의 기본 403 핸들러(로그아웃 리다이렉트)를 쓰면 안 되므로skipForbiddenHandler: true를 지정하고 화면에서 직접 에러 메시지를 표시한다 (src/lib/api-error-message.ts). - 파일 다운로드: Wave 상세 응답의
files[].downloadUrl은 백엔드 서버 origin 기준 상대 경로이며 프론트 앱 origin과 다르다.NEXT_PUBLIC_FILE_ORIGIN환경변수(백엔드와 동일 호스트,.env.local/.env.development/.env.production에 정의)와 결합해서 사용한다 (src/lib/file-download.ts). 경로를 직접 조합하지 않는다. - 차트 라이브러리: 프로젝트에 없었으므로 KriUiRegistry(
https://ui-registry.kric.com/r/kri-chart.json)의 echarts 래퍼(kri-chart,KriBarChart등)를 shadcn CLI로 설치했다 (src/components/chart/). 새 의존성(echarts,echarts-for-react)이 추가됐다. - 차트/통계표 데이터 해석:
resultGroups가 렌더링 단위. 통계표는 모든categories/series.values를 그대로 쓰고, 차트는category.chartVisible === true인 인덱스만 category/series를 함께 필터링해서 사용한다 (src/lib/chart-utils.ts의toChartData).categories[i]와 각series[n].values[i]는 항상 같은 인덱스로 정렬되어 있다는 전제. - 에러 응답: RFC 7807(
application/problem+json)이며errorToResponse(@kri/common/http)가 그대로 BFF 응답에 프록시한다. 프론트는detail보다code(예:WAVE_ACCESS_DENIED,WAVE_NOT_FOUND,PART_NOT_FOUND)로 분기하는 걸 우선한다. - 로그인 필터 vs 업무 오류 403 구분: 인증 필터 단계에서 막힌 요청(토큰 없음/무효)은 바디 없는 401/403으로 온다.
WAVE_ACCESS_DENIED같은 업무 오류는 RFC7807code가 있는 정상 JSON 응답이다.code가 없는 401/403은 세션이 실제로 무효하다는 뜻이므로/logout으로 보내야 한다 (src/lib/api-error-message.ts의isSessionInvalid). 반대로 클라이언트가 이미 로그아웃 상태(useAuth()의auth.user가 없음)라면 애초에 API를 호출하지 않고 즉시/logout으로 보낸다 (AppMainLayout.tsx) — 두 체크는 서로 다른 계층(클라이언트가 아는 상태 vs 서버가 판정한 토큰 유효성)이라 둘 다 필요하다.
⚠️ nextApi(브라우저 클라이언트) 필수 수정 사항 — 스캐폴딩 버그
NEXT_PUBLIC_API_BASE=/api(상대 경로)를 createHttpClient에 그대로 넘기면 브라우저의 모든 API 호출이 예외 없이 즉시 실패한다. @kri/common의 createBaseUrl이 내부적으로 new URL(baseUrl)을 base 인자 없이 호출하는데(node_modules/@kri/common/dist/http/http-client.js), 상대 경로만 단독으로 넘기면 브라우저 URL 생성자가 document.baseURI로 자동 보정해주지 않고 TypeError: Failed to construct 'URL': Invalid URL을 던진다. 원래 스캐폴딩(@kri/create-next-app)은 이 버그를 가진 채로 생성되며, example CRUD가 실사용된 적이 없어 지금까지 드러나지 않았었다.
src/lib/http-client.ts에서 브라우저에서는 window.location.origin과 결합해 절대 URL로 변환한 뒤 createHttpClient에 넘기도록 고쳐뒀다 — 이 파일을 재생성하거나 유사 패턴(nextApi 스타일 클라이언트)을 다른 프로젝트에 복제할 때 이 처리를 빠뜨리지 말 것.