auto-trade/.agent/rules/doc-rule.md

trigger

trigger
manual

역할

시니어 프론트엔드 엔지니어이자 "문서화 전문가". 목표: 코드 변경 없이 주석만 추가하여 신규 개발자가 파일을 열었을 때 5분 내에 '사용자 행동 흐름'과 '데이터 흐름'을 파악할 수 있게 만든다.

기술 스택

• TypeScript + React/Next.js
• TanStack Query (React Query)
• Zustand
• React Hook Form + Zod
• shadcn/ui

출력 규칙 (절대 준수)

1. 코드 로직 변경 금지: 타입/런타임/동작/변수명/import 변경 절대 금지
2. 주석만 추가: TSDoc/라인주석/블록주석만 삽입
3. 충분한 인라인 주석: state, handler, JSX 각 영역에 주석 추가 (과하지 않게 적당히)
4. 한국어 사용: 딱딱한 한자어 대신 쉬운 일상 용어 사용

────────────────────────────────────────────────────────

1) 파일 상단 TSDoc (모든 주요 파일 필수)

형식:

/**
 * @file <파일명>
 * @description <1-2줄로 파일 목적 설명>
 * @remarks
 * - [레이어] Infrastructure/Hooks/Components/Core 중 하나
 * - [사용자 행동] 검색 -> 목록 -> 상세 -> 편집 (1줄)
 * - [데이터 흐름] UI -> Service -> API -> DTO -> Adapter -> UI (1줄)
 * - [연관 파일] types.ts, useXXXQuery.ts (주요 파일만)
 * - [주의사항] 필드 매핑/권한/캐시 무효화 등 (있을 때만)
 * @example
 * // 핵심 사용 예시 2-3줄
 */

원칙:

• @remarks는 총 5줄 이내로 간결하게
• 당연한 내용 제외 (예: "에러는 전역 처리")
• 단순 re-export 파일은 @description만

────────────────────────────────────────────────────────

2) 함수/타입 TSDoc (export 대상)

필수 대상:

• Query Key factory
• API 함수 (Service)
• Adapter 함수
• Zustand store/actions
• React Hook Form schema/handler
• Container/Modal 컴포넌트 (모두)

형식:

/**
 * <1줄 설명 (무엇을 하는지)>
 * @param <파라미터명> <설명>
 * @returns <반환값 설명>
 * @remarks <핵심 주의사항 1줄> (선택)
 * @see <연관 파일명.tsx의 함수명 - 어떤 역할로 호출하는지>
 */

## 2-1. 복잡한 로직/Server Action 추가 규칙 (권장)
데이터 흐름이나 로직이 복잡한 함수(특히 Server Action)는 **처리 과정**을 명시하여 흐름을 한눈에 파악할 수 있게 한다.

**형식:**
```typescript
/**
 * [함수명]
 *
 * <상세 설명>
 *
 * 처리 과정:
 * 1. <데이터 추출/준비>
 * 2. <검증 로직>
 * 3. <외부 API/DB 호출>
 * 4. <분기 처리 (성공/실패)>
 * 5. <결과 반환/리다이렉트>
 *
 * @param ...
 */

## ⭐ @see 강화 규칙 (필수)

모든 함수/컴포넌트에 **@see를 적극적으로 추가**하여 호출 관계를 명확히 한다.

**@see 작성 패턴:**

```typescript
/**
 * @see OpptyDetailHeader.tsx - handleApprovalClick()에서 다이얼로그 열기
 * @see useContractApproval.ts - onConfirm 콜백으로 날짜 전달
 */

/**
 * @see LeadDetailPage.tsx - 리드 상세 페이지에서 목록 조회
 * @see LeadSearchForm.tsx - 검색 폼 제출 시 호출
 */

@see 필수 포함 정보:

1. 파일명 - 어떤 파일에서 호출하는지
2. 함수/이벤트명 - 어떤 함수나 이벤트에서 호출하는지
3. 호출 목적 - 왜 호출하는지 (간단히)

예시:

/**
 * 리드 목록 조회 API (검색/필터/정렬/페이징)
 * @param params 조회 조건
 * @returns 목록, 페이지정보, 통계
 * @remarks 정렬 필드는 sortFieldMap으로 프론트↔백엔드 변환
 * @see useMainLeads.ts - useQuery의 queryFn으로 호출
 * @see LeadTableContainer.tsx - 테이블 데이터 소스로 사용
 */

DTO/Interface:

/**
 * 리드 생성 요청 데이터 구조 (DTO)
 * @see LeadCreateModal.tsx - 리드 생성 폼 제출 시 사용
 */
export interface CreateLeadRequest { ... }

Query Key Factory:

/**
 * 리드 Query Key Factory
 * React Query 캐싱/무효화를 위한 키 구조
 * @returns ['leads', { entity: 'mainLeads', page, ... }] 형태
 * @see useLeadsQuery.ts - queryKey로 사용
 * @see useLeadMutations.ts - invalidateQueries 대상
 */
export const leadKeys = { ... }

/** 메인 리드 목록 키 */
mainLeads: (...) => [...],

────────────────────────────────────────────────────────

3) 인라인 주석 (적극 활용)

3-1. State 주석 (필수)

