4월 초, 나는 Claude Code를 「AI가 써주는 편리한 도구」로서 사용하기 시작했다. AI 에이전트 (AI Agent)를 접하는 것은 그것이 처음이었다. 2개월 후인 지금, 나는 Claude Code를 「에이전트 편집부를 움직이는 지시역」으로 사용하고 있다.

전환점은 CLAUDE.md에 writer/reviewer/reader라는 몇 줄을 적은 순간이었다. 그것만으로 Claude Code와의 관계성이 근본적으로 변했다. 이 2개월 동안 프로젝트의 커밋 (Commit) 수는 2,185건에 달했고, 기사 파일은 132개(아카이브 7개 포함. 우리 쪽은 Hatena 공개 완료 100개, Zenn 투고 완료 41개)가 되었다.

본 기사는 Zenn Fes의 「이번 봄에 시작한 일」 테마에 대한 응모작입니다.

이 기사의 실시 기록 (2026년 4월~6월): Claude Code를 4월 초부터 사용하기 시작하여, 약 2개월 만에 Zenn Book 3권을 썼다. 전환점은 CLAUDE.md에 writer/reviewer/reader라는 역할을 적은 몇 줄이었다. 프로젝트 시작 이후의 커밋 수는 2,185건, 기사 파일 수는 132개(아카이브 7개 포함. 우리 쪽은 Hatena 공개 완료 100개, Zenn 투고 완료 41개).

2개월 만에 쓴 Zenn Book 3권

이 2개월 동안 Zenn Book을 3권 썼다.

Vol.1 「코드를 못 쓰는 내가 Claude Code로 『AI 팀』을 만들기까지」

코드를 작성하지 않는 내가 Claude Code로 9체의 AI 에이전트 팀을 만들어 나가는 실록. 첫 10일 만에 원형이 만들어졌고, 그 체험을 적었다.

Vol.2 「코드를 못 쓰는 내가 Claude Code로 『AI 팀』을 운영하기까지」

팀을 「만드는 것」과 「운영하는 것」은 별개의 기술이라는 것을 깨달은 기록. 플레이북 (Playbook)・위임 프로토콜 (Delegation Protocol)・품질 게이트 (Quality Gate)의 3층 구조를 다루고 있다.

Vol.3 「코드를 못 쓰는 내가 Claude Code로 『AI 팀』과 계속 써 내려가기까지」

팀이 움직이게 된 이후의 「그렇다면, 무엇을 계속 써 내려갈 것인가」라는 질문에 대한 기록. 안테나 모델 (Antenna Model)로의 전환, 소재 노트 설계, 4단계 루프 (준비하기→쓰기→전달하기→회수하기)를 다루고 있다.

3권에서 다룬 테마는 실제로 이 2개월 동안 경험한 것을 그대로 적은 것이다. Vol.1을 다 썼을 시점에 Vol.2의 테마가 생겨났고, Vol.2를 다 썼을 시점에 Vol.3의 테마가 명확해졌다. 테마가 먼저 있었던 것이 아니라, Claude Code를 사용하는 과정에서 자연스럽게 생겨난 것이다.

전환점: 「직접 쓰는 것」에서 「지시하는 쪽이 되는 것」까지

첫 2주 동안은 Claude Code에게 「이 내용으로 기사를 써줘」라고 직접 부탁했다. 지시를 내리면 AI가 쓰고, 내가 수정한다. 그 사이클을 반복하고 있었다.

전환점은 CLAUDE.md에 에이전트의 역할을 적었을 때였다.

여기서는 내가 사용하고 있는 writer/reviewer/reader라는 이름을 예로 들지만, 이것은 저자의 편집부적인 용도에 맞춘 이름이며, 코드 리뷰어 (Code Reviewer) 역할 에이전트나 테스트 실행 에이전트 등 자신의 용도에 맞춰 자유롭게 교체할 수 있다.

## 에이전트 조직
COO ─── 오케스트레이션 (Orchestration)
├── researcher ── 조사・분석
...

에이전트에게 역할을 명시하여 Claude Code를 호출하는 것만으로 움직임이 바뀌었다. writer는 집필에 전념하고, reviewer는 사실 확인을 수행하며, reader는 독자 관점에서 감정 리뷰를 한다. 나의 역할은 「무엇을 쓸 것인가」를 결정하는 것과 각 에이전트의 출력을 최종 판단하는 것으로 좁혀졌다.

