api2/docs/agent-workflow.md

Codex 작업 규칙

작업 원칙

• 기존 구조와 네이밍을 우선 존중한다.
• 한 번에 큰 리팩터링을 하지 말고, 요청 범위 안에서 필요한 만큼만 수정한다.
• 인코딩 문제가 보이는 문자열은 무심코 대량 수정하지 말고 원인과 영향 범위를 먼저 확인한다.
• 요청 범위를 벗어나는 개선점은 강제로 반영하지 말고 제안으로 분리한다.

에이전트 응답 원칙

• 무엇을 바꿨는지보다 왜 그렇게 바꿨는지를 짧고 분명하게 설명한다.
• 파일 수정 후 가능하면 테스트 또는 최소 실행 검증 결과를 함께 남긴다.
• 사용자가 IDE 에서 파일을 수정하거나 새 파일을 만든 뒤 질문할 수 있으므로, 관련 답변 전에는 저장된 최신 파일 상태를 다시 확인하는 것을 우선한다.
• 이전에 읽은 세션 문맥만으로 최신 파일 상태를 단정하지 말고, 저장되지 않은 편집 내용은 확인할 수 없음을 전제로 설명한다.

작업 진행 표시

• 기능 또는 모듈 단위 작업에서만 진행 상태를 표시한다.
• 시작 전에는 최대 4개 단계로 나누고, 현재 완료 기준으로 퍼센트를 표시한다.
• 완료는 ✓, 진행 중은 ●, 예정은 ○로 표시한다.
• 퍼센트는 시간 예측이 아니라 실제 완료한 단계 기준으로 표시한다.
• 컴파일, 테스트, 실제 연동 검증은 필요한 경우 별도 단계로 표시한다.
• Redis, 파일, 외부 API 등 기능이 사용하지 않는 의존성 검증 단계는 표시하지 않는다.
• 단순 파일 확인이나 검색에는 진행 상태를 표시하지 않는다.
• 오류가 발생하면 해당 단계에 머물고 원인과 다음 조치를 짧게 공유한다.

모델 라우팅 규칙

• Terra는 현재 작업의 총괄 역할을 맡는다. 구조 설계, 레거시 분석, 보안·권한·트랜잭션·Redis 판단, 오류 원인 분석, 코드 리뷰와 실제 연동 검증은 Terra가 처리한다.
• Luna는 범위가 명확하고 독립적인 반복 작업을 맡는다. DTO·VO·Mapper 보일러플레이트 작성, 단순 CRUD 이관, 컴파일·단위 테스트 실행, 포맷과 정적 확인이 대상이다.
• 한 대화 안에서 모델을 교체하는 대신, Terra가 필요한 작업만 Luna 하위 작업으로 위임하고 결과를 다시 검토한다.
• 같은 파일 또는 강하게 연결된 파일을 동시에 수정하는 작업은 충돌 방지를 위해 Terra가 직접 처리한다.
• 보안, 데이터 손상 가능성, 다중 모듈 영향, 실제 DB·Redis·외부 연동이 포함되면 Luna 단독 처리 대상으로 보내지 않는다.
• 모델 라우팅은 작업의 난이도와 위험도로 판단한다. 단순 반복이라는 이유만으로 도메인 정책이나 DB 변경 판단까지 위임하지 않는다.
• 추론 강도는 Terra와 Luna 모두 기본 medium으로 사용한다.
• 비용과 응답 속도를 우선하므로 high 이상의 추론 강도는 사용하지 않는다. 더 깊은 판단이 필요하면 Terra가 범위를 나누어 확인하고 결과를 단계적으로 공유한다.

작업별 담당

작업	기본 담당	기준
실행 모듈, 업무 패키지, API 구조 설계	Terra	admin, front, core와 standard, bespoke의 경계를 판단한다.
레거시 분석과 이관 범위 결정	Terra	기존 정책, 누락 기능, 호환성을 해석한다.
단일·복합 SQL 분류, 트랜잭션과 응답 코드 결정	Terra	재사용성과 데이터 정합성을 판단한다.
JWT, Security, 권한, CORS, Redis, 파일, 외부 연동	Terra	보안·운영 영향이 크다.
확정된 standard CRUD DTO·VO·Mapper·XML 작성	Luna	이미 정해진 계약을 반복 적용한다.
확정된 Form, 응답 VO, Swagger 설명 작성	Luna	API 필드와 문구가 확정된 경우에 한한다.
import, 네이밍, 포맷, XML namespace/id 점검	Luna	독립적이고 저위험인 기계적 확인이다.
compileJava, 단위 테스트 실행	Luna	빠른 반복 검증을 우선한다.
통합·실제 연동 테스트 시나리오와 결과 판단	Terra	Security, DB, Redis, 외부 의존성의 영향 범위를 판단한다.
오류 원인 분석과 수정 방향 결정	Terra	로그 해석을 넘어 구조와 정책을 확인한다.

적용 흐름

Terra: 구조, SQL 분류, 정책, 테스트 조건 결정
  -> Luna: 확정된 계약의 반복 구현과 빠른 컴파일·단위 검증
  -> Terra: 결과 검토, 통합·실제 연동 검증, 다음 수정 방향 결정

• 판단 기준은 한 문장으로 정리한다. 새 설계·정책 판단이 필요하면 Terra, 이미 정해진 계약을 여러 파일에 적용하면 Luna다.
• Luna가 작성한 결과도 Terra가 기존 구조, 보안 규칙, 실제 의존성 영향과 함께 검토한 뒤 반영한다.

사용자 선호 규칙

• 신규 API 또는 기존 기능 이관 작업은 코드나 파일 생성 전에 먼저 패키지와 메서드 구성을 트리 구조로 제시한다. 이 단계에서는 구현 코드를 먼저 보여주지 않는다.
• 작업 전 구조 제시는 실행 모듈 -> 업무 1 depth 패키지 -> Controller API 메서드 -> 업무 Service 메서드 -> Form/VO -> core standard/bespoke Service/Mapper/핵심 메서드 순서로 작성한다.
• 구조 제시 단계에서 core standard와 bespoke의 책임을 함께 구분한다. 단일 테이블 CRUD와 전용 조회는 standard, JOIN·집계·복합 SQL은 bespoke로 표시한다.
• 사용자가 구조와 메서드 구성을 확인한 뒤에만 코드 제시 또는 직접 작성을 진행한다.
• 소스코드 변경이 필요한 요청에서는 바로 구현하지 말고 먼저 다음 중 무엇을 원하는지 확인한다.
• 코드로 보여주기: 사용자가 직접 프로젝트에 반영할 수 있도록 예시 코드나 패치를 제공한다.
• 직접 작성하기: 에이전트가 저장소에 직접 수정한다.
• 사용자는 코드 흐름을 먼저 파악하고 코드 컨벤션에 맞게 직접 반영하는 방식을 선호하므로, 선택이 명시되지 않았다면 기본적으로 코드로 보여주기를 우선 제안한다.
• 이 규칙은 이후 작업에서도 반복 확인 대상이며, 에이전트는 이를 임의로 생략하지 않는다.