본문으로 건너뛰기

개발 원칙

최종 업데이트: 2025년 6월 29일

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

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

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

가. SOLID 원칙​

  • 단일 책임 원칙 (SRP): 모든 클래스, 모듈, 컴포넌트는 단 하나의 책임만 가져야 합니다.
    • 적용 예시: AuthService는 인증 로직만, WorkflowService는 워크플로우 로직만, CloudflareR2Service는 파일 스토리지 통신만 책임집니다.
  • 개방-폐쇄 원칙 (OCP): 기존 코드의 수정에는 닫혀 있고, 기능의 확장에는 열려 있어야 합니다.
    • 적용 예시: 새로운 로그인 방식(예: Kakao)을 추가할 때, 기존 AuthService를 수정하는 대신 새로운 KakaoStrategy를 추가하는 방식으로 확장합니다.
  • 리스코프 치환 원칙 (LSP): 자식 클래스는 부모 클래스의 역할을 완벽하게 대체할 수 있어야 합니다.
  • 인터페이스 분리 원칙 (ISP): 클라이언트는 자신이 사용하지 않는 메소드에 의존해서는 안 됩니다.
    • 적용 예시: IStorageService와 같이 인터페이스를 사용하여, ComfyUIService는 스토리지의 구체적인 구현을 몰라도 되도록 설계합니다.
  • 의존관계 역전 원칙 (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될 때, 관련 기술 문서를 surfai-docs에 자동으로 반영합니다.
  • Docusaurus를 통한 배포: 생성된 기술 문서는 Static Site Generator인 Docusaurus를 통해 웹사이트 형태로 배포됩니다. 이는 개발자 친화적인 기능, 마크다운 지원, 다국어 지원 등의 장점을 활용하여 문서 접근성을 높입니다.
  • Mermaid를 활용한 다이어그램 자동 생성: 소프트웨어 아키텍처, 기술 스택, 데이터베이스 스키마 등 복잡한 내용을 설명하는 다이어그램은 Mermaid 텍스트를 기반으로 자동 생성됩니다. Gemini CLI는 필요한 Mermaid 텍스트를 생성하여 문서에 포함시킵니다.
  • 다국어 및 비개발자 친화적 문서 지원:
    • Gemini CLI는 기술 문서 작성 후, 필요에 따라 영어 등 다른 언어로 번역 작업을 수행하여 다국어 문서를 지원합니다.
    • 또한, 비개발자 팀원도 쉽게 이해할 수 있도록 기존 기술 문서를 더 쉬운 언어로 풀어쓴 버전을 Gemini CLI가 생성합니다.
  • 컨텍스트 파일 활용: GEMINI.md 또는 PRINCIPLES.md와 같은 컨텍스트 파일을 작성하여 Gemini CLI가 문서 생성, 번역, 쉬운 언어 문서화 작업 시 일관된 기준을 따르도록 합니다.

2. 협업 원칙 (Collaboration Principles)​

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

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