@angar2/taskery 0.1.0

package/template/.claude/skills/task-plan.md

@@ -0,0 +1,210 @@
+---
+description: task 기획 채우기 — Requirements / Scope / Dev Plan / Test Plan 4 섹션 작성, draft → planned
+---
+
+# /task-plan
+
+## 개요
+
+`draft` 상태 task의 본문 4 섹션(Requirements / Scope / Dev Plan / Test Plan)을 채우고 status를 `planned`로 갱신. 사용자와 대화로 진행 — 인터뷰 + 증폭 + 코드 서치 + Phase 분할.
+
+리뷰는 *대화로 OK* 자동 전이로 단순화 — 별도 리뷰 단계 없음.
+
+## 호출 시점
+
+- `/task-init`로 만든 빈 골격 task에 기획 채울 때.
+- 기존 task 기획 다시 짜고 싶을 때 (단 status=`draft`만. `planned` 이상이면 *직접 Edit*하거나 `/task-init` 새로 만들 것 권장).
+
+## 입력 처리
+
+인자 = (선택) `TASK-NNN` 또는 자동 선택.
+
+분기:
+- **인자 명시**: `.project/tasks/<vX.X>/<NNN>_*.md` 또는 `TASK-<NNN>_*/task.md` 찾아서 진행.
+- **인자 없음**: 활성 plan 버전의 `.project/tasks/<vX.X>/` 안 *상태=draft인 가장 최근 task* 자동 선택 + confirm.
+
+## 단계
+
+### Step 1 — task 파일 + active plan 확인
+
+1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
+2. task 파일 Read:
+   - 인자 있음 → 해당 파일.
+   - 인자 없음 → `ls .project/tasks/<vX.X>/` 결과 중 status=draft인 가장 최근 파일. 발견 시 *"TASK-<NNN> 진행할까요?"* confirm. 없으면 *"draft 상태 task가 없네요. `/task-init` 먼저 호출하세요."* + 종료.
+3. 상태 = `draft` 검증. 다른 상태면 종료 + 안내.
+
+### Step 2 — Requirements 인터뷰 + 증폭
+
+1. 사용자 발화(직전 대화 + task 제목) 정독.
+2. 메인이 *증폭/구체화* — 사용자가 빠뜨리기 쉬운 디테일 보충:
+   - **에러 처리**: 빈 값 / 형식 오류 / 네트워크 오류 등
+   - **보안 고려**: 인증/인가 / 입력 검증 / SQL/XSS 방어 등 (해당 시)
+   - **엣지 케이스**: 동시 호출 / 타임아웃 / 부분 실패 등 (해당 시)
+   - **UX 마이크로 디테일**: 로딩 스피너 / 비활성 버튼 / 키보드 접근성 등 (UI task 시)
+3. 사용자에게 *"이렇게 이해했는데 맞아? 빠진 거 있어?"* confirm. 답 받고 합의된 최종 요구로 정리.
+4. `## Requirements` 섹션 Edit:
+   ```markdown
+   ## Requirements
+
+   사용자 요구:
+   - <원래 발화 그대로 또는 정리>
+
+   메인 증폭:
+   - <에러 처리 / 보안 / 엣지 케이스 / UX 디테일 — 합의된 항목>
+
+   합의:
+   - <최종 합의 — 무엇을 만드는가 한두 줄 요약>
+   ```
+
+### Step 3 — Scope (코드 서치)
+
+1. Grep / Glob / Read로 *영향 받을 파일* 탐색:
+   - 키워드 검색 (관련 도메인 명, 함수명, API 경로 등)
+   - 디렉토리 스캔 (`src/<관련영역>/`)
+   - 인접 파일 (간접 영향 가능성)
+2. `## Scope` 섹션 Edit — 3 파트:
+   - **수정**: 변경될 파일 + 어느 함수/로직
+   - **신규**: 새로 만들 파일 + 예상 경로/역할
+   - **인접**: 간접 영향 가능 파일 (검토 대상 알림용)
+
+```markdown
+## Scope
+
+수정:
+- `src/<...>` — <함수/로직>
+
+신규:
+- `src/<...>` — <역할>
+
+인접 (간접 영향):
+- `src/<...>` — <영향 종류>
+```
+
+### Step 4 — Dev Plan (Phase 분할)
+
+1. 규모(헤더의 micro/small/medium/large) 기준으로 Phase 수 결정:
+   - **micro**: Phase 1 (단일)
+   - **small**: Phase 2~3
+   - **medium**: Phase 4~7
+   - **large**: Phase 8+ (또는 *분리 검토 권장* — 사용자에게 task 쪼갬 제안)
+2. 각 Phase = *독립 단위, 커밋 1개로 의미 있는 단위*.
+3. 각 Phase 5 필드 작성:
+   - **파일**: 변경 대상 (예: `src/auth/login.ts`)
+   - **왜**: 이 phase의 동기/목적
+   - **어떻게**: 구현 방법 1~3줄
+   - **완료 기준**: 끝났다고 판단할 기준 (예: *"API endpoint 200 반환"*)
+   - **진행**: `[ ]`
+4. **Phase 0 (선택) — plan 문서 변경 검토**:
+   - 본 task가 `.project/plans/<vX.X>/` 9 기획 문서 중 어느 것을 *수정/추가/삭제*해야 하는지 검토.
+   - 변경 있음 → Phase 0에 명시 + `spec-diffs/<NNN>_<slug>_spec-diff.md` 파일 생성 (Step 6).
+   - 변경 없음 → Phase 0 생략.
+5. **Phase 점진 작성 OK** — 처음부터 모든 Phase 일괄 작성 금지. 지금 명확한 Phase만 작성하고 진행 중 추가 가능.
+
+```markdown
+## Dev Plan
+
+### Phase 0 — plans/<vX.X>/ 기획 문서 변경 (선택)
+- 변경 문서: <FEATURES.md / API-SPEC.md / ...>
+- 변경 내용: <요약>
+- spec-diff: `spec-diffs/<NNN>_<slug>_spec-diff.md`
+- 진행: [ ]
+
+### Phase 1 — <짧은 이름>
+- 파일: ...
+- 왜: ...
+- 어떻게: ...
+- 완료 기준: ...
+- 진행: [ ]
+
+### Phase 2 — ...
+```
+
+### Step 5 — Test Plan (자유 형식 + 가이드라인)
+
+양식 강제 X. *작업에 맞게 자유롭게* 작성. 단 가이드라인 준수 (TASK_DOC_RULE §2.5):
+
+- **자기완결적**: `/task-test` 격리 세션이 *task.md만 보고* 수행 가능. 메인의 plan/dev 컨텍스트 없이.
+- **명령/기대값 포함**: 무엇을 실행하고 무엇이 기대되는지 명확.
+- **메인 가정 X**: *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 금지.
+
+자유 형식 예 (체크리스트 / 시나리오 / 명령 나열):
+
+```markdown
+## Test Plan
+
+1. `npm run dev` → http://localhost:3000/<경로> 접속.
+2. <시나리오 1>:
+   - 기대: <응답/표시>
+3. <시나리오 2>:
+   - 기대: ...
+
+검증 명령:
+- `npm run lint` PASS
+- `npm run typecheck` PASS
+- `npm run build` PASS
+- `npm test <관련 파일>` PASS
+```
+
+검증 명령은 프로젝트 루트 `CLAUDE.md`의 *검증 명령* 섹션을 참조해 그대로 인용.
+
+### Step 6 — spec-diff 처리 (Phase 0 변경 있을 시)
+
+1. `.project/tasks/<vX.X>/spec-diffs/` 디렉토리 존재 확인 (없으면 `mkdir -p`).
+2. `spec-diffs/<NNN>_<slug>_spec-diff.md` Write — 형식:
+
+```markdown
+# Spec Diff — TASK-<NNN> <제목>
+
+## <plans/<vX.X>/<문서명>.md> [NEW|MOD|DEL]
+
++++
++ <추가/변경 내용>
+---
+- <삭제 내용 (있을 시)>
+```
+
+3. 변경 없음 → Phase 0 자체 생략 + spec-diff 파일 생성 X.
+
+### Step 7 — 사용자 합의 + 상태 전이
+
+1. 작성된 4 섹션 보여주기 — *"이렇게 가자?"* 합의 요청.
+2. 사용자 *"OK"* / *"수정해줘"* 응답:
+   - **OK** → Step 8 진행.
+   - **수정 요청** → 해당 섹션 수정 후 다시 합의. 한도 없이 반복 OK (반복 잦으면 task 분리/규모 재조정 검토).
+3. 합의 완료 후 헤더 status → `planned`로 Edit.
+
+### Step 8 — 결과 보고
+
+```
+✅ TASK-<NNN> 기획 완료
+- Requirements / Scope / Dev Plan / Test Plan 작성
+- 상태: draft → planned
+- Phase 수: <N>개 (규모: <X>)
+- spec-diff: <있음 / 없음>
+- 다음: /task-dev TASK-<NNN> 으로 구현 진입
+```
+
+## 도구 가이드
+
+- **Read**: task 파일 / 활성 plan 9 기획 문서 / 관련 코드 정독
+- **Grep / Glob**: Scope 코드 서치 (관련 함수/파일 탐색)
+- **Edit**: task 파일 4 섹션 채우기 + status 전환
+- **Write**: spec-diff 파일 (Phase 0 변경 시)
+- **AskUserQuestion**: Requirements 증폭 confirm / 합의 단계 / Phase 분할 검토
+
+## 주의사항
+
+- **본문 영역만 작성** — 헤더 5컬럼 중 *상태*만 갱신(`draft` → `planned`). 생성일/플랜/유형/규모는 `/task-init`에서 작성된 값 유지. 단 Step 4에서 *규모가 명백히 잘못 추정*된 게 드러나면 사용자 confirm 후 갱신 OK (예: medium 추정했는데 Phase 8개 나옴 → large 갱신 + 분리 검토).
+- **Phase 선제적 일괄 작성 금지** — small task에 medium 분량 Phase 작성하는 함정 회피. 명확한 것만 작성하고 진행 중 추가.
+- **Test Plan 자기완결적** — 격리 세션이 *task.md만 보고* 수행 가능해야. 메인의 plan/dev 컨텍스트 *"위 Phase에서 만든 X"* 같은 표현 금지. 코드/동작/명령만 명시.
+- ***"잘 될 거야"* 가정 금지** — Test Plan에 메인 가정 작성 금지. 코드와 동작만 신뢰.
+- **합의 없이 status 전환 X** — 사용자 OK 받기 전 `planned` 작성 금지. 합의가 *대화로 OK = 자동 전이* 룰의 핵심.
+- **과규모(large) 시 분리 제안** — Phase 8개 초과 또는 성격 다른 기능 혼재 시 task 분리 권장. 사용자에게 *"A/B로 쪼갤까요?"* 제안.
+
+## 상태 전이
+
+| 진입 시 | 종료 시 |
+|--------|--------|
+| `draft` | `planned` |
+
+(예외 — 합의 못 함: status 그대로 `draft` 유지. 다음 호출 시 다시 시도.)

