s-canvas/CONTRIBUTING.md

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. 시작하기

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. 새 기능/버그 수정 워크플로

# 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)