# WORKFLOW-RULES.md (DIRECT-WORKFLOW 상세 규칙)

> 이 파일은 DIRECT-WORKFLOW.md의 상세 규칙을 담은 참조 문서입니다.
> 핵심 워크플로우는 DIRECT-WORKFLOW.md를 참조하세요.

## TDD 규칙 (Lv.2+ 작업에만 적용)

코딩 진입 전(Step 3 실행 전) 아래 절차를 따르세요. Lv.1 단순 수정, 설정/문서 작업은 제외합니다.

1. **테스트 파일 존재 여부 확인**: 해당 모듈의 테스트 파일(`test_<module>.py` 또는 `<module>.test.ts`)이 존재하는지 확인
2. **테스트 파일 없으면**: 테스트 먼저 작성 → 실행하여 실패 확인(RED) → 최소 구현(GREEN) → 리팩터(REFACTOR)
3. **기존 테스트 있으면**: 새 테스트 케이스 추가 → 실행하여 실패 확인(RED) → 구현 → 통과 확인
4. **팀원에게 위임 시**: 구현 서브태스크에 "테스트 먼저 작성" 지시를 반드시 포함

상세 가이드: `~/.claude/skills/tdd-enforcement/SKILL.md` 참조

## LSP 활용 규칙
- 코드 작성/수정 후 반드시 pyright로 타입 체크 실행
- 명령어: `pyright <수정한 파일들>`
- 에러 0건 확인 후 다음 단계 진행
- WARN(경미한 타입 불일치)은 허용하되, 보고서에 기록
- 새 파일 생성 시에도 pyright 체크 필수
- 팀 공용 스크립트: `bash /home/jay/workspace/teams/shared/run_pyright.sh <파일들>`

## Git 커밋 규칙
- 서브태스크 단위로 커밋 (하나의 논리적 변경 = 하나의 커밋)
- 커밋 메시지 형식: `[task-id] 변경 내용 요약`
  - 예: `[task-300.1] 렌더러 Bold 폰트 적용 + 오버플로우 방지`
- 코드 변경 시 반드시 `black` + `isort` 포매팅 후 커밋
- 커밋 전 pyright 체크 통과 필수

### ★★★ Git 원복은 프로젝트(파일) 단위로만 (대원칙)
- 원복/롤백 시 **본인 작업 파일만 대상으로 지정**
- `git checkout -- <파일1> <파일2>` (파일 단위 지정) ✅
- `git stash`, `git checkout .`, `git reset --hard` (전체 대상) ❌ 절대 금지
- 이유: 다른 팀/세션의 uncommitted 변경까지 날아감
- 사고 사례: `git stash`로 대시보드/조직도/스킬 등 무관한 변경 전부 소실

## Context Pressure Hierarchy (컨텍스트 압박 시 우선순위)

> gstack A10 도입: 장시간 작업으로 컨텍스트 윈도우가 부족해질 때, 어떤 정보를 우선 유지할지 명시적으로 정의.

컨텍스트 윈도우가 부족한 상황에서는 아래 우선순위 순서로 정보를 유지한다. 높은 순위의 정보를 절대 삭제하지 않는다.

1. **작업 지시 + task_id** — 현재 무엇을 하고 있는지 (절대 유지)
2. **에러 상태** — 현재 발생 중인 에러와 스택트레이스 (디버깅 필수)
3. **테스트 결과** — 최근 pytest/pyright 실행 결과 (품질 보증)
4. **변경 파일 목록** — 현재까지 수정/생성한 파일 경로 (작업 추적)
5. **팀원 서브태스크 결과** — Task tool 반환값 요약 (통합에 필요)
6. **설계 결정 사항** — 왜 이 방식을 선택했는지 (맥락 보존)
7. **참고 문서 내용** — SKILL.md, 가이드 등 (재참조 가능하므로 마지막)

### 실천 규칙
- 서브태스크 결과는 **핵심 요약만** 유지 (전문 보관 불필요)
- 참고 문서는 **경로만** 기억하고 필요 시 재읽기
- 에러 로그는 **관련 부분만** 유지 (전체 스택트레이스 불필요)
- 컨텍스트 부족 시 자동으로 우선순위 7부터 축소

