요약
공동위키에 처음 기여하려는 사람이 **“내 컴퓨터는 지금 어디까지 준비됐나”**를 AI(Claude Code)에게 한 번에 점검시키고, 빠진 것을 하나씩 채워 첫 PR 직전까지 가는 과정을 정리했다. 점검표 프롬프트 한 장, 실제 진단 결과, 그리고 처음 해보는 사람이 걸리기 쉬운 함정 네 가지를 담았다.
1단계 — 점검표를 통째로 AI에게 건네기
항목을 하나씩 물어보는 대신, 점검표 전체를 붙여넣고 ✅/❌ 형식으로 답하라고 하면 AI가 필요한 명령을 알아서 실행하고 한눈에 보이는 결과표를 만들어 준다. 실제로 쓴 점검표(요약):
내 컴퓨터의 바이브 코딩 환경을 점검해줘. 아래 항목을 하나씩 확인하고 ✅ 또는 ❌로 표시해줘.
[PC 로컬 도구] 1. Node.js 2. Git 3. Git 사용자 이름/이메일 4. VSCode 5. Obsidian [AI 도구] 6. Claude Code 7. CLAUDE.md 8. Anthropic API 키 [클라우드 서비스] 9. GitHub 레포 10. Quartz 11. Cloudflare Pages 12. Supabase [연대지능 위키] 13. 위키 저장소 Fork 14. 위키 문서 작성 15. PR 제출 경험
요령: 항목마다 어떤 명령으로 확인할지(node --version, gh repo list --fork 등)를 같이 적어주면 AI가 엉뚱한 방법으로 헤매지 않는다.
2단계 — 진단 결과 읽기
처음 받은 결과는 이랬다.
| 영역 | 결과 |
|---|---|
| PC 로컬 도구 (1~5) | 모두 ✅ |
| AI 도구 (6~8) | Claude Code ✅, CLAUDE.md ❌, API 키 ❌ |
| 클라우드 서비스 (9~12) | 모두 ❌ |
| 연대지능 위키 (13~15) | 확인 불가 — GitHub CLI(gh)가 없어서 |
여기서 배운 점 두 가지:
- ❌가 곧 “해야 할 일”은 아니다. API 키(8번)는 Claude Code에 구독 계정으로 로그인해 쓰고 있다면 필요 없다. Quartz(10번)는 위키 사이트를 만드는 도구인데, 기여자 저장소에는 없어도 된다. AI에게 “이게 꼭 필요한 거야?”라고 되물어서 진짜 공백만 추려라.
- “확인 불가”는 도구 하나로 풀리는 경우가 많다. 13·15번은 GitHub CLI 하나만 설치하면 한꺼번에 확인됐다.
3단계 — 빠진 것 채우기 (순서가 중요)
AI가 제안한 순서대로 했더니 한 단계가 다음 단계의 확인 도구가 되었다.
- GitHub CLI 설치 — AI에게 “설치해줘” 한마디면
winget install GitHub.cli로 끝난다. - GitHub 로그인 — 이것만은 사람이 해야 한다(아래 함정 2 참고). 로그인 후 다시 점검하니 13번(Fork) ✅로 바뀌었다.
- 내 Fork를 컴퓨터로 가져오기(clone) —
gh repo clone 내계정/solidarity-intelligence-wiki.gh로 받으면 원본 저장소가upstream으로 자동 연결되어, 나중에 최신 문서를 받아오기 쉽다. - 문서 1편 쓰고 PR — 지금 이 문서가 그 결과물이다.
처음 하는 사람이 걸리는 함정 네 가지
함정 1. 설치 직후 명령을 못 찾는다. 켜져 있던 AI 세션은 설치 전의 경로 목록(PATH)을 기억한다. gh를 설치해도 gh라고 치면 “없는 명령”이 된다. 새 터미널을 열거나, 당분간 전체 경로(C:\Program Files\GitHub CLI\gh.exe)로 부르면 된다.
함정 2. 로그인은 사람이 직접 해야 한다. 로그인은 대화형 절차라 AI가 대신 못 한다. Claude Code 입력창 맨 앞에 !를 붙이면 그 명령을 내가 직접 실행할 수 있다. 화면에 8자리 일회용 코드가 나오면 https://github.com/login/device 에 입력하고 승인한다. 비밀번호를 AI에게 알려주지 않는 안전한 방식이다.
함정 3. ! 명령은 PowerShell이 아니라 bash로 실행된다. Windows라서 PowerShell 문법(& "C:\Program Files\...")으로 쳤다가 syntax error near unexpected token '&' 오류가 났다. bash 문법으로 "/c/Program Files/GitHub CLI/gh.exe" auth login --web처럼 쳐야 한다. AI가 알려준 명령이 오류가 나면 오류 메시지를 그대로 보여주면 고쳐준다.
함정 4. 승인을 기다리다 “시간 초과”가 떠도 실패가 아니다. 브라우저 승인을 기다리는 동안 명령이 2분을 넘기면 “백그라운드로 옮겨짐”이라고 나온다. 끝난 게 아니라 아직 기다리는 중이다. 코드를 입력하고 승인하면 백그라운드에서 마저 끝난다. 헷갈리면 AI에게 “완료된 거야?”라고 물으면 상태를 확인해 준다.
덤 — 저장소 구조가 점검표와 다를 수 있다
점검표에는 “wiki/ 폴더의 .md 파일 수”라고 적었지만, 실제 이 위키의 문서 폴더는 문서/(분야지식·사회운동·실천기술·용어사전)였다. 점검표는 출발점일 뿐이고, 실제 저장소의 CONTRIBUTING.md를 AI에게 읽혀서 규칙을 확인하는 것이 정확하다.
교훈
- 점검표 한 장이 막막함을 할 일 목록으로 바꾼다. “뭐부터 해야 하지?”가 ”❌ 몇 개 채우기”가 된다.
- ❌를 다 없애려 하지 말고, 필요한 ❌만 골라라. AI에게 필요성을 되물으면 된다.
- 사람이 해야 하는 일(로그인·승인)과 AI가 할 일(설치·확인·정리)을 나누면 빠르다.
- 점검은 한 번으로 끝나지 않는다. 하나를 채울 때마다 다시 점검시키면 진행 상황이 눈에 보인다.
참고
- 기여 방법:
CONTRIBUTING.md - 이어 읽기: 공동위키에 처음 기여하기, AI 작업환경 정비 — 도구 공백 진단과 해결
- 작업 환경: Windows 11, Claude Code 2.1, GitHub CLI 2.101 (2026-09-26 기준)