Claude Code 학술 워크플로우, 포크 후 10분 만에 첫 데모까지 검증하기

이 글을 읽으면 학술 작업용으로 미리 짜인 Claude Code 설정을 내 저장소로 가져와, 환경이 제대로 깔렸는지 점검하고 첫 데모 산출물(PDF와 HTML)까지 만들어 검증하는 순서를 결정할 수 있다. 오늘 남길 결과물은 딱 하나, "내 환경에서 데모가 컴파일되는지 확인된 체크리스트"다.

이게 무슨 도구이고, 왜 봐야 할까?

한 줄로 말하면, 슬라이드·논문·데이터 분석 같은 학술 작업을 Claude Code로 돌리도록 미리 설정해 둔 "포크용 출발점"이다. 여기서 포크(fork)는 남의 깃허브 저장소를 내 계정으로 통째로 복사해 내 것으로 만드는 것을 말한다.

직접 빈 화면에서 Claude Code 설정을 짜본 사람은 안다. 어떤 규칙 파일을 둘지, 어떤 명령을 만들지 매번 고민하는 게 번거롭다. 이 프로젝트(claude-code-my-workflow)는 실제 PhD 강의에서 쓰던 설정을 정리해 둔 것이라, 그 초기 세팅 고민을 건너뛰게 해준다. 다만 LaTeX나 Quarto 같은 학술 도구를 안 쓰는 사람이라면 데모 부분은 건너뛰어도 된다. 프로젝트 설명 기준으로, 에이전트·규칙·오케스트레이션 패턴 자체는 그냥 텍스트나 코드 작업에도 쓸 수 있다고 한다.

오늘 만들 산출물: 3단계 검증 체크리스트

결론부터 말하면, 포크 → 점검 스크립트 실행 → 데모 2개 컴파일, 이 세 단계만 통과하면 "내 환경 준비 완료"다.

1단계 — 포크하고 클론하기. 깃허브 페이지에서 Fork를 누른 뒤, 내 계정으로 복사된 저장소를 내려받는다.

git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project
./scripts/validate-setup.sh

여기서 YOUR_USERNAME은 본인 깃허브 아이디로 바꾼다. 마지막 줄의 점검 스크립트(validate-setup.sh)가 핵심인데, 이건 무엇이 빠졌는지를 설치 링크와 함께 알려주는 "준비물 검사기"다.

2단계 — Claude Code 켜고 시작 프롬프트 붙여넣기. 터미널에서 claude를 실행한다(VS Code라면 Claude Code 패널을 연다). 그다음 프로젝트 이름과 2~3문장 설명을 채운 시작 프롬프트를 붙여넣으면, 설정 파일들을 읽고 내 프로젝트에 맞춰 채워준다.

여기서 알아두면 편한 점 하나. 기본 상태에서는 도구를 쓸 때마다 허락을 묻는다(이걸 권한 모드라고 한다). 매번 승인하기 귀찮다면, 프로젝트 설명상 claude --permission-mode acceptEdits 같은 모드로 편집 자동 승인을 켤 수 있다. 또 템플릿의 .claude/settings.json이 자주 쓰는 명령 약 100개를 미리 승인해 둬서, 기본 권한에서도 대부분은 묻지 않고 진행된다고 설명한다.

3단계 — 데모로 진짜 도는지 확인하기. 점검 스크립트를 한 번 더 돌린 뒤, Claude 안에서 두 명령을 실행한다.

/compile-latex HelloWorld   # Slides/HelloWorld.tex → PDF
/deploy HelloWorld          # Quarto/HelloWorld.qmd → HTML

둘 다 성공하면 환경이 준비된 것이다. 이때 HelloWorld.tex와 HelloWorld.qmd를 지우고 진짜 작업을 시작하면 된다.

데모가 안 돌면 뭘 먼저 봐야 할까?

가장 먼저 점검 스크립트의 출력부터 본다. 데모를 끝까지 돌리려면 XeLaTeX(Beamer 슬라이드용)와 Quarto(Quarto 샘플용)가 필요하고, R과 깃허브 CLI는 권장 사항이다. 점검 스크립트가 "무엇이 없는지 + 설치 링크"를 직접 알려주므로, 빨간 줄이 가리키는 도구부터 깔면 된다. 참고로 첫 설치에는 대략 30분 정도가 더 걸릴 수 있다고 안내한다.

내 환경에서 직접 돌린 결과를 말하는 건 아니다. 위 명령들은 독자가 자기 컴퓨터에서 직접 확인하라고 제시하는 절차다. 그래서 "성공률 몇 %"처럼 단정하지 않고, 두 데모가 컴파일되는지를 본인이 눈으로 확인하는 게 검증의 핵심이다.

근거 확인

이 글의 모든 명령·파일 이름·단계는 프로젝트의 공개 설명을 기준으로 정리했다. 직접 확인하려면 원문을 참고하면 된다: https://github.com/pedrohcgs/claude-code-my-workflow

다음 판단 기준은 간단하다. 두 데모가 PDF와 HTML로 나오면 환경은 준비된 것이고, 안 나오면 점검 스크립트가 가리킨 도구부터 설치하면 된다.