teguma: Instructions file for Codex

teguma 운영환경

Figma 오픈소스 프로젝트 컬렉션. 이슈 기반 개발, 릴리스 관리, 자동화 리뷰를 따른다.

---

핵심 원칙

• 1 이슈 = 1 브랜치 = 1 워크트리 — 워크트리는 항상 깔끔하게 유지
• 작업 순서: 이슈 조사(인터넷 조사 포함) → 기획/명세 작성 → 구현 → PR → 리뷰 → 머지
• tidy: 레포 구조·거버넌스·문서 정비 시 tidy 스킬 사용
• atlas: 코드 아틀라스 유지보수 시 maintain-code-atlas 스킬 사용

---

브랜치·워크트리 규약

main            ← 항상 릴리스 가능 상태
feat/<issue>-<slug>
fix/<issue>-<slug>
hotfix/<slug>
research/<slug> ← 조사 전용 (머지 안 할 수 있음)

• 워크트리 경로: ../teguma-wt/<branch-name>
• 머지 후 워크트리 즉시 제거 (git worktree remove)
• main은 fast-forward 전용, force-push 금지

---

커밋 규약 (Conventional Commits)

feat: <summary>        → minor
fix: <summary>         → patch
docs: <summary>
chore: <summary>
refactor: <summary>
test: <summary>
perf: <summary>
breaking: <summary>    → major

• 본문에 Closes #<issue> 또는 Refs #<issue> 포함
• 1 커밋 = 1 논리 변경. WIP 커밋은 squash 전까지만 허용

---

1. 리뷰 절차

1. 셀프 리뷰 — git diff main...HEAD 전체 읽기, 오타·디버그 코드·주석 처리 확인
2. AI 리뷰 — 설계 원칙(SOLID, DRY, KISS)·엣지 케이스·명세 일치 여부 점검
3. fixup — 지적 사항 반영, git commit --fixup 사용
4. squash merge — gh pr merge --squash --delete-branch

리뷰 체크리스트:

• 명세(spec)와 구현이 일치하는가
• 에러 핸들링·빈 입력·대형 입력 엣지 케이스
• 시크릿·개인정보 하드코딩 없음
• 테스트가 핵심 경로를 커버하는가
• 불필요한 의존성 추가 없음

---

2. 머지 후 루틴

git checkout main && git pull --ff-only
git worktree remove ../teguma-wt/<branch>
git branch -d <branch>
gh issue close <issue>   # 또는 PR 머지가 자동 close

• 이슈 닫힘 확인 후 릴리스 판단 (아래 3번 참조)
• 마일스톤 진행률 갱신

---

3. 릴리스 체계

• semver 엄격 준수: MAJOR.MINOR.PATCH
• feat → minor, fix → patch, breaking → major
• CHANGELOG.md 자동 갱신 (Conventional Commits 기반)
• 릴리스 시 작성:
  • CHANGELOG.md 항목
  • GitHub Release 노트 (What Changed / Breaking / Migration)
  • 태그: v<semver>
• 매 버전 업데이트 리포트 작성 → docs/releases/v<version>.md

---

4. 핫픽스 절차

긴급 수정용 빠른 경로:

1. hotfix/<slug> 브랜치를 main에서 생성
2. 명세 생략 가능, AI 리뷰 생략 가능
3. 최소 셀프 리뷰(변경 diff 읽기)는 필수
4. 머지 후 즉시 patch 릴리스
5. 사후에 이슈 등록 + 회고 기록

---

5. 주간 회고