Claude Code의 새로운 실험, 자동화, 프레젠테이션, 에이전트 연동 등 다양한 실전 활용기를 다루는 개발자의 도구 실험기.
나는 claude code를 나와 팀원들이 사용할 수 있도록, 멋진 사용법 개요 글을 쓸 계획이었다. 하지만 직접 이것저것 실험해볼수록 점점 더 흥미로워졌다. 그래서 이 글은 claude code 입문서가 아니다. 그건 Anthropic에서 이미 훌륭하게 정리했다. 대신:
우리는 진지한 과학(Serious Science™)을 해볼 것이다.
정확히 무슨 뜻이냐고? 일부는 유용하고, 일부는 좀 더... 실험적이다.
"가끔 과학은 예술에 더 가깝다, Morty. 많은 사람들이 그걸 이해 못하지." - Rick Sanchez
덧붙여, 이번 프로젝트는 결코 저렴하지는 않다. 나는 한 달에 $250짜리 Claude Max를 쓴다. 불태울 수 있는 돈의 범위는 각자 결정하시라.
그래도 더 이상 시간을 낭비하지 말자…
새로운 도구를 쓸 때 가장 어려운 부분 중 하나는, 뇌를 "새로운 가능성"에 맞춰 다시 훈련하는 것이다. 이제까지 새로운 코드베이스에 온보딩하는 일은 늘 골치 아픈 일이었다. 문서를 읽고, 동료랑 페어 프로그래밍 하고, grep으로 코드베이스를 샅샅이 뒤지며 조금씩 적응해왔다. 하지만 이런 새로운 툴들은 황당하고 신박한 아이디어의 세계를 연다.
예를 들어, claude code를 marp와 함께 쓸 수 있다.
그래서, 그게 뭐냐고…?
아이디어는 이렇다 — claude code가 코드베이스를 분석해 그 내용을 CODEBASE.md에 정리하게 한다. 다 끝나면, 그 결과를 PRESENTATION.md로(마프 형식, 즉 슬라이드용) 변환하도록 시킨다. 마지막으로 marp PRESENTATION.md를 돌리고, open PRESENTATION.html 하면,
짜잔! 이제 코드베이스 설명 슬라이드 덱이 생긴다.
더 대단한 건, 이걸 claude code 명령어로 만들어두면, 우리 팀 누구나 /onboard만 쳐서 즉시 최신화된 슬라이드 덱을 받을 수 있다는 사실이다. 신박하지 않은가?
간단한 버전을 직접 해보고 싶다면:
$ brew install marp-cli
$ claude --dangerously-skip-permissions # 과학자 모드
> "rust borrow checker를 설명하는 마프 형식의 PRESENTATION.md(슬라이드용)를 생성해 줄 수 있니?"
$ marp PRESENTATION.md # PRESENTATION.html 생성
$ open PRESENTATION.html
이게 대규모 코드베이스에도 통하냐고? 아마 아닐 거다. 현실적으로 엄청난 분량의 컨텍스트를 처리해야 하고, claude code는 자동으로 내부적으로 /compact를 돌릴 것이다. 시간이 지나면 결과물의 정확도·성능이 점점 떨어질 가능성도 크다. 반대로, 각 디렉터리별로 병렬화하면? 누가 알겠는가!
# .src/ 디렉터리의 모든 `*.py` 파일에 적용하는 간단한 예시
# claude 설치 경로에 따라 명령어를 바꿔야 할 수도 있음
$ find ./src -name '*.py' -print0 | xargs -0 -n1 -P4 $HOME/.claude/local/claude -p "3 ways to improve @'{}'"
이제 에이전트 스크립팅이 된다
claude code는 cursor보다 더 강력해보인다. 그 이유 중 하나는, "스크립팅"이 가능하다는 점. 결국 cursor는 에디터에 가깝고, claude code는 (과장해 말하면) 스위스 군용 칼 같다.
다른 예를 들어보자 — 월요일 아침, 커피를 내리면서 컴퓨터에 가서 ./last_week.sh를 실행한다. 이 스크립트는 claude code로 레포의 지난 일주일 변경사항을 분석, 리포트를 만들어주고, 텍스트-투-스피치로 요약해 읽어준다. 멋지지 않은가? 실제로 그렇다!
# 이번 데모에는 새로 나온 `claude-code-sdk-python`을 씀
# claude code를 파이썬에서 래핑해준다
# [url]: https://github.com/anthropics/claude-code-sdk-python
# GitHub의 `gh` CLI가 필요함
$ gh repo clone anthropics/claude-code-sdk-python
# claude code를 헤드리스 모드로 실행
# 사용도구를 명시적으로 넘겨줘야 함
$ claude -p "Can you summarize the last week of changes in this repository? In particular, focus on the most edited, new and deleted files. Please consult the diffs not just the commit messages. Lastly, can you write the results to last_week.md. Please construct the summary as a narrative versus a mere repetition of facts." --allowedTools "Bash(git log:*)" "Bash(git diff:*)" "Write"
# 여기에선 맥에 기본 있는 `say` 명령어로 결과를 읽어줌 (작성자는 리눅스를 씀)
# 최신 STOA TTS로 바꿔도 됨
$ cat last_week.md | say
$ rm last_week.md
# Claude Code SDK Python: 탄생과 다듬음의 한 주간
이번 주는 Claude Code SDK for Python의 창세를 알리며, 초기 커밋과 함께 전체 아키텍처를 일거에 구축하는 야심찬 첫 시작과 함께 견고한 기반을 마련하기 위한 꼼꼼한 손질이 이어졌다.
## 기반 다지기
6월 16일 리포지토리 생성과 동시에 전체 SDK를 한 번에 가져오는, 22개 파일 1,774라인의 대규모 커밋이 이루어졌다. 이는 뼈대만이 아니라 기능 전체를 구현한, 완성된 SDK였다. 주요 내용은:
- **핵심 SDK 파일**: 메인 구현부(`src/claude_code_sdk/` 하위)와 subprocess CLI 통신을 위한 내부 트랜스포트 계층(`_internal/transport/subprocess_cli.py`), 광범위한 에러 핸들링, 전체 테스트 스위트를 포함
- **테스트 모듈**: 유닛부터 통합 테스트까지 5개 모듈을 통해 품질을 초기에 확보
- **CI/CD 흐름**: 린트, 테스트, 배포를 위한 GitHub Actions 3개 구성으로 유지보수성과 안정성에 초점을 맞춤
- **개발자 경험**: 빠른 시작 예제(`examples/quick_start.py`)와 자세한 README로 사용자 가치 제공
## 다듬음 단계
초기 임포트 이후엔 코드 포매팅 등 8개 파일 손질에 집중, import 구문 정리, 공백, 스타일 유지 등 협업 및 가독성 증진을 위해 주력했다. 특히 테스트 모듈의 assert문·구조 재정렬, 운반 계층 소폭 손질 등 유지관리성과 명료성 확보에 힘썼다.
## 신뢰성 강화
마지막 커밋은 CI 안정성 확보였다. Codecov 업로드 실패가 테스트를 막지 않도록 워크플로 변경 – 실제 운영경험이 배어있는 조치이다.
## 한 주간 돌아보기
이 7일간 단순히 코드만이 아니라, Claude Code와 상호작용하는 깔끔하고 현대적인 Python SDK의 탄생이 이루어졌다. 타입 힌트, 체계적 에러 처리, 외부 API와 내부 구현의 분리가 돋보인다. 추상화된 운반 계층 등 향후 확장성도 고려했다. 1일차부터 유닛·통합 테스트가 갖춰진 점도 인상적이다.
이 한 주는 Claude Code 생태계에, 파이썬에서 자연스럽게 강력한 기능을 쓸 발판을 놨다.
셰익스피어급은 아니지만, 새 프로젝트 개요론 괜찮은 수준이다. 더 다듬으면 더 명확하고 생기있게 만들 수도 있을 것이다.
claude code의 에이전트적 코딩 능력에 대한 이야기가 많았다. 하지만 실제론 그게 표면일 뿐이다. 앞선 두 기법은 출력을 텍스트→프레젠테이션·음성 등으로 바꾼 것이지만, 그뿐이 아니라…
whisper, 스크린샷, ffmpeg 등을 합치면 claude code가 [약간 수상한] 영상 편집기도 될 수 있지 않을까?
또 다른 흥미 포인트는 서브-에이전트 개념이다. Amp code가 이 패턴을 잘 설명한 글을 최근에 공개했다. claude code도 비슷한 기능(아마 하이쿠 모델 활용) 지원하지만, 우리는 그것대신 좀 탈선해서 이중화로 실험한다.
claude code가 주목받는 와중에 OpenAI도 자체 CLI 툴 codex를 공개했다. 오픈소스고, 곧 러스트 버전도 나온다. STOA(o3, o3-pro) 모델도 접속 가능하다.
그럼 Anthropic 서브-에이전트 대신 codex로 바꿔보면?
먼저 CLAUDE.md에 codex 호출법을 명확히 써둔다:
## 명령어
- codex로 서브에이전트에게 태스크를 위임할 수 있다
- 에이전트 호출법: `codex -q -a full-auto "<task description>"`
codex는 기본적으로 모든 도구를 쓸 수 있고, claude code는 헤드리스 모드에선 도구 권한을 명시적으로 줘야 한다. (모든 권한을 ~/.claude/settings.json에서 수동으로 줄 수도 있다. 참고)
# 현 작업 디렉터리: $HOME/Desktop/claude-code-sdk-python
$ claude --dangerously-skip-permissions # 과학자 모드
# 예전에는 직접 입력 안 해도 codex를 써줬지만, 재현 위해 명시적 입력
> "서브에이전트로 @src/ 최상위 파일 모두를 분석해 개선점 3가지씩 제안하게 할 수 있니? codex를 써줘."
약간 요령이 필요하지만, 동작한다.
이 아이디어를 확장하면 매력적이다. 예를 들어 서로 다른 연구소의 에이전트를 쓰는 것. Anthropic, OpenAI, 그리고 (아직 CLI는 아니지만) Google의 Jules까지 섞을 수도 있을 것이다.
토큰 측면에선 바보짓이나, 평가 실험으로는 흥미롭다. 메인 에이전트가 심판(판정용 LLM)처럼 움직이는 구조다.
또한 얼마나 깊이 재귀적으로 서브에이전트 호출할 수 있는지 실험해보고 싶다.
한계도 명확하다. 토큰 용량: codex는 매 동작마다 대량의 텍스트를 내보낸다. 이론상 -q --quiet로 비활성화 가능하지만, 지금은 작동 안 한다(환경변수 CODEX_QUIET_MODE=1도 마찬가지).
다시 말하지만, 토큰 소모가 정신나갔고, OpenAI/O3(요즘 값 싸짐!)에도 돈을 내고 있다.
실제로 쓸모가 있냐고? 아마 별로.
하지만 한 LLM이 다른 LLM의 답을 평가하게 하는 실험으론 흥미롭다.
모델이 다른 에이전트로 구성된 팀으로 확장하면 더 비용효율적인 협업·병렬작업도 기대된다.
꽤 정신없는 여정이었지만, 무언가 새로운 생각거리가 되었길 바란다. claude code에는 아직 미개발된 잠재력이 많다. 게다가 파이썬 SDK 출시 덕분에, 더 기상천외한 활용법도 곧 등장하리라 본다. 앞으로 사람들이 얼마나 기발하게 사용법을 개척할지 기대된다.