261006_01_DOC: 공용 프런트엔드 참조 문서 및 에이전트 스킬 정비
This commit is contained in:
89
AGENTS.md
89
AGENTS.md
@@ -35,6 +35,13 @@ Later and more specific instructions may override earlier general instructions o
|
||||
- Lead with the result or decision, then provide only the detail needed to verify it.
|
||||
- Do not create or retain a full session transcript.
|
||||
|
||||
### Attention-Aware Response Style
|
||||
|
||||
- Use `attention-aware-communication` for substantive answers, progress updates, and completion reports.
|
||||
- Default to concise, bottom-line-first Korean without omitting a condition, risk, number, or uncertainty needed for a correct decision.
|
||||
- Give full detail when the user requests depth. Use Spartan style only when explicitly requested.
|
||||
- Presentation rules never reduce investigation, implementation, validation, or reporting obligations.
|
||||
|
||||
## Work Authorization
|
||||
|
||||
- The default workflow is discussion first and explicit execution approval second.
|
||||
@@ -152,6 +159,13 @@ Preferred human-facing tools:
|
||||
- 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.
|
||||
|
||||
## Workflow Skills
|
||||
|
||||
- Use `project-reference-loader` before substantive repository analysis, planning, implementation, debugging, or review. Read only the current project and shared references routed for that task, and reread them for each related task even if they were loaded earlier in the session.
|
||||
- Use `karpathy-guidelines` when implementing, refactoring, or reviewing code. It keeps assumptions visible, changes surgical, and success criteria verifiable.
|
||||
- Use `verification-before-completion` before claiming that work is complete, fixed, passing, ready, or safe to commit or publish.
|
||||
- A skill does not expand task scope or authorize Git publication, database execution, deployment, destructive actions, or external communication.
|
||||
|
||||
## Validation
|
||||
|
||||
- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands.
|
||||
@@ -222,61 +236,38 @@ When implementation is complete, report in Korean:
|
||||
|
||||
## 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.
|
||||
|
||||
## KriFrontCommon Repository Rules
|
||||
### Required Shared References
|
||||
|
||||
### Repository Role and Public Surface
|
||||
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
|
||||
|
||||
- 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.
|
||||
| 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` |
|
||||
|
||||
### TypeScript and Dependency Rules
|
||||
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.
|
||||
|
||||
- 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.
|
||||
# KriFrontCommon Project Instruction Router
|
||||
|
||||
### Verification and Release Boundary
|
||||
## Required Project References
|
||||
|
||||
- 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.
|
||||
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
|
||||
|
||||
| Task scope | Required reference |
|
||||
|---|---|
|
||||
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
|
||||
|
||||
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
|
||||
|
||||
## Harness Workflow
|
||||
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user