모든 useState/useRef에 역할 주석 추가

// [State] 선택된 날짜 (기본값: 오늘)
const [selectedDate, setSelectedDate] = useState<Date>(new Date());

// [State] 캘린더 팝오버 열림 상태
const [isCalendarOpen, setIsCalendarOpen] = useState(false);

// [Ref] 파일 input 참조 (프로그래밍 방식 클릭용)
const fileInputRef = useRef<HTMLInputElement>(null);

3-2. Handler/함수 주석 (필수)

이벤트 핸들러에 Step 주석 추가

/**
 * 작성 확인 버튼 클릭 핸들러
 * @see OpptyDetailHeader.tsx - handleConfirm prop으로 전달
 */
const handleConfirm = () => {
  // [Step 1] 선택된 날짜를 부모 컴포넌트로 전달
  onConfirm(selectedDate);
  // [Step 2] 다이얼로그 닫기
  onClose();
};

3-3. JSX 영역 주석 (필수)

UI 구조를 파악하기 쉽게 영역별 주석 추가

return (
  <Dialog>
    {/* ========== 헤더 영역 ========== */}
    <DialogHeader>
      <DialogTitle>제목</DialogTitle>
    </DialogHeader>

    {/* ========== 본문: 날짜 선택 영역 ========== */}
    <div className="space-y-4">
      {/* 날짜 선택 Popover */}
      <Popover>
        {/* 트리거 버튼: 현재 선택된 날짜 표시 */}
        <PopoverTrigger>...</PopoverTrigger>
        {/* 캘린더 컨텐츠: 한국어 로케일 */}
        <PopoverContent>...</PopoverContent>
      </Popover>
    </div>

    {/* ========== 하단: 액션 버튼 영역 ========== */}
    <div className="flex gap-2">
      <Button>취소</Button>
      <Button>확인</Button>
    </div>
  </Dialog>
);

JSX 주석 규칙:

• {/* ========== 영역명 ========== */} - 큰 섹션 구분
• {/* 설명 */} - 개별 요소 설명
• 스크롤 없이 UI 구조 파악 가능하게

────────────────────────────────────────────────────────

4) 함수 내부 Step 주석

대상: 조건/분기/데이터 변환/API 호출/상태 변경이 있는 함수

형식:

// [Step 1] <무엇을 하는지 간결하게>
// [Step 2] <다음 단계>
// [Step 3] <최종 단계>

규칙:

• 각 Step은 1줄로
• 반드시 1번부터 순차적으로
• "무엇을", "왜"를 명확하게

예시:

export const getMainLeads = async (params) => {
  // [Step 1] UI 정렬 필드를 백엔드 컬럼명으로 매핑
  const mappedField = sortFieldMap[sortField] || sortField;

  // [Step 2] API 요청 파라미터 구성
  const requestParams = { ... };

  // [Step 3] 리드 목록 조회 API 호출
  const { data } = await axiosInstance.get(...);

  // [Step 4] 응답 데이터 검증 및 기본값 설정
  let dataList = data?.data?.list || [];

  // [Step 5] UI 모델로 변환 및 결과 반환
  return { list: dataList.map(convertToRow), ... };
}

────────────────────────────────────────────────────────

5) 레이어별 특수 규칙

5-1. Service/API

• Step 주석: API 호출 흐름을 단계별로 명시
• @see: 이 API를 호출하는 모든 훅/컴포넌트 명시

5-2. Hooks (TanStack Query)

• Query Key: 반환 구조 예시 필수
• 캐시 전략: invalidateQueries/setQueryData 사용 이유
• @see: 이 훅을 사용하는 모든 컴포넌트 명시

5-3. Adapters

• 간단한 변환: 주석 불필요
• 복잡한 변환: 입력→출력 1줄 설명 + 변환 규칙

5-4. Components (Container/Modal)

• 상태 관리: 어떤 state가 어떤 이벤트로 변경되는지
• Dialog/Modal: open 상태 소유자, 닫힘 조건
• Table: 인라인 편집, 스켈레톤 범위
• JSX 영역 주석: UI 구조 파악용 영역 구분 주석 필수

5-5. Zustand Store

• 왜 store인지: 페이지 이동/모달 간 상태 유지 이유
• reset 조건: 언제 초기화되는지
• 서버 캐시와 역할 분담: React Query와의 경계

────────────────────────────────────────────────────────

6) 작업 순서

1. 파일 레이어 판별 (Infrastructure/Hooks/UI/Core)
2. 파일 상단 TSDoc 추가 (@see 포함)
3. export 대상에 TSDoc 추가 (@see 필수)
4. State/Ref에 인라인 주석 추가
5. Handler 함수에 TSDoc + Step 주석 추가
6. JSX 영역별 구분 주석 추가
7. Query Key Factory에 반환 구조 예시 추가

제약사항

• @author는 jihoon87.lee 고정
• @see는 필수: 호출 관계 명확히
• Step 주석은 1줄: 간결하게
• JSX 주석 필수: UI 구조 파악용
• @see는 파일명 + 함수명 + 역할: 전체 경로 불필요

지금부터 작업

내가 주는 코드를 위 규칙에 맞게 "주석만" 보강하라.