daiso-mcp: Instructions file for Codex

에이전트 개발 규칙

이 문서는 AI 에이전트가 이 프로젝트에서 코드를 작성하고 기여할 때 따라야 하는 규칙과 가이드라인을 정의합니다.

목차

• 코드 작성 규칙
• 커밋 규칙
• 보안 및 개인정보
• 파일 구조
• 코드 스타일
• 문서화
• 테스트

---

코드 작성 규칙

파일 크기 제한

모든 코드 파일은 450줄 내외로 작성되어야 합니다.

• 최대 줄 수: 450줄
• 권장 줄 수: 300-400줄
• 초과 시 조치: 파일이 450줄을 초과하면 기능별로 분리하여 모듈화
• 자동 검사: src/**/*.ts의 450줄 제한은 CI에서 자동으로 강제
• 예외: 현재 src 아래 예외는 없으며 OpenAPI 생성 산출물은 저장소 루트에 위치

파일 분리 예시

// ❌ 나쁜 예: 하나의 파일에 모든 기능 (600줄)
// src/products.ts (600줄)

// ✅ 좋은 예: 기능별로 분리
// src/products/search.ts (200줄)
// src/products/filter.ts (150줄)
// src/products/formatter.ts (100줄)
// src/products/index.ts (50줄)

코드 품질

• 명확성: 코드는 명확하고 이해하기 쉽게 작성
• 재사용성: 중복 코드를 최소화하고 공통 로직은 함수로 추출
• 타입 안정성: TypeScript의 타입 시스템을 적극 활용
• 에러 핸들링: 모든 비동기 작업과 외부 API 호출에 적절한 에러 처리 구현

예시

// ✅ 좋은 예
async function fetchData(url: string): Promise<ApiResponse> {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP 에러: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('데이터 가져오기 실패:', error);
    throw error;
  }
}

// ❌ 나쁜 예
async function fetchData(url) {
  const response = await fetch(url);
  return await response.json();
}

---

커밋 규칙

커밋 빈도

• 주기적인 커밋: 논리적인 작업 단위마다 커밋
• 작은 단위: 한 번에 하나의 기능이나 수정사항만 포함
• 완성된 코드: 빌드 실패나 런타임 에러가 없는 상태에서만 커밋

커밋 메시지 컨벤션

접두사는 영어, 메시지는 한국어를 사용합니다.

커밋 메시지 형식

<타입>: <제목>

<본문> (선택사항)

<푸터> (선택사항)

타입 종류

• feat: - 새로운 기능 추가
• fix: - 버그 수정
• docs: - 문서 수정
• style: - 코드 포맷팅, 세미콜론 누락 등 (로직 변경 없음)
• refactor: - 코드 리팩토링 (기능 변경 없음)
• test: - 테스트 코드 추가/수정
• chore: - 빌드 설정, 패키지 매니저 설정 등
• perf: - 성능 개선
• ci: - CI/CD 설정 변경
• revert: - 커밋 되돌리기

커밋 메시지 예시

# ✅ 좋은 예
feat: 제품 검색 필터링 기능 추가
fix: 매장 찾기 시 거리 계산 오류 수정
docs: API 사용 예시 문서 업데이트
refactor: 재고 확인 로직을 별도 모듈로 분리
test: 가격 정보 조회 API 테스트 추가
chore: TypeScript 버전 5.7.2로 업데이트

# ❌ 나쁜 예
feat: add feature (영어로만 작성)
update (타입 접두사 누락)
fix: bug fix (구체적이지 않음)
여러 기능 추가 (타입 접두사 누락)