<!--
동기화 영향 보고서
==================
버전 변경: 1.0.0 (초기 버전)

추가된 원칙:
- I. 테스트 주도 개발 (협상 불가)
- II. 정리 우선
- III. 코드 품질 표준
- IV. 커밋 규율
- V. 단순성 (YAGNI)
- VI. 시각적 문서화

추가된 섹션:
- 기술 스택 및 의존성
- 개발 워크플로우

템플릿 상태:
- .specify/templates/plan-template.md: ✅ 호환 (변경 불필요)
- .specify/templates/spec-template.md: ✅ 호환 (변경 불필요)
- .specify/templates/tasks-template.md: ✅ 호환 (변경 불필요)

후속 TODO: 없음
-->

# Synapse SDK 헌법

## 핵심 원칙

### I. 테스트 주도 개발 (협상 불가)

모든 기능 개발에서 TDD 사이클을 반드시 따라야 합니다:

1. **Red**: 작은 기능 증분을 정의하는 실패하는 테스트 작성
2. **Green**: 테스트를 통과시키기 위한 최소한의 코드 구현
3. **Refactor**: 테스트가 통과한 후에만 코드 구조 개선

**규칙**:
- 테스트는 반드시 구현 코드보다 먼저 작성해야 합니다
- 테스트 실패는 명확하고 정보를 제공해야 합니다
- 결함 수정 시, 먼저 문제를 재현하는 실패하는 테스트를 작성해야 합니다
- 모든 테스트는 커밋 전에 반드시 통과해야 합니다

**근거**: TDD는 높은 테스트 커버리지를 보장하고, 더 나은 설계를 유도하며, 회귀를
조기에 발견합니다. 테스트되지 않은 코드는 부채이므로 이는 협상 불가입니다.

### II. 정리 우선

모든 변경은 두 가지 유형으로 분리해야 합니다:

1. **구조적 변경**: 동작을 변경하지 않고 코드 재배치 (이름 변경, 메서드 추출,
   코드 이동)
2. **동작적 변경**: 실제 기능 추가 또는 수정

**규칙**:
- 구조적 변경과 동작적 변경을 동일한 커밋에 혼합해서는 안 됩니다
- 둘 다 필요한 경우 구조적 변경을 먼저 수행해야 합니다
- 구조적 변경은 전후로 테스트를 실행하여 검증해야 합니다

**근거**: 변경 유형을 분리하면 코드 리뷰가 쉬워지고, 병합 충돌이 줄어들며,
회귀의 원인을 분리할 수 있습니다.

### III. 코드 품질 표준

모든 코드는 다음 품질 표준을 준수해야 합니다:

- **DRY**: 중복을 철저히 제거
- **명확한 의도**: 이름과 구조를 통해 의도 표현
- **명시적 의존성**: 모든 의존성을 가시적이고 명시적으로
- **단일 책임**: 메서드를 작고 한 가지 작업에 집중
- **최소 부작용**: 상태와 부작용 최소화
- **가장 단순한 해결책**: 가능한 가장 단순한 접근법 사용

**근거**: 고품질 코드는 유지보수 부담을 줄이고, 가독성을 개선하며, 시스템을
확장하고 디버그하기 쉽게 만듭니다.

### IV. 커밋 규율

다음 조건이 모두 충족될 때만 커밋해야 합니다:

1. 모든 테스트가 통과
2. 모든 컴파일러/린터 경고가 해결됨
3. 변경이 단일 논리적 작업 단위를 나타냄
4. 커밋 메시지가 구조적 변경인지 동작적 변경인지 명확히 명시

**규칙**:
- 크고 드문 커밋보다 작고 빈번한 커밋 사용
- 각 커밋은 독립적으로 리뷰 가능해야 합니다
- 커밋 메시지는 프로젝트의 conventional commit 형식을 따라야 합니다

**근거**: 규율 있는 커밋은 깔끔하고 bisect 가능한 히스토리를 만들어 디버깅을
돕고 확신을 가지고 롤백할 수 있게 합니다.

### V. 단순성 (YAGNI)

