Skip to main content

개발 원칙

이 문서는 vivid-ai 프로젝트의 모든 개발 과정에서 일관되게 적용되는 핵심 원칙과 협업 방식을 정의합니다.

1. 기술적 원칙 (Technical Principles)​

우리의 코드는 다음 원칙들을 기반으로 작성되어야 하며, 이는 장기적인 유지보수성과 확장성을 보장하기 위함입니다.

가. SOLID 원칙​

  • 단일 책임 원칙 (SRP): 모든 클래스, 모듈, 컴포넌트는 단 하나의 책임만 가져야 합니다.
    • 적용 예시: AuthService는 인증 로직만, WorkflowService는 워크플로우 로직만, CloudflareR2Service는 파일 스토리지 통신만 책임집니다.
  • 개방-폐쇄 원칙 (OCP): 기존 코드의 수정에는 닫혀 있고, 기능의 확장에는 열려 있어야 합니다.
    • 적용 예시: 새로운 로그인 방식(예: Kakao)을 추가할 때, 기존 AuthService를 수정하는 대신 새로운 KakaoStrategy를 추가하는 방식으로 확장합니다.
  • 리스코프 치환 원칙 (LSP): 자식 클래스는 부모 클래스의 역할을 완벽하게 대체할 수 있어야 합니다.
  • 인터페이스 분리 원칙 (ISP): 클라이언트는 자신이 사용하지 않는 메소드에 의존해서는 안 됩니다.
    • 적용 예시: IStorageService와 같이 인터페이스를 사용하여, UIService는 스토리지의 구체적인 구현을 몰라도 되도록 설계합니다.
  • 의존관계 역전 원칙 (DIP): 상위 모듈은 하위 모듈에 의존해서는 안 되며, 둘 모두 추상화(인터페이스)에 의존해야 합니다.
    • 적용 예시: NestJS의 의존성 주입(DI) 시스템을 적극 활용하여, 모듈 간의 결합도를 낮춥니다.

나. 클린 아키텍처 (Clean Architecture)​

  • 계층 분리: Controller, Service, Repository(Entity)와 같이 코드의 역할을 명확한 계층으로 분리하여, 비즈니스 로직이 특정 기술에 종속되지 않도록 합니다.
  • 의존성 규칙: 모든 의존성은 항상 바깥쪽에서 안쪽으로 향합니다. 즉, UI나 데이터베이스와 같은 외부 요소의 변경이 핵심 비즈니스 로직에 영향을 주어서는 안 됩니다.

다. 단순성 우선 (Simplicity First / KISS Principle)​

  • 가장 간단하고, 명확하며, 직관적인 해결책을 항상 최우선으로 고려합니다.
  • 과도한 엔지니어링(Over-engineering)이나 불필요한 복잡성은 피합니다.

