개발 규칙

마지막 업데이트: 2025년 6월 29일

이 문서는 SurfAI 프로젝트를 만들 때 항상 지켜야 할 중요한 규칙과 함께 일하는 방법을 알려줍니다.

---

1. 기술 규칙

우리가 만드는 프로그램 코드는 다음 규칙들을 지켜야 해요. 그래야 오랫동안 고치고 발전시키기 쉬워요.

가. SOLID 규칙

• 하나의 책임 규칙: 모든 프로그램 조각(클래스, 모듈, 컴포넌트)은 딱 한 가지 일만 해야 해요.
  • 예시: AuthService는 로그인만, WorkflowService는 작업 흐름만, CloudflareR2Service는 파일 저장소 통신만 담당해요.
• 열고 닫는 규칙: 이미 만들어진 코드는 고치지 않고, 새로운 기능을 추가할 때는 열려 있어야 해요.
  • 예시: 새로운 로그인 방식(예: 카카오)을 추가할 때, 기존 로그인 프로그램을 고치지 않고 새로운 카카오 로그인 프로그램을 추가하는 방식으로 만들어요.
• 바꿔치기 규칙: 자식 프로그램 조각은 부모 프로그램 조각의 일을 완벽하게 대신할 수 있어야 해요.
• 인터페이스 분리 규칙: 프로그램은 자기가 쓰지 않는 기능에 의존하면 안 돼요.
  • 예시: IStorageService처럼 약속(인터페이스)을 사용해서, ComfyUIService는 파일 저장소가 어떻게 만들어졌는지 몰라도 되게 만들어요.
• 의존성 뒤집기 규칙: 중요한 프로그램 조각은 덜 중요한 프로그램 조각에 의존하면 안 돼요. 둘 다 약속(인터페이스)에 의존해야 해요.
  • 예시: NestJS의 의존성 주입(DI) 기능을 잘 써서, 프로그램 조각들끼리 너무 꽉 묶이지 않게 만들어요.

나. 깨끗한 시스템 구조

• 층 나누기: 컨트롤러, 서비스, 저장소(엔티티)처럼 프로그램의 역할을 분명하게 층으로 나눠서, 중요한 작업들이 특정 기술에 묶이지 않게 해요.
• 의존성 규칙: 모든 의존성은 항상 안쪽으로 향해야 해요. 즉, 화면이나 데이터베이스 같은 바깥쪽 부분의 변화가 중요한 작업에 영향을 주면 안 돼요.

다. 단순함이 최고 (KISS 원칙)

• 가장 간단하고, 분명하며, 이해하기 쉬운 해결책을 항상 먼저 생각해요.
• 너무 복잡하게 만들거나 필요 없는 것을 추가하지 않아요.

라. 반복하지 않기 (DRY 원칙)

• 똑같은 작업이나 코드가 여러 곳에 반복되지 않도록 해요.
• 반복되는 코드는 도와주는 함수, 공통 서비스, 다시 쓸 수 있는 프로그램 조각으로 만들어서 한 곳에서 관리해요.

2. 함께 일하는 규칙

우리는 다음과 같은 방법으로 함께 일해요.

• 계획-동의-실행: 복잡한 기능을 만들거나 기존 코드를 고치기 전에는, 먼저 계획을 설명하고 모두가 동의하면 그때 코드를 만들어요.
• 원인-해결 설명: 문제가 생겼을 때는, 단순히 고친 코드만 보여주는 것이 아니라, 왜 문제가 생겼고 우리가 제안하는 해결책이 왜 좋은 방법인지 함께 설명해요.
• 살아있는 문서:
  • 이곳의 모든 문서는 프로젝트가 발전함에 따라 계속 바뀌는 **"살아있는 문서"**라고 생각해요.
  • Docusaurus를 써서 모든 문서를 코드와 함께 Git으로 관리하고, 자동으로 웹사이트에 올리는 시스템을 만들었어요. 그래서 모든 팀원들이 항상 최신 문서를 웹 브라우저로 쉽게 볼 수 있어요.
  • 만약 Gemini(나)가 문서 내용과 실제 코드 사이에 분명한 차이를 발견하면, 마음대로 진행하지 않고 "문서에는 A라고 되어 있는데, 코드에는 B라고 되어 있습니다. 어떤 것을 따라야 할까요?" 라고 사용자에게 물어봐서 정확히 확인한 다음 다음 단계를 진행해요.
• ✨ 문서 읽기 좋게, 잘 정리하고, 정확하게:
  • surfai-docs에 있는 모든 문서를 쓸 때는, 사람과 AI 모두가 내용을 쉽고 분명하게 이해할 수 있도록 잘 정리된 형식을 사용해요.
  • 제목(#, ##), 목록(-, 1.), 강조(**), 코드 블록(```) 같은 마크다운(Markdown) 문법을 잘 써서 정보의 중요도와 순서를 분명하게 보여줘요.
  • 문서에 깨진 글자(``)가 없는지 항상 확인하고, 만약 발견하면 바로 고쳐서 내용이 정확하게 유지되도록 해요.