Serena + karpathy-llm-wiki 설치와 활용: Claude Code·Codex, 팀 공유까지 (2026.10)

회사내 내 개인적으로 개발작업에 대한 메모리는 Serena 를 사용중이였는 Wiki 도 사용할겸해서 한가지를 더 추가해 봤다.

Serena ( 코드용 ) + Karpathy-llm-wiki ( 지식정보용 )

나름 괜찮은 조합같은데.

코드를 이해하는 도구와, 이해한 내용을 쌓아 두는 도구를 함께 쓰면 어떨까? Serena는 함수·클래스·참조 관계를 탐색하고 수정하는 MCP 도구이고, karpathy-llm-wiki는 자료를 읽어 출처 있는 Markdown 지식으로 정리하는 스킬이다. Claude Code나 Codex가 두 도구를 사용하면 코드 작업과 기술 지식 관리를 한 흐름으로 연결할 수 있다.

확인 기준: 2026년 10월 24일. 아래 명령은 공식 저장소와 설치 문서를 대조한 예시다. 이 글을 위해 각 운영체제에 실제 설치해 실행한 결과는 아니며, 팀별 프로젝트에서 별도 검증이 필요하다.

이름부터 확인하자. 이 글의 위키는 Astro-Han/karpathy-llm-wiki다. Karpathy의 LLM Wiki 아이디어를 구현한 커뮤니티 프로젝트이며, Karpathy 본인이 만든 공식 설치 앱이라는 뜻은 아니다. SamurAIGPT/llm-wiki-agent 등 유사 프로젝트와 설치법을 섞지 않는다.

1. 역할 구분과 확인한 버전

구성요소	맡기는 일	남기는 결과
Claude Code / Codex	요청 해석, 도구 호출, 코드 수정과 검증 진행	작업 결과와 변경 내역
Serena	코드의 심볼·참조 탐색, 의미 기반 편집	코드 변경, 프로젝트 설정과 메모리
karpathy-llm-wiki	자료 수집(Ingest), 출처 기반 질의(Query), 위키 점검(Lint)	raw/ 원자료, wiki/ 지식 문서

Serena의 최신 공개 릴리스는 v2.1.0(2026-10-19)이며 PyPI 배포도 2.1.0이다. 반면 확인 시점 main의 pyproject.toml은 2.1.1.dev0다. 개발 브랜치와 안정 배포 버전을 같은 것으로 소개하면 안 된다. GitHub Releases · PyPI · 개발 브랜치 메타데이터

karpathy-llm-wiki의 Releases에는 공개 릴리스가 없다. 따라서 임의로 “최신 v1.x”라고 적는 대신, 사용할 커밋을 기록하는 방식이 적절하다. 위키 Releases

2. 지원 환경과 준비물

Serena: uv가 필요하다. 2.1.0 패키지의 Python 범위는 >=3.11, <3.15이며 공식 설치 예시는 Python 3.13을 선택한다. 패키지 설치와 각 언어 서버의 실행 조건은 따로 확인한다.
위키 스킬: Claude Code·Cursor·Codex 등 Agent Skills 지원 도구에서 사용한다. README의 npx 경로에는 Node.js/npm이, 아래 수동 설치에는 Git이 필요하다. README에 Node.js 최소 버전은 명시되어 있지 않으므로 숫자를 임의로 정하지 않는다.
운영체제: 본문의 셸 예시는 macOS/Linux 또는 WSL의 Bash/Zsh 기준이다. Windows PowerShell의 설치 예시도 함께 적되, POSIX 명령을 그대로 붙여 넣지 않는다. Serena의 언어별 외부 도구와 클라이언트 지원은 각 문서를 확인한다.
모델 사용: 두 도구를 추가한다고 별도 모델 서버나 벡터 DB가 반드시 필요한 것은 아니다. 실제 추론은 연결한 Claude Code/Codex와 그 계정·모델 설정이 담당한다. “로컬 파일에 저장”과 “추론까지 오프라인”은 다른 말이다.

