AI 도우미에게 건네는
꼼꼼한 백엔드 작업 설명서

둘러보고 카드 채우기

2단계

AI가 AGENTS.md, build.gradle, 코딩 규칙 문서를 읽어요. 한 곳만 고치는 작은 수정이라 상황 카드는 여섯 줄만 채워요.

결과

%, _를 검색하면 그 글자가 든 제품만 나와요

티켓

“검색어의 특수 문자를 글자 그대로 찾기” → 이번 범위

구조

Java 21, Spring Boot 4, jOOQ, 클린 아키텍처

규칙

google-java-format 훅, LIKE 검색은 escapeLike

생성물

jOOQ 코드 (스키마 변경이 없어 해당 없음)

완료 기준

테스트, changelog.d/ 조각, script/*.http 예제

분류하고 안내서 펼치기

3단계

검색 결과가 바뀌니 API 동작이에요. 쿼리를 건드리니까 데이터 안전 안내서가 필요해요. DB가 %를 어떻게 읽는지 확인해야 해서 테스트와 운영 안내서도 펼쳐요. 런타임 에이전트 안내서는 앱 안 AI 도구와 상관없어서 덮어 둬요.

버그부터 재현하기

규칙 1규칙 2

고치기 전에 버그가 정말 있는지 테스트로 보여 줘요. 새 파일을 만들지 않고 검색 조건을 이미 테스트하던 SearchConditionsIT에 케이스를 하나 더해요. 이 테스트는 Testcontainers로 띄운 진짜 MySQL에서 돌아요. %의 진짜 뜻은 진짜 DB가 알거든요.

// SearchConditionsIT.java (이미 있던 테스트 파일)
@Test
void contains_treatsPercentAsPlainText() {
    // 이름에 %가 들어간 제품은 하나도 없어요
    List<ProductRecord> found = productRepository.searchByName("%");

    // 그러니 아무것도 안 나와야 해요
    assertThat(found).isEmpty();
}

$ ./gradlew test --tests "SearchConditionsIT"
SearchConditionsIT > contains_treatsPercentAsPlainText() FAILED
    Expecting empty but was: [제품 128개]

원인 고치기

6단계

원인은 공용 헬퍼 SearchConditions.contains()가 검색어를 그대로 LIKE에 넣은 거예요. 신고된 제품 검색 한 곳만 땜질하지 않고 원인인 헬퍼를 고쳐요.

 static Condition contains(Field<String> field, String keyword) {
-    return field.like("%" + keyword + "%");
+    return field.like("%" + escapeLike(keyword) + "%", '\\');
 }

같은 재현 다시 돌리기

규칙 1

처음과 똑같은 테스트를 똑같은 조건으로 다시 돌려요. 초록불이 켜졌어요. 증상이 사라진 걸 확인했으니 이제 고쳤다고 말할 수 있어요.

$ ./gradlew test --tests "SearchConditionsIT"
SearchConditionsIT > contains_treatsPercentAsPlainText() PASSED
BUILD SUCCESSFUL

같은 원인으로 가는 길 찾기

6단계규칙 2

헬퍼를 부르는 곳을 모두 찾고 고친 코드가 받아들이는 다른 입력도 확인해요. 처리 방법은 짐작하지 않고 테스트를 돌린 결과로 정해요. 새 케이스는 모두 원래 있던 테스트 파일에 더해요.

$ rg -n "SearchConditions.contains\(" src/main/java
ProductRepositoryImpl.java:41
SbomRepositoryImpl.java:88
AdminSearchRepositoryImpl.java:57
TagRepositoryImpl.java:33
ReportExportJob.java:112

빨간 기존 테스트 따져 보기

규칙 4

관리자 고급 검색의 기존 테스트가 빨개졌어요. 여기서 테스트를 고쳐 초록불을 만들면 안 돼요. 누가 맞는지 먼저 따져요. 관리자 검색은 원래 %를 와일드카드로 쓰는 기능이라 테스트가 맞아요. 이 화면은 예전 동작을 담은 containsPattern()을 쓰게 길을 나눠요.

$ ./gradlew test --tests "AdminSearchRepositoryImplTest"
AdminSearchRepositoryImplTest > advancedSearch_supportsWildcard() FAILED

 // AdminSearchRepositoryImpl.java
-        .where(SearchConditions.contains(PRODUCT.NAME, pattern))
+        .where(SearchConditions.containsPattern(PRODUCT.NAME, pattern))

$ ./gradlew test
BUILD SUCCESSFUL
# 기존 테스트는 한 글자도 고치지 않았어요

되돌려서 빨간불 확인하기

규칙 3

새 테스트가 진짜로 버그를 잡을 수 있는지 확인해요. 고친 줄만 잠깐 되돌리면 새 테스트가 빨개져야 해요. 케이스마다 결과를 따로 봐서, 하나 덕분에 전부 통과한 것처럼 보이는 일을 막아요.

# escapeLike를 잠깐 빼고 돌려요
$ ./gradlew test --tests "SearchConditionsIT" --tests "SbomRepositoryImplTest"
contains_treatsPercentAsPlainText() FAILED
contains_treatsUnderscoreAsPlainText() FAILED
sbomSearch_treatsPercentAsPlainText() FAILED
# 다시 넣고 돌려요
BUILD SUCCESSFUL

세 케이스 모두 같은 수정을 가리키니 영수증에서는 하나로 쳐요.

설명 고치고 체크리스트 확인하기

규칙 5규칙 6규칙 7

헬퍼의 Javadoc에는 “검색어에 와일드카드를 쓸 수 있다”고 적혀 있었어요. 이제 틀린 말이니 같은 변경에서 고쳐요. 스키마는 그대로라 jOOQ 재생성은 해당 없음으로 적고 우리 팀 완료 기준을 한 줄씩 확인해요.

 /**
- * keyword에 SQL 와일드카드(%, _)를 쓸 수 있다.
+ * keyword의 %, _는 글자 그대로 찾는다. 와일드카드가 필요하면 containsPattern()을 쓴다.
  */