package/template/.claude/skills/task-test.md

@@ -0,0 +1,189 @@
+---
+description: task 격리 세션 검증 — Task tool 격리 호출 + Test Plan 그대로 수행, developed → testing → tested
+---
+
+# /task-test
+
+## 개요
+
+`developed` 상태 task를 *격리 세션*으로 검증. 메인이 *Task tool*로 sub-agent 호출 + task.md를 prompt로 넘김. 격리 세션은 *task.md만 보고 자기완결적*으로 Test Plan 수행 + PASS/FAIL/UNCERTAIN + 근거 리턴.
+
+**왜 격리?** 메인 세션은 plan/dev 컨텍스트가 누적되어 *"잘 됐을 거야"* confirmation bias 작동. 격리 세션이 *코드와 동작만 신뢰*해서 가정 없이 검증.
+
+## 호출 시점
+
+- `/task-dev` 끝나고 self-check PASS 받은 직후.
+- 도중 끊겼던 검증 이어서 (status=`testing`).
+
+## 입력 처리
+
+인자 = (선택) `TASK-NNN` 또는 자동 선택.
+
+분기:
+- **인자 명시**: 해당 task 파일.
+- **인자 없음**: 활성 plan 버전의 *상태=developed인 가장 최근 task* 자동 선택 + confirm.
+
+## 단계
+
+### Step 1 — task 파일 + Test Plan 추출
+
+1. `.project/AGENT-GUIDE.md` Read → 활성 plan 버전 확인.
+2. task 파일 Read:
+   - 인자 있음 → 해당 파일.
+   - 인자 없음 → `developed` 상태 가장 최근 task. 발견 시 confirm. 없으면 *"검증할 task 없음."* + 종료.
+3. 상태 = `developed` 검증. `testing`이면 이어가기 (Step 2 skip). 그 외면 종료.
+4. `## Test Plan` 섹션 + `## Dev Plan`의 Phase별 *완료 기준* 정독. 자기완결성 점검 — 다른 문서 참조나 *"위에서 만든 X"* 같은 표현 있으면 사용자에게 보고 + Test Plan 보강 후 재시도.
+
+### Step 2 — status 전환 (developed → testing)
+
+진입 시 `developed`인 경우만 헤더 status를 `testing`으로 Edit.
+
+### Step 3 — 격리 세션 호출 (Task tool)
+
+Task tool로 sub-agent spawn. prompt는 *자기완결적* — task.md 경로 + 격리 룰만 명시. 메인 컨텍스트 일체 안 들어감.
+
+**Task tool prompt 본문 (정확히 이 형식)**:
+
+```
+당신은 격리 세션의 tester입니다. 이 prompt에 명시된 룰만 따르고, 메인 세션의 plan/dev 가정은 일체 없습니다.
+
+## 대상 task
+
+파일 경로: <ABSOLUTE_PATH_TO_TASK_MD>
+
+이 파일을 직접 Read 해서 ## Test Plan 섹션 + ## Dev Plan의 Phase별 완료 기준을 정독하세요. 다른 문서 참조 X — task.md 하나만 봅니다.
+
+## 수행 룰
+
+1. ## Test Plan 시나리오를 *순서대로* 그대로 수행. 임의 추가 / 스킵 / 변형 금지.
+2. 각 시나리오마다 *실제 명령 실행* — 실행 없이 pass 처리 절대 금지.
+3. 검증 명령 (린트/타입/빌드/테스트) 모두 직접 실행.
+4. 코드와 동작만 신뢰. *"잘 될 거야"* / *"문제 없을 듯"* 같은 가정 일체 금지.
+5. UI/브라우저 시나리오는 가능한 범위에서 자동화 (Playwright 사용 가능). 자동화 불가능 시 UNCERTAIN으로 표기 + 사용자검수 필요 안내.
+6. 코드 파일 직접 수정 절대 금지. 임시 파일(테스트 스크립트 등) 생성 시 종료 후 삭제.
+
+## 결과 형식 (이 포맷 그대로 리턴)
+
+### 종합 판정
+- **PASS** / **FAIL** / **UNCERTAIN** 중 하나
+- 한 줄 요약
+
+### 시나리오별 결과
+| # | 시나리오 | 실행 명령/방식 | 결과 | 근거 |
+|---|---------|------------|------|------|
+| 1 | <Test Plan 시나리오 1 그대로> | <실행한 명령> | ✅/❌/❓ | <로그 인용 / 응답 / 출력> |
+| 2 | ... | ... | ... | ... |
+
+### 검증 명령 결과
+- 린트: <PASS/FAIL + exit code + 메시지>
+- 타입체크: <...>
+- 빌드: <...>
+- 단위 테스트: <PASS 케이스 수 / FAIL 케이스 수>
+
+### 실패 / 불확정 상세 (해당 시)
+- <어느 시나리오 / 무엇이 깨졌는지 / 어느 로그가 그 증거인지>
+
+### 사용자검수 필요 항목 (해당 시)
+- <자동화 불가능한 시나리오 — 스크린샷 경로 또는 수동 검수 가이드>
+
+## 종료 조건
+
+위 형식 그대로 리턴 후 종료. 코드 수정 시도 금지 — 결과 리턴만.
+```
+
+**구현 디테일**:
+- `<ABSOLUTE_PATH_TO_TASK_MD>` 자리에 `.project/tasks/<vX.X>/<NNN>_<slug>.md` (또는 폴더 승격 시 `<...>/task.md`)의 절대 경로 삽입.
+- Task tool의 `subagent_type`: `general-purpose` (도구 풀 다 필요).
+- Task tool의 `description`: `Isolated test for TASK-<NNN>`.
+
+### Step 4 — 결과 리턴 + Result 섹션 기록
+
+격리 세션 리턴 결과를 `## Result` 섹션의 *테스트* 부분에 기록:
+
+```markdown
+## Result
+
+### 진행
+(`/task-dev`에서 작성된 그대로)
+
+### 테스트 (격리 세션 결과)
+- **<PASS / FAIL / UNCERTAIN>**.
+- 시나리오 <N>개 중 PASS <X>개 / FAIL <Y>개 / UNCERTAIN <Z>개.
+- 검증 명령 (린트/타입/빌드/테스트) 모두 PASS.
+- 근거:
+  - <격리 세션 표 인용 — 핵심 시나리오 + 증거>
+  - <검증 명령 출력 인용>
+
+(FAIL / UNCERTAIN 시) 실패 상세:
+- <시나리오 N: 무엇이 깨졌는지 + 로그 인용>
+```
+
+### Step 5 — PASS / FAIL / UNCERTAIN 분기
+
+격리 세션 종합 판정에 따라 분기.
+
+#### PASS 분기
+
+1. 헤더 status → `tested` Edit.
+2. 결과 보고:
+```
+✅ TASK-<NNN> 격리 검증 PASS
+- 시나리오 <N>개 모두 PASS
+- 검증 명령 모두 PASS
+- 상태: testing → tested
+- 다음: /task-close TASK-<NNN> 으로 git 마무리
+```
+
+#### FAIL 분기
+
+1. status는 `testing` 그대로 (자체 전환 X — 사용자 판단 필요).
+2. 사용자에게 보고:
+```
+❌ TASK-<NNN> 격리 검증 FAIL
+- 실패 시나리오: <목록>
+- 근거: <로그 / 응답 인용>
+
+어떻게 할까?
+1. "고쳐" — 메인이 status를 developing으로 되돌림 + /task-dev 재진입
+2. "OK 마무리" — 실패 알면서 /task-close 진행 (위험: 알려진 결함 채로 closed)
+```
+3. 사용자 *"고쳐"* → 헤더 status `testing` → `developing` Edit + `/task-dev` 안내. 사용자 *"OK 마무리"* → status `testing` → `tested` Edit (단 Result 섹션에 *"알려진 결함 있음"* 명시) + `/task-close` 안내.
+
+#### UNCERTAIN 분기
+
+격리 세션이 자동화 불가능한 시나리오(예: 모바일 사파리 / 외부 결제 / 시각 디자인) 발견 시:
+
+1. 사용자검수 필요 항목 사용자에게 표시 + 스크린샷 경로 (있으면).
+2. 사용자에게 *"이 부분 직접 검수 부탁. 결과 어땠어?"* 묻기.
+3. 사용자 *"PASS"* → PASS 분기로. 사용자 *"FAIL"* → FAIL 분기로.
+
+### Step 6 — 결과 보고 (위 분기별 메시지)
+
+## 도구 가이드
+
+- **Read**: task 파일 / `## Test Plan` + `## Dev Plan` 정독
+- **Edit**: status 전환 + Result 섹션 기록
+- **Task tool**: 격리 세션 호출 (Step 3 prompt 사용)
+- **AskUserQuestion**: FAIL/UNCERTAIN 시 사용자 판단 받기
+
+## 주의사항
+
+- **격리 세션이 코드 수정하면 안 됨** — prompt에 *"코드 파일 직접 수정 절대 금지"* 명시되어 있지만 한 번 더 결과 검토 시 코드 변경 흔적 있으면 사용자에게 보고.
+- **메인이 시나리오 임의 추가 X** — `## Test Plan`에 명시된 것만 격리 세션이 수행. 진행 중 *"이것도 같이 검증하자"* 떠오르면 task.md `## Test Plan` Edit 후 재호출.
+- **자기완결성 검증 먼저** — Step 1에서 Test Plan이 *"위에서 만든 X"* 같은 메인 컨텍스트 의존 표현 있으면 격리 세션이 헤맴. 보강 후 재시도.
+- **PASS 자체 판정 X** — 메인이 *"잘 됐을 듯"* 판정하지 X. 격리 세션 결과만 신뢰.
+- **임시 파일 정리** — 격리 세션이 만든 Playwright 스크립트 / 임시 데이터 종료 시 삭제. 코드베이스 오염 X.
+- **사용자검수 시나리오는 자동화 못 잡음** — UI 미세 조정 / 시각 디자인 / 외부 결제 등은 UNCERTAIN으로 가야 정상. PASS 강제 X.
+- **FAIL → developing 자동 되돌림 X** — 사용자 *"고쳐"* 답 받기 전 status 갱신 금지. *대화로 OK = 자동 전이* 룰의 핵심.
+- **테스트 후 plumbing fix 발견 시** — 격리 PASS 후에도 plumbing(빌드 산출물 정리, 설정 수정 등) fix 필요할 수 있음. 분기:
+  - 검증 명령 *동작 자체에 영향 X* (예: 산출물 위치 정리, 주석 수정) → 메인 자체 재검증 OK (lint/typecheck/build/test 재실행)
+  - 검증 명령 *동작 변경* (예: build 명령 자체 변경, 새 검증 명령 추가, 환경 변수 추가) → **격리 세션 재호출 필수** (환경 변경으로 격리 가정 무효화 — 재검증 가치 사라짐)
+
+## 상태 전이
+
+| 진입 시 | 종료 시 |
+|--------|--------|
+| `developed` | `tested` (PASS) |
+| `developed` | `developing` (FAIL + 사용자 *"고쳐"*) |
+| `developed` | `tested` (FAIL + 사용자 *"OK 마무리"* — 알려진 결함 명시) |
+| `testing` (이어가기) | 동일 분기 |

