# S-CANVAS 개발 사이클 (Red → Green)

> **피드백 #6/#7/#8**: 사용자가 명시한 개발 관리 원칙. 이 문서는 그 원칙을 코드화.

## 1. 개발 사이클 — Red → Green → Push

```
[로컬]                       [원격]
       ↓
   코드 작성/수정
       ↓
   ruff check (자동 fix)  ← Red 단계: 린트 위반 0
       ↓
   pytest (회귀 + 단위)   ← Red → Green 전환: 모든 테스트 통과
       ↓
   git commit             ← pre-commit hook이 ruff 재검사
       ↓
   git push               ← Gitea Actions가 ruff + pytest 재실행
       ↓                     모두 Green 시에만 main에 머지
   [성공 → 다음 작업]
   [실패 → Red 복귀]
```

**핵심 원칙**: Red가 켜진 상태로는 push 금지. main은 항상 Green.

## 2. 새 버그 발견 시 (피드백 #7)

> "버그가 식별되면 수정 후 재발하지 않도록 하는 알고리즘도 필요"

**알고리즘**:
1. 버그 재현 코드 → `tests/test_regressions.py` 에 **먼저** 추가 (Red 상태).
2. pytest 실행 → 새 테스트 fail 확인 (재현 확인).
3. 수정 코드 작성 → pytest 통과 확인 (Green).
4. commit (테스트 + 수정 함께).
5. 이후 누군가가 같은 버그를 재도입하려 하면 → CI에서 즉시 catch.

이게 "재발 방지 알고리즘". 메모만 적는 게 아니라 **실행 가능한 가드**로.

## 3. 코드 퀄리티 장치 (피드백 #8)

| 단계 | 도구 | 무엇을 차단 |
|---|---|---|
| 작성 중 | ruff (LSP/IDE) | 실시간 린트 |
| commit 시 | pre-commit | ruff + 위생 + 비밀 누출 |
| push 시 | Gitea Actions | ruff + py_compile + pytest 매트릭스 |
| 코드 리뷰 | code-reviewer subagent | 비전 위반/구조 함정 |

## 4. 시작하기

```powershell
cd D:\2026\PROGRAM\1_S-CANVAS

# uv 환경
uv venv .venv313 --python 3.13
.\.venv313\Scripts\activate
uv pip install -e ".[py313,dev]"

# pre-commit 등록
pre-commit install
pre-commit install --hook-type pre-push   # push 직전 pytest 추가 게이트

# 테스트 한 번 돌려서 환경 확인
pytest -ra
ruff check
```

## 5. 새 기능/버그 수정 워크플로

```powershell
# 0. 기능 브랜치
git checkout -b feature/my-thing

# 1. (버그 수정인 경우만) 회귀 테스트 먼저 추가 → Red 확인
#    tests/test_regressions.py 에 새 함수 추가
pytest tests/test_regressions.py::test_new_thing  # → fail (정상)

# 2. 코드 작성/수정

# 3. ruff 자동 수정
ruff check --fix

# 4. pytest 통과 확인 (Green 도달)
pytest -ra

# 5. commit (pre-commit이 ruff 재검사)
git add -p
git commit -m "fix: <설명>"

# 6. push (pre-push hook이 pytest 재실행)
git push origin feature/my-thing

# 7. PR 만들기 → Gitea Actions가 매트릭스 검증 → main 머지
```

## 6. 자동 push (피드백 #6 — 본 라운드 미구현, 다음 라운드)

현재는 사람이 `git push` 실행. 다음 라운드 후보:

- **옵션 A (보수)**: `pre-push` 훅에서 ruff + pytest pass 시 자동 `git push` (사람 한 번 더 확인 필요).
- **옵션 B (적극)**: 로컬 `watch` 데몬 — Green 도달 직후 자동 push.
- **옵션 C (안전)**: feature 브랜치만 자동 push, main은 항상 PR.

옵션 C 권장. main 보호는 Gitea repo settings → Branch Protection 으로 강제.

## 7. 서브에이전트 활용

`.claude/agents/` 안 7개 specialized agent — Claude Code 세션에서 자동/명시 호출:
- `product-vision-keeper` — 큰 결정 전 검토
- `ux-designer` — UI 변경
- `performance-guardian` — 성능 회귀 의심
- `library-architect` — 새 구조물/플러그인
- `pyvista-renderer` — 3D 시각 품질
- `code-reviewer` — 코드 변경 후 비판
- `INSTALL_AND_USE.md` — 설치/사용 가이드

`.claude/agents/INSTALL_AND_USE.md` 참고.

## 8. 산출물 (이번 라운드 신규)

- `harness/crash_logger.py` — 크래시 로그 + faulthandler (#1)
- `scanvas_maker.py` `_TIN_EARTH_CMAP` — 파란색 없는 TIN 컬러맵 (#3)
- `pyproject.toml` + `UV_GUIDE.md` — uv 마이그레이션 (#5)
- `ARCHITECTURE_PLAN.md` — Core/Plugin 분리 설계 (#10)
- `PERFORMANCE_BASELINE.md` — 19 핫스팟 + 측정 plan (#11)
- `UI_REDESIGN_PLAN.md` — single-window 재설계 (#4)
- `tests/` + `.pre-commit-config.yaml` + `.gitea/workflows/ci.yml` + 본 문서 — 개발 사이클 인프라 (#6/#7/#8)
- `~/.claude/projects/.../memory/feedback_no_ab_pingpong.md` — A/B 무한루프 금지 영구 룰 (#9)