docs: 프로젝트 개발 가이드 문서 추가

[RookieAND]

🎯 PR 제목

docs: 프로젝트 개발 가이드 문서 추가

📑 작업 상세 내역

• 문서 작업
  • CLAUDE.md 프로젝트 아키텍처 및 코딩 컨벤션 가이드를 추가합니다
  • PR 문서 자동 생성 스킬(.claude/skills/pr-create/SKILL.md)을 추가합니다
  • PR GitHub 제출 스킬(.claude/skills/pr-submit/SKILL.md)을 추가합니다
  • API 레이어 구조 및 신규 도메인 추가 가이드(src/apis/README.md)를 추가합니다
  • 컴포넌트 작성 규칙 및 접근성 체크리스트(src/components/README.md)를 추가합니다

🙏 리뷰 요청 사항

• CLAUDE.md의 코딩 컨벤션이 프로젝트 현재 구조와 일치하는지 확인해주세요
• API 및 컴포넌트 가이드가 실제 개발 워크플로우에 도움이 되는지 검토해주세요
• PR 스킬 문서가 명확하고 사용하기 쉬운지 확인해주세요

📃 참고 자료

• 추가된 문서

  • CLAUDE.md - 프로젝트 전체 가이드 (아키텍처, 기술 스택, 코딩 컨벤션)
  • .claude/skills/pr-create/SKILL.md - PR 문서 자동 생성 워크플로우
  • .claude/skills/pr-submit/SKILL.md - GitHub PR 제출 자동화
  • src/apis/README.md - API 레이어 개발 가이드
  • src/components/README.md - 컴포넌트 개발 가이드

• 문서 구조

  • 프로젝트 개요 및 기술 스택 소개
  • API 패턴 및 신규 도메인 추가 절차
  • 컴포넌트 작성 규칙 및 베스트 프랙티스
  • 폼 처리, 스타일링, 에러 처리 가이드라인
  • PR 생성 및 제출 자동화 워크플로우

🖼️ 작업 결과물

문서 개요

CLAUDE.md

• 내용: 프로젝트 전체 아키텍처 및 개발 가이드
• 포함 섹션:
  • 프로젝트 개요 및 기술 스택
  • 프로젝트 구조 및 디렉토리 구성
  • 코딩 컨벤션 (네이밍, 임포트 규칙)
  • API 패턴 및 React Query 사용법
  • 폼 처리 패턴 (React Hook Form + Zod)
  • 스타일링 가이드 (Tailwind CSS v4 + CVA)
  • 에러 처리 및 환경 변수 관리

src/apis/README.md

• 내용: API 레이어 구조 및 개발 가이드
• 포함 내용:
  • API 모듈 구조 (api.ts, type.ts, queryKey.ts 등)
  • Query Key Factory 패턴
  • React Query Options 작성법
  • 신규 도메인 추가 체크리스트
  • 에러 처리 및 타입 안전성 가이드

src/components/README.md

• 내용: 컴포넌트 개발 규칙 및 체크리스트
• 포함 내용:
  • 컴포넌트 작성 규칙
  • Props 타입 정의 패턴
  • CVA를 사용한 변형 관리
  • 접근성 체크리스트 (ARIA, 키보드 내비게이션)
  • 반응형 디자인 가이드

PR 스킬 문서

• pr-create: 커밋 이력 기반 PR 문서 자동 생성
• pr-submit: GitHub PR 제출 및 reviewer/label 자동 설정

기대 효과

1. 온보딩 시간 단축: 새로운 팀원이 프로젝트 구조를 빠르게 이해
2. 일관된 코드 품질: 코딩 컨벤션 및 베스트 프랙티스 준수
3. 생산성 향상: PR 생성/제출 자동화로 반복 작업 감소
4. 유지보수성 개선: 명확한 가이드라인으로 코드 일관성 유지

[gemini-code-assist]

Summary of Changes

Hello @RookieAND, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 Pull Request는 프로젝트의 개발 효율성과 코드 품질을 향상시키기 위한 광범위한 문서화를 도입합니다. 새로운 팀원의 온보딩 시간을 단축하고, 개발자 간의 일관된 코드 스타일 및 개발 패턴을 유지하며, PR 생성 및 제출 과정을 자동화하여 반복 작업을 줄이는 것을 목표로 합니다. 이를 통해 전반적인 개발 생산성과 유지보수성을 개선할 것으로 기대됩니다.

