From 453e9634f65143ff98337a81468c14f711617293 Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Thu, 6 Aug 2026 15:46:09 +0900 Subject: [PATCH] =?UTF-8?q?260806=5F01=5FENH:=20AI=20Agent=20=ED=95=98?= =?UTF-8?q?=EB=84=A4=EC=8A=A4=20=EC=A0=81=EC=9A=A9=20=EB=B0=8F=20KriCommon?= =?UTF-8?q?=20=EB=B2=84=EC=A0=84=20=EC=A0=95=EB=A0=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/profile.yml | 21 ++++ .agent/project.md | 29 +++++ .gitattributes | 4 + AGENTS.md | 290 +++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + build.gradle | 2 +- 6 files changed, 346 insertions(+), 1 deletion(-) create mode 100644 .agent/profile.yml create mode 100644 .agent/project.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agent/profile.yml b/.agent/profile.yml new file mode 100644 index 0000000..8da8389 --- /dev/null +++ b/.agent/profile.yml @@ -0,0 +1,21 @@ +schema_version: 1 + +project: + id: short-url + name: ShortUrl + type: shared-service + layer: backend + legacy: false + +stack: + - java-springboot + +shared_contracts: + consumes: + - kri-common + +databases: + - id: short-url-data + engine: mysql + role: primary + access: read-write diff --git a/.agent/project.md b/.agent/project.md new file mode 100644 index 0000000..1712d78 --- /dev/null +++ b/.agent/project.md @@ -0,0 +1,29 @@ +## ShortUrl Repository Rules + +### Repository Role and Contracts + +- This repository is a Java 17 Spring Boot shared service for short-URL creation and lookup, redirects, QR-code images, and Excel-based bulk workflows. +- Treat endpoint paths, short keys, redirect status and headers, request and response DTOs, QR image behavior, Excel formats, cache behavior, error responses, and authentication rules as contracts used by other projects. +- Preserve the established controller, service, configuration, DTO, and persistence boundaries. Keep controllers thin and place normalization, validation, collision handling, and lookup behavior in services. +- Consume KriCommon through `com.kri.common:starter:beta.1.6.3`. Do not change that approved version or duplicate a KriCommon feature without separate explicit approval. + +### URL and Redirect Safety + +- Normalize and validate target URLs before persistence. Preserve the repository's supported schemes and reject control characters, malformed URLs, unsafe schemes, and values that exceed configured limits. +- Do not fetch, preview, probe, or otherwise contact a submitted target URL during validation unless that network action is separately approved. +- Preserve short-key uniqueness and deterministic collision handling. Design create and bulk-import flows so retries do not produce inconsistent mappings or duplicate records. +- Do not expose target URLs in logs, error details, metrics labels, or completion reports. Avoid reflecting untrusted URL content into HTML or response headers. +- Preserve redirect, caching, proxy-header, and public-path behavior unless an API compatibility change is explicitly approved. + +### Bulk, QR, and Persistence Safety + +- Validate Excel file type, size, row count, cell length, and per-row errors before bulk processing. Bound memory use and preserve the documented template and result format. +- QR generation must encode only the intended value, preserve configured dimensions and response type, and avoid filesystem or network side effects. +- Preserve MySQL transaction, index, uniqueness, character-set, and collation behavior. Do not execute SQL, migrations, or data corrections as part of source-code validation. +- Preserve authentication, authorization, validation, administrative allowlists, rate limits, and abuse controls for create, upload, and reporting endpoints. + +### Documentation and Verification + +- `AGENTS.md` and `CLAUDE.md` are harness-generated outputs. Never edit either file directly; edit `.agent/project.md` or `.agent/profile.yml` and recompose instead. +- Use the repository Gradle Wrapper and run `.\gradlew.bat compileJava` on Windows for relevant changes, followed by focused tests when safe. +- Do not start the service, follow redirects, connect to a real database, or contact submitted target URLs during validation without separate explicit approval. diff --git a/.gitattributes b/.gitattributes index 8af972c..e081a32 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,7 @@ /gradlew text eol=lf *.bat text eol=crlf *.jar binary +/AGENTS.md text eol=lf +/CLAUDE.md text eol=lf +/.agent/*.md text eol=lf +/.agent/*.yml text eol=lf diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8f2d6de --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,290 @@ + + +# KRI Development Base Instructions + +This document defines the shared working rules for KRI development repositories. +Keep project-specific facts and commands in the project profile and project rules. + +## Instruction Resolution + +Apply repository instructions in this order: + +1. Base rules +2. Project-type rules +3. Technology-stack rules +4. Shared consumer contracts +5. Project-specific rules +6. The explicitly approved task scope + +Later and more specific instructions may override earlier general instructions only within their stated scope. + +- Apply a shared consumer contract only when `.agent/profile.yml` declares it. +- Do not silently resolve a material instruction conflict. Report the conflicting rules and request a decision before changing files. +- Rules involving destructive actions, credentials, external systems, production, deployment, databases, or Git publication require explicit authorization even when a later rule is less restrictive. + +## Communication + +- Respond to the user in Korean unless the user requests another language. +- Keep code identifiers, commands, paths, protocol names, and external API terms in their original form. +- Follow the repository's existing language conventions for code comments and user-facing messages. +- Lead with the result or decision, then provide only the detail needed to verify it. +- Do not create or retain a full session transcript. + +## Work Authorization + +- The default workflow is discussion first and explicit execution approval second. +- During discussion, perform only read-only investigation needed to understand the task and propose a concrete plan, unless the user prohibits inspection. +- Read-only investigation may include file inspection, code search, encoding checks, `git status`, `git diff`, `git log`, and sanitized official-documentation lookup. +- Before execution approval, do not edit files, install dependencies, run builds or tests, start services, connect to databases, or change local or external state. +- Before requesting approval, describe the intended scope, affected areas, validation plan, and material risks. +- Treat approval as limited to the presented scope. Pause and discuss again if the work materially expands. +- If the user explicitly requests immediate execution without prior discussion, the discussion gate may be skipped for the stated scope. +- Fast-track authorization does not implicitly authorize protected operations such as destructive commands, production changes, deployments, database mutations, Git publication, or external messages. + +## Local Development Environment + +- Primary OS: Windows 11. +- Primary shell: PowerShell. +- Use Git Bash only when the repository already depends on Bash or POSIX shell behavior. +- Prefer repository-provided wrappers and scripts over globally installed commands. +- Do not assume that GNU utilities, WSL, Docker, or a Unix-compatible shell are available unless the project profile confirms them. +- Detect Java, Node.js, .NET, Python, package-manager, and database-tool versions from repository configuration. +- Do not install or modify global toolchains as part of a project task. + +Preferred human-facing tools: + +- Classic ASP: Visual Studio Code +- Java and Spring Boot: IntelliJ IDEA +- C# and .NET: JetBrains Rider +- JavaScript, TypeScript, and Next.js: JetBrains WebStorm +- Python: JetBrains PyCharm +- Microsoft SQL Server: SQL Server Management Studio +- Other databases: JetBrains DataGrip + +- These preferences do not authorize launching or controlling a GUI application. +- Prefer IDE-independent commands that can also run in CI. +- Do not modify global IDE settings. +- Do not create or modify `.idea`, `.vscode`, workspace, or run-configuration files unless the approved task requires it. +- Preserve existing shared IDE configuration when it is already tracked. + +## PowerShell and Path Safety + +- Quote paths containing spaces, brackets, parentheses, Korean characters, or PowerShell metacharacters. +- Prefer `-LiteralPath` when operating on an exact filesystem path. +- Use project-relative paths in committed configuration and documentation. Do not commit machine-specific paths such as `D:\_____Dev\...`. +- Do not pass filesystem targets between PowerShell, `cmd.exe`, and Bash for destructive or recursive operations. +- Keep a filesystem operation within one shell from target resolution through execution. +- Before a recursive delete or move, resolve and verify every absolute target. +- Never use a drive root, workspace root, user profile, unresolved variable, wildcard, or broad glob as a recursive delete target. +- Prefer recoverable operations when practical. + +## Change Discipline + +- Preserve all existing user changes, including uncommitted and untracked work. +- Keep changes minimal but complete for the approved objective. +- Avoid unrelated cleanup, formatting, renaming, dependency upgrades, and architectural refactoring. +- Do not overwrite or revert unrelated changes. +- Stop and report when the requested change overlaps existing work in a way that cannot be handled safely. +- Prefer changing an authoritative source over editing generated output. +- Treat files marked as generated as read-only unless regeneration is part of the approved plan. +- Do not edit vendored dependencies, build outputs, caches, or generated clients unless explicitly required. +- Do not regenerate a broad set of files for a narrow change without first explaining the expected output scope. + +## Text Encoding and Korean Content Safety + +- Treat the existing file encoding, BOM state, and line-ending style as part of the file's contract. +- Preserve Korean comments, user-facing messages, error messages, identifiers, and documentation exactly unless the task explicitly requires changing them. +- Do not assume that garbled terminal output means the file itself is corrupted. Verify bytes and encoding before modifying suspicious text. +- Before editing an existing text file, determine its current encoding and BOM state when repository configuration does not already guarantee them. +- Do not convert encoding, add or remove a BOM, or normalize line endings as a side effect of an unrelated change. +- Avoid whole-file rewrites for small changes. +- Do not rewrite source files through `Get-Content | Set-Content`, `Out-File`, shell redirection, or another method whose encoding behavior is implicit. +- Do not use a patching or formatting tool on a non-UTF-8 file unless it is known to preserve that file's encoding. +- Treat a console display problem and an on-disk encoding problem as separate issues. +- After editing Korean text, inspect the diff for replacement characters (`�`), mojibake, unexpected escapes, BOM changes, and unrelated line-ending changes. +- Run `.agent/tools/check-encoding.ps1` when it is available and the change touches Korean text or a non-default encoding. +- If encoding cannot be identified confidently, stop before writing and report the affected file and evidence. +- For a new text file, follow repository configuration. If no rule exists, use UTF-8 without BOM. + +## Git Safety + +- Use `git status`, `git diff`, and `git log` for read-only investigation. +- Do not run `commit`, `push`, `pull`, `fetch`, `merge`, `rebase`, `reset`, `checkout`, `switch`, `stash`, `clean`, `tag`, or force operations unless that specific operation is explicitly approved. +- Source-edit approval does not include commit or push approval. +- Never amend an existing commit unless explicitly requested. +- Before an approved commit, show the intended files, validation results, and proposed commit message. +- Never push directly to a protected branch unless the user names the target branch and explicitly authorizes the push. + +## Dependencies and External Actions + +- Use the package manager, lockfile, and toolchain already selected by the repository. +- Do not install global packages. +- Do not add, remove, or upgrade a dependency unless it was included in the approved plan. +- Pause for approval if an unplanned dependency becomes necessary. +- Keep lockfiles synchronized with approved dependency changes. +- Do not deploy, publish packages, create releases, send messages or email, call business APIs, or modify external services unless explicitly requested. +- Never upload proprietary source code, internal documents, credentials, customer data, or database contents to an external service. +- Remove secrets and unnecessary internal identifiers from external search queries. + +## Database Safety + +- Treat writing or reviewing SQL as source code separately from executing SQL against a database. +- SQL files, migrations, schema proposals, and query drafts may be created within an approved source-change scope. +- Do not connect to a shared, staging, or production database without explicit authorization for that environment. +- Read-only queries against a non-local database also require authorization because results may contain sensitive data. +- Do not execute DDL, DML, stored procedures, migrations, administrative commands, or data-correction scripts against a non-disposable database without separate authorization for the exact target and operation. +- Source-change approval does not authorize migration execution. +- Use a disposable local or test database for approved validation only after verifying its identity and disposable nature. +- Never place credentials, connection strings, or sensitive query results in source files, logs, generated documents, or chat output. + +## Secrets and Sensitive Data + +- Never add credentials, tokens, passwords, private keys, connection strings, session identifiers, or production data to source control. +- Read sensitive files only when the approved task requires it and no safer source exists. +- Prefer inspecting configuration keys and schemas without displaying secret values. +- Never echo secrets into terminal output, chat responses, logs, diffs, generated documents, test fixtures, or screenshots. +- Redact sensitive values when reporting errors or command output. +- 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. + +## Validation + +- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands. +- Include intended validation in the discussion-phase plan. +- After approved changes, run the narrowest relevant validation first, then broader checks when appropriate. +- Limit formatting to files within the approved scope. +- Do not run tests that require a shared database, production service, paid external API, or sensitive data unless separately authorized. +- Do not claim that a check passed unless it was executed successfully. +- If a check cannot be run, state the exact reason. +- Distinguish a current-change failure from a pre-existing failure or an undetermined failure. +- Do not fix unrelated failures without expanding the approved scope. +- Inspect the worktree after validation for unexpected generated files, formatting churn, encoding changes, or lockfile changes. + +## Artifacts and Session Records + +- Do not create full-session transcripts, automatic HTML copies, analysis reports, or extra documentation unless explicitly requested. +- Store durable information in the repository's existing documentation structure. +- Do not place generated reports or temporary analysis files in the repository root. +- Remove task-specific temporary files created by the current task after validation when removal is safe. + +## Completion Report + +When implementation is complete, report in Korean: + +- what changed and why; +- the main affected files or components; +- validation commands actually executed and their results; +- checks not executed and the reason; +- remaining risks, assumptions, or follow-up work; +- database, deployment, dependency, encoding, and compatibility impact when applicable. + +- Do not report completion while required validation is failing or known encoding corruption is unresolved. +- Keep the report concise and do not include a full session transcript. + +## Shared Service Project Rules + +- Treat APIs, message formats, callback behavior, identifiers, error responses, and operational defaults as contracts used by multiple consumers. +- Prefer backward-compatible API and schema evolution. +- Identify all externally visible side effects before changing a request flow. +- Design retryable operations to be idempotent where duplicate execution could send multiple notifications, create duplicate records, or generate inconsistent results. +- Define explicit timeout, retry, and failure behavior for external dependencies. +- Do not send real email, SMS, notifications, callbacks, or business requests during development or validation. +- Use mocks, fakes, test recipients, or disposable local integrations only when their safety is verified. +- Do not expose credentials, message contents, personal data, shortened target URLs, or authentication material in logs. +- Preserve authentication, authorization, rate limits, validation, and abuse controls when modifying endpoints. +- Review database and rollout compatibility before changing persisted data or shared service behavior. +- Include consumer impact and rollback considerations in the completion report. + +## Java and Spring Boot + +- Treat the configured JDK, Spring Boot, Gradle, plugin, dependency, and package versions as authoritative. +- Use the repository's Gradle Wrapper. Do not substitute a machine-global Gradle installation. +- Preserve the established package layout and controller, application/service, domain, and persistence boundaries. +- Keep controllers thin, place business rules in the established service/domain layer, and prefer constructor injection. +- Apply request and configuration validation at boundaries and preserve the project's exception and response conventions. +- Make transaction boundaries explicit and narrow; do not add broad transactions to hide lifecycle or query problems. +- Preserve authentication, authorization, auditing, logging, and secret-management conventions. +- Do not edit generated QueryDSL or other generated sources. Change their source definitions and regenerate only when the repository workflow requires it. +- Use the approved KriCommon contract when the project profile includes it; do not duplicate shared backend behavior locally. +- Run the narrowest relevant Gradle compile, test, static-analysis, and build tasks. + +## MySQL + +- Use MySQL syntax and behavior only for data sources whose declared engine is `mysql`. +- Preserve the configured version, schema, character set, collation, time zone, naming, migration, and access conventions. +- Parameterize values. Do not build SQL by concatenating untrusted input. +- Consider indexes and execution plans for changed filters, joins, ordering, grouping, and pagination without guessing from small data sets. +- Preserve transaction, locking, null, date/time, decimal, and generated-key semantics. +- Do not introduce MSSQL or other dialect syntax into MySQL paths. +- A source-code change approval authorizes SQL analysis and migration drafting only. Execute DDL, DML, procedures, or migrations only with separate explicit approval and the declared data-source access level. + +## KriCommon Consumer Contract + +### Dependency and API Boundary + +- Consume KriCommon as `com.kri.common:starter:` 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.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. + +### 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. +- Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope. + +## ShortUrl Repository Rules + +### Repository Role and Contracts + +- This repository is a Java 17 Spring Boot shared service for short-URL creation and lookup, redirects, QR-code images, and Excel-based bulk workflows. +- Treat endpoint paths, short keys, redirect status and headers, request and response DTOs, QR image behavior, Excel formats, cache behavior, error responses, and authentication rules as contracts used by other projects. +- Preserve the established controller, service, configuration, DTO, and persistence boundaries. Keep controllers thin and place normalization, validation, collision handling, and lookup behavior in services. +- Consume KriCommon through `com.kri.common:starter:beta.1.6.3`. Do not change that approved version or duplicate a KriCommon feature without separate explicit approval. + +### URL and Redirect Safety + +- Normalize and validate target URLs before persistence. Preserve the repository's supported schemes and reject control characters, malformed URLs, unsafe schemes, and values that exceed configured limits. +- Do not fetch, preview, probe, or otherwise contact a submitted target URL during validation unless that network action is separately approved. +- Preserve short-key uniqueness and deterministic collision handling. Design create and bulk-import flows so retries do not produce inconsistent mappings or duplicate records. +- Do not expose target URLs in logs, error details, metrics labels, or completion reports. Avoid reflecting untrusted URL content into HTML or response headers. +- Preserve redirect, caching, proxy-header, and public-path behavior unless an API compatibility change is explicitly approved. + +### Bulk, QR, and Persistence Safety + +- Validate Excel file type, size, row count, cell length, and per-row errors before bulk processing. Bound memory use and preserve the documented template and result format. +- QR generation must encode only the intended value, preserve configured dimensions and response type, and avoid filesystem or network side effects. +- Preserve MySQL transaction, index, uniqueness, character-set, and collation behavior. Do not execute SQL, migrations, or data corrections as part of source-code validation. +- Preserve authentication, authorization, validation, administrative allowlists, rate limits, and abuse controls for create, upload, and reporting endpoints. + +### Documentation and Verification + +- `AGENTS.md` and `CLAUDE.md` are harness-generated outputs. Never edit either file directly; edit `.agent/project.md` or `.agent/profile.yml` and recompose instead. +- Use the repository Gradle Wrapper and run `.\gradlew.bat compileJava` on Windows for relevant changes, followed by focused tests when safe. +- Do not start the service, follow redirects, connect to a real database, or contact submitted target URLs during validation without separate explicit approval. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/build.gradle b/build.gradle index 2d80f24..5674b90 100644 --- a/build.gradle +++ b/build.gradle @@ -31,7 +31,7 @@ repositories { } dependencies { - implementation "com.kri.common:starter:beta.1.4.0" + implementation "com.kri.common:starter:beta.1.6.3" implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.boot:spring-boot-starter-security'