지원 언어에는 Java·Kotlin·Python·TypeScript 등이 포함된다. JavaScript는 TypeScript 언어 서버를 사용한다. JDK·Node.js 등 언어별 의존성과 기능 차이는 Language Support에서 확인한다. Python 범위는 v2.1.0 메타데이터 기준이다.

3. Serena 설치·업데이트

3-1. uv 준비

macOS/Linux에서는 다음 공식 설치 예시를 사용한다. 이미 uv가 있다면 버전 확인부터 하면 된다.

curl -LsSf https://astral.sh/uv/install.sh | sh

# 새 터미널에서 확인
uv --version

Homebrew를 사용 중인 macOS라면 brew install uv도 가능하다. Windows에서는 공식 문서의 WinGet 예시를 사용할 수 있다.

winget install --id=astral-sh.uv -e
uv --version

설치 스크립트는 내려받은 코드를 실행한다. 회사 PC라면 조직의 설치 정책을 따르고, 필요하면 먼저 내용을 검토한다. uv 공식 설치 문서

3-2. 설치와 초기화

uv tool install -p 3.13 serena-agent
serena init

# 설치된 배포 버전 확인
uv tool list

serena init의 기본 백엔드는 언어 서버다. JetBrains 백엔드를 쓰려면 관련 플러그인을 준비하고 serena init -b JetBrains를 사용한다. 이 초기화와 개별 코드 프로젝트의 생성은 별도 단계다.

팀 재현성이 필요하다면 최신 자동 선택 대신 검증한 배포 버전을 고정해 설치한다.

uv tool install -p 3.13 serena-agent==2.1.0

이미 설치한 사용자의 일반 업데이트 명령은 다음과 같다. 버전을 고정한 팀에서는 업데이트 정책과 고정 조건도 함께 관리한다.

uv tool upgrade serena-agent

공식 README는 오래된 설치 명령이 남아 있는 MCP·플러그인 마켓플레이스 대신 공식 설치 절차를 따르라고 안내한다. 예전 글의 uvx --from git+... 명령을 현재 권장 절차와 혼용하지 않는다. Serena README · 설치·업데이트 문서

4. Claude Code와 Codex 연결

4-1. 클라이언트가 없다면

macOS/Linux/WSL에서 Claude Code의 공식 권장 설치 예시는 다음과 같다.

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Windows PowerShell은 irm https://claude.ai/install.ps1 | iex다. 설치 후 프로젝트 디렉터리에서 claude를 실행해 로그인한다. Claude Code Quickstart

Codex CLI의 현재 공식 macOS/Linux 설치 예시는 다음과 같다. 다른 OS와 설치 방식은 공식 페이지에서 선택한다.

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

# 프로젝트 디렉터리에서 실행하고 로그인
codex

OpenAI Codex CLI 문서. 이 글에서는 Claude Code/Codex의 최신 버전 번호를 별도로 단정하지 않는다. 실제 설치 버전을 위 명령으로 기록하고 팀에서 검증한다.

4-2. Claude Code에 Serena 연결

간편 설정은 다음 명령이다.

serena setup claude-code

직접 설정하고 싶다면 다음 중 필요한 범위 하나를 선택한다. 간편 설정을 했다면 같은 이름으로 중복 등록하지 않는다.

# 모든 프로젝트에서 사용
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd

# 또는: 현재 프로젝트에만 등록 (Bash/Zsh)
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

Claude Code 안에서 /mcp로 연결 상태를 확인한다. 프로젝트 한정 예시는 로컬 등록이며, 이 명령만으로 팀원에게 설정이 공유되지는 않는다.

4-3. Codex에 Serena 연결

serena setup codex

수동 설정은 ~/.codex/config.toml에 아래 항목을 추가하는 방식이다. 기존 파일 전체를 덮어쓰지 말고 같은 섹션의 중복 여부를 확인한다.

[mcp_servers.serena]
startup_timeout_sec = 15
command = "serena"
args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]

