4.3 KiB
4.3 KiB
KriCommon Repository Rules
Repository Role and Package Boundaries
- This repository is the Java 17 Spring Boot starter/library
com.kri.common:starter:<commonVer>built with Gradlejava-libraryandmaven-publish. build.gradlevariablecommonVeris 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 undercom.kri.common.runtimeand composition undercom.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.
Dependency and Auto-Configuration Safety
- 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.
Feature Invariants
- 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. JsonUtilrequires an explicitObjectMapper; do not introduce hidden global mapper state.- Preserve
Asia/Seouland 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.
Documentation and Verification
AGENTS.mdandCLAUDE.mdare harness-generated outputs. Never edit either file directly.- Edit
.agent/project.mdwhen KriCommon's repository workflow, build, maintenance, or verification rules change. - Edit
.agent/consumer.mdin 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.mdand 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 byD:\_____Dev\_________AgentHarnessBase\scripts\agent-harness.cmd verify --project kri-common. - If composition cannot be run, leave the authoritative
.agentsource corrected, report that the generated output is stale, and do not patchAGENTS.mdmanually. - Update
README.md,.agent/consumer.md, configuration metadata, examples, and tests as applicable when public behavior changes. - Verify property names against their
@ConfigurationPropertiesclasses and ensure examples import publiccom.kri.common.feature.*APIs unless internals are intentionally documented. - On Windows, run
.\gradlew.bat compileJavafor 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.