## 외부 서비스 테스트 규칙

외부 서비스(Threads, SNS, API 등)에 실제 데이터를 올리는 테스트 시:
1. **테스트 결과물 삭제 금지**: 제이회장님이 직접 확인한 후에만 삭제. 자동 삭제 절대 금지.
2. **실패 로그 보존 필수**: 실패 발생 시 에러 메시지, 스택트레이스를 보고서에 전문 기록. "성공 건만 보고"는 보고 부실.
3. **테스트 데이터 품질**: 의미 있는 콘텐츠로 테스트. 검정 화면, 빈 텍스트 등 무의미한 데이터 사용 금지.
4. **테스트 횟수 최소화**: 불필요한 반복 업로드 금지. 1회 성공 확인이면 충분.
5. **보고서에 테스트 결과 전수 기록**: 성공/실패 모두 포함. 실패 건 누락 금지.

## QC 재시도 규칙 [DEPRECATED — Phase 2에서 Hook으로 대체 예정]
- qc_verify.py 실행 → FAIL 항목 발견 시:
  1. FAIL 원인 분석 및 코드 수정
  2. qc_verify.py 재실행
  3. 최대 3회 재시도. 3회 실패 시 팀장이 아누에게 에스컬레이션
- WARN은 보고서에 기록하되 재시도 불필요

## 세션 경량화 규칙 (Session Optimization)

> 컨텍스트 윈도우가 제한적이므로, 세션 관리를 통해 성능을 유지한다.

### 핵심 원칙
1. **한 세션 = 한 가지 일**: 리서치와 구현을 같은 세션에서 하지 않는다
2. **최적 세션 길이**: 30~45분. 이 이상이면 체크포인트 저장 후 새 세션
3. **리서치→/compact→구현 패턴**: 리서치 완료 후 반드시 /compact 실행하고 구현 진입
4. **파일 Read 최소화**: 전체 파일 Read 대신 필요 라인만. 큰 파일은 서브에이전트(Task)로 탐색
5. **중간 체크포인트**: 작업 중간에 진행 상태를 파일로 저장 (세션이 죽어도 이어갈 수 있도록)
   - 체크포인트 경로: `{WORKSPACE_ROOT}/memory/checkpoints/{task_id}.md`
6. **성능 저하 징후 감지 시 즉시 /compact**:
   - 이전에 거부한 방법을 다시 시도
   - 이미 제공된 정보를 재질문
   - 파일 경로 혼동
   - 단순 작업에 여러 번 실패

### /compact 트리거 조건
- 도구 50회 호출 시 (strategic-compact 훅이 자동 경고)
- 리서치 완료 후 구현 진입 전
- 성능 저하 징후 감지 시
- 30분 이상 경과 시

## 서브에이전트 완료 검증 게이트 (필수)
서브에이전트(팀원)는 "완료" 보고 전 반드시 다음을 수행해야 한다:
1. **검증 명령어 식별**: 변경한 코드에 대한 테스트/검증 명령어를 특정한다
2. **실행**: 해당 명령어를 실제로 실행한다 (상상/추론 금지)
3. **전체 출력 확인**: 출력 결과를 끝까지 읽고 에러가 없는지 확인한다
4. **exit code 확인**: 명령어의 exit code가 0인지 확인한다
5. **보고**: 검증 결과를 포함하여 "완료" 보고한다

### 금지 표현 (완료 보고에 사용 불가)
- "should work" / "아마 될 것"
- "probably passes" / "통과할 것으로 예상"
- "I believe it works" / "잘 될 거라 생각"
- "tested mentally" / "머릿속으로 테스트"

**증거 없는 완료 보고 = 미완료 처리**

## 코드 리뷰 피드백 수용 프로토콜
리뷰 피드백(팀장/QC/마아트 등)을 받았을 때 서브에이전트(팀원)는 다음 절차를 따른다:

