Files
short-url/.agent/project.md

2.8 KiB

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.