chore: 리뷰 에이전트 제거와 스킬 구조 정리(#94)

[xunssoie]

PR Summary

.claude의 리뷰 에이전트 3종과 write-api-docs 스킬을 제거하고, run-test를 write-test에 병합해 도구 구성을 슬림화했습니다. 삭제한 도구를 가리키던 다른 스킬의 참조와, 폐기되는 템플릿이 들고 있던 코드 골격도 함께 정리했습니다.

Problem

문제 1 - 쓰이지 않는 리뷰 에이전트가 중복 서술을 떠안고 있음

리뷰 에이전트 3종(logic, security, performance)은 도입 이후 실제 작업 흐름에서 호출되지 않았습니다. 그런데 각 파일이 레이어 구조, 인증 방식, 서비스 정책 위치, 인덱스 선언 방식 같은 프로젝트 지식을 자기 안에 다시 서술하고 있었습니다. 구조나 정책이 바뀔 때마다 코드와 컨벤션 문서 외에 에이전트 파일까지 따라 고쳐야 하는 중복 지점이었고, 정작 그 갱신의 대가로 얻는 것은 없었습니다.

문제 2 - run-test와 write-test의 분리가 실효 없이 지시만 충돌시킴

write-test는 이미 Phase 5에서 작성한 테스트를 실행하고 실패를 고치는 단계를 갖고 있었고, run-test는 실행과 실패 분석만 담당했습니다. 두 스킬은 서로를 Do NOT use for로 가리키며 경계를 유지했지만, 테스트를 쓰면 곧바로 돌려봐야 하므로 실제로는 write-test 하나로 끝나는 흐름이 대부분이었습니다. 더 나쁜 건 실패 시 대응이 서로 반대였다는 점입니다. write-test는 "분석하고 수정하라", run-test는 "사용자 확인 없이 수정하지 마라"로, 같은 상황에 상반된 지시가 남아 있었습니다.

문제 3 - write-api-docs 스킬이 컨벤션 문서의 껍데기이자 코드와 어긋난 템플릿

API 문서 작성 규칙은 api-docs-convention.md에 이미 정리되어 있고, 스킬은 그 문서를 읽으라고 지시하는 절차 껍데기에 가까웠습니다. 실제로 직전 작업(#92)에서는 스킬을 거치지 않고 계획서에 Docs 인터페이스 변경을 적어 implement가 컨벤션대로 처리했습니다. 게다가 스킬이 들고 있던 코드 템플릿은 500 응답 선언을 기본 골격처럼 제시했지만, 저장소의 Docs 인터페이스 9개 중 500을 선언한 파일은 하나도 없었습니다. 참조하는 순간 코드와 다른 결과가 나오는 템플릿이었습니다.

Solution

해결 1 - 리뷰 에이전트 디렉토리 제거

.claude/agents/를 통째로 삭제했습니다. 코드 리뷰는 PR에 붙는 코드래빗과 이를 판정,반영하는 review-feedback 스킬이 이미 담당하고 있어, 같은 역할을 로컬 에이전트로 이중 유지할 이유가 없다고 판단했습니다. 이로써 프로젝트 지식을 서술하는 곳이 컨벤션 문서와 서비스 정책으로 다시 좁혀집니다.

해결 2 - run-test를 write-test의 실행 단계로 흡수

write-test의 Phase 5가 run-test의 실행과 실패 원인 분석 절차를 그대로 받았습니다. 인자가 비어 있거나 이미 존재하는 테스트 클래스명이면 작성 Phase를 건너뛰고 실행으로 직행하는 분기를 넣어, "테스트 돌려줘" 같은 실행 전용 요청도 같은 스킬에서 받습니다.

충돌하던 실패 대응은 원인의 주체로 갈랐습니다. 방금 작성한 테스트 코드 쪽 문제면 스킬이 고치고 재실행하며, 테스트 대상 코드의 버그면 원인과 방안을 보고만 하고 손대지 않습니다. 후자는 write-test가 원래 선언하고 있던 경계와 같아서, 두 지시가 모순 없이 한 스킬 안에 놓입니다.

해결 3 - write-api-docs 폐기, 인터페이스 골격은 컨벤션 문서로 이관

스킬을 삭제하고 템플릿의 인터페이스 골격을 api-docs-convention.md로 옮겼습니다. 규칙과 예시가 한 파일에 모이면 implement가 계획서를 보고 Docs를 작성할 때 볼 곳이 하나로 정해집니다. 코드와 어긋나던 500 응답 블록은 옮기지 않았고, 대신 실제로 발생하는 응답만 선언하라는 규칙을 명시해 다음 작성자가 관성으로 되살리지 않도록 했습니다.

Related Issue

• close chore: 리뷰 에이전트 제거와 스킬 구조 정리 #94

[github-actions]

Test Results

284 tests   284 ✅  4s ⏱️
 91 suites    0 💤
 91 files      0 ❌

Results for commit 67ab77d.