「직접 쓰는 것」에서 「지시하는 쪽이 되는 것」으로의 전환은, 도구의 사용법이 변했다기보다 Claude Code와의 관계성이 변했다고 표현하는 것이 더 정확하다.

조직으로서 움직이는 감각

현재의 집필 플로우는 다음과 같다.

• ネタ장 (researcher): 웹 리서치와 데일리 리포트를 통해 기사 소재를 수집. 매일 아침 자동으로 실행되는 리서치 에이전트가 관심 영역의 트렌드를 스캔하여ネタ장(researcher)에 쌓아둔다.
• 집필 (writer): ネタ장과 지시 사항을 전달받아 원고를 작성. 1인칭은 「私(나)」로 고정하며, 구성 규칙은 Playbook에 기재되어 있다.
• 팩트 체크 (reviewer): 수치, 고유명사, URL의 사실 여부를 확인한다. 사실과 의견을 구분하여 작성했는지, 인용의 정확도가 높은지 확인한다.
• 감정 리뷰 (reader): 예상 독자 페르소나로서 원고를 읽고, "여기서 이탈할 것 같다", "이 숫자의 근거가 불안하다"와 같은 피드백을 반환한다.
• 공개 (COO): Hatena Blog, Zenn, Qiita로의 크로스 포스팅을 CLI 스크립트로 실행.

이러한 분업은 내가 처음부터 설계한 것이 아니다. "자주 발생하는 지적 패턴"을 반복해서 Playbook에 추가해 나가는 과정에서 자연스럽게 이 형태가 되었다.

품질 게이트(Quality Gate)는 세 가지 축으로 보고 있다. "사실 정확성 (팩트 체크)", "독자 경험 (감정 리뷰)", "구조 및 재현성 (라이팅 가이드라인 준수)"의 세 지점을 확인하여, 일정 기준을 충족한 기사만을 공개한다. 게이트를 통과하는 것 자체가 목적은 아니다. "왜 이 부분이 걸렸는가"에 대한 지적 패턴을 축적함으로써 라이팅 가이드라인이 성장해 나간다.

ネタ장은 현재 158개가 있다 (2026-06-02 실측). 기사 파일은 132개 (아카이브 7개 포함. Hatena 공개 완료 100개, Zenn 투고 완료 41개). Rate Limit(속도 제한) 때문에 모든 기사를 Zenn에 투고할 수 있는 것은 아니지만, 이 정도 규모의 관리를 나 혼자 하는 것은 어렵다. 에이전트들이 역할을 분담하여 관리하고 있기 때문에 유지할 수 있는 것이다.

예기치 못한 일: 사고가 시스템을 단련시켰다

순조롭기만 했던 것은 아니다. 가장 큰 사고는 blogsync와 관련된 것이었다.

Hatena Blog에 기사를 공개할 때는 blogsync라는 도구를 사용하고 있었다. 5월에 들어서면서 블로그 기사의 커스텀 URL이 의도치 않게 바뀌는 사고가 여러 차례 발생했다. 처음에는 4개의 기사 URL이 변경되어, 기존의 SNS 공유 링크나 검색 엔진의 인덱스가 무효화되었다. 같은 사고가 형태를 바꾸며 4번 반복되었다.

4번째 사고 이후, 근본적인 해결책을 선택했다. blogsync에 대한 의존을 완전히 끊고, Hatena Blog의 AtomPub API를 직접 호출하는 CLI를 직접 구현했다. 5월 30일에 blogsync 완전 제거가 완료되었고, 그 이후로 URL 변경 사고는 제로가 되었다.

이 경험을 통해 배운 것은 "사고는 시스템의 개선 트리거(Trigger)가 된다"는 것이다. 매번 발생하는 사고는 logs/governance-incidents/에 인시던트(Incident) 파일로 기록된다. 재발 방지책은 CLAUDE.md의 규칙에 추가된다. 사고를 반복할 때마다 거버넌스(Governance) 체계가 구체화되었다.

2개월 전에는 CLAUDE.md에 16줄밖에 적혀 있지 않았다 (프로젝트 시작 시점의 git 히스토리로 확인). 지금은 수백 줄의 규칙, Playbook, 트리거 리스트가 존재한다. 이것은 계획하여 설계한 것이 아니라, 사고와 개선을 반복한 결과로서 쌓아 올린 것이다.

