ACJB

Imported from tjfakstn/ACJB (AGENTS.md). Install upstream with npx skills add tjfakstn/ACJB. Copyright stays with the author.

AGENT.md

이 문서는 이 저장소에서 작업하는 AI 코딩 에이전트(Claude Code, Cursor, Copilot 등)를 위한 안내서입니다. 사람을 위한 문서는 README.md, 기여 규칙은 CONTRIBUTING.md를 참고하세요. TODO: 표시는 팀에서 확정 후 채워 넣어야 하는 부분입니다.

1. 프로젝트 개요

팀명: 안캡잘부 (아주대학교 소프트웨어학과 26-2 캡스톤디자인) 프로젝트명: TODO: 서비스 이름 확정

Figma와 GitHub를 기반으로 개발 과정에서 발생하는 QA를 보다 편하게 관리할 수 있는 서비스입니다.

해결하려는 문제

• 디자인과 실제 구현 사이의 차이를 확인하는 작업이 수작업이고 반복적임
• 발견된 이슈가 흩어져 있어 정리와 추적이 어려움
• 디자이너 · 개발자 · PM 사이에서 "무엇을 어떻게 고쳐야 하는지"가 명확히 전달되지 않음

핵심 목표

1. 디자인(Figma)과 구현(배포된 화면/코드)의 차이를 확인할 수 있게 한다
2. 발견된 이슈를 구조화된 형태로 정리한다
3. 수정이 필요한 지점을 빠르게 찾아 GitHub 흐름으로 연결한다

우리가 중요하게 생각하는 것

완성된 결과물보다, 문제를 올바르게 정의하고 검증 가능한 형태로 해결해 나가는 과정을 우선합니다. 에이전트도 마찬가지로 완성도 높은 큰 덩어리보다, 검증 가능한 작은 단위로 작업해 주세요.

2. 팀 & 역할

• 제품 스펙/우선순위 결정 → 오단비
• 코드·개발 전반 → 설만수 (오단비가 개발 보조)
• UI 컴포넌트·디자인 토큰 변경 → 최유정

에이전트는 위 영역에 영향을 주는 변경을 할 때, PR 설명에 담당자를 명시해 주세요.

3. 기술 스택

TODO: 나머지는 확정되는 대로 채우기

결정 배경은 docs/decision_log.md 참고.

4. 저장소 구조

TODO: 실제 구조로 갱신

.
├── apps/            # 서비스 애플리케이션
├── packages/        # 공용 모듈
├── docs/            # 기획·설계 문서
└── AGENT.md

• 새 디렉터리를 만들 때는 이 표를 함께 갱신할 것
• 문서(docs/)와 코드가 어긋나면 문서를 먼저 고칠 것

5. 개발 환경 & 자주 쓰는 명령어

TODO: 실제 명령어로 갱신

# 설치
TODO

# 개발 서버
TODO

# 린트 / 포맷
TODO

# 테스트
TODO

# 빌드
TODO

환경 변수

• 실제 값은 .env에 두고, 절대 커밋하지 않습니다
• 새 환경 변수를 추가하면 .env.example에 키와 설명을 함께 추가합니다
• Figma / GitHub 토큰은 로컬에서만 사용하고, 로그에 출력하지 않습니다

6. 코드 컨벤션

• 언어: TODO (예: TypeScript strict 모드)
• 포맷터/린터: TODO (예: Prettier + ESLint) — 커밋 전 반드시 실행
• 네이밍: 파일 TODO, 컴포넌트 PascalCase, 함수/변수 camelCase, 상수 UPPER_SNAKE_CASE
• 주석은 "무엇"보다 "왜"를 남깁니다
• 외부 API(Figma, GitHub) 응답은 반드시 타입/스키마로 검증한 뒤 사용합니다

7. Git & 협업 규칙

브랜치 (2026-09-09 개정 — 실제 개발이 대부분 1인 체제라 영역별 브랜치로 단순화)