Highlights

• 프로젝트 개발 가이드 추가: 프로젝트 아키텍처, 기술 스택, 코딩 컨벤션 등 전반적인 개발 가이드라인을 담은 CLAUDE.md 문서가 추가되었습니다.
• PR 문서 자동 생성 스킬 추가: 커밋 이력을 기반으로 GitHub PR 문서를 자동으로 생성하는 .claude/skills/pr-create/SKILL.md 문서가 추가되었습니다.
• PR GitHub 제출 스킬 추가: 생성된 PR 문서를 GitHub에 업로드하고 리뷰어 및 라벨을 자동으로 설정하는 .claude/skills/pr-submit/SKILL.md 문서가 추가되었습니다.
• API 레이어 구조 및 신규 도메인 추가 가이드: API 레이어의 구조와 새로운 API 도메인을 추가하는 절차 및 모범 사례를 설명하는 src/apis/README.md 문서가 추가되었습니다.
• 컴포넌트 작성 규칙 및 접근성 체크리스트: 컴포넌트 개발 규칙, CVA 사용법, 접근성 체크리스트 등을 포함하는 src/components/README.md 문서가 추가되었습니다.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• .claude/skills/pr-create/SKILL.md
  • 커밋 이력을 분석하여 GitHub PR 문서를 자동으로 생성하는 스킬에 대한 상세 가이드가 추가되었습니다.
  • 브랜치 정보 수집, 베이스 브랜치 결정, 커밋/변경사항 추출 및 그룹핑, PR 제목 생성, Markdown 문서 생성 절차가 설명되었습니다.
  • 커밋이 없거나 베이스 브랜치를 찾을 수 없는 경우의 에러 처리 방법과 사용 예시가 포함되었습니다.
• .claude/skills/pr-submit/SKILL.md
  • 생성된 PR 문서를 GitHub에 업로드하고 리뷰어 및 라벨을 자동으로 설정하는 스킬에 대한 상세 가이드가 추가되었습니다.
  • PR 문서 존재 확인, PR 제목 추출 및 타입 분석, 라벨 자동 결정, 리뷰어 자동 추출, 브랜치 Push 확인, PR 생성 및 정리 작업 절차가 설명되었습니다.
  • PR 문서가 없거나 브랜치가 remote에 없는 경우, GitHub CLI 인증 실패, 라벨이 존재하지 않는 경우의 에러 처리 방법과 사용 예시가 포함되었습니다.
• CLAUDE.md
  • 프로젝트 개요, 기술 스택, 프로젝트 구조, 코딩 컨벤션 등 프로젝트 전반에 걸친 개발 가이드가 추가되었습니다.
  • API 패턴, 폼 처리 패턴, 스타일링 가이드, 에러 처리, 환경 변수, 배포 및 CI/CD 전략에 대한 상세 설명이 포함되었습니다.
  • Tailwind 프리픽스 필수, React Query Retry 설정, Docker Build, useSuspenseQuery 사용, 보안, Next.js Image Optimization, 디자인 시스템, 성능 최적화, 타입 안전성, 캐시 전략 등 중요 주의사항이 명시되었습니다.
• src/apis/README.md
  • API 레이어의 디렉토리 구조와 새로운 API 도메인을 추가하는 방법에 대한 가이드가 추가되었습니다.
  • type.ts, api.ts, queryKey.ts, queryOptions.ts, mutationOptions.ts, index.ts 파일별 작성 규칙과 예시가 제공되었습니다.
  • Query Key 네이밍 규칙, staleTime 설정 가이드, Mutation 성공 시 쿼리 무효화 로직, 에러 처리 방법 등 중요 규칙이 명시되었습니다.
• src/components/README.md
  • 컴포넌트 분류, 새 컴포넌트 추가 방법, CVA 변형 작성 가이드 등 컴포넌트 개발에 대한 가이드가 추가되었습니다.
  • 스타일링 규칙 (ygi: 프리픽스, 디자인 토큰 사용 등), 접근성(a11y) 체크리스트, 'use client' 사용 기준이 설명되었습니다.
  • 성능 최적화 팁 (조건부 렌더링, React.memo, useMemo, useCallback)과 기존 컴포넌트 참고 자료가 포함되었습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

