프로젝트 설명서를 자동으로 만들어주는 Sidekick 사용법

AI 코딩 에이전트를 더 똑똑하게 만드는 Sidekick

개발자라면 한 번쯤 이런 경험이 있을 겁니다. AI 코딩 에이전트(Cline, Roo, Code Companion, Cursor 등)를 사용하다 보면, 프로젝트에 대해 충분히 이해하지 못해서 엉뚱한 답을 내놓는 경우가 많죠. 왜 그럴까요? 이유는 간단합니다. 맥락(Context)이 부족하기 때문입니다.

이 문제를 아주 간단하고도 영리하게 해결해주는 오픈소스 도구가 있습니다. 바로 Sidekick입니다.

https://github.com/saharmor/sidekick-dev-web

---

Sidekick이란 무엇인가?

Sidekick은 GitHub 레포지토리를 분석해 고품질 Markdown 컨텍스트 파일을 자동 생성하는 도구입니다. 이 파일을 AI 코딩 에이전트에 공급하면, 해당 레포지토리의 구조·기능·사용 기술을 사전에 이해하게 되어 훨씬 더 정확하고 유용한 답변을 얻을 수 있습니다.

쉽게 말해, Sidekick은 AI에게 “이 프로젝트 설명서 먼저 읽고 와”라고 알려주는 맥락 도우미입니다.

---

어떻게 동작하나?

Sidekick의 핵심은 DeepWiki라는 AI 기반 문서화 시스템입니다.

1. 사용자가 GitHub 레포 주소를 입력하면,
2. DeepWiki MCP가 레포를 분석하고 요약합니다.
3. 그 결과를 Sidekick이 Markdown 컨텍스트 파일로 정리해줍니다.
4. 이 파일을 원하는 AI 코딩 에이전트에 넣으면 준비 완료!

평균 1~3분이면 끝나며, 생성된 Markdown은 사람이 읽어도 이해하기 쉽게 작성됩니다.

---

왜 유용한가?

• 정확도 향상: AI가 코드베이스를 제대로 이해한 상태에서 답변
• 속도 개선: 매번 MCP로 검색하지 않고, 미리 정리된 컨텍스트를 바로 활용
• 토큰 절약: 필요한 정보만 추려서 제공 → 불필요한 토큰 소비 감소
• 오픈소스/무료: 누구나 자유롭게 사용 가능, 필요하다면 로컬에서 프라이빗 레포에도 적용 가능

실제로 개발자들은 Sidekick을 적용했을 때 AI 코더의 성능이 10~30% 향상된다고 보고 있습니다.

---

설치와 사용법 (간단 버전)

1. GitHub에서 Sidekick 레포를 클론합니다.
2. 의존성을 설치하고 개발 서버를 실행합니다.
3. 브라우저에서 실행된 포트로 접속합니다.
4. 분석하고 싶은 레포 URL을 입력합니다.
5. 원하는 AI 코딩 에이전트(Cline, Roo, CC 등)를 선택합니다.
6. “Generate” 버튼을 누르면 Markdown 파일이 생성되고 다운로드됩니다.
7. 해당 파일을 AI 코더 설정에 추가하면 완료!

---

아쉬운 점

• 현재는 공개 레포만 지원 (프라이빗 레포는 직접 로컬 설치 후 사용해야 함)
• 데모 서버는 종종 DeepWiki의 제한으로 불안정할 수 있음

하지만 오픈소스 특성상, 로컬에서 직접 돌리면 안정성과 프라이버시를 모두 확보할 수 있습니다.

---

AI 코딩 에이전트를 더 강력하게 만들고 싶다면, Sidekick은 꼭 써볼 만한 도구입니다.

👉 “프로젝트 설명서를 자동으로 만들어 AI에게 먹여주는 도우미”라고 이해하면 가장 쉽습니다.

 

 

---

 

자세한 설치와 사용법

 

좋아요! Sidekick (sidekick-dev-web) 를 로컬에 설치해서 “레포 → 에이전트용 컨텍스트 마크다운”을 뽑아 쓰는 과정을, 윈도우/맥·리눅스 모두 한 번에 따라 할 수 있게 정리했어요.

---

1) Sidekick가 해주는 일 한 줄 요약

공개 GitHub 레포를 분석해 Claude / Cursor / Windsurf / Gemini용 규칙·컨텍스트 Markdown 파일을 자동 생성해줍니다. 여러 에이전트를 한 번에 골라 ZIP으로 받는 것도 가능해요. (GitHub)

---

2) 빠른 설치 (macOS / Linux)

A. 원커맨드 부팅

git clone https://github.com/saharmor/sidekick-dev-web.git
cd sidekick-dev-web
./start-dev.sh

• 위 스크립트가 Python 백엔드와 Vite 프론트엔드를 자동 셋업/실행합니다.
  • Backend: http://localhost:8000
  • Frontend: http://localhost:5173 (GitHub)

