​

리니어 이슈 워크플로

이 repo 의 이슈는 컨텐츠 팀(CONT) 이다. 사내 다른 repo 에 같은 이름의 스킬이 개발 팀(CTY) 기준으로 존재하므로, 다른 repo 에서 시작한 세션을 이 디렉토리로 옮겨 쓰는 경우 로드된 스킬이 그쪽 값일 수 있다. 이 파일을 직접 읽어 확인한다.

​

원칙

• 한 세션 = 한 이슈. 세션에서 이슈를 만들었거나 이어받았으면, 그 세션의 후속 요청·추가 작업도 같은 이슈에 코멘트·TODO 로 기록한다. 새 이슈 생성은 사용자가 명시적으로 별건으로 요청할 때만
• 이슈 생성 전 기존 이슈부터 확인. 사용자가 언급한 이슈 키 → 세션에서 이미 다룬 이슈 → 같은 작업을 다루는 기존 이슈(필요시 list_issues 검색) 순으로 확인하고, 있으면 새로 만들지 않고 그 이슈에 이어서 기록한다 (코멘트 + TODO 체크)
• 세션마다 실제 작업을 시작할 때 이슈 생성이 원칙. 플랜을 세우고 작업하는 경우에는 플랜 확정 시점에 이슈를 생성할지 사용자에게 컨펌받는다
• 단순 질문/조사/오타 한 줄 수정은 이슈 없이 진행
• chore(스킬·에이전트 설정·의존성 등 repo 메타 정비)는 이슈를 만들지 않는다 — <user>/main 에 로컬 커밋만 하고 push 는 사용자가 수동으로 한다 (아래 브랜치 운용). 문서 내용·사이트 구성을 바꾸는 변경이면 chore 가 아니다

​

이슈 생성

• 1 Urgent: 사이트 다운·잘못된 안내로 인한 장애성 문의 (즉시 대응)
• 2 High: 신규 기능 문서화, 사이트 구조 개편, 사용자가 직접 요청한 핵심 작업
• 3 Medium: 내용 보강·개선·정리
• 4 Low: 오타·문구 다듬기, nice-to-have
• 제목: [포터/Docs] <이슈 제목>
• 본문 형식 (마크다운):

## 요구사항
사용자 요청 요약

## 계획
작업 접근

## TODO
- [ ] 작업 단위 체크박스 (커밋·PR 항목 포함)

​

브랜치 운용 — 허브에서 수정, 커밋 시에만 전환 (기본)

절대 규칙 (모든 에이전트·하네스 공통, 예외 없음)

• master · main · development 에 commit / push / PR 절대 금지 — PR base 로도 쓰지 않는다. 회사 정본이라 개인이 직접 건드리지 않는다. git status 의 “Main branch” 표시를 신뢰하지 말 것.
• PR base 는 항상 <user>/main (개인 통합 허브).
• 이슈 작업은 이슈 브랜치에 커밋 후 반드시 <user>/main 으로 복귀 — 체크아웃을 이슈 브랜치에 남겨두지 않는다.
• 에이전트는 <user>/main 에 push·pull 하지 않는다 — push 와 최신화(pull, PR 머지 후)는 사용자가 직접 한다. 단 chore 의 로컬 commit 은 예외로 <user>/main 에서 하되 push 는 사용자 몫 (아래).

• 커밋 시퀀스(한 번에 실행): git switch -c <user>/cont-XXX(기존 브랜치면 -c 없이) → 내 파일만 스테이징 → 커밋 → git log --oneline -1 로 브랜치 확인 → git switch <user>/main 복귀
• 커밋 직후 허브 트리에는 그 변경이 없다(이슈 브랜치에만 존재). 이어서 확인하거나 같은 이슈에 커밋을 더 쌓으려면 PR 을 <user>/main 에 머지하고 허브에서 pull 한 뒤 계속한다 — 안 그러면 이전 커밋이 빠진 상태 위에서 수정하게 된다
• 미머지 이슈에 의존할 때만 그 이슈 브랜치를 베이스로(스택), PR 베이스도 동일하게 — 선행 이슈 머지 후 베이스를 <user>/main 으로 전환
• PR 머지 후 정리: git branch -d <user>/cont-XXX (원격은 GitHub auto-delete)
• 머지된 이슈 재작업 시 브랜치는 최신 <user>/main 에서 재생성 — git branch -f <user>/cont-XXX <user>/main (또는 삭제 후 재생성) 후 커밋, PR 은 새로 생성. 옛 브랜치 tip 에서 이어 커밋하면 그 사이 머지된 다른 작업이 빠진 낡은 상태 위에서 작업하게 된다
• chore(스킬·에이전트 설정·의존성 등 repo 메타 정비)는 <user>/main 에 로컬 커밋만 한다 (이슈·별도 브랜치·PR 없이). push 는 사용자가 수동으로 하므로 에이전트는 push 하지 않는다. 커밋 전 git status 로 내 파일만 스테이징하는 규칙은 동일