개발은 YAGNI (You Aren't Gonna Need It) 원칙을 따라야 합니다:

- 현재 요구사항에 필요한 것만 구현
- "혹시 모르니까"라는 이유로 기능, 추상화, 인프라를 추가하지 않음
- 조기 최적화 지양
- 추상적 프레임워크보다 구체적 구현 선호

**규칙**:
- 추가되는 모든 복잡성은 현재의 구체적인 필요로 정당화되어야 합니다
- 필요한지 확실하지 않으면 생략
- 구체적인 코드에서 패턴이 나타날 때만 추상화를 추가하도록 리팩토링

**근거**: 불필요한 복잡성은 즉각적인 가치 없이 유지보수 부담, 인지 부하, 버그
발생 가능 영역을 증가시킵니다.

### VI. 시각적 문서화

명세서와 계획 작성 시 mermaid 차트를 적극 활용해야 합니다:

- **아키텍처 다이어그램**: 시스템 구성요소와 관계 시각화
- **시퀀스 다이어그램**: API 호출 흐름과 컴포넌트 상호작용
- **상태 다이어그램**: 엔티티의 상태 전이
- **ER 다이어그램**: 데이터 모델과 관계
- **플로우차트**: 비즈니스 로직과 의사결정 흐름

**규칙**:
- 복잡한 흐름이나 관계는 반드시 다이어그램으로 시각화해야 합니다
- 텍스트 설명만으로 이해하기 어려운 부분은 다이어그램 추가
- 다이어그램은 mermaid 형식을 사용하여 버전 관리 가능하게 유지

**근거**: 시각적 문서화는 복잡한 시스템을 빠르게 이해하게 하고, 팀 간 의사소통을
개선하며, 설계 리뷰를 효과적으로 만듭니다.

## 기술 스택 및 의존성

이 프로젝트는 다음 기술 스택을 사용합니다. 모든 개발은 이러한 기술과 호환되어야
합니다:

- **언어**: Python 3.12+
- **분산 처리**: Ray (Job, Task, Serve)
- **CLI 프레임워크**: Click
- **데이터 검증**: Pydantic
- **스토리지**: fsspec, s3fs (클라우드 스토리지)
- **테스트**: pytest

**주요 의존성**:
- ray: 분산 처리 및 ML 워크플로우
- click: CLI 명령어 인터페이스
- pydantic: 데이터 모델 검증
- cookiecutter: 플러그인 템플릿 생성
- streamlit: 개발자 도구 대시보드

**규칙**:
- 새 의존성은 반드시 정당화되고 검토되어야 합니다
- 의존성은 반드시 특정 버전에 고정되어야 합니다
- 보안 업데이트는 신속하게 적용되어야 합니다

## 개발 워크플로우

표준 개발 워크플로우는 다음 순서를 따릅니다:

1. **테스트 작성**: 기능의 작은 부분에 대한 간단한 실패하는 테스트 생성
2. **구현**: 테스트를 통과시키기 위한 최소한의 코드 작성
3. **검증**: 테스트를 실행하여 통과 확인 (Green 단계)
4. **정리**: 필요한 구조적 변경 수행, 각 변경 후 테스트 실행
5. **구조적 커밋**: 구조적 변경을 별도로 커밋
6. **반복**: 다음 기능 증분을 위한 또 다른 테스트 추가
7. **동작적 커밋**: 동작적 변경을 구조적 변경과 별도로 커밋

**코드 리뷰 요구사항**:
- 모든 PR은 이 헌법 준수 여부를 검증해야 합니다
- PR은 새 기능에 대한 테스트를 포함해야 합니다
- PR은 병합 전에 모든 CI 검사를 통과해야 합니다

**Ruff 포맷팅**:
- 모든 커밋 전에 `ruff format .` 실행
- 린팅 문제 해결을 위해 `ruff check --fix .` 실행
- 모든 코드는 Ruff 검사를 통과해야 합니다

## 거버넌스

이 헌법은 Synapse SDK 개발을 위한 협상 불가능한 원칙을 수립합니다. 모든 팀
멤버와 기여자는 이러한 원칙을 준수해야 합니다.

**우위**: 이 헌법은 코드베이스의 충돌하는 임시 관행, 구두 합의, 또는 레거시
패턴보다 우선합니다.

**준수**:
- 모든 PR과 코드 리뷰는 헌법 준수를 검증해야 합니다
- 위반은 병합 전에 해결되어야 합니다
- 이러한 원칙을 넘어서는 복잡성은 명시적으로 정당화되어야 합니다

**수정**:
- 이 헌법의 변경은 다음을 요구합니다:
  1. 변경 사항과 근거를 문서화한 서면 제안
  2. 팀 검토 및 승인
  3. 해당하는 경우 기존 코드에 대한 마이그레이션 계획
- 버전은 시맨틱 버전 관리에 따라 증가해야 합니다:
  - MAJOR: 원칙 제거 또는 이전 버전과 호환되지 않는 재정의
  - MINOR: 새 원칙 또는 섹션 추가
  - PATCH: 명확화 및 표현 개선

**런타임 지침**: 상세한 구현 패턴, 테스트 규칙, 코딩 표준은
[AGENT.md](../../AGENT.md)를 참조하세요.

**버전**: 1.0.0 | **비준일**: 2025-12-08 | **최종 수정일**: 2025-12-08