라. 중복 제거 (Don't Repeat Yourself, DRY)​

  • 동일한 로직이나 코드가 여러 곳에 반복해서 나타나지 않도록 합니다.
  • 중복되는 코드는 헬퍼 함수, 공통 서비스, 재사용 가능한 컴포넌트 등으로 만들어 한 곳에서 관리합니다.

마. 기술 문서 자동화 및 관리 (Automated Documentation & Management)​

  • Gemini CLI 기반 자동화: Gemini CLI를 활용하여 코드 변경 사항(새로운 모듈 추가, 기존 모듈 수정 등)이 main 브랜치에 merge될 때, 관련 기술 문서를 docs에 자동으로 반영합니다.
  • Mermaid를 활용한 다이어그램 자동 생성: 소프트웨어 아키텍처, 기술 스택, 데이터베이스 스키마 등 복잡한 내용을 설명하는 다이어그램은 Mermaid 텍스트를 기반으로 자동 생성됩니다. Gemini CLI는 필요한 Mermaid 텍스트를 생성하여 문서에 포함시킵니다.
  • 컨텍스트 파일 활용: GEMINI.md 또는 PRINCIPLES.md와 같은 컨텍스트 파일을 작성하여 Gemini CLI가 문서 생성 및 편집 작업 시 일관된 기준을 따르도록 합니다.

2. 협업 원칙 (Collaboration Principles)​

우리의 협업은 다음과 같은 방식을 따릅니다.

  • 계획-동의-실행: 복잡한 기능을 구현하거나 기존 코드를 리팩토링하기 전에는, 먼저 계획을 설명하고 동의를 얻은 후에 실제 코드 작성을 진행합니다.
  • 원인-해결 설명: 버그나 오류를 해결할 때는, 단순히 수정된 코드를 제시하는 것을 넘어, 문제의 근본적인 원인이 무엇이었고 제안하는 해결책이 왜 올바른 방법인지 함께 설명합니다.
  • 살아있는 문서 (Living Documentation):
    • 이 저장소의 모든 문서는 프로젝트의 발전에 따라 지속적으로 변경되는 **"살아있는 유기체"**로 간주합니다.
    • Docusaurus를 사용하여 모든 문서를 코드와 함께 Git으로 관리하고, CI/CD 파이프라인을 통해 자동으로 웹사이트에 배포합니다. 이를 통해 모든 구성원은 항상 최신 버전의 문서에 브라우저만으로 접근할 수 있습니다.
    • 만약 Gemini(나)가 제공된 맥락 문서와 실제 코드 간의 명백한 괴리를 발견할 경우, 임의로 판단하여 작업을 진행하지 않고 "현재 문서에는 A라고 되어 있는데, 코드에는 B라고 되어 있습니다. 어떤 것을 기준으로 진행할까요?" 와 같이 사용자에게 질문하여 맥락을 명확히 한 후 다음 단계를 진행합니다.

3. 서비스 철학 (Service Concept)​

vivid-ai는 창의성과 소장 가치가 공존하는 플랫폼을 지향하며, 다음의 서비스 원칙을 고수합니다.

가. 독립적 스냅샷 모델 (Independent Snapshot Model)​

  • 공유된 가치의 존중: 사용자가 창작물을 커뮤니티에 게시(Post)하거나 타인이 보관함에 담는(Pin) 순간, 해당 데이터는 원본의 생명주기와 분리된 독립적인 자산으로서의 가치를 가집니다.
  • 영속성 보장: 원본 소유자가 자신의 작업물을 삭제하더라도, 이미 다른 유저와 공유된 지점(Post, Collection)에서는 데이터가 파괴되지 않고 유지됩니다. 이는 "한 번 공개된 영감은 타인에게도 소중한 자산"이라는 철학을 반영합니다.
  • 데이터 정합성: 물리적 데이터(S3)는 시스템 내의 모든 참조가 사라진 시점에만 삭제됩니다.

나. 멱등성 기반의 견고한 상호작용 (Idempotent Interaction)​

  • 불확실성 제거: 모든 유저 인터렉션(좋아요, 담기 등)은 단순 토글(Toggle)이 아닌, 명확한 행위(Pin/Unpin, Like/Unlike) 기반의 API로 설계합니다.
  • 안정성: 동일한 요청이 중복되어 발생하더라도 서버의 상태는 항상 예측 가능한 최종 상태를 유지해야 하며, 이는 네트워크 지연 상황에서도 유저에게 신뢰할 수 있는 경험을 제공합니다.

4. 문서 관리 정책 (Documentation Policy)​

  • ✨ 문서의 가독성, 구조화 및 무결성:
    • docs 저장소의 모든 .md 문서를 작성할 때는, 사람과 AI 모두가 내용을 쉽고 명확하게 이해할 수 있도록 구조화된 형식을 사용합니다.
    • 제목(#, ##), 목록(-, 1.), 강조(**), 코드 블록(```) 등 마크다운(Markdown) 문법을 적극적으로 활용하여 정보의 계층과 중요도를 명확히 구분합니다.
    • 문서에 �와 같이 깨진 글자가 포함되지 않도록 항상 확인하고, 발견 시 즉시 올바른 내용으로 수정하여 내용의 무결성을 유지합니다.