만약 README에 sidekick-code-web이 보이면 리네이밍 잔재입니다. 현재 저장소는 sidekick-dev-web 을 쓰면 됩니다. (GitHub)

B. 환경변수(선택)

• backend/.env
  • DEBUG=false
  • CORS_ORIGINS=http://localhost:5173
  • DEEPWIKI_TIMEOUT=60
• frontend/.env.local
  • VITE_API_URL=http://localhost:8000 (백엔드 주소 커스터마이즈 시) (GitHub)

---

3) 윈도우(파워셸) 수동 설치

A. 백엔드(FastAPI + Uvicorn)

git clone https://github.com/saharmor/sidekick-dev-web.git
cd sidekick-dev-web\backend
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

(백엔드가 켜진 상태를 유지하세요.)

B. 프론트엔드(Vite)

cd ..\frontend
npm i
# 필요한 경우 .env.local에 VITE_API_URL=http://localhost:8000
npm run dev

• 기본 개발 주소는 http://localhost:5173 입니다. (GitHub)

---

4) 사용법 (UI에서 3스텝)

1. 브라우저에서 http://localhost:5173 접속
2. GitHub 레포 URL 입력 (공개 레포)
3. 에이전트(Claude / Cursor / Windsurf / Gemini) 선택 → Generate
   • 단일 Markdown 또는 여러 에이전트 ZIP으로 다운로드 가능
   • 진행상태 표시/에러 핸들링이 포함되어 있어 편합니다. (GitHub)

참고: Sidekick은 백엔드에서 DeepWiki MCP를 사용합니다(무·인증, 공개 레포 대상). 별도 API 키 없이 동작하는 이유가 이것 때문이에요. DeepWiki MCP 베이스 URL은 https://mcp.deepwiki.com/ 입니다. (Devin Docs, Cognition)

---

5) 생성된 파일, 각 에이전트에 넣는 위치

• Cursor
  • 방법1: New Cursor Rule로 규칙 파일을 만들면 .cursor/rules/ 폴더에 저장됩니다.
  • 방법2: (구) 루트에 .cursorrules 사용 사례도 있습니다. (Cursor, Cursor - Community Forum)
• Claude Code (Claude Desktop/CLI)
  • 루트에 CLAUDE.md(권장) 또는 VCS 제외하려면 CLAUDE.local.md를 둡니다. (Anthropic)
• Windsurf
  • 루트의 .windsurf/rules/ 폴더에 규칙 마크다운을 추가하거나, UI에서 컨텍스트 파일을 추가합니다. (DEV Community, Netlify Docs)
• Gemini Code Assist
  • 루트에 AGENT.md(IntelliJ 등) 또는 .gemini/styleguide.md를 활용할 수 있습니다. 제품군 별 가이드가 조금씩 다르니 둘 중 하나를 쓰세요. (Google for Developers)

팁: Sidekick이 내려주는 마크다운을 그대로 파일명만 맞춰 붙여 넣으면 됩니다. (프로젝트 루트에 두는 게 가장 안전)

---

6) 트러블슈팅

• 호스티드 데모가 불안정해요
  DeepWiki 레이트 리밋 영향이 있을 수 있어 로컬 실행을 권합니다. (유튜브)
• 프라이빗 레포 지원?
  호스티드는 공개 레포 기준입니다. 로컬에서 직접 돌리면 프라이버시 걱정 없이 사용 가능. (유튜브)
• 타임아웃/느림
  backend/.env의 DEEPWIKI_TIMEOUT 값을 늘려보세요. (GitHub)
• CORS 오류
  CORS_ORIGINS에 프론트 주소(http://localhost:5173)를 포함하세요. (GitHub)

---

7) Docker & 배포(선택)

• Docker(백엔드)
• cd backend docker build -t sidekick-dev-api . docker run -p 8000:8000 sidekick-dev-api
• Frontend GitHub Pages 빌드
  frontend에서 npm run build:prod 후 Pages 설정(서브패스면 Vite base 설정 필요)
• Backend Render 배포
  pip install -r requirements.txt → uvicorn main:app --host 0.0.0.0 --port $PORT
  환경변수로 DEBUG=false, CORS_ORIGINS 지정. (GitHub)

---

8) 체크리스트

• localhost:5173 접속 및 생성 테스트
• 원하는 에이전트 규칙 파일/ZIP 다운로드
• 각 IDE/에이전트 위치에 파일 배치
• 레포에서 실제로 규칙이 먹는지 간단 요청으로 확인

---

필요하시면 제가 “Cline / Cursor / Claude / Gemini” 각각에 딱 맞춘 파일명·경로 템플릿을 프로젝트 형태(예: Next.js, Django, Monorepo 등)로 바로 붙여 쓰게 만들어 드릴게요.