package/template/.project/FRICTION_LOG.md

@@ -0,0 +1,23 @@
+# FRICTION_LOG
+
+> 짜증 / 한계 / 짚이는 부분 누적.
+> 메인이 사용자 발화에서 *"이거 짜증나"* 감지하거나 사용자 명시 요청 시 한 줄씩 추가.
+> `/refine` 스킬이 정독 + 반복 패턴 감지 + bottoms-up 보강 제안.
+
+**사용 규칙**:
+- 한 행에 한 짜증
+- 손수 편집 X — 메인이 대화로 적음
+- *"이거 짜증나, 적어줘"* 발화 또는 메인 자체 감지 시 추가
+
+---
+
+## 짜증 누적
+
+| 날짜 | 짜증 | 맥락 (어느 task / 스킬 / 카테고리) |
+|------|------|-----------------------------------|
+
+---
+
+## /refine 회고 메타 행
+
+(매 `/refine` 호출 결과를 메타 행으로 추가 — 다음 회고가 *이전 결과 참조*용)

package/template/.project/rules/GIT_RULE.md

@@ -0,0 +1,169 @@
+# GIT_RULE
+
+> 이 파일은 taskery 시스템 권장 프로젝트별 git 정책이다.
+> 우선순위: **이 파일** (`.project/rules/GIT_RULE.md`) → 글로벌 (`~/.claude/rules/GIT_RULE.md`) → 메인 판단.
+> 프로젝트별 변형이 필요하면 `.project/rules/GIT_RULE.local.md` 생성 (npx update 미터치).
+
+---
+
+## 기본 원칙
+
+- **git 작업은 메인 세션이 `/task-close` 스킬 또는 직접 수행**.
+- **main, dev 직접 커밋 절대 금지**: 모든 작업은 태스크 브랜치에서 진행.
+- **하나의 브랜치는 하나의 태스크만 담당**.
+- **작업 브랜치는 dev에서 분기, dev로 병합**.
+- **dev → main 병합은 사용자가 직접 수행**.
+
+---
+
+## 브랜치 구조
+
+| 브랜치 | 용도 |
+|--------|------|
+| `main` | 프로덕션 |
+| `dev` | 통합 개발 |
+| `{타입}/{개발자}_{TASK-NNN}_{kebab-slug}` | 태스크 작업 브랜치 |
+
+### 브랜치 타입
+
+| 타입 | 태스크 유형 |
+|------|-----------|
+| `feature` | feature |
+| `bug` | bug |
+| `improve` | improvement |
+| `refactor` | refactor |
+| `docs` | docs |
+| `chore` | chore |
+
+### 개발자 식별자
+
+고정 목록이 아니며 실제 작업자 이름을 사용한다.
+
+| 작업자 | 식별자 |
+|--------|--------|
+| 사용자 | `angar2` |
+| Claude | `claude` |
+| 기타 AI | 해당 AI 이름 (예: `gpt`, `gemini`) |
+
+### 브랜치 예시
+
+```
+feature/claude_TASK-001_user-auth
+bug/angar2_TASK-002_login-crash
+refactor/gpt_TASK-003_cleanup-api
+```
+
+---
+
+## 커밋 태그
+
+| 태그 | 용도 |
+|------|------|
+| `feat:` | feature |
+| `fix:` | bug |
+| `improve:` | improvement |
+| `refactor:` | refactor |
+| `docs:` | docs, chore |
+| `test:` | 테스트 파일 (유형 무관) |
+
+---
+
+## 커밋 메시지 형식
+
+```
+{태그}: [TASK-{NNN}] Phase {N} - {작업 요약}
+
+- {처리 내용 1}
+- {처리 내용 2}
+- 사유: {변경 이유}
+```
+
+### 예시
+
+```
+feat: [TASK-001] Phase 1 - 사용자 인증 로직 구현
+
+- JWT 기반 인증 로직 구현
+- 로그인 API 엔드포인트 추가
+- 사유: 기존 세션 방식 한계로 전환
+```
+
+---
+
+## 커밋 순서 (태스크 완료 시 — `/task-close` 스킬)
+
+태스크 마무리 시 메인이 아래 순서를 반드시 준수한다.
+
+```
+1. Phase별 기능 커밋 (각 Phase마다 1개)
+2. 태스크 문서 커밋
+3. CHANGELOG 커밋
+4. dev 브랜치 병합 (--no-ff)
+```
+
+### 태스크 문서 커밋 메시지
+
+```
+docs: [TASK-{NNN}] 태스크 문서 완료
+```
+
+### CHANGELOG 커밋 메시지
+
+```
+docs: [TASK-{NNN}] CHANGELOG 업데이트
+```
+
+### 병합 커밋
+
+- 머지 커밋 메시지는 git 기본 메시지 사용
+- `-m` 옵션으로 커밋 메시지 지정 금지
+- **`--no-ff` 강제 (일반 타입)**: feature/bug/improvement/refactor 등 일반 작업 브랜치 → dev 병합 시 `git merge --no-ff {브랜치명}` 사용. fast-forward 병합 절대 금지. 머지 커밋이 없으면 작업 브랜치 삭제 후 분기 정보 영구 손실(90일 reflog GC 후 추적 불가).
+- **plan/roadmap 임시 docs 브랜치 예외**: 단일 커밋이라 `--ff-only` 가능.
+
+---
+
+## 작업 브랜치 삭제 정책
+
+작업 브랜치(feature/* / bug/* / improve/* / refactor/* / docs/* / chore/*)는 다음 조건 모두 만족 시에만 삭제한다:
+1. dev 브랜치에 `--no-ff` 병합 완료 (머지 커밋이 dev에 기록됨)
+2. 사용자 명시 승인 ("브랜치 삭제해" 등 직접 요청)
+
+**메인 세션 룰**: 사용자 승인 없는 작업 브랜치 삭제 지시 절대 금지. 머지 후 자동 삭제 X. 사용자가 직접 요청 시에만 `git branch -d {브랜치명}` 실행. (단, plan/roadmap 임시 docs 브랜치는 단일 커밋 ff-only 머지 후 자동 삭제 가능.)
+
+---
+
+## Hook 안전망 — `git-guard.sh`
+
+`.claude/hooks/git-guard.sh`가 PreToolUse(Bash)로 다음 명령 차단:
+- `main` / `dev` 직접 커밋
+- `git push --force` (작업 브랜치 외 / 사용자 미승인)
+- `git commit --no-verify`
+- `git branch -D` (사용자 미승인)
+- `git reset --hard` (사용자 미승인)
+
+이 hook은 *catastrophic 차단 안전망*. 잘 지키면 작동 0회 (무해).
+
+---
+
+## 금지 사항
+
+- 민감 정보 커밋 금지 (`.env`, API KEY, Secret Key 등)
+- 여러 태스크를 하나의 브랜치에서 작업 금지
+- 커밋 순서 임의 변경 금지
+- 승인 없이 dev 브랜치 병합 금지
+- **destructive 명령 사용자 승인 필수**: 다음 명령은 사용자 명시 승인 없이 절대 실행 금지:
+  - `git reset --hard ...`
+  - `git push --force ...`
+  - `git branch -D ...`
+  - `git clean -fd ...`
+  → 정상 흐름에서 위 명령 사용 사유 없음. 충돌/오류 발생 시 사용자에게 보고 + 승인 요청 의무.
+
+---
+
+## 수정 이력
+
+| 날짜 | 변경 사항 |
+|------|----------|
+| 2026-05-07 | `--no-ff` 강제 + 작업 브랜치 삭제 정책 + destructive 명령 사용자 승인 필수 룰 추가 |
+| 2026-05-08 | git 작업은 메인 세션이 `/task-close` 스킬 또는 직접 수행으로 단일화. git-guard.sh hook 안전망 명시 추가 |
+| 2026-05-09 | 표현 정제 — 인명 / 경박 표현 / 스킬 용어 / 이전 버전 비교 단락 정리 |