• 완료테스트 추가 (persistence 지원 코드는 테스트 필수)
• 완료changelog.d/TICKET-000-search-like-escape.fix.md
• 완료script/product.http에 keyword=%25 호출 예제
• 완료google-java-format 훅 통과
• 해당 없음jOOQ 재생성: 스키마 변경이 없어요
• 미룸리뷰 승인: 사람이 할 일이에요

영수증 남기기

8단계

마지막으로 보고서를 스킬의 스크립트에 넘겨요. 스크립트가 첫 줄에 id 도장을 찍어 읽기 전용 파일로 올리고 위치를 알려 주면, AI는 답변을 영수증 줄로 끝내요. 확인하지 못한 곳과 막힌 점도 숨기지 않고 적어요.

$ node "$BACKEND_SKILL_DIR/scripts/write-evidence-report.mjs" write \
    "<project-root>" .superloopy/evidence run-20261012t101500z-search-like < report.md
.superloopy/evidence/superloopy-backend/run-20261012t101500z-search-like/backend-skill-report.md

<!-- superloopy-backend-report-id: run-20261012t101500z-search-like -->
# superloopy-backend 보고서: 제품 검색 특수 문자
...
## regression_test_failed_without_fix
| contains_treatsPercentAsPlainText 외 2개 (같은 수정이라 하나로 침) | SearchConditions.contains()의 escapeLike | ./gradlew test --tests "SearchConditionsIT" | Expecting empty but was: [제품 128개] |
## unrequested_changes
none
## routes_into_the_mechanism
| SbomRepositoryImpl.searchByName | 고침 | sbomSearch_treatsPercentAsPlainText |
| 입력 "_" | 고침 | contains_treatsUnderscoreAsPlainText |
| AdminSearchRepositoryImpl.advancedSearch | 핀 | advancedSearch_supportsWildcard |
| TagRepositoryImpl.searchByTag | 막힘 | 후속 티켓 초안 |
| ReportExportJob.findByName | 확인 못 함 | ReportExportJobIT 실행 필요 (배치 DB) |
## definition_of_done
| 테스트 | 완료 |
| changelog.d 조각 | 완료 |
| script/*.http 예제 | 완료 |
| 리뷰 승인 | 미룸 |

영수증을 올렸어요: .superloopy/evidence/superloopy-backend/run-20261012t101500z-search-like/backend-skill-report.md
SUPERLOOPY_EVIDENCE: .superloopy/evidence/superloopy-backend/run-20261012t101500z-search-like/backend-skill-report.md

영수증이 만들어지는 과정과 생김새 자세히 보기