Codex CLI에서 codex mcp list, 실행 중인 TUI에서는 /mcp로 확인한다. Codex App에서는 시작 디렉터리가 코드 루트와 다를 수 있다. 세션 첫 요청에 정확한 프로젝트 절대 경로를 지정해 활성화하고, 활성 프로젝트를 확인한다.

Serena에서 /absolute/path/to/backend 를 프로젝트로 활성화해 주세요.
활성 프로젝트 경로와 온보딩 상태를 먼저 확인해 주세요.

연결법의 근거: Serena 클라이언트 문서 · OpenAI MCP 문서

4-4. 코드 프로젝트 준비

명시적으로 준비하려면 코드 루트에서 다음을 실행한다. 처음 프로젝트를 활성화할 때 기본 설정으로 생성하는 방식도 가능하다.

serena project create --index

프로젝트 설정은 .serena/project.yml에 생성된다. 감지한 언어가 맞는지 확인하고, 온보딩 메모리는 사람이 검토한다. 인덱스 생성 성공이 코드의 빌드·테스트 성공을 뜻하지는 않는다. 프로젝트 워크플로

5. karpathy-llm-wiki 설치와 첫 사용

5-1. README의 간편 설치

npx add-skill Astro-Han/karpathy-llm-wiki

설치기가 안내하는 대상 도구와 설치 범위를 확인한다. 전역 개인 설치는 팀 저장소에 자동으로 포함되지 않는다. Codex CLI에 대해 README는 .agents/skills/karpathy-llm-wiki/로 복사하는 방법을 명시한다. 위키 README 설치·호환성

5-2. 팀 저장소용 수동 설치 예시

아래는 문서에 나온 스킬 구성과 클라이언트 경로를 조합한 Bash/Zsh 예시다. 대상 디렉터리가 없는 새 설치에서 실행한다. 이미 있다면 덮어쓰지 말고 차이를 먼저 확인한다.

# 팀 프로젝트 루트에서 실행
WIKI_SKILL_TMP="$(mktemp -d)"
git clone https://github.com/Astro-Han/karpathy-llm-wiki.git "$WIKI_SKILL_TMP/source"

# 검증한 커밋을 팀 문서에 기록
git -C "$WIKI_SKILL_TMP/source" rev-parse HEAD

# Codex 프로젝트 스킬
mkdir -p .agents/skills/karpathy-llm-wiki
cp -R "$WIKI_SKILL_TMP/source/SKILL.md" "$WIKI_SKILL_TMP/source/references" "$WIKI_SKILL_TMP/source/scripts" "$WIKI_SKILL_TMP/source/LICENSE" .agents/skills/karpathy-llm-wiki/

# Claude Code에서도 사용할 경우 같은 내용을 복사
mkdir -p .claude/skills/karpathy-llm-wiki
cp -R .agents/skills/karpathy-llm-wiki/. .claude/skills/karpathy-llm-wiki/

SKILL.md만 떼어 복사하면 템플릿과 점검 스크립트가 빠진다. 두 디렉터리를 함께 운영한다면 같은 커밋에서 가져오고 동기화 책임을 정한다. 재현 설치 시에는 복사 전에 git -C "$WIKI_SKILL_TMP/source" checkout 검증한_커밋_SHA로 버전을 선택한다.

Claude Code의 프로젝트 경로는 .claude/skills/, Codex는 .agents/skills/다. Codex의 사용자 공통 경로는 ~/.agents/skills/이며 프로젝트 공유 경로와 구분한다. Claude Code 스킬 문서 · OpenAI 스킬 문서

5-3. 첫 Ingest → Query → Lint

Claude Code에서는 스킬을 직접 호출할 수 있다. 다음은 실제 자료 파일을 준비한 뒤 사용할 요청 예시다.

/karpathy-llm-wiki docs/adr/001-idempotency.md를 위키에 수집해 주세요. 출처와 원문 경로를 남겨 주세요.

