261006_01_DOC: 공용 백엔드 참조 문서 및 에이전트 스킬 정비
This commit is contained in:
112
AGENTS.md
112
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.
|
||||
@@ -215,86 +229,38 @@ When implementation is complete, report in Korean:
|
||||
|
||||
## KriCommon Consumer Contract
|
||||
|
||||
### Dependency and API Boundary
|
||||
|
||||
- Consume KriCommon as `com.kri.common:starter:<approved-version>` using the consumer repository's established Gradle dependency and version-management conventions.
|
||||
- Import service-facing APIs from `com.kri.common.feature.*`. Treat `com.kri.common.runtime.*` as internal and do not bind application code to it unless no public API exists and the exception is explicitly documented.
|
||||
- Include the matching Spring starter for any optional Web, Security, JPA, Redis, AOP, or Swagger integration the service enables; KriCommon intentionally declares many integrations as compile-only.
|
||||
- Prefer the shared feature or an approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, or utility behavior locally.
|
||||
|
||||
### Configuration and Overrides
|
||||
|
||||
- KriCommon configuration uses only `kri.*`. Established groups include `kri.auth.jwt`, `kri.auth.apikey`, `kri.crypto`, `kri.security`, `kri.swagger`, `kri.web`, `kri.web.mdc`, `kri.http.bypass`, `kri.redis`, `kri.scheduling`, and `kri.error.expose`.
|
||||
- Read the version-matched README and configuration-property classes before setting a property; do not infer a property name or default from an older service.
|
||||
- Supply production JWT secrets, API keys, credentials, allowlists, and service URLs through the consumer's approved secret and configuration system. Never rely on library example or default secrets in production.
|
||||
- Preserve consumer override points. KriCommon's default security chain is created only when the consumer does not provide one, and overridable beans should remain explicit.
|
||||
- Adding a path to API-key allowed paths scopes where API-key authentication is attempted; it does not make the path public or grant authorization.
|
||||
|
||||
### Major Optional Capabilities
|
||||
|
||||
- JWT and API-key authentication integrate with Spring Security. API-key JPA preload requires Spring Data JPA; a consumer-provided claims provider can be used without JPA.
|
||||
- Common Web may register error handling, tracing/MDC, request-user resolution, enum conversion, and CORS behavior. Check for overlap before defining consumer-local equivalents.
|
||||
- Swagger support requires springdoc and defines the shared Bearer/API-key schemes and grouped paths.
|
||||
- Redis and scheduling are opt-in through their `kri.*.enabled` settings and matching runtime dependencies.
|
||||
- HTTP bypass targets are server-configured. Never accept an arbitrary full target URL from a frontend; retain allowed-path checks and do not forward hop-by-hop headers.
|
||||
- The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`.
|
||||
- `ExternalApiClient` multipart requests generate their own boundary and ignore a caller-supplied `Content-Type`. Multipart headers and `formField` values use UTF-8, while file bodies preserve the supplied bytes.
|
||||
- Multipart filenames, including non-ASCII names, are sent unchanged in the quoted `filename` parameter as raw UTF-8. No ASCII fallback or `filename*` parameter is added; CR/LF rejection and quote/backslash escaping still apply.
|
||||
- `JsonUtil` requires the consumer's explicit `ObjectMapper`; shared date/time helpers define KST as `Asia/Seoul` and also expose UTC semantics.
|
||||
- Crypto APIs are under `com.kri.common.feature.crypto.*` and do not use a central key database. AES uses PBKDF2-HMAC-SHA256 key derivation with salt and defaults to AES-256-GCM; callers may supply a master key, salt, IV, AAD, and detached or appended GCM tag representation for legacy interoperability.
|
||||
- `kri.crypto.aes.keys` and per-call master keys are supported operational compromises. Never log them or commit real values. Per-call key material takes precedence over configured keys, and encrypted values retain key ID and KDF metadata for decryption compatibility.
|
||||
- AES-GCM always requires its authentication tag. Use `AES_256_CBC_PKCS5` only for explicitly identified legacy data that has no tag, and do not treat CBC as authenticated encryption.
|
||||
- `DigestService` supports SHA-256/SHA-512 plus legacy-only MD5/SHA-1. `AdaptiveHashService` uses BCrypt for short secrets; do not use MD5, SHA-1, or a fast digest for new password or secret storage.
|
||||
|
||||
### Project Instruction Budget
|
||||
|
||||
- Keep `.agent/project.md` at or below 9 KiB (9,216 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schema details, query or procedure inventories, API examples, and migration history to linked project documentation, and keep concise read-routing instructions here.
|
||||
|
||||
### Upgrade and Verification
|
||||
|
||||
- Review KriCommon release notes, README changes, configuration defaults, auto-configuration conditions, and affected public APIs before upgrading.
|
||||
- Commit dependency-lock or resolved-version changes according to the consumer repository's policy.
|
||||
- Run the consumer's focused compile and tests after an upgrade, including application-context startup tests when auto-configuration or security behavior is affected.
|
||||
- Consume KriCommon as `com.kri.common:starter:<approved-version>` through the repository's established Gradle version-management convention.
|
||||
- Import service-facing APIs from `com.kri.common.feature.*`; treat `com.kri.common.runtime.*` as internal.
|
||||
- Prefer a shared feature or approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, crypto, or utility behavior locally.
|
||||
- Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope.
|
||||
|
||||
## KriCommon Repository Rules
|
||||
### Required Shared References
|
||||
|
||||
### Repository Role and Package Boundaries
|
||||
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
|
||||
|
||||
- This repository is the Java 17 Spring Boot starter/library `com.kri.common:starter:<commonVer>` built with Gradle `java-library` and `maven-publish`.
|
||||
- `build.gradle` variable `commonVer` is the version source. Version changes and publication require separate explicit approval.
|
||||
- Treat types under `com.kri.common.feature`, `kri.*` configuration properties, auto-configuration behavior, optional endpoints, Maven coordinates, and documented defaults as public contracts.
|
||||
- Put stable service-facing APIs under `com.kri.common.feature`. Keep implementations under `com.kri.common.runtime` and composition under `com.kri.common.autoconfigure`; consumers should not depend on runtime internals.
|
||||
- Register consumer-active auto-configurations in `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`.
|
||||
| Task scope | Required reference |
|
||||
|---|---|
|
||||
| Dependency, configuration, security, Web, Swagger, Redis, scheduling, HTTP, JSON, or date/time behavior | `.agent-harness/references/kri-common/platform-capabilities.md` |
|
||||
| Encryption, hashing, key material, or legacy crypto interoperability | `.agent-harness/references/kri-common/crypto-contract.md` |
|
||||
| KriCommon version upgrade or consumer verification | `.agent-harness/references/kri-common/upgrade-and-verification.md` |
|
||||
|
||||
### Dependency and Auto-Configuration Safety
|
||||
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.
|
||||
|
||||
- Many Spring integrations are intentionally `compileOnly`. Do not assume Spring Web, Security, JPA, Redis, AOP, or springdoc is present in every consumer.
|
||||
- Guard optional integrations with the appropriate classpath, bean, missing-bean, and property conditions. A consumer-provided bean must remain able to override a default where that is the established contract.
|
||||
- Do not introduce configuration prefixes outside `kri.*`.
|
||||
- Do not make an optional starter mandatory without an approved compatibility review and migration plan.
|
||||
- Never hard-code real secrets, credentials, service URLs, or API keys. Examples must use obvious placeholders or local-only values.
|
||||
- Do not log or expose raw API keys, bearer tokens, credentials, or unrestricted target URLs.
|
||||
# KriCommon Project Instruction Router
|
||||
|
||||
### Feature Invariants
|
||||
## Required Project References
|
||||
|
||||
- Preserve the default security chain's consumer override point and the established order of API-key and JWT filters.
|
||||
- Path restrictions for API-key authentication scope authentication attempts; they do not grant authorization or replace `kri.security.public-paths`.
|
||||
- Keep bypass target base URLs server-side, enforce configured allowed paths, and exclude hop-by-hop headers. Preserve response bytes and target `Content-Type`.
|
||||
- `JsonUtil` requires an explicit `ObjectMapper`; do not introduce hidden global mapper state.
|
||||
- Preserve `Asia/Seoul` and UTC semantics in shared date/time APIs.
|
||||
- Keep public enum, JPA, Excel, Redis, HTTP, authentication, web, cache, and utility behavior compatible unless a breaking change is explicitly approved.
|
||||
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
|
||||
|
||||
### Documentation and Verification
|
||||
| Task scope | Required reference |
|
||||
|---|---|
|
||||
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
|
||||
|
||||
- `AGENTS.md` and `CLAUDE.md` are harness-generated outputs. Never edit either file directly.
|
||||
- Edit `.agent/project.md` when KriCommon's repository workflow, build, maintenance, or verification rules change.
|
||||
- Edit `.agent/consumer.md` in the same task when a public API, configuration property, default, auto-configuration condition, endpoint, extension point, dependency requirement, security behavior, or other consumer-facing contract changes.
|
||||
- A source-code change does not update harness documents automatically. The Agent making a consumer-facing change is responsible for updating `.agent/consumer.md` and the relevant human documentation before completion.
|
||||
- After an approved harness-source change, run `D:\_____Dev\_________AgentHarnessBase\scripts\agent-harness.cmd compose --project kri-common`, followed by `D:\_____Dev\_________AgentHarnessBase\scripts\agent-harness.cmd verify --project kri-common`.
|
||||
- If composition cannot be run, leave the authoritative `.agent` source corrected, report that the generated output is stale, and do not patch `AGENTS.md` manually.
|
||||
- Update `README.md`, `.agent/consumer.md`, configuration metadata, examples, and tests as applicable when public behavior changes.
|
||||
- Verify property names against their `@ConfigurationProperties` classes and ensure examples import public `com.kri.common.feature.*` APIs unless internals are intentionally documented.
|
||||
- On Windows, run `.\gradlew.bat compileJava` for relevant source changes. Use additional focused tests and checks when present.
|
||||
- For auto-configuration changes, verify import registration and all classpath, bean, and property conditions.
|
||||
- Do not run publish tasks or edit consumer repositories without separate explicit approval. Publishing additionally requires configured Gitea credentials and performs a remote version check.
|
||||
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