main      # 배포 가능한 상태 — 절대 직접 작업/커밋 금지. dev에서 병합될 때만 갱신
dev       # 통합 브랜치 — server + client를 합쳐서 검증
server    # 백엔드(Spring) 작업
client    # 프론트엔드(React) 작업

• 분야별 작업 흐름: server(또는 client)에서 server/<작업 설명> 하위 브랜치로 분기 → 작업 완료되면 server로 병합 → server가 어느 정도 쌓이면 dev로 통합
• 아주 작은 수정이면 하위 브랜치 없이 server/client에 바로 커밋해도 됨
• server/client → dev: 통합 확인 위해 수시로 병합 (셀프 머지 가능)
• dev → main: 배포할 때만 병합. 병합 전 dev에서 실제로 동작 확인 필수
• 팀원(오단비)이 코드에 기여할 경우에도 server/client 브랜치를 통해서만 작업하고 main은 건드리지 않음

이전 방식(이슈번호 기반 feat/fix/docs/refactor/chore 접두사, develop 브랜치)은 폐기. 배경: decision_log.md

커밋 메시지 — Conventional Commits 확정

<type>: <설명>

feat: Figma 프레임 목록 조회 API 추가
fix: 이슈 목록 페이지네이션 오류 수정
docs: AGENT.md 초안 작성
refactor: 이슈 매핑 로직 단순화
test: 프레임 diff 유닛 테스트 추가
chore: eslint 설정 정리

• type: feat fix docs refactor test chore style perf 중 하나
• 설명은 한글/영어 무관, 현재형 동사로 "무엇을 했는지"만 간결하게
• 커밋 하나 = 논리적으로 하나의 변경 단위 (여러 목적 섞지 않기)

PR

• 하나의 PR은 하나의 목적만 다룹니다
• PR 템플릿에 따라 무엇을 / 왜 / 어떻게 검증했는지를 반드시 작성합니다
• server/client → dev는 셀프 머지 가능 (혼자 개발하는 영역이라 리뷰어를 못 구하는 경우가 많음)
• dev → main(배포)은 가능하면 팀원 1명 확인 후 머지. 급하면 셀프 머지하되 PR 설명에 검증 근거를 충분히 남길 것
• 제목도 Conventional Commits 형식 권장 (예: feat: 프레임 diff 조회 API 추가)

이슈

• 버그/기능/QA 이슈는 이슈 템플릿을 사용합니다 (버그 리포트, 기능 요청, QA 이슈 3종)

8. QA & 검증

우리 서비스가 다루는 주제인 만큼, 우리 저장소의 QA 기준도 명확해야 합니다.

• 기능 추가 시 최소 1개의 테스트 또는 재현 가능한 수동 검증 절차를 남깁니다
• UI 변경 시 Figma 화면과의 차이를 스크린샷으로 PR에 첨부합니다
• "동작할 것 같다"가 아니라 실제로 실행해 본 결과를 근거로 삼습니다

9. 에이전트 작업 규칙

해도 되는 것

• 요청받은 범위 안에서의 코드 작성·수정·리팩터링
• 테스트 추가, 문서 갱신
• 여러 접근이 가능할 때 선택지와 트레이드오프를 먼저 제시

반드시 확인받아야 하는 것

• 의존성 추가/제거, 스택 변경
• DB 스키마 변경, 마이그레이션
• 외부 API 스코프·권한 변경
• 파일 대량 삭제·이동, 디렉터리 구조 변경

하지 말아야 하는 것

• 시크릿/토큰을 코드나 로그에 남기기
• 요청하지 않은 범위까지 임의로 수정하기
• 확인되지 않은 API 스펙을 추측해서 구현하기 (모르면 물어볼 것)
• main 브랜치에 직접 커밋

모호할 때: 추측해서 진행하지 말고, 확인이 필요한 지점을 명시하고 멈춰 주세요.

10. 도메인 용어집

TODO: 팀에서 쓰는 용어로 정리

11. 참고 링크

TODO

• 기획 문서:
• 디자인 파일(Figma):
• 이슈 보드:
• 배포 주소: