codewiki — 코드 프로젝트의 백과사전을 만들어주는 도구

큰 코드 프로젝트에 처음 들어가면 이런 게 궁금하죠.

• 이 프로젝트는 전체적으로 어떻게 생겼지?
• 이 기능은 어디서 시작해서 어떤 순서로 실행되지?
• 이 파일을 고치면 어디에 영향이 가지?

codewiki는 이 질문들에 답하는 "프로젝트 전용 위키"를 만들어줍니다. 기계가 사실을 모으고 AI가 설명을 씁니다. 결과물은 Obsidian으로 열어보는 마크다운 문서라 사람이 읽기도 좋고, AI에게 "이거 읽고 작업해"라고 주기도 좋습니다.

지원 언어: C, C++, Python, IDL(.idl), Franca(.fidl — SOME/IP 계열) — 섞여 있어도 됩니다.

---

5분 만에 시작하기

0단계 — 설치

필수: Python 3.8 이상. 그리고 이 폴더를 아무 데나 복사하세요. (예: ~/codewiki)

python3 --version     # 3.8 이상이면 OK

권장: tree-sitter — C/C++를 정밀하게 읽으려면 설치하세요.

cd ~/codewiki
pip install -r requirements-parser.txt

왜 권장인가요? 없어도 돌아갑니다. 하지만 없으면 도구가 자기가 못 읽은 부분을 알지 못합니다. 그러면 AI가 "이 함수 아무도 안 씁니다"라고 자신 있게 틀린 말을 할 수 있어요. tree-sitter가 있으면 "여기는 제가 못 읽었습니다"를 알려주기 때문에 그런 일이 안 생깁니다. 이게 이 도구의 핵심입니다.

실측: 공개 코드(vsomeip, Zephyr, FreeRTOS)에서 심볼을 19% 더 찾았고, 매크로가 많은 코드일수록 격차가 컸습니다(Zephyr +50%).

편의: 별명 등록 (매번 긴 경로를 안 치려고)

# macOS/Linux — ~/.zshrc 또는 ~/.bashrc 에 추가
alias cw='python3 ~/codewiki/cw.py'

# Windows PowerShell — $PROFILE 에 추가
function cw { python "$HOME\codewiki\cw.py" @args }

등록 후 터미널을 새로 열거나 source ~/.zshrc를 하세요. 별명 없이 python3 ~/codewiki/cw.py doctor 처럼 써도 똑같이 동작합니다.

1단계 — 환경 점검

cd /내/프로젝트/폴더     # .git 이 있는 프로젝트 최상위로
cw doctor

파이썬 버전, 파서 상태, 파일 개수, 한글 인코딩, 제외하면 좋을 폴더를 점검합니다. 맨 위 C/C++ 파서: 줄을 확인하세요.

• tree-sitter 사용 가능 (정밀 모드) ← 이게 나와야 좋습니다
• tree-sitter 미설치 ← 0단계의 pip 설치를 다시 해보세요

"대상 파일이 너무 많다"고 나오면: .codewiki/config.json을 열어 exclude_dirs에 외부 라이브러리·생성 코드 폴더를 추가하세요. (doctor가 후보를 알려줍니다)

2단계 — 준비 (한 방에 끝)

cw setup

이 한 줄이 자동으로 합니다:

1. 프로젝트에 wiki/ 폴더와 빈 양식 설치
2. 코드 전체를 읽어 함수·참조 관계 수집 (9,000개 파일도 몇 초)
3. 파일별 자동 요약 페이지 생성
4. 프로젝트 지도를 화면에 출력 + .codewiki/map.md에 저장

여기까지 AI를 전혀 안 썼고, 돈도 안 들었습니다.

3단계 — 파서가 얼마나 읽어냈는지 확인 ⭐

cw parse-report

이 단계를 건너뛰지 마세요. 위키를 얼마나 믿어도 되는지가 여기서 정해집니다.

## 판정: 보통 (파서가 못 읽은 파일 12/94 = 13%)

## 파서가 못 읽은 것 (판정에 반영됨)
- 매크로가 시그니처를 가림 (macro_mangled_decl): 31곳
- ## 토큰 붙이기(이름이 소스에 없음) (token_paste): 4곳

## 코드의 성질 (판정에 반영 안 됨, 그러나 알아야 함)
- 조건부 컴파일 분기 (ifdef_branch): 87곳
- 함수 포인터 테이블 등록 (fnptr_table): 12곳

## 다음에 할 일
→ 이 심볼들의 이름은 실제와 다를 수 있습니다. 위키에서 사실로 단정하면 안 됩니다.
→ 여기 등록된 함수들은 '호출자 없음'으로 보일 수 있습니다. 데드코드 판정 시 주의하세요.

"나쁨"이 나와도 당황하지 마세요. 고장이 아닙니다. 빌드를 돌리지 않고 소스만 읽는 이상 매크로·조건부 컴파일은 원래 완전히 해석할 수 없습니다. 중요한 건 "못 읽은 곳을 알고 있다"는 것이고, 저 목록이 바로 그겁니다. 위키를 만들 때 AI가 이 지점들을 사실로 단정하지 않게 됩니다.

판정	뜻	어떻게 하나
좋음	파서가 대부분 읽어냄	그냥 진행하세요
보통	일부 매크로에서 막힘	진행하되, 해당 파일의 위키 설명은 한 번 검토
나쁨	매크로가 많은 코드	진행은 가능. 아래 3.5단계를 해보세요

3.5단계 — 매크로가 범인이면 (선택)

3단계 결과에 ## 못 읽게 만든 범인 목록이 떴다면 이 단계를 해보세요. 안 떴으면 건너뛰셔도 됩니다.

MEDIA_PUBLIC void start_camera(int id); 처럼 함수 앞에 붙는 장식 매크로는 파서를 깨뜨립니다. 그런데 지우기만 하면 나머지가 그대로 읽힙니다. 매크로가 무엇으로 전개되는지는 알 필요가 없습니다.

문제는 어떤 매크로를 지워도 되는지 겉모습으로는 알 수 없다는 겁니다. 셋 다 그냥 대문자 단어라서요.

코드	지우면
MEDIA_PUBLIC void f(int);	✅ 구멍이 사라짐 (장식)
RTI_BOOL check(int);	❌ 함수가 통째로 사라짐 (타입 이름)
MOCK_METHOD(int, run, (int));	❌ 괄호가 남아 더 나빠짐 (인자를 받음)

그래서 기계가 하나씩 실제로 지워보고 재게 했습니다.

cw try-macros

## 넣어도 되는 것 (구멍이 줄고, 잃는 심볼이 없음)
- PRIVILEGED_FUNCTION: 구멍 610 → 395곳 (파일 40개 기준)

## 넣으면 안 되는 것 — 심볼이 사라집니다
- PRIVILEGED_DATA: 7개 사라짐 (예: BaseType_t, QueueHandle_t, TaskHandle_t)
  → 타입 이름으로 쓰이는 매크로입니다. 지우면 반환 타입이
    없어져서 파서가 함수인 줄 모르게 됩니다.

## 넣어도 소용없는 것
- ADC: 괄호가 남아 더 나빠짐
  → 인자를 받는 매크로는 이름만 지워서는 해결되지 않습니다.

## .codewiki/config.json 에 붙여넣으세요
  "ignore_macros": ["PRIVILEGED_FUNCTION"]

맨 아래 줄을 .codewiki/config.json 에 붙여넣고 다시 돌리면 됩니다.

cw index
cw parse-report

exclude_dirs 는 지우지 마세요. ignore_macros 줄만 추가하는 겁니다. 통째로 갈아엎으면 build, third_party 같은 폴더가 다시 색인에 들어옵니다.

"넣으면 안 되는 것"에 있는 이름은 절대 넣지 마세요. 위키에서 함수가 조용히 사라집니다. 목록은 추측이 아니라 실제로 지워보고 확인한 결과입니다.

실제 효과 (FreeRTOS 658개 파일 기준)

	전	후
구멍	24,401곳	23,301곳
심볼	39,910개	40,910개

구멍이 줄 뿐 아니라 못 찾던 함수 1,000개를 찾아냈습니다. 다만 프로젝트마다 다릅니다 — 구멍만 줄고 심볼은 그대로인 경우도 있습니다. 그때도 이득입니다. 멀쩡히 읽은 코드에 붙던 "확인 필요" 딱지가 걷히거든요.

4단계 — AI에게 본문을 쓰게 하기

Claude Code처럼 명령을 실행할 수 있는 AI라면: 그냥 "이 프로젝트 위키 만들어줘" 라고 하세요. (스킬은 cw setup 이 이미 깔아뒀습니다. Claude Code를 한 번 다시 켜세요.)

채팅만 되는 AI(사내 챗봇 등)라면: 아래 두 파일 내용을 복사해서 붙여넣으세요.

1. .codewiki/map.md — 프로젝트 지도
2. ~/codewiki/prompts/1-generate.md — 작업 지시문

AI가 모듈 설명 → 실행 흐름 → 전체 개요 순서로 씁니다. 한 번에 전부 시키지 마세요. 핵심 모듈 2~3개부터 시작하는 게 좋습니다.

5단계 — 검사

cw lint

AI가 쓴 문서의 근거 주소가 진짜인지 기계가 검사합니다. "에러 0건"이 합격입니다. 에러가 있으면 그 목록을 AI에게 주고 고치게 하세요.

6단계 — 구경하기

Obsidian에서 내프로젝트/wiki 폴더를 여세요 (Open folder as vault).

wiki/
├── 00-overview.md   ← 여기부터 읽으세요. 전체 그림
├── modules/         ← 부품별 설명
├── flows/           ← 기능별 실행 순서
├── module-map.md    ← 모듈 의존 그림 (자동 생성, 안 낡음)
├── decisions/       ← 왜 이렇게 만들었나 (가장 귀한 정보)
├── notes/           ← 함정·경험 ("이 함수 스레드 안전 아님" 등)
├── glossary.md      ← 팀 용어 사전
└── files/           ← 파일별 자동 요약 (편집 금지 — 덮어써집니다)

Obsidian이 없어도 됩니다. 그냥 마크다운 파일이라 아무 편집기로나 보여요.

---

평소 사용법 — 명령 3개만 기억하세요

코드를 고치고 커밋한 다음:

cw update       # ① 낡은 문서를 찾아줌
                # ② 그 목록을 AI에게 주고 고치게 함
cw lint         # ③ 검사
cw update --mark-done    # ④ "여기까지 반영 완료" 도장

cw update가 이렇게 알려줍니다: "이 문서 2개가 낡았어요. 이 파일들이 바뀌었기 때문이에요." 전체를 다시 만들 필요가 없습니다.

목록을 매번 손으로 넘겨야 하나요?

• 명령 실행 가능한 AI(Claude Code 등): 아니요. "위키 갱신해줘" 한마디면 알아서 cw update 돌리고 고치고 lint까지 합니다.
• 채팅만 되는 AI: 네, 출력을 복사해서 붙여줘야 합니다. 채팅 AI는 당신 컴퓨터에서 명령을 실행할 수 없거든요.

---

어떤 원리인가요? (안 읽어도 쓸 수 있습니다)

원리 ① 코드를 복사하지 않고 "주소"만 적는다

위키에 코드를 붙여넣으면 코드가 바뀔 때마다 위키가 낡습니다. 그래서 주소로만 가리킵니다.

src/net/server.c#server_start ← "server.c 안의 server_start 함수"

함수가 파일 안에서 위아래로 밀려도 주소는 그대로 유효합니다.

원리 ② 모든 문장에 "신뢰도 딱지"가 붙는다

AI는 가끔 그럴듯한 거짓말을 합니다. 그래서 모든 문장에 딱지가 붙습니다.

딱지	뜻
^[confirmed: 주소]	코드에서 직접 확인. 근거 주소 필수
^[inferred]	정황상 추측. 틀릴 수 있음
^[unknown]	코드만으로는 알 수 없었음

cw lint가 "confirmed라 해놓고 근거가 없거나 가짜면" 에러를 냅니다. AI가 거짓말해도 걸립니다.

원리 ③ "못 읽은 것"을 숨기지 않는다 ⭐

이게 이 도구의 핵심입니다.

코드 분석은 완벽할 수 없습니다. 매크로, 함수 포인터, 조건부 컴파일은 빌드를 돌리지 않으면 원래 해석이 안 됩니다.

문제는 못 읽었다는 사실을 도구가 말해주지 않을 때 생깁니다. 그러면 AI 눈에는 완전한 지도로 보이고, 자신 있게 틀린 말을 합니다.

"handle_can_frame은 아무도 호출하지 않습니다. 삭제해도 됩니다." → 사실은 매크로로 함수 포인터 테이블에 등록되어 인터럽트에서 불리고 있었음

codewiki는 못 읽은 지점을 전부 기록합니다(cw parse-report로 확인). 그래서 AI의 답이 이렇게 바뀝니다:

"제가 확인한 직접 호출자는 없습니다. 다만 can_table.c의 매크로 3곳을 제가 못 읽었고, 거기서 등록하고 있을 수 있습니다. 확인해 보세요."

도구가 더 똑똑해진 게 아닙니다. 못 읽었다는 걸 숨기지 않을 뿐인데 답이 "지우세요"에서 "확인해 보세요"로 바뀝니다.

원리 ④ 코드가 바뀌면 "낡은 문서만" 찾아준다

문서마다 "나는 이 파일들에 의존한다"가 적혀 있어서, 바뀐 파일에 의존하는 문서만 골라 알려줍니다.

---

명령어 한눈에 보기

명령	언제 쓰나
cw doctor	제일 먼저. 환경 점검
cw setup	프로젝트에 처음 위키 만들 때 (딱 1번)
cw parse-report	setup 직후. 파서가 얼마나 읽어냈는지 + 못 읽은 곳
cw try-macros	parse-report에 "범인 매크로"가 떴을 때. 지워도 되는 것만 골라줌
cw install-skills	Claude Code 스킬 재설치 (setup이 자동으로 해줌)
cw update	코드를 고친 뒤. 낡은 문서 찾기
cw update --mark-done	AI가 갱신을 마친 뒤 도장 찍기
cw lint	AI가 문서를 쓰거나 고친 뒤 검사
cw context <함수이름>	특정 코드를 고치기 전 관련 정보 모으기
cw coverage	위키가 어디를 다루고 어디가 비었는지
cw log --gaps	위키에 없어서 코드를 열어본 질문 (다음 문서화 후보)
cw status	지금 상태 (파일 몇 개, 어느 커밋 기준인지)
cw map / index / stubs	setup이 묶어서 해줌. 보통 직접 쓸 일 없음

---

보너스 기능

코드를 고치기 전에: cw context

cw context server_start

정의 위치, 누가 부르는지, 뭘 부르는지, 관련 위키 문서를 한 번에 모아줍니다. 이걸 AI에게 주고 "고쳐줘" 하면 훨씬 정확해집니다.

정확도는 항목마다 다릅니다:

항목	정확도
정의 위치	높음 — 파서가 직접 찾은 사실
관련 위키 문서	높음 — 기계적 대조
호출자·호출 대상	이름이 독특하면 좋음, init() 같이 흔하면 부정확

