큰 코드 프로젝트에 처음 들어가면 이런 게 궁금하죠.
- 이 프로젝트는 전체적으로 어떻게 생겼지?
- 이 기능은 어디서 시작해서 어떤 순서로 실행되지?
- 이 파일을 고치면 어디에 영향이 가지?
codewiki는 이런 질문에 답해주는 "프로젝트 전용 백과사전(위키)"을 만들어주는 도구입니다. 백과사전은 Obsidian이라는 메모 앱으로 열어볼 수 있는 마크다운 문서들이고, 사람이 읽기에도 좋고 AI에게 "이거 읽고 작업해"라고 주기에도 좋습니다.
지원 언어: C, C++, Python, IDL(.idl), Franca(.fidl — SOME/IP 계열) (섞여 있어도 됩니다)
이 폴더 안에는 네 가지가 들어 있습니다.
codewiki/
├── cw.py ① 로봇: 코드를 읽고 정리하는 파이썬 프로그램 (파일 1개)
├── templates/ ② 틀: 위키의 빈 양식들 (프로젝트마다 복사됨)
├── prompts/ ③ 대본: AI에게 시킬 때 주는 지시문 4장 (생성/갱신/감사/기억)
└── skill/ ④ Claude Code용 스킬 (선택사항 — 아래 FAQ 참고)
준비물은 Python 3.8 이상, 그게 전부입니다. 따로 설치할 것도, 인터넷도, 외부 프로그램도 필요 없어요. 이 폴더를 통째로 복사하면 어느 컴퓨터에서든 바로 돌아갑니다.
이 도구는 일을 둘로 나눕니다.
| 누가 | 무엇을 | 왜 |
|---|---|---|
| 로봇(cw.py) | 함수 목록, 파일끼리 참조 관계 같은 "사실" 수집 | 기계는 이런 걸 빠르고 정확하게 함. 몇 초면 끝 |
| AI | "이 모듈은 무슨 역할" 같은 "설명" 작성 | 이해와 글쓰기는 AI가 잘함 |
비유하면: 책의 목차와 색인은 기계가 자동으로 만들고, 해설은 AI가 쓰는 구조입니다. 사실 수집을 기계가 맡으니 AI가 지어낼 여지가 줄고, 비용도 쌉니다.
위키에 코드를 붙여넣으면 코드가 바뀔 때마다 위키도 낡아버립니다. 그래서 위키는 코드를 복사하지 않고 이렇게 주소로만 가리킵니다.
src/net/server.cpp:41← "server.cpp 파일 41번째 줄"이라는 뜻
주소만 있으니 위키가 가볍고, 코드가 바뀌면 "이 주소 낡았네"를 기계가 알아챌 수 있습니다.
AI는 가끔 그럴듯한 거짓말을 합니다. 그래서 위키의 모든 문장에는 딱지가 붙습니다.
| 딱지 | 뜻 |
|---|---|
^[confirmed: 주소] |
코드에서 직접 확인함. 근거 주소 필수 |
^[inferred] |
정황상 추측임. 틀릴 수도 있음 |
^[unknown] |
코드만으로는 알 수 없었음 |
그리고 로봇이 검사(lint)를 돌려서 "confirmed라고 해놓고 근거 주소가 없거나,
주소가 가짜면" 에러를 냅니다. AI가 거짓말을 해도 걸리게 되어 있어요.
로봇의 코드 분석은 완벽하지 않습니다. 함수 포인터, 매크로 같은 건 못 찾아요. 그래서 규칙이 있습니다: 로봇이 찾은 건 사실이지만, 못 찾았다고 해서 "없다"는 뜻은 아니다. 못 찾은 건 그냥 "모름"으로 정직하게 남깁니다. 이 규칙 덕분에 분석이 불완전해도 위키가 거짓말을 하지는 않습니다.
위키 문서마다 머리말에 "나는 이 파일들에 의존한다"가 적혀 있습니다.
코드가 바뀌면(git 커밋 기준) 로봇이 바뀐 파일을 보고
그 파일에 의존하는 문서만 골라서 "이 문서들 낡았어요"라고 알려줍니다.
그러면 AI에게 그 문서들만 고치게 시키면 됩니다. 전체를 다시 만들 필요가 없어요.
먼저 매번 긴 명령을 치지 않도록 별명을 등록해두면 편합니다.
터미널 설정 파일(~/.zshrc 또는 ~/.bashrc)에 한 줄 추가:
alias cw='python3 ~/codewiki/cw.py'(codewiki 폴더를 다른 곳에 뒀다면 그 경로로 바꾸세요)
cd /내/프로젝트/폴더 # .git 폴더가 있는 프로젝트 최상위로 이동
cw doctor로봇이 스스로를 테스트하고 환경을 점검해서 알려줍니다: 파이썬 버전은 괜찮은지, 파서가 정상 동작하는지, 파일이 몇 개인지, 한글 인코딩 문제는 없는지, 제외하면 좋을 폴더(외부 라이브러리 등)는 뭔지. 마지막에 "문제 없음"이 나오면 다음 단계로.
파일이 너무 많다고 나오면:
.codewiki/config.json을 열어exclude_dirs에 제외할 폴더 이름을 추가하세요. (doctor가 후보를 알려줍니다)
cw setup이 한 줄이 자동으로 해주는 것:
- 프로젝트 안에
wiki/폴더와 빈 양식들을 설치 - 코드 전체를 읽어서 함수·참조 관계를 수집 (9,000개 파일도 몇 초)
- 파일마다 자동 요약 페이지 생성 (
wiki/files/아래) - 프로젝트 지도를 화면에 출력 +
.codewiki/map.md에 저장
여기까지는 AI가 전혀 안 쓰였고, 돈도 안 들었습니다.
이제 AI 차례입니다. 방법은 쓰는 도구에 따라 둘 중 하나:
방법 A — Claude Code처럼 명령 실행이 가능한 AI라면: 그냥 "이 프로젝트 위키 만들어줘"라고 하면 됩니다. (codewiki 스킬이 설치되어 있으면 알아서 절차대로 합니다)
방법 B — 채팅만 되는 AI라면: 다음 두 가지를 복사해서 AI에게 붙여넣으세요.
.codewiki/map.md파일 내용 (프로젝트 지도)~/codewiki/prompts/1-generate.md파일 내용 (작업 지시문)
AI가 지시문에 따라 모듈 설명 → 실행 흐름 → 전체 개요 순서로 문서를 씁니다.
cw lintAI가 쓴 문서의 근거 주소가 진짜인지, 딱지 규칙을 지켰는지 로봇이 검사합니다. "에러 0건"이 나와야 합격입니다. 에러가 있으면 그 목록을 AI에게 주고 고치게 하세요.
Obsidian 앱에서 내프로젝트/wiki 폴더를 열면(Open folder as vault) 끝!
wiki/
├── 00-overview.md ← 여기부터 읽으세요. 전체 그림
├── modules/ ← 부품별 설명 (이 모듈은 무슨 역할, 뭘 조심해야 하나)
├── flows/ ← 기능별 실행 순서 (요청이 들어오면 무슨 일이 벌어지나)
├── module-map.md ← 모듈 사이 의존 그림 (로봇이 자동으로 그림, 낡지 않음)
├── decisions/ ← 왜 이렇게 만들었나 (가장 귀한 정보)
├── notes/ ← 작업하며 알게 된 함정·경험 ("이 함수 스레드 안전 아님" 등)
├── glossary.md ← 팀 용어 사전
└── files/ ← 파일별 자동 요약 (로봇이 만듦, 편집 금지)
코드를 고치고 커밋한 다음:
cw update로봇이 알려줍니다: "이 문서 2개가 낡았어요. 이 파일들이 바뀌었기 때문이에요."
그 목록과 ~/codewiki/prompts/2-update.md(갱신 지시문)를 AI에게 주면
AI가 낡은 문서만 고칩니다. 끝나면:
cw lint # 검사 통과 확인
cw update --mark-done # "여기까지 반영 완료" 도장 찍기이게 전부입니다. 평소에는 cw update → AI에게 넘기기 → cw lint 세 개만 기억하세요.
목록을 매번 손으로 넘겨야 하나요? 쓰는 AI에 따라 다릅니다.
- 명령 실행이 가능한 AI(Claude Code 등): 넘길 필요 없음. "위키 갱신해줘" 한마디면 AI가 스스로
cw update를 돌리고 목록을 읽고 고치고 lint까지 합니다.- 채팅만 되는 AI: 네,
cw update출력을 복사해서 붙여줘야 합니다. 채팅 AI는 당신 컴퓨터에서 명령을 실행할 수 없기 때문입니다.
cw context Server::start이 함수에 대해 알아야 할 것을 한 번에 모아줍니다: 어디에 정의되어 있고, 누가 이 함수를 부르고, 이 함수는 뭘 부르고, 관련된 위키 문서는 뭔지. 이 출력을 AI에게 주고 "이거 고쳐줘" 하면 AI가 훨씬 정확하게 작업합니다.
얼마나 정확한가요? 항목마다 다릅니다:
| 항목 | 정확도 | 이유 |
|---|---|---|
| 정의 위치 (파일·줄번호) | 높음 | 분석기가 직접 찾은 사실 |
| 관련 위키 문서 | 높음 | 문서의 의존 선언과 기계적으로 대조 |
| 호출자·호출 대상 | 이름이 독특하면 좋음, 흔하면 부정확 | 이름만 보고 추정하기 때문 |
Server::start처럼 독특한 이름은 거의 정확하지만, init(), get()처럼
프로젝트에 수십 개 있는 흔한 이름은 동명이인을 구분하지 못해 엉뚱한 게
섞일 수 있습니다. 함수 포인터나 매크로를 거친 호출은 아예 못 잡고요.
그래서 이 출력은 "AI에게 주는 출발점 지도"이지 최종 판결문이 아닙니다 —
AI가 이걸 받아서 실제 코드를 열어 확인하는 게 정상적인 사용 흐름입니다.
위키의 진짜 가치는 시간이 지나며 코드에 없는 지식이 쌓이는 데 있습니다. AI와 작업하다가 새로 알게 된 것("이 함수는 겉보기와 달리 스레드 안전이 아니더라", "이건 하드웨어 제약 때문에 이렇게 한 거야")이 생기면:
- 명령 실행이 되는 AI: "방금 알게 된 거 위키에 남겨줘" 또는 "기억해둬" 한마디면 됩니다.
- 채팅 AI:
~/codewiki/prompts/4-capture.md를 붙여넣으세요.
AI가 그 지식을 종류에 따라 notes/(함정·경험), decisions/(설계 이유),
glossary.md(용어)에 정리해서 남깁니다. notes에는 관련 파일이 기록되어 있어서,
나중에 그 코드가 바뀌면 cw update가 "이 노트 낡았을 수 있음"까지 알려줍니다.
IDL(RTI DDS, CycloneDDS 등)이나 Franca(.fidl, SOME/IP 계열) 정의 파일이 있으면, 색인할 때 정의 파일과 이를 사용하는 코드를 자동으로 이어줍니다 — 생성 코드의 파일 이름 관례와 인터페이스 이름 언급을 근거로요. 벤더에 상관없이 동작하고, 이름 기반 추정이므로 "추정" 등급으로만 기록됩니다. 파일 stub의 "언어 경계 연결" 섹션에서 볼 수 있습니다.
모듈(폴더)끼리 누가 누굴 참조하는지를 그림(mermaid)으로 그려주는 문서입니다. Obsidian에서 열면 화살표 그림으로 보이고, IDL 같은 언어 경계는 점선으로 표시됩니다.
별도 명령이 없습니다 — 자동입니다. cw setup 때 처음 생기고,
cw update 때 코드 변경이 있으면 자동으로 다시 그려집니다.
wiki/files/와 같은 "로봇 소유" 문서라서 편집하면 안 되고(덮어써집니다),
대신 절대 낡지 않습니다.
cw coverage모듈별로 위키가 몇 %나 다루고 있는지, 그리고 "많이 참조되는 중요한 파일인데 아직 어떤 문서도 안 다루는 것" 목록을 보여줍니다. 큰 프로젝트에서 위키를 조금씩 키워갈 때 "다음에 뭘 문서화할지"를 이 목록으로 정하면 됩니다.
~/codewiki/prompts/3-verify.md를 위키를 만들지 않은 다른 AI 세션에 주면,
위키의 주장들을 코드와 대조해서 틀린 곳을 찾아줍니다. 분기에 한 번 정도 권장.
| 명령 | 언제 쓰나 |
|---|---|
cw doctor |
새 컴퓨터/새 프로젝트에서 제일 먼저. 환경 점검 |
cw setup |
프로젝트에 처음 위키를 만들 때 (딱 1번) |
cw update |
코드를 고친 뒤. 낡은 문서를 찾아줌 |
cw update --mark-done |
AI가 문서 갱신을 마친 뒤 도장 찍기 |
cw lint |
AI가 문서를 쓰거나 고친 뒤 검사 |
cw context <함수이름> |
특정 코드를 고치기 전에 관련 정보 모으기 |
cw coverage |
위키가 어디를 다루고 어디가 비었는지 + 다음 문서화 후보 |
cw status |
지금 상태 확인 (파일 몇 개, 어느 커밋 기준인지) |
cw map / cw index / cw stubs |
setup이 묶어서 해주는 개별 단계. 보통 직접 쓸 일 없음 |
Q. 파일이 9,000개가 넘는데 괜찮나요? 네. 로봇의 작업(수집·검사)은 9,000개 파일 기준 몇 초입니다. 다만 AI에게 문서를 쓰게 할 때는 한 번에 전부 시키지 말고, 핵심 모듈 2~3개부터 시작해서 필요할 때 하나씩 늘리세요. 위키는 자라나는 것이지 한 번에 완성하는 게 아닙니다.
Q. AI가 쓴 설명이 틀리면 어떡하죠?
세 겹의 안전장치가 있습니다. ① 모든 문장에 신뢰도 딱지 —
"추측"이라고 쓰인 건 원래 틀릴 수 있는 겁니다. ② cw lint가 근거 주소를
기계로 검사합니다. ③ 가끔 감사 지시문(3-verify)으로 대조 검사를 돌립니다.
그래도 최종 확인은 "당신이 가장 잘 아는 모듈의 문서"를 직접 읽어보는 것입니다.
Q. 한글 주석이 있는 옛날 파일이 있는데 깨지나요? 안 깨집니다. UTF-8이 아니면 자동으로 CP949(한글 윈도우 인코딩)로 다시 읽습니다.
Q. universal-ctags 같은 걸 설치해야 하나요? 아니요. 내장 분석기만으로 동작합니다. ctags가 우연히 설치되어 있으면 자동으로 활용하는 것뿐이에요.
Q. wiki 폴더를 회사 공용 저장소에 커밋해도 되나요?
되면 하는 게 좋습니다(팀 전체가 공유). 안 되면 프로젝트의
.git/info/exclude 파일에 wiki/와 .codewiki/ 두 줄을 추가하세요 —
나만 보는 로컬 위키가 됩니다. (.codewiki/는 어차피 자동으로 커밋 제외됩니다)
Q. 회사 AI가 최신 모델이 아닌데 되나요? 됩니다. 어려운 일(사실 수집, 검사, 낡은 문서 찾기)은 전부 로봇이 하고, AI에게는 좁고 명확한 일만 시키도록 지시문이 짜여 있습니다. 모델이 약할수록 lint 검사가 더 자주 잡아주는 것뿐이에요.
Q. init 하니까 CLAUDE.md, AGENTS.md가 생겼어요. 뭔가요? 그 프로젝트에서 일하는 AI 에이전트에게 "이 프로젝트엔 위키가 있으니 활용해라"라고 알려주는 안내판입니다. 이미 같은 이름 파일이 있으면 건드리지 않습니다.
Q. Claude Code 스킬은 어떻게 설치하나요? Claude Code를 쓴다면 한 번만 복사하면 됩니다:
mkdir -p ~/.claude/skills && cp -r ~/codewiki/skill/codewiki ~/.claude/skills/이후에는 "위키 만들어줘", "위키 갱신해줘", "기억해둬" 같은 말만으로 전체 절차(명령 실행 → 문서 작성 → lint → 도장)가 자동으로 돌아갑니다. 다른 AI 도구를 쓴다면 이 단계는 건너뛰고 prompts/ 대본을 쓰면 됩니다.
- 컴파일러 수준의 정밀 분석은 못 합니다. 매크로로 만들어진 함수, C++ 템플릿의 복잡한 사용, 함수 포인터가 실행 중에 어디로 가는지는 못 찾습니다. 그래서 "못 찾은 건 모름으로 표시"라는 원리 ③이 있는 겁니다.
- 호출 관계는 "이름 기반 추정"입니다. 같은 이름의 함수가 여러 개면 헷갈릴 수 있어서 추정(inferred) 등급으로만 기록합니다.
- 함수 모양은 그대로인데 동작만 바뀐 경우, 아주 멀리 있는 문서가 낡는 것까지는 못 잡습니다. 그래서 가끔 감사(3-verify)를 돌리라는 겁니다.
- 언어 경계 연결은 "이름"이 있어야 합니다. SOME/IP(vsomeip)처럼 서비스를 숫자 ID로만 다루는 코드는 자동으로 못 잇습니다. 그런 지식("ID 0x1234 = 센서 수집 서비스")이야말로 기억 루프로 notes/에 남겨둘 가치가 있는 것들입니다.
cw update는 git을 쓰는 프로젝트에서만 동작합니다.
- 먼저
cw doctor를 돌려보세요. 대부분의 환경 문제를 찾아줍니다. - doctor의 출력과 에러 메시지를 그대로 AI에게 보여주고 물어보세요.
cw.py는 파일 하나짜리 파이썬 프로그램이라 AI가 직접 읽고 원인을 찾을 수 있습니다.