chore: 에이전트 설정 정비 및 미사용 자산 정리

[Whale0928]

에이전트 설정(codex / Claude Code)의 어긋남을 바로잡고, 더 이상 쓰지 않는 자산을 정리한다. 운영 코드 변경은 없다.

변경 사항

에이전트 설정

• CLAUDE.md에 누락돼 있던 GSL Runtime Boundary Rules 섹션 추가
• AGENTS.md의 잘못된 제품명(Codex.ai/code)과 personal 파일명(Codex.personal.md) 수정
• 양쪽 지침에 "에이전트 설정 미러 규칙" 섹션 신설
• 양쪽 지침에 "배포 및 실행 인프라" 섹션 신설
• 지침·README에 Facade 완충 지대 설계 배경 문서화, @FacadeService 구현체 위치 오기 수정 (facade → 실제는 service)
• 지침 다이어트: 일반론 섹션 삭제, 어노테이션·레포지토리 장문 상세를 표로 압축 (스킬 references에 상세 유지)
• 동작하지 않던 훅 4개 파일 제거 (.codex/ 디렉터리 소멸)
• deploy-batch 스킬 제거

미사용 자산 정리

• http/ 요청 파일 47개 제거
• compose/*.yml 4개 제거
• 워크플로 통합 후 남은 *.yml.bak 3개 제거
• .actrc 제거
• .gitignore 죽은 규칙 16줄 정리
• 완료된 계획 문서 2개를 plan/complete/로 이동

배경

이 저장소는 codex(AGENTS.md + .agents)와 Claude Code(CLAUDE.md + .claude)의 미러 구성을 쓴다. 스킬 세트는 바이트 단위로 일치했으나 지침과 훅이 어긋나 있었다.

지침 불균형

CLAUDE.md에 GSL Runtime Boundary Rules 섹션이 통째로 없었다. 스킬 자동 체이닝을 막는 규칙이라 Claude 쪽에 더 필요한 내용이다. AGENTS.md는 기계적 치환 흔적으로 "Codex (Codex.ai/code)", "Codex.personal.md"라는 잘못된 표기가 남아 있었다.

두 문서가 다시 어긋나지 않도록 "에이전트 설정 미러 규칙" 섹션을 양쪽에 추가했다. 런타임 이름·스킬 디렉터리 경로·personal 파일명·첫 줄 제목 외의 차이는 동기화 누락으로 간주한다.

훅 제거

훅 2종을 조사한 결과 둘 다 존재 이유가 없어 전부 제거했다.

PostToolUse (spotlessApply) — build.gradle:44-48이 이미 compileJava에 spotlessApply를 걸어두어 중복이었다. 훅은 편집 한 번마다 Gradle을 호출해 더 느렸다. codex 쪽 사본은 codex가 설정하지 않는 $CLAUDE_PROJECT_DIR를 참조해 cd가 실패했고, 줄 끝 || true에 묻혀 조용히 넘어가고 있었다.

SessionStart (Docker 부트스트랩) — TestContainers용 Docker를 설치·기동하는 스크립트로, CLAUDE_CODE_REMOTE != true면 즉시 종료하는 게이트가 걸려 있어 Claude Code 웹 환경 전용이었다. 해당 환경을 쓰지 않으므로 죽은 코드다. codex 쪽 사본은 게이트 변수 자체가 Claude 전용이라 실행될 수 없었다. .codex/hooks.json에는 특정 개발자 머신의 Windows 절대경로가 박혀 있었다.

deploy-batch 스킬 제거

SKILL.md가 .claude/skills/.../scripts/ 경로를 15곳 하드코딩해 codex 사본도 Claude 경로를 실행하는 구조였다. 배포는 GitHub Actions dispatcher로 일원화하므로 스킬 자체를 제거했다.

gh workflow run deploy_batch.yml -f environment=production -f version=1.2.3

배포 인프라 문서화

루트의 compose/*.yml이 과거 단일 호스트 배포 잔재로 남아 있어 실제 운영 구성을 오판하기 쉬웠다. 워크플로·스크립트·문서 어디에서도 참조되지 않아 제거하고, 대신 클러스터를 조회해 확인한 실제 구성을 양쪽 지침에 기록했다.

항목	production	development
product-api	2 replicas	1 replica
admin-api / batch	각 1 replica	각 1 replica
Redis	redis-replication StatefulSet 3 파드	동일

• k3s v1.33.5, HPA 없음(replica 고정), GitOps는 ArgoCD 담당
• 엣지는 Envoy Gateway v1.2.6, HTTPRoute가 /api/v1·/api/v2·/actuator만 통과시키고 나머지는 block-unknown-paths로 차단
• ClientTrafficPolicy가 PROXY protocol을 켜고 클라이언트 X-Forwarded-For를 제거하므로 앱이 받는 XFF는 신뢰 가능
• 인스턴스가 2대 이상이므로 요청 카운팅·잠금은 JVM 로컬 상태로 구현하지 말 것을 규칙으로 명시

미사용 자산 정리

• http/ — API 요청 파일 47개. AI 에이전트로 요청을 대신하게 되어 사용하지 않는다.
• *.yml.bak 3개 — d03c8001(2026-06-29)에서 배포 워크플로를 통합하며 남긴 구버전. 확장자가 .yml이 아니라 gh workflow list --all에도 등록되지 않는 상태였다. 통합 워크플로가 한 달째 정상 동작 중이다.
• .actrc — act 로컬 실행 설정.
• .gitignore — 멀티모듈 전환 전 루트 src/ 기준 규칙 6건, 중복 2건, Jekyll 잔재 2건, http_old/ 제거. 누락돼 있던 AGENTS.personal.md는 추가했다.

검증

• 두 지침 문서가 런타임 고유 토큰 외에 차이가 없음을 diff로 확인했다.
• .agents / .claude 스킬 디렉터리가 diff -rq 기준 완전히 일치함을 확인했다.
• .gitignore 정리 후 git check-ignore로 대표 경로 8개(빌드 산출물, IDE, .env, personal 지침, QueryDSL 생성물 등)가 여전히 무시되는지 회귀 확인했다.
• ./gradlew :bottlenote-mono:compileJava --dry-run으로 spotlessApply가 태스크 그래프에 포함되는 것을 확인했다. 훅 제거 후에도 포매팅은 보장된다.
• Java/Kotlin 운영 코드 변경이 없어 Gradle 빌드와 테스트는 실행하지 않았다.

제외 범위

• GSL 스킬셋 개편은 별도 작업이다. 구형 상태임을 양쪽 지침의 해당 섹션에 표시해 뒀다.
• deploy_batch.yml 워크플로 자체는 변경하지 않았다.
• plan/stale/ 6개 문서는 손대지 않았다.