출발점 지도이지 최종 판결문이 아닙니다. AI가 이걸 받아 실제 코드를 열어보는 게 정상 흐름입니다.

배운 것을 위키에 쌓기 (기억 루프)

위키의 진짜 가치는 코드에 없는 지식이 쌓이는 데 있습니다. ("이 함수는 겉보기와 달리 스레드 안전이 아니다", "이건 하드웨어 제약 때문이다")

• 명령 실행 가능한 AI: "방금 알게 된 거 위키에 남겨줘" 한마디
• 채팅 AI: prompts/4-capture.md를 붙여넣기

notes/(함정), decisions/(설계 이유), glossary.md(용어)에 정리됩니다.

언어 경계 연결 (IDL·미들웨어)

.idl(DDS)이나 .fidl(SOME/IP) 정의 파일이 있으면, 정의와 이를 쓰는 코드를 자동으로 이어줍니다. 이름 기반 추정이라 "추정" 등급으로만 기록됩니다.

가끔 한 번씩: 위키 감사

prompts/3-verify.md를 위키를 만들지 않은 다른 AI 세션에 주면 코드와 대조해 틀린 곳을 찾아줍니다. 분기에 한 번 정도.

---

막혔을 때

1. 먼저 cw doctor를 돌려보세요. 대부분의 환경 문제를 찾아줍니다.

2. 그래도 안 되면 에러 메시지를 AI에게 그대로 보여주세요. cw.py는 파일 하나짜리 파이썬 프로그램이라 AI가 직접 읽고 원인을 찾을 수 있습니다.

자주 나오는 상황:

증상	원인·해결
tree-sitter 버전 충돌	pip install -r requirements-parser.txt 를 다시 실행. 버전이 핀으로 고정돼 있습니다
cw: command not found	별명 등록 후 터미널을 새로 여세요. 또는 python3 ~/codewiki/cw.py 로 직접 실행
facts.db가 없습니다	cw setup 을 먼저 실행하세요
update가 안 됩니다	git 저장소에서만 동작합니다. 커밋을 한 번은 해야 합니다
대상 파일이 수만 개	.codewiki/config.json 의 exclude_dirs 에 외부 라이브러리 폴더 추가

---

자주 묻는 질문

Q. 파일이 9,000개가 넘는데 괜찮나요? 네. 기계 작업(수집·검사)은 몇 초입니다. 다만 AI에게 문서를 쓰게 할 때는 핵심 모듈 2~3개부터 시작하세요. 위키는 자라나는 것이지 한 번에 완성하는 게 아닙니다.

Q. AI가 쓴 설명이 틀리면요? 안전장치가 셋입니다. ① 모든 문장에 신뢰도 딱지 — "추측"이라 쓰인 건 원래 틀릴 수 있는 겁니다. ② cw lint가 근거를 기계로 검사. ③ 가끔 감사(3-verify) 실행. 그래도 최종 확인은 당신이 가장 잘 아는 모듈의 문서를 직접 읽어보는 것입니다.

Q. 한글 주석이 있는 옛날 파일이 깨지나요? 안 깨집니다. UTF-8이 아니면 CP949(한글 윈도우 인코딩)로 자동 재시도합니다.

Q. 회사 AI가 최신 모델이 아닌데 되나요? 됩니다. 어려운 일(사실 수집, 검사, 낡은 문서 찾기)은 전부 기계가 하고, AI에게는 좁고 명확한 일만 시킵니다. 모델이 약할수록 lint가 더 자주 잡아줄 뿐이에요.

Q. wiki 폴더를 회사 저장소에 커밋해도 되나요? 되면 하는 게 좋습니다(팀 공유). 안 되면 .git/info/exclude에 wiki/와 .codewiki/ 두 줄을 추가하세요. 나만 보는 로컬 위키가 됩니다.