1. **기술적 재진술**: 피드백을 자신의 말로 기술적으로 재설명한다
2. **코드베이스 실사용 확인**: 해당 피드백이 실제 코드에서 어떻게 적용되는지 확인한다
3. **YAGNI 체크**: 피드백 적용이 현재 요구사항에 실제로 필요한 변경인지 판단한다
4. **근거 없으면 반박**: 피드백에 기술적 근거가 부족하면 정중히 반박한다

### 금지 표현 (리뷰 피드백 수신 시)
- "Great point!" / "좋은 지적이에요!"
- "Absolutely, I'll fix that right away" (무비판 수용)
- 피드백의 모든 항목을 무조건 적용

### 핵심 원칙
- 리뷰어도 틀릴 수 있다. 비판적으로 평가하라.
- 불필요한 수정은 코드 복잡도만 높인다.
- "수정했습니다"가 아니라 "수정한 이유"를 보고하라.

## 합리화 방지 (Anti-Rationalization) — 프로세스 스킵 금지

### <HARD-GATE> 절대 스킵 불가 프로세스
다음 프로세스는 어떤 이유로든 건너뛸 수 없다:
- TDD 사이클 (Lv.2+ 작업)
- 완료 전 검증 게이트
- 보고서 작성

### Red Flag 문장 — 이 말이 나오면 프로세스 위반 경고
아래 문장(또는 유사한 표현)은 프로세스를 스킵하려는 합리화 신호다:
- "이건 너무 단순해서 TDD가 불필요하다" → TDD 스킵 금지
- "이미 수동으로 테스트했다" → 자동 테스트 필수
- "작은 수정이라 검증 불필요" → 모든 변경은 검증 필요
- "이 스킬은 이미 기억하고 있다" → 최신 버전을 다시 읽어라
- "시간이 부족하니 나중에 테스트" → 테스트 없이 완료 보고 불가

### 합리화 감지 시 행동
1. 위 문장 또는 유사 표현이 떠오르면 → 즉시 멈추고 해당 프로세스를 실행한다
2. 프로세스를 실행한 뒤에도 불필요하다고 판단되면 → 근거를 보고서에 명시한다
3. 근거 없이 스킵한 것이 발견되면 → 미완료 처리

## 에이전트 미팅 기록 규칙

에이전트 미팅을 진행하는 경우(Level 3+ 작업, 제이회장님 지시 등), **반드시** 미팅 기록을 별도 파일로 저장해야 합니다.

### 저장 위치
`{WORKSPACE_ROOT}/memory/meetings/{task_id}-meeting.md`

사이클이 여러 개인 경우:
`{WORKSPACE_ROOT}/memory/meetings/{task_id}-meeting-cycle{N}.md`

### 미팅 기록 파일 포맷

```markdown
# {미팅 주제}

**일시**: YYYY-MM-DD
**Task**: {task_id}
**팀**: {team_id}
**퍼실리테이터**: {팀장 이름}
**참석자**: {참석 에이전트 목록}

---

## 안건

### [토론 1] {주제}
**{참가자A}**: 발언 내용
**{참가자B}**: 발언 내용
...

### [토론 2] {주제}
...

---

## 합의 사항
- 결정 1
- 결정 2

## 미해결 사항
- (있으면 기록)
```

### 핵심 규칙
1. 미팅 기록은 보고서(reports/)와 **별도** 파일로 저장 (보고서에는 "미팅 N사이클 진행, 상세: meetings/{task_id}-meeting.md 참조" 형태로 링크)
2. 보고서에 미팅 내용을 중복 기술하지 말 것 — 합의 결론만 요약하고 상세는 미팅 파일 참조
3. 사이클별로 별도 파일 생성 (1사이클만이면 단일 파일)
4. 로키(DA) 공격 및 반영 결과는 미팅 파일에 포함

## ⚠️ 디자인 작업 제한
이미지 생성, 배너/광고소재 디자인, 카드뉴스, 인포그래픽 등 비주얼 디자인 작업은 **개발팀 범위 밖**입니다.
- satori-cardnews, gemini-image, hybrid-image, canvas-design 스킬 직접 호출 금지
- 디자인 관련 작업이 지시에 포함되어 있으면 보고서에 "디자인팀 호출 필요"로 명시
- 디자인팀: dispatch.py --team design으로 별도 위임