261006_01_DOC: 공용 프런트엔드 참조 문서 및 에이전트 스킬 정비
This commit is contained in:
7
.agent/consumer-references/change-and-verification.md
Normal file
7
.agent/consumer-references/change-and-verification.md
Normal 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.
|
||||
9
.agent/consumer-references/package-and-runtime.md
Normal file
9
.agent/consumer-references/package-and-runtime.md
Normal 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.
|
||||
7
.agent/consumer-references/react-compiler.md
Normal file
7
.agent/consumer-references/react-compiler.md
Normal 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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
25
.agent/references/repository-rules.md
Normal file
25
.agent/references/repository-rules.md
Normal 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.
|
||||
Reference in New Issue
Block a user