Q. init 하니까 CLAUDE.md, AGENTS.md가 생겼어요. 그 프로젝트의 AI 에이전트에게 "여기 위키 있으니 활용해라"라고 알려주는 안내판입니다. 같은 이름 파일이 이미 있으면 건드리지 않습니다.

Q. Claude Code 스킬은 어떻게 설치하나요?

cw setup 이 알아서 깝니다. 따로 하실 게 없습니다.

처음 돌릴 때 이렇게 뜹니다.

Claude Code 스킬
- 프로젝트 .claude/skills — 새로 깖: codewiki, codewiki-query
- 개인 /Users/나/.claude/skills — 새로 깖: codewiki, codewiki-query
  → Claude Code 를 다시 켜면 인식됩니다. 이후 '위키 만들어줘' 한마디로 됩니다.

두 군데에 깔립니다.

위치	효과
프로젝트 .claude/skills/	이 저장소를 받은 사람은 아무것도 안 해도 됩니다
개인 ~/.claude/skills/	내 모든 프로젝트에서 동작합니다

설치되는 스킬:

스킬	언제 쓰이나
codewiki	위키 생성·갱신 ("위키 만들어줘", "기억해둬")
codewiki-query	코드에 대한 질문 ("이거 어떻게 동작해?", "지워도 돼?")

Claude Code를 다시 켜야 인식됩니다. 이후 말로만 시키면 전체 절차가 돌아갑니다.

이미 같은 내용이면 건드리지 않고 조용히 넘어갑니다. codewiki를 새 버전으로 받았을 때만 "갱신"이라고 뜹니다.

따로 다시 깔고 싶으면:

cw install-skills

Q. 인터넷이 안 되는 망분리 환경인데요? pip install만 되면 됩니다. 그 외에는 인터넷을 쓰지 않습니다. 코드가 외부로 나가는 일도 없습니다 — 전부 로컬에서 돌아갑니다.

---

이 도구가 못 하는 것 (솔직하게)

• 컴파일러 수준의 정밀 분석은 못 합니다. 매크로로 만들어진 함수, 복잡한 C++ 템플릿, 함수 포인터의 런타임 목적지는 못 찾습니다. → 대신 못 찾았다는 걸 cw parse-report로 알려줍니다.
• 호출 관계는 이름 기반 추정입니다. 같은 이름의 함수가 여럿이면 헷갈릴 수 있어 "추정(inferred)" 등급으로만 기록합니다.
• 함수 모양은 그대로인데 동작만 바뀐 경우, 멀리 있는 문서가 낡는 것까지는 못 잡습니다. 그래서 가끔 감사(3-verify)를 돌리라는 겁니다.
• 숫자 ID로만 다루는 인터페이스는 자동으로 못 잇습니다. (SOME/IP 등) 그런 지식("ID 0x1234 = 센서 수집 서비스")이야말로 기억 루프로 notes/에 남겨둘 가치가 있는 것입니다.
• cw update는 git 저장소에서만 동작합니다.

---

테스트에 참여해 주셔서 감사합니다

이 도구는 아직 다듬는 중입니다. 다음 세 가지만 알려주시면 큰 도움이 됩니다.

① cw parse-report의 결과

• 판정이 뭐였나요? (좋음 / 보통 / 나쁨)
• "파서가 못 읽은 것" 상위 2~3개가 뭐였나요?

이게 가장 중요합니다. 다음에 뭘 고칠지가 여기서 정해집니다.

② 어디서 막혔나요? 설치, 실행, 이해 — 어느 단계든 "여기서 멈췄다" 하는 지점이 있으면 알려주세요. README가 부족했다는 뜻이라 그것도 고칠 거리입니다.

③ 위키 내용이 틀린 곳 당신이 잘 아는 모듈의 문서를 읽어보고 틀린 게 있으면 알려주세요. 어떤 딱지(confirmed/inferred)가 붙어 있었는지도 같이요.

에러가 났다면 cw doctor 출력과 에러 메시지를 함께 주시면 원인 찾기가 빠릅니다.