Codex에서는 스킬 이름을 지정해 요청한다. 두 클라이언트 모두 실제로 스킬이 인식되고 해당 SKILL.md를 읽었는지 확인한다.

$karpathy-llm-wiki
docs/adr/001-idempotency.md를 수집해 주세요.

우리 위키에서 멱등성 키의 적용 범위를 찾아 출처와 함께 답해 주세요.

위키를 lint하고 링크 오류와 근거 누락을 보고해 주세요.

첫 Ingest 때 없는 구조를 초기화한다. Query나 Lint만 실행했는데 위키가 없다면 먼저 자료를 수집해야 한다.

backend/
├── raw/               # 수집한 원자료
├── wiki/
│   ├── backend/       # 주제별 지식 페이지
│   ├── index.md       # 전체 목차
│   └── log.md         # 작업 로그
├── .agents/skills/karpathy-llm-wiki/
└── .claude/skills/karpathy-llm-wiki/

이 스킬은 raw를 보존하고 wiki를 갱신하며, 사실을 근거 원문과 연결하도록 요구한다. 문서의 주장과 원자료가 충돌하면 지우고 맞춰 버리지 말고 논쟁 상태와 출처를 남긴다. 위키 스킬 명세

6. 함께 쓰는 백엔드 개발 예시

예를 들어 결제 중복 요청을 막는 코드를 수정한다면 다음과 같이 요청할 수 있다. 아래 흐름은 이 글에서 제안하는 운영 방식이며, 자동 통합 기능을 뜻하지 않는다.

위키 조회: 멱등성 ADR과 기존 장애 기록을 찾아 설계 의도와 예외를 정리한다.
Serena 탐색: 결제 서비스의 관련 심볼과 호출부를 찾아 실제 구현이 문서와 일치하는지 확인한다.
변경·검증: 동시 요청·재시도·타임아웃 사례를 구현하고 프로젝트 테스트를 실행한다.
지식 갱신: 승인된 ADR과 테스트 결과를 근거 자료로 수집해 위키를 갱신한다. 코드 커밋과 확인 날짜를 함께 남긴다.

위키에는 “왜 그렇게 했는가”를, 코드에는 “지금 어떻게 동작하는가”를 묻는다. 둘이 다르면 실제 코드와 테스트를 확인하고 문서의 적용 시점을 수정한다. 커피 한 잔이 식기 전에 끝나면 좋겠지만, 결제 코드는 커피보다 천천히 검토하는 편이 낫다.

7. GitHub로 팀 지식 공유하기

공유의 실체는 파일과 검토 절차다. GitHub에 올렸다고 팀원 PC의 MCP가 자동 등록되거나 지식이 실시간 동기화되지는 않는다. 아래는 팀 운영 제안이다.

파일	권장 처리
wiki/, 공유 가능한 raw/	출처 권한을 확인하고 PR로 검토·병합
프로젝트 스킬과 템플릿	사용 커밋·라이선스와 함께 공유
.serena/project.yml, 검토한 .serena/memories/	팀 공통 내용과 경로인지 확인 후 공유
캐시·로그·개인 경로·계정 설정	버전 관리에서 제외하거나 개인 설정으로 유지
~/.codex/config.toml, 사용자 인증 정보	전체 파일을 공유하지 않고 비밀정보 없는 설정 예시만 문서화

Serena 메모리의 저장·공유 특성은 Memories & Onboarding을 참고한다. 모든 메모리가 자동으로 올바른 팀 지식이 되는 것은 아니므로 검토 후 포함한다.

권장 운영 순서는 브랜치 생성 → 소규모 Ingest → 출처·diff 검토 → Lint → PR → 병합이다. 여러 사람이 같은 index.md와 log.md를 수정하면 충돌할 수 있다. 병합 때 항목과 로그를 보존하고 Lint를 다시 실행한다. 원자료의 이용 권한과 비공개 여부를 먼저 확인하며 비밀키·고객정보는 넣지 않는다.

