> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getporter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> 리니어(CONT) 이슈 생성·커밋·상태 관리 규칙. Use when starting actual documentation work in a session (원칙 — 세션마다 작업 시작 시 이슈 생성, 한 세션 = 한 이슈, 생성 전 기존 이슈 확인, 플랜 단계에서는 이슈 생성 여부를 사용자에게 컨펌), when committing doc changes, or when recording progress on an existing issue. 단순 질문/조사/오타 한 줄 수정에는 불필요. 브랜치 절대 규칙 — master/main/development 에 commit·push·PR 금지, PR base 는 항상 개인 통합 브랜치, chore 는 개인 통합 브랜치에 로컬 커밋만(push 는 사용자 수동).

# SKILL

# 리니어 이슈 워크플로

세션에서 실제 작업(문서·설정 변경)을 시작할 때 리니어 이슈를 만들고, 커밋·진행상황·상태를 이슈 기준으로 관리한다.

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

## 원칙

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

## 이슈 생성

| 항목   | 값                                                         |
| ---- | --------------------------------------------------------- |
| 팀    | **컨텐츠** (이슈 키 `CONT`)                                     |
| 프로젝트 | **Porter AI**                                             |
| 마일스톤 | **마케팅 / 컨텐츠**                                             |
| 담당자  | **이슈를 생성한 사람** (`assignee: "me"` — 팀원마다 다르므로 특정인 하드코딩 금지) |
| 상태   | 작업 시작 시 **In Progress** → 작성·검증·커밋 완료 시 **In Review**     |
| 우선순위 | 작업 성격으로 자동 선택 (아래 기준) — 판단이 어려우면 Medium                   |

**우선순위 기준** (`priority`: 1=Urgent, 2=High, 3=Medium, 4=Low):

* **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 는 사용자 몫 (아래).

수정·검증은 허브(메인 체크아웃, `<user>/main` — `mintlify dev` 가 여기서 돈다)의 워킹트리에서 하고, **커밋할 때만 이슈 브랜치로 전환**한다. `<user>/main` 브랜치 자체에는 커밋하지 않는다. 미커밋 변경은 `git switch` 때 워킹트리에 그대로 따라오므로 검증이 수정 즉시 가능하다.

* **커밋 시퀀스(한 번에 실행)**: `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` 로 내 파일만 스테이징하는 규칙은 동일

**워크트리 옵션 (병렬 세션용)**: 두 작업을 병렬로 진행할 때는 `git worktree add ../docs.getporter.ai.wt/cont-XXX -b <user>/cont-XXX` 로 전용 워크트리를 만들어 그 디렉토리에서 작업한다. `mintlify dev` 는 포트가 겹치므로 워크트리에서는 다른 포트로 띄운다(`npx mintlify dev --port 3001`). 끝나면 `git worktree remove ../docs.getporter.ai.wt/cont-XXX`

## 커밋 규칙

* **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 유지)