​

커밋 규칙

• commit / push / PR / merge 는 모두 사용자가 명시적으로 지시할 때만 실행한다. 문서 수정·검증(mintlify dev)까지는 자동 진행해도 되지만, 그 다음은 사용자 응답을 기다린다. 한 번의 “커밋” 지시는 그 시점 변경분 1회에만 적용 — 이후 이어진 수정에는 자동 적용되지 않으니 다시 지시받는다. “X 커밋하고 Y 진행” 같은 복합 지시에서도 “커밋”은 X 에만 적용되고 Y 작업 후엔 별도 지시가 필요하다. chore 도 예외 아님(어디에 커밋할지의 규칙일 뿐, 지시 없이 커밋하지 않는다)
• 각 동작은 개별 지시다 — “커밋해” ≠ “PR 만들어”. 커밋 지시에 push·PR 생성이 따라오지 않고, 브랜치 운용 방식 안내(“이슈 브랜치로 커밋하는 방식으로 진행” 등)도 PR 생성 지시가 아니다. PR 은 “PR” 이라는 말이 명시된 지시가 있을 때만 만든다
• 이슈의 gitBranchName(<user>/cont-XXX) 브랜치를 따서 커밋. 베이스는 <user>/main(의존하는 미머지 이슈가 있으면 그 이슈 브랜치). 개인 통합 브랜치가 없어 보여도 master/main/development 를 베이스로 쓰지 말고 사용자에게 통합 브랜치를 확인한다 (위 절대 규칙)
• 커밋 메시지는 AGENTS.md 커밋 컨벤션을 따르고 subject 끝에 이슈 키(CONT-XXX)
• 병렬 세션 주의 (허브 워킹트리 공유 시): 허브를 여러 세션이 같이 수정하는 동안은 다른 세션의 미커밋 변경이 섞여 있고, 체크아웃 브랜치도 다른 세션이 언제든 바꿀 수 있다 (전용 워크트리에서는 해당 없음)
  • 커밋 직전 반드시 git branch --show-current 로 이슈 브랜치인지 확인, 커밋 직후 git log --oneline -1 로 어느 브랜치에 들어갔는지 재확인
  • 커밋이 다른 브랜치에 들어갔으면: 임시 worktree(git worktree add)에서 이슈 브랜치로 cherry-pick 후, 오염된 브랜치는 체크아웃되지 않은 경우에만 git branch -f <branch> <commit>^ 로 복구 — 현재 체크아웃 브랜치에 git reset 을 쓰면 그 사이 또 브랜치가 바뀌어 엉뚱한 브랜치를 되감을 수 있다
  • 커밋 전 git status/git diff 로 파일 소유를 확인하고 내 작업 파일만 스테이징
  • 혼합 파일(내 hunk + 타 세션 hunk)은 hunk 단위 분리: git diff <file> → 내 hunk 만 남긴 패치 → git apply --cached — 스테이징 후 git diff --cached 로 타 세션 변경 미포함을 검증

​

후속 작업 기록

• 작업 진행·완료 시 이슈에 진행상황 코멘트: 커밋 해시(있으면), 검증 결과, 진행 중 발견/수정한 이슈
• 커밋/PR 이후에 이어지는 후속 변경(피드백 반영·추가 요구)도 같은 이슈에 라운드 단위로 코멘트한다 — 커밋 전이라도 변경 내용·검증 결과·미커밋 상태를 남기고, 다음 커밋/PR 시점까지 기록을 미루지 않는다
• 검증을 진행했으면 무엇을 어떻게 확인했는지 코멘트에 남긴다 — 실행한 명령/URL, 통과·실패 건수, 실패한 항목과 조치. mintlify dev 로 확인한 화면이면 어떤 경로를 열어 무엇을 봤는지까지 적는다
• 본문 TODO 를 하나씩 체크: save_issue 로 description 을 갱신 (- [ ] → - [x], 커밋한 항목엔 커밋 해시 병기 권장)
• 이슈 상태 In Review 전환은 작성·검증이 끝나고 커밋까지 지시받아 완료된 시점에 (커밋 전이라면 In Progress 유지)