261006_01_DOC: 공용 프런트엔드 참조 문서 및 에이전트 스킬 정비

This commit is contained in:
2026-10-06 10:19:15 +09:00
parent 33a89d9da4
commit cf9f9f610d
20 changed files with 448 additions and 101 deletions

View File

@@ -0,0 +1,7 @@
# KriFrontCommon Change and Verification
- 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.
- Keep `.agent/project.md` near 2-3 KiB as a routing document. Move conditional schemas, endpoint inventories, examples, and issue history to routed `.agent/references/` documents instead of deleting them.
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.

View File

@@ -0,0 +1,9 @@
# KriFrontCommon Package and Runtime Contract
- 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-hub` for the corresponding capability.
- 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.

View File

@@ -0,0 +1,7 @@
# React Compiler and Manual Memoization
- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration.
- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as 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.

View File

@@ -1,34 +1,18 @@
## KriFrontCommon Consumer Contract
### Package Usage
- Consume this contract through the published `@kri/common` package and only through entry points declared in its `package.json` `exports` map.
- 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-hub` for the corresponding capability.
- Consume the published `@kri/common` package only through entry points declared by its `package.json` `exports` map.
- 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
- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration.
- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as 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.md` at 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.
- Prefer a public shared helper or an approved backward-compatible library addition over copying or forking shared behavior locally.
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.
### Required Shared References
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
| Task scope | Required reference |
|---|---|
| Package entry points, runtime boundaries, HTTP, authentication, state, storage, environment, or optional peer integrations | `.agent-harness/references/kri-front-common/package-and-runtime.md` |
| React rendering performance, memoization, or React Compiler behavior | `.agent-harness/references/kri-front-common/react-compiler.md` |
| Package upgrade, dependency changes, lockfile, or verification | `.agent-harness/references/kri-front-common/change-and-verification.md` |
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.

View File

@@ -1,25 +1,18 @@
## KriFrontCommon Repository Rules
# KriFrontCommon Project Instruction Router
### Repository Role and Public Surface
## Required Project References
- This repository publishes the ESM package `@kri/common`; the repository name and package name intentionally differ.
- Treat `package.json` `exports`, exported TypeScript declarations, entry-point behavior, and documented environment requirements as public contracts.
- Supported entry points are the package root and the explicitly declared subpaths in `package.json`. Do not create or document imports from `src`, `dist`, or another undeclared path.
- Keep runtime-specific code separated. Browser-only APIs must not leak into server entry points, and server-only behavior must not enter browser bundles.
- `src` is the source of truth. `dist` and declaration files are generated artifacts and must not be edited directly.
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
### TypeScript and Dependency Rules
| Task scope | Required reference |
|---|---|
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
- Preserve ESM, `NodeNext` module resolution, explicit `.js` relative import specifiers, declaration generation, and the current strict compiler options.
- Keep exported types narrow and backward-compatible. Review any changed function signature, default, thrown error, serialization shape, or type export as a consumer-facing change.
- React, TanStack Query, and Jotai integrations are optional. Do not make an optional peer mandatory for consumers that use only core utilities.
- Do not add hidden global state for configuration, authentication, HTTP error handling, or query behavior.
- Never expose secrets or server-only environment values through browser-facing configuration helpers.
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
### Verification and Release Boundary
## Harness Workflow
- Install with the repository's selected package manager and lockfile.
- Run `npm run typecheck` for source changes and `npm run build` when declarations or package output may change.
- Inspect the relevant `dist` entry points and generated declarations after changing exports.
- Update `.agent/consumer.md` and human-facing documentation in the same approved change when a public contract changes.
- Version changes, publication, registry changes, and consumer-repository edits require separate explicit approval.
- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly.
- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`.
- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8.
- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source.

View File

@@ -0,0 +1,25 @@
## KriFrontCommon Repository Rules
### Repository Role and Public Surface
- This repository publishes the ESM package `@kri/common`; the repository name and package name intentionally differ.
- Treat `package.json` `exports`, exported TypeScript declarations, entry-point behavior, and documented environment requirements as public contracts.
- Supported entry points are the package root and the explicitly declared subpaths in `package.json`. Do not create or document imports from `src`, `dist`, or another undeclared path.
- Keep runtime-specific code separated. Browser-only APIs must not leak into server entry points, and server-only behavior must not enter browser bundles.
- `src` is the source of truth. `dist` and declaration files are generated artifacts and must not be edited directly.
### TypeScript and Dependency Rules
- Preserve ESM, `NodeNext` module resolution, explicit `.js` relative import specifiers, declaration generation, and the current strict compiler options.
- Keep exported types narrow and backward-compatible. Review any changed function signature, default, thrown error, serialization shape, or type export as a consumer-facing change.
- React, TanStack Query, and Jotai integrations are optional. Do not make an optional peer mandatory for consumers that use only core utilities.
- Do not add hidden global state for configuration, authentication, HTTP error handling, or query behavior.
- Never expose secrets or server-only environment values through browser-facing configuration helpers.
### Verification and Release Boundary
- Install with the repository's selected package manager and lockfile.
- Run `npm run typecheck` for source changes and `npm run build` when declarations or package output may change.
- Inspect the relevant `dist` entry points and generated declarations after changing exports.
- Update `.agent/consumer.md` and human-facing documentation in the same approved change when a public contract changes.
- Version changes, publication, registry changes, and consumer-repository edits require separate explicit approval.