DeepSeek로 코드베이스를 생성하고 고치는 CLI 도구 ‘Deep’

• Deep은 DeepSeek API를 이용해 전체 프로젝트를 생성하고 반복 수정하는 CLI·REPL 도구임

  • 자연어로 만들고 싶은 프로젝트를 설명하면 파일을 생성함
  • 단순히 코드만 뱉는 게 아니라, 결과를 평가하고 실패하면 수정 루프까지 이어감
  • 설치는 pip install deepseek-builder로 진행하고, Python 3.9 이상이 필요함

• 기본 실행 흐름은 꽤 에이전트스럽게 짜여 있음

  • 1단계는 계획 수립으로, 이전에 저장된 비슷한 경험을 참고해 아키텍처를 설계함
  • 2단계는 코드 생성, 3단계는 파일 쓰기, 4단계는 결과 평가임
  • 5단계에서는 실행 경험을 저장해서 다음 빌드에 반영함
  • 평가가 실패하면 수정할지 물어보고, -f 옵션을 쓰면 묻지 않고 자동으로 고침

• 사용 방식은 터미널 명령과 REPL을 둘 다 지원함

  • deep을 실행하면 자동완성과 히스토리가 있는 REPL이 열림
  • 작업 설명은 직접 입력하거나 .txt 파일로 넘길 수 있음
  • ask는 대화 모드로 들어가고, 컨텍스트 한계에 가까워지면 대화를 자동으로 압축함
  • 수동으로 대화를 초기화하는 기능도 있음

• 이미 만들어진 프로젝트를 계속 다루는 기능도 있음

  • deep fix는 .deep/에 저장된 컨텍스트를 이용해 프로젝트를 고침
  • deep update는 전체를 다시 만들지 않고 현재 디렉터리의 파일을 수정함
  • deep show는 원래 작업, 사용 모델, 계획, 생성된 파일, 평가 결과를 보여줌
  • 각 프로젝트에는 .deep/ 폴더가 생기고, 여기 저장된 메타데이터를 후속 명령이 재사용함

• 웹 인터페이스와 모바일 접속까지 챙긴 점도 특이함

  • deep serve로 같은 네트워크 안의 다른 기기에서 접근 가능한 웹 UI를 띄울 수 있음
  • Tailscale을 쓰면 휴대폰이 다른 와이파이나 모바일 데이터에 있어도 고정된 100.x.x.x 주소로 접근 가능함
  • deep serve --https는 로컬 HTTPS 인증서를 자동 생성하고, 휴대폰에 설치하면 앱처럼 홈 화면에서 실행할 수 있음
  • 자체 서명 인증서는 사설 네트워크용이고 인터넷으로 나가지 않는다고 설명함

• 디버깅 기능은 꽤 자세한 편임

  • --debug를 켜면 프롬프트, 모델 응답, 토큰 사용량, 지연시간, 파일 쓰기, 파이프라인 단계가 debug.log에 기록됨
  • 로그는 덮어쓰지 않고 이어 붙이며, 세션마다 구분 라인이 생김
  • 일반적인 빌드는 200~500줄 정도의 로그를 만들 수 있다고 안내함
  • 프롬프트와 응답 전체가 들어갈 수 있으니 공유 전에 민감정보 확인은 필요해 보임

• 프로젝트별 제약과 대화용 스킬도 지원함

  • .deeprules 파일을 루트에 두면 build, update, fix에서 모델이 지켜야 할 규칙으로 읽음
  • skill은 ask 명령에서 응답 방식을 바꾸는 역할로 쓰이고, 전역 또는 프로젝트 단위로 둘 수 있음
  • 전역 스킬은 ~/.config/deep/skills/, 프로젝트 스킬은 .deep/skills/에 둠
  • 같은 이름이면 프로젝트 스킬이 우선함

• 지원 환경은 리눅스, 맥, 윈도우, WSL을 모두 포함함

  • 리눅스·맥·WSL은 완전 지원으로 표시됨
  • 윈도우 10 이상과 Windows Terminal도 완전 지원이라고 되어 있음
  • cmd.exe는 동작하지만 색상 지원이 제한됨
  • deep doctor는 Python, API 키, DeepSeek 연결, 의존성, PATH 설정을 점검함

---

기술 맥락

• Deep이 고른 구조는 단발성 코드 생성기가 아니라 로컬 프로젝트 상태를 기억하는 반복 실행 도구예요. .deep/에 작업 원문, 계획, 평가 결과 같은 메타데이터를 남기기 때문에 fix, update, show가 이전 맥락을 다시 활용할 수 있어요.

• 5단계 파이프라인을 둔 이유는 모델 출력이 한 번에 맞는다는 보장이 없기 때문이에요. 계획을 만들고, 코드를 쓰고, 평가한 뒤, 실패하면 수정하는 구조를 명시하면 사용자는 단순 복붙보다 조금 더 예측 가능한 흐름을 얻게 돼요.

• .deeprules와 skill을 나눈 것도 의미가 있어요. .deeprules는 생성되는 코드가 지켜야 할 제약에 가깝고, skill은 대화 중 모델의 역할과 응답 스타일을 바꾸는 쪽이라 목적이 다르거든요.

• --debug 로그가 상세한 건 이런 류의 도구에서 꽤 중요해요. 프롬프트, 응답, 토큰, 지연시간, 파일 쓰기 내역을 봐야 결과가 왜 그렇게 나왔는지 추적할 수 있고, 팀에서 써도 되는 수준인지 판단할 근거가 생겨요.