나만의 수학 오답노트
Team Delta Front
학생이 만든 오답을 모아 학습 흐름을 끊김 없이 이어주는 나만의 수학 오답노트 플랫폼
세모는 오답을 단순히 “저장”하는 서비스가 아니라, 오답을 다시 풀고 정리하는 과정을 습관으로 만들 수 있게 돕는 학습 공간입니다.
등록 → 확인 → 복습 → 시각화까지 한 흐름으로 연결해, 오답 정리가 실제 실력 향상으로 이어지도록 설계했습니다.
오답이 쌓이면, 다시 풀고 정리할 이유가 생기고
그 과정이 반복되면 공부가 “지속되는” 경험으로 바뀝니다.
| 밥비 | 빙빙 |
|---|---|
 |
 |
| 윤소은 | 김준휘 |
| 역할 | 종류 |
|---|---|
| Monorepo / Workspace |  |
| Framework |  |
| Library |  |
| Programming Language |  |
| Data Fetching / HTTP |   |
| Styling |  |
| UI Docs / Visual Testing |   |
| Testing |   |
| Linting / Formatting |   |
| CI / Deployment (CD) |   |
팀 생산성을 위해 “예측 가능한 규칙”을 우선합니다. 작업은 이슈 기반으로 분리하고, PR 단위로 공유/리뷰/머지합니다.
우리 브랜치 전략은 GitHub Flow 기반 + develop 통합 브랜치 방식입니다.
- develop: 개발용(통합 브랜치) — 모든 작업 브랜치는 develop로 PR 후 머지
- main: 배포용(릴리즈 브랜치) — 배포 시점에만 develop → main 머지
이슈 기반으로 브랜치를 생성하며, 브랜치명은 아래 규칙을 따릅니다.
| 브랜치 | 용도 | 규칙 / 예시 |
|---|---|---|
develop |
개발용(통합) | 모든 작업 브랜치는 develop로 PR |
main |
배포용(릴리즈) | 배포 시점에만 develop → main |
feat/#<issue>/<name> |
기능 작업 | feat/#1/card |
fix/#<issue>/<name> |
버그 수정 | fix/#12/splash-redirect |
refactor/#<issue>/<name> |
리팩토링 | refactor/#2/my-page |
style/#<issue>/<name> |
스타일/포맷 | style/#31/import-order |
test/#<issue>/<name> |
테스트 | test/#18/bar-graph-utils |
chore/#<issue>/<name> |
설정/잡무 | chore/#7/commitlint |
PR 제목은 아래 형식으로 작성합니다.
Type: 작업 내용Type은 앞 글자 대문자로 통일합니다. 예)Feat: 홈 그래프 모션 추가,Fix: 스플래시 재노출 문제 해결
PR은 아래 템플릿을 기반으로 가능한 자세하게 작성합니다.
<!---- 'Closes #'다음에 완료한 이슈 넘버를 작성해 주세요. ex) Closes #4 !-->
## 🔗 관련 이슈
Closes #
## 💡 작업 내용
## 💬 원하는 리뷰 방식(선택)
## 📸 Screenshots or Video(선택)- UI 변경이 있는 경우 스크린샷 필수
- 인터렉션/흐름이 중요한 경우 영상 또는 GIF 권장
- 리뷰어에게 부탁하고 싶은 점/확인이 필요한 부분/도움이 필요한 부분은 “원하는 리뷰 방식”에 주저하지 말고 작성합니다.
- 리뷰/머지 전에 라벨을 꼭 달아 주세요.
- 작업 담당자와 작업 성격을 추후 필터링할 수 있어요.
최소 1명 승인(Approve) 후 merge 가능합니다. 가능한 한 PR 단위를 작게 유지해 리뷰 부담을 낮춥니다. merge된 브랜치는 바로 삭제하여 불필요한 브랜치가 누적되는 것을 방지합니다.
아래 포맷을 사용합니다.
type: 작업 내용- 예:
fix: ~~ 버그 수정,feat: ~~ 기능 구현
| Type | 설명 | 예시 |
|---|---|---|
✨ feat |
기능 구현 / 신규 기능 추가 | feat: 홈 그래프 모션 추가 |
🐛 fix |
버그 수정 | fix: 스플래시가 로그인 리다이렉트 후 다시 뜨는 문제 수정 |
📝 docs |
문서 수정(README/Wiki/가이드 등) | docs: PR 템플릿 추가 |
🎨 style |
포맷/스타일 변경(동작 변화 없음) | style: import 정렬 및 포맷 정리 |
🧪 test |
테스트 추가/수정 | test: 그래프 유틸 테스트 추가 |
🧹 chore |
설정/잡무(기능과 직접 관련 없음) | chore: husky 설정 추가 |
🏗️ build |
빌드/번들/배포 관련 변경 | build: next 빌드 설정 수정 |
🧩 refactor |
리팩토링(동작 변화 없이 구조 개선) | refactor: bar graph 모션 로직 훅으로 분리 |
우리 팀의 코드 품질과 유지보수성을 높이기 위해 기본 코딩 컨벤션을 정리합니다. 모든 신규/수정 코드는 본 규칙을 기본으로 따르며, 예외가 필요한 경우 PR에서 근거를 함께 남깁니다.
TypeScript 기반으로 작성하고, 스타일은 Vanilla Extract(.css.ts)만 사용합니다.
절대 경로 import를 사용하며, index를 key로 쓰지 않습니다. var 키워드는 금지합니다.
또한 공통(shared) 코드는 특정 페이지/도메인에 강하게 의존하지 않도록 설계하여 결합도를 낮게 유지합니다. 전역 상태 접근이나 사이드 이펙트는 최소화하고, 필요 시 props/인터페이스로 주입해 교체 가능성을 확보합니다.
🏷️ 네이밍 컨벤션
| 대상 | 규칙 | 예시 |
|---|---|---|
| 폴더/파일명 | kebab-case | bar-graph-01.tsx, use-bar-graph-motion.ts |
| 컴포넌트/타입 | PascalCase | BarGraph01, CardGraph01Props |
| 변수/함수 | camelCase | handleClick, isActive |
| 상수 | BIG_SNAKE_CASE | GRAPH_TABS, STATE_KEY |
| Props 타입 | 컴포넌트명 + Props |
ButtonProps, AnswerSectionProps |
| API 응답 타입 | XXXResponse |
GetUserListResponse |
| 함수 접두사 | 의미에 맞는 접두사 사용 | get/create/check/handle/is/has/can... |
| TanStack Query 훅 | use + 행위 + 대상 + Query/Mutation |
useGetUserListQuery, usePostCommentMutation |
⚛️ React 컴포넌트 규칙
컴포넌트는 접근성을 기본으로 고려합니다. 버튼/탭/다이얼로그 등 상호작용 요소는 적절한 role과 aria 속성을 제공하고, 클릭 가능한 요소는 키보드 조작 가능해야 합니다.
렌더 성능을 위해 불필요한 재렌더를 피하고, useMemo, useCallback, React.memo는 “효과가 명확한 경우에만” 적용합니다.
리스트 렌더링 시 key는 반드시 안정적인 식별자(id)를 사용합니다. index key는 금지합니다.
🎨 스타일링 규칙 (Vanilla Extract)
스타일은 반드시 .css.ts에서 정의하고, 디자인 토큰을 우선 사용합니다.
컴포넌트 상태나 타입 변화는 recipe와 variant로 표현하고, 불필요하게 중복되는 style 선언은 제거합니다.
반응형은 @media, @container 등을 사용하되, 동일 패턴이 반복되면 공통 상수/유틸로 승격합니다.
🪝 Hooks 규칙
커스텀 훅은 파일명/함수명이 반드시 use*로 시작해야 합니다.
훅이 로딩/에러 상태를 다룬다면 호출부에서 상태를 명확히 구분할 수 있도록 설계합니다.
제네릭 훅은 타입 매개변수 기본값이 적절한지 검토하고, TanStack Query 훅은 네이밍 컨벤션(use + 행위 + 대상 + Query/Mutation)을 따릅니다.
🔌 API 규칙
API 코드는 TanStack Query 통합을 전제로 작성하며, QueryKey Factory 사용을 권장합니다.
응답 타입은 제네릭/불변 데이터 기준으로 타입 안정성을 확보하고, 네이밍은 HTTP메서드 + 명사 형태를 따릅니다(getUserList, postComment 등).
async/await 패턴은 프로젝트 내에서 일관되게 유지합니다.
🧭 라우팅 규칙
라우팅 구조는 중첩 레이아웃과 에러 경계를 적절히 활용합니다. 동적 import 기반 코드 스플리팅을 고려해 chunk 분리를 검토하고, 라우트 전환 시 상태 보존이 필요한 경우 전략을 명확히 합니다.
🧊 상수 규칙
상수는 BIG_SNAKE_CASE로 작성하고 export const로 내보냅니다.
의미 있는 이름을 사용하며, 리터럴은 as const로 타입을 좁혀 안정성을 확보합니다.
🛡️ 보안/성능 체크
민감한 값(API 키/시크릿 등)은 하드코딩하지 않고 환경 변수로 관리합니다.
외부 라이브러리를 추가할 때는 “왜 필요한지”와 “대체 가능성/교체 용이성”을 PR에 남깁니다.
성능 최적화 도구(memo, useMemo, useCallback)는 근거가 있는 곳에만 적용합니다.
📚 Storybook 규칙
스토리 파일은 가능한 한 props 변형을 충분히 커버하도록 작성합니다. 주요 variant, disabled/active 상태, edge case 값(빈 값/최대치/최소치 등)을 포함해 컴포넌트 사용 범위를 문서화합니다.
PR이 develop, main에 올라오면 아래 체크가 자동 수행됩니다.
linttypechecktestbuild
배포는 Vercel로 운영합니다.
(배포 플로우는 팀 정책에 맞게 develop/main 기준으로 관리합니다.)