비용 측면도 솔직하게 적는다. Anthropic과 Claude Max 플랜을 계약하고 있다. 월 $100 플랜이다. 일반적인 Claude 사용 방식(개인 이용, 채팅 중심)이라면 $20인 Pro 플랜으로도 충분하지만, 본 기사와 같이 여러 에이전트를 상시 가동하는 제작 규모에서는 Max 플랜이 현실적이라고 판단했다.

Claude Code를 사용하기 시작한 사람을 위한 다음 단계

Claude Code를 사용하기 시작한 사람에게 "다음 단계"로서 권하고 싶은 것이 하나 있다.

CLAUDE.md에 에이전트의 역할을 적는 것, 그것만으로 충분하다.

구체적으로는 프로젝트 루트의 CLAUDE.md에 다음과 같은 기술을 추가한다.

## 에이전트 조직
이 프로젝트에서는 다음과 같은 역할을 가진 에이전트를 구분하여 사용한다.
- **reviewer**: 사실 확인, 수치 검증, 출처 체크를 담당한다.
...

이렇게 작성한 후 Claude Code에 "reviewer로서 다음 원고를 체크해줘"라고 지시하면, 역할의 문맥(Context)을 가진 답변이 돌아온다. 처음에는 3줄이면 된다. "내가 무엇을 시키고 싶은가"가 명확해짐에 따라 자연스럽게 상세해질 것이다.

"너무 복잡하다"고 느낄지도 모른다. 나도 그렇게 느꼈다. 하지만 처음에는 3줄이면 된다. 지금의 형태가 되기까지 2개월이 걸렸다. 한꺼번에 설계하기보다, 사용하면서 키워 나가는 것이 현실적이며 사용법에 맞는 규칙이 만들어진다.

역할 분담을 명시하면 Claude Code에 지시를 내리는 방식도 달라진다. "뭐든지 해줘"보다는 "reviewer로서 수치의 근거를 확인해줘"라고 하는 편이 출력의 질이 안정된다. 모호한 지시를 내리기보다 역할과 문맥을 먼저 전달하는 것이 더 좋은 결과로 이어진다.

이것이 내가 이번 봄, Claude Code를 사용하며 발견한 점이다.

이번 봄을 지나며

2개월 전의 나는 "AI에게 써달라고 하기"를 시작했다. 2개월 후의 나는 "AI 팀에게 지시하기"가 일상이 되어 있었다. 시작하는 것과 지속하는 것은 별개의 기술이며, 지속하는 것과 이를 시스템화(仕組み)하는 것 또한 별개라는 사실을 이번 봄에 처음으로 실감했다. CLAUDE.md의 몇 줄이 기점이 되었고, 사고(incident)가 시스템을 단련시켰으며, 시스템이 계속해서 써 내려갈 수 있는 토대가 되었다. "이번 봄에 시작한 일"이라는 테마에 대한 나의 대답은, 도구를 사용하기 시작한 것이 아니라 시스템을 키우기 시작한 것이다.

이번 봄에 쓴 Zenn Book 3권

• Vol.1 「코드를 못 쓰는 내가 Claude Code로 「AI 팀」을 만들기까지」 (서장·제1부는 무료 공개)
• Vol.2 「코드를 못 쓰는 내가 Claude Code로 「AI 팀」을 운영하기까지」 (서장은 무료 공개)
• Vol.3 「코드를 못 쓰는 내가 Claude Code로 「AI 팀」과 계속 써 내려가기까지」 (서장은 무료 공개)

관련 기사

• CLAUDE.md에 에이전트의 역할을 적은 이야기 — 전환점이 된 한 줄의 배경
• 매일 아침 자동 실행되는 리서치 에이전트를 만들었다 — 데일리 리서치 자동화 시스템
• 거버넌스(Governance) 시스템을 어떻게 키웠는가 — 사고와 규칙 진화의 사이클
• 품질 게이트(Quality Gate) 3축 설계 — reviewer/reader/SEO의 운용 상세
• 플레이북(Playbook)·트리거 리스트란 무엇인가 — CLAUDE.md 헌법의 구조
• Claude Code 블로그 집필 하네스(Harness)를 템플릿화한 이야기 — 집필 기반을 다른 블로그에도 전용한 사례

이 기사는 はてなブログ(Hatena Blog)로부터의 크로스 포스트입니다.

Discussion