프로젝트 개발 가이드 문서 추가 PR을 검토했습니다. 몇몇 문서의 코드 예제가 저장소의 코딩 스타일 가이드와 일치하지 않는 부분을 발견하여 수정을 제안합니다. 특히 컴포넌트 선언 방식에 대한 예제가 실제 코드 및 가이드라인과 달라 통일이 필요합니다. 또한 API 가이드 문서에서 코드 예제 오타를 발견했습니다.

[gemini-code-assist]

컴포넌트 작성 규칙 예시가 저장소 스타일 가이드와 일치하지 않습니다. 스타일 가이드(64-77행)에서는 모든 컴포넌트를 화살표 함수로 작성하도록 규정하고 있으나, 예시에서는 function 선언을 사용하고 있습니다. 이는 실제 프로젝트 코드(src/components/button/Button.tsx 등)와도 달라 혼동을 줄 수 있습니다. 가이드의 일관성을 위해 화살표 함수 방식으로 수정하는 것이 좋습니다.

Suggested change

	export function Button({ variant, className, ...props }: ButtonProps) {
	return (
	<button
	className={buttonVariants({ variant, className })}
	{...props}
	/>
	);
	}
	export const Button = ({ variant, className, ...props }: ButtonProps) => {
	return (
	<button
	className={buttonVariants({ variant, className })}
	{...props}
	/>
	);
	};

References

1. 모든 컴포넌트는 화살표 함수(Arrow Function)로 작성하고, 선언과 동시에 export해야 합니다. function 선언 방식은 사용하지 않습니다. ^(link)

[gemini-code-assist]

컴포넌트 기본 템플릿 예시가 저장소 스타일 가이드(64-77행)의 컴포넌트 작성 규칙(화살표 함수 사용)과 다릅니다. function 선언 대신 const와 화살표 함수를 사용하는 방식으로 수정하여 가이드의 일관성을 유지하고 개발자의 혼동을 방지해야 합니다.

export const ComponentName = ({
  variant,
  size,
  disabled,
  loading,
  icon,
  className,
  children,
  ...props
}: ComponentNameProps) => {
  return (
    <button
      className={cn(
        componentVariants({ variant, size, disabled: disabled || loading }),
        className
      )}
      disabled={disabled || loading}
      {...props}
    >
      {loading && <Spinner />}
      {icon && <span className="ygi:mr-2">{icon}</span>}
      {children}
    </button>
  );
};

References

1. 모든 컴포넌트는 화살표 함수(Arrow Function)로 작성하고, 선언과 동시에 export해야 합니다. function 선언 방식은 사용하지 않습니다. ^(link)

[gemini-code-assist]

Mutation hook 예제 코드에 오타가 있습니다. use Create[Domain]은 유효한 함수명이 아니므로, useCreate[Domain]으로 수정해야 합니다. 개발자가 코드를 복사하여 사용할 때 오류가 발생할 수 있습니다.

Suggested change

	export const use Create[Domain] = () => {
	export const useCreate[Domain] = () => {

[gemini-code-assist]

React.memo 사용 예시 또한 스타일 가이드(64-77행)에 따라 화살표 함수로 작성하는 것이 일관성에 좋습니다. memo로 감싸는 컴포넌트도 화살표 함수 형태로 수정하는 것을 권장합니다.

Suggested change

	export const HeavyComponent = memo(function HeavyComponent({ data }: Props) {
	// 복잡한 렌더링 로직
	});
	export const HeavyComponent = memo(({ data }: Props) => {
	// 복잡한 렌더링 로직
	});

References

1. 모든 컴포넌트는 화살표 함수(Arrow Function)로 작성해야 한다는 규칙은 일관성을 위해 React.memo로 감싸는 컴포넌트에도 적용하는 것이 좋습니다. ^(link)

[youngminss]

오케이 이거는 일단 프로젝트에 바로 반영하자 !
나는 회사에서는 작업하면서 내가 반복적으로 프롬프팅하거나 추가적인 팀 컨벤션이 생기면 지속적으로 보완해주는 skill 을 따로 만들어서 등록해서 사용하고 있는데 괜찮은 것 같았어