261006_01_ENH: AI Agent용 하네스 변경 적용

This commit is contained in:
2026-10-06 14:02:21 +09:00
parent 453e9634f6
commit a88be762f4
14 changed files with 425 additions and 76 deletions

View File

@@ -1,29 +1,18 @@
## ShortUrl Repository Rules
# ShortUrl Project Instruction Router
### Repository Role and Contracts
## Required Project References
- 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.
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
### URL and Redirect Safety
| Task scope | Required reference |
|---|---|
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
- 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.
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
### Bulk, QR, and Persistence Safety
## Harness Workflow
- 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.
- `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.

View File

@@ -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.