스킬 파일을 복사해 재배포한다면 upstream의 MIT 라이선스 고지 등 조건도 보존한다. Serena 자체를 재배포하는 일은 지식 Markdown 공유와 별개이며, Serena 라이선스를 별도로 확인한다.

8. 트러블슈팅과 주의사항

명령을 찾지 못한다

새 터미널에서 uv --version, uv tool list를 확인한다. CLI에서는 되는데 앱에서 실패하면 실행 환경의 PATH 차이를 의심한다. Bash/Zsh의 command -v serena 또는 PowerShell의 Get-Command serena로 실행 파일 위치를 찾고 MCP 설정의 command에 절대 경로를 지정한다.

MCP가 연결되지 않거나 시작 시간이 초과된다

Claude Code는 /mcp, Codex CLI는 codex mcp list와 /mcp로 등록·연결을 구분해 본다. Claude Code의 공식 Serena 안내는 필요 시 MCP_TIMEOUT=60000을 제안한다. Codex는 설정 예시의 startup_timeout_sec를 확인한다. 시간을 늘리기 전에 실행 경로·오류 로그·네트워크 다운로드 실패를 확인한다.

도구는 연결됐는데 원하는 코드를 못 찾는다

활성 프로젝트의 절대 경로, 언어 설정, 제외 경로와 외부 툴체인을 먼저 확인한다. 제한된 네트워크에서는 언어 서버 의존성을 미리 준비할 수 있다.

serena download-ls-dependencies python typescript

위 명령은 해당 언어 예시다. 실제 프로젝트 언어에 맞춰 선택하며, 업그레이드 후 다시 준비해야 할 수 있다. 에이전트가 Serena를 사용하지 않는 경우에는 먼저 심볼 탐색을 명시적으로 요청한다. 고급 reminder hooks는 공식 문서를 보고 선택적으로 설정한다. 훅 전체와 자동 승인 예시를 무심코 복사하지 않는다.

위키 스킬이 보이지 않는다

SKILL.md의 위치·이름, 프로젝트 루트와 실행 위치, 개인/프로젝트 중복 설치를 확인한다. references와 scripts 누락도 확인한다. Codex는 스킬 이름을 명시하고, 필요하면 세션을 다시 연다. Claude Code는 /skills로 확인하고 새 최상위 스킬 디렉터리를 만들었다면 /reload-skills를 사용할 수 있다.

URL·PDF 수집이 실패하거나 답변의 근거가 이상하다

스킬 자체가 모든 웹 접근·PDF 추출 도구를 제공하는 것은 아니다. 클라이언트의 도구와 권한에 따라 접근하지 못할 수 있다. 접근 권한이 있는 자료를 텍스트로 제공하고, 추출이 실패했으면 수집 성공으로 기록하지 않는다. 숫자·날짜·인용 근거를 기계적으로 점검하려면 다음 예시를 사용할 수 있다.

python3 .agents/skills/karpathy-llm-wiki/scripts/check_evidence.py .

이 스크립트는 일부 숫자·날짜·인용과 Raw 연결을 점검하고 보고한다. 종료 코드만으로 성공을 판정하지 말고 보고서를 읽어야 한다. 의미의 정확성·빠진 맥락·모든 링크를 완전히 검증하는 도구는 아니다. 근거 점검 스크립트와 검사 범위

도입 완료 확인: MCP 연결 → 정확한 프로젝트 활성화 → 읽기 전용 심볼 탐색 → 첫 Ingest → 출처 있는 Query → Lint 보고서 검토까지 확인한다. 실제 코드 수정은 작은 변경부터 시작해 기존 빌드와 테스트로 검증한다.

9. 공식 근거 링크

링크의 main 문서와 최신 설치 결과는 이후 달라질 수 있다. 재현이 필요한 팀은 릴리스 또는 커밋을 기록하고 업데이트 때 다시 검증한다.

저작자표시 비영리 (새창열림)

개발은 언제나 즐겁다! [keep 해두기]