장기 글쓰기 프로젝트 품질 유지 비법: 보조 에이전트 4개 활용 가이드
2026.06.09
# [Claude Code] 장기 글쓰기 프로젝트 품질을 유지하는 보조 에이전트 4개를 만들었다
## 📝 한줄 요약
여러 권에 걸친 한국어 글쓰기 프로젝트에서, 줄 단위 피드백으로 쌓아 올린 글쓰기 규칙이 후속 권에도 같은 강도로 적용되도록 Claude Code 서브에이전트 4개를 프로젝트 폴더 전용으로 만들었다.
바쁘시면 이것만 읽어도 돼요:
- 사용한 도구: Claude Code 서브에이전트 시스템 (`.claude/agents/`)
- 만든 것: 작성 보조 에이전트 1개 + 자료 검증·grep 점검·중복 탐지 보조 에이전트 3개
- 핵심 판단: 「본문 전체를 자동으로 써 주는 에이전트」는 만들지 않음. 사용자 피드백 루프가 끊겨 품질이 떨어지기 때문
- 적용 범위: 해당 프로젝트 폴더에서만 자동 사용 가능
- 배운 점: 에이전트는 「판단이 필요한 일」보다 「반복 가능하고 기계적인 일」에 적합
## 🎯 이런 분들께 도움돼요
- 한 번에 끝나지 않고 여러 권·여러 챕터로 이어지는 긴 글쓰기 프로젝트를 AI와 진행 중인 분
- 메모리에 규칙이 쌓이고는 있지만 매번 적용을 깜빡하는 분
- Claude Code 서브에이전트를 어떤 작업에 쓸지·어떤 작업에는 쓰면 안 되는지 가늠해 보고 싶은 분
## 😫 문제 상황 (Before)
여러 권으로 구성된 한국어 글쓰기 프로젝트였다. 첫 번째 권의 챕터들을 작성하는 동안 사용자가 줄 단위 피드백을 줬다.
「어색한 어휘 → 자연스러운 표현」, 「모호한 정의 → 정확한 정의」, 「본문에 부적합한 예시 삭제」, 「특정 기호를 본문 서술 안에서 쓰지 말 것」 같은 결정들이 메모리 파일에 수십 개 항목으로 누적됐다.
문제는 후속 권을 쓸 때다. 메모리 파일이 자동으로 컨텍스트에 로드되긴 하지만, 매번 새 챕터를 쓸 때마다 다음 작업을 반복해야 했다.
- 기획서 상세 목차에서 해당 챕터 위치 찾기
- 용어집·문체 가이드·메모리 여러 종 다시 펼치기
- 참고 자료(원전) 직접 읽기
- 초안 작성
- 의무 grep 점검과 마크다운 렌더링 점검을 손으로 돌리기
- 잡힌 줄마다 「회피인지 false positive인지」 직접 판정
같은 작업을 챕터 수만큼 반복할 일이 남아 있었다.
## 🛠️ 사용한 도구
- 도구명: Claude Code (서브에이전트 시스템)
- 모델: Claude Opus 4.7
- 특이사항: 서브에이전트 정의 파일은 마크다운 + frontmatter 형식. 프로젝트 폴더의 .claude/agents/ 아래 두면 그 폴더에서 Claude Code 실행 시 자동 사용 가능
---
## 🔧 작업 과정
### 1. 「전체 자동 작성 에이전트」를 만들지 않기로 한 판단
처음 사용자가 「하네스 에이전트로 만들어서 다음 권 작성에 쓸 수 있을까」라고 물었을 때, 단순한 답은 「가능합니다, 만들겠습니다」였다. 그런데 한 단계 뒤로 물러나서 봤더니 첫 번째 권의 품질이 만들어진 진짜 메커니즘은 사용자의 줄 단위 피드백 루프였다.
```
나머지 권 작성 시에도 첫 번째 권에서 여러 번 검토하면서 정리한 기준과 메모리를 적용하여 동일하게 같은 기준으로 작성하고 검토할 것
```
서브에이전트는 한 번 호출하면 최종 텍스트만 반환하고 그 안에서는 사용자와의 대화가 없다. 「챕터 한 편을 통째로 쓰는 에이전트」를 만들면 메모리에 박힌 수십 개 규칙은 적용되지만, 메모리에 박히지 않은 새 어색함은 한 번에 통과돼 그대로 산출된다. 첫 번째 권 수준의 품질은 안 나온다.
그래서 사용자에게 솔직하게 「자동 작성 에이전트는 권하지 않습니다」를 먼저 말하고, 대신 보조 에이전트 3개를 제안했다.
### 2. 4개 에이전트의 역할 분담 — 무엇을 자동화하고 무엇을 자동화하지 않을지
```
프로젝트 전용으로 해당 폴더에 메인 에이전트와 3개의 서브에이전트 모두 작성해줘
```
사용자가 메인 에이전트도 포함해 4개를 만들기로 결정. 다만 메인 에이전트도 「자체 검증을 통과한 v0 초안」을 만들어 반환하고 사용자 피드백 루프는 메인 대화에서 진행한다는 구조로 설계했다.
| 에이전트 | 무엇을 하는가 | 왜 자동화에 적합한가 |
|---|---|---|
| 작성 보조 에이전트 | 챕터 v0 초안 작성 + 자체 grep 통과 보고 | 기획서·용어집·메모리 규칙·참고 자료 위치를 한 번에 모두 로드해야 하는 사전 준비가 무겁다. 매번 메인 대화에서 하면 컨텍스트 낭비 |
| 자료 검증 에이전트 | 참고 자료 읽고 핵심 정의·수치·인용 가능한 한 줄 추출 | 「자료 그대로 옮길 한 문장」을 뽑는 것은 폐쇄형 작업. 결과만 받으면 됨 |
| grep 점검 에이전트 | 여러 항목 grep 배터리 실행 + 줄별 「회피 / 허용 / false positive」 판정 | 기계적·반복적. 매 챕터마다 손으로 돌리는 게 비효율 |
| 중복 탐지 에이전트 | 새 챕터와 기존 챕터들 사이 개념 중복 탐지 | 한 사람 눈으로 여러 권 전체 교차 점검이 어려움. 에이전트가 잘함 |
대신 다음 작업은 「자동화하지 않기」로 결정했다.
- 챕터 전체를 마무리하는 작업 → 사용자 피드백 루프 끊김
- 메모리에 새 규칙을 박는 작업 → 메인 대화의 판단이 필요
- 사용자 피드백을 어떻게 반영할지 결정하는 작업 → 메인 대화에서 진행
### 3. 프로젝트 전용 vs 사용자 전역 — 위치 결정
사용자가 「이 에이전트는 이 폴더에서만 적용되는 거야? 다른 폴더에서도 가능해?」라고 물었다.
```
| 범위 | 저장 위치 | 적용 범위 |
| 프로젝트 전용 | <현재 폴더>/.claude/agents/<이름>.md | 이 폴더(또는 하위)에서만 |
| 사용자 전역 | ~/.claude/agents/<이름>.md | 이 PC의 모든 프로젝트 |
```
네 에이전트 모두 해당 프로젝트의 참고 자료 경로·내부 규칙·기획서 구조에 강하게 결합돼 있어, 다른 글쓰기 프로젝트에 그대로 적용하면 오히려 방해된다. 프로젝트 전용으로 결정.
폴더가 클라우드에 동기화돼 있으면 다른 기기에서 같은 클라우드로 폴더를 열어도 같은 에이전트가 그대로 따라온다.
### 4. 에이전트 파일 작성
.claude/agents/ 디렉터리를 만들고 4개 마크다운 파일을 작성했다. 각 파일은 frontmatter(`name`, description, tools)와 시스템 프롬프트로 구성. 핵심은 시스템 프롬프트에 다음 내용을 박는 것이었다.
- 어떤 메모리 파일을 어떤 순서로 읽을지
- 출력 양식 (메인 대화가 받아서 그대로 활용할 수 있는 구조화 보고서)
- 무엇을 자동화하지 말지 (예: 작성 보조는 「완성본을 자처하지 않는다」, grep 점검은 「자체적으로 파일을 수정하지 않는다」)
특히 작성 보조 에이전트의 시스템 프롬프트에는 첫 번째 권에서 가장 자주 지적받은 규칙들을 매 문장 점검 항목으로 박았다.
## ✅ 결과 (After)
### Before vs After
| 항목 | Before | After |
|------|--------|-------|
| 새 챕터 작성 사전 준비 | 메인 대화에서 기획서·용어집·메모리·참고 자료 여러 종을 직접 펼침 | 자료 검증 에이전트 한 번 호출로 핵심 인용 한 줄까지 정리된 보고서 받음 |
| grep 점검 | 여러 grep 명령을 손으로 입력하고 줄별 판정도 직접 | grep 점검 에이전트 한 번 호출로 「수정 필요 N건 / 허용 패턴 N건」 표로 보고 |
| 권·Part 사이 중복 탐지 | 사람 눈으로 여러 권 전체 교차 점검 (사실상 불가능) | 중복 탐지 에이전트 한 번 호출로 「개념별 등장 위치 매핑」 |
| 사용자 피드백 루프 | 메인 대화에서 진행 | 그대로 메인 대화에서 진행 (의도된 보존) |
### 결과물
- 프로젝트 폴더 .claude/agents/ 아래 4개 에이전트 파일 생성 완료
- 클라우드 동기화로 다른 기기에서도 자동 사용 가능
- 다음 챕터 작성 시점에 시범 운용 예정
## 💬 이 과정에서 배운 AI 활용 팁
### 효과적이었던 것
1. 「에이전트가 해야 할 일」보다 「에이전트가 하면 안 되는 일」을 먼저 정의 — 자동화의 경계가 분명해진다
2. 출력 양식을 시스템 프롬프트에 박기 — 에이전트가 「그래서 결과를 어떻게 표현할지」 고민하지 않아도 됨. 메인 대화도 받자마자 그대로 쓸 수 있음
3. 메인 에이전트도 「완성본 자처 금지」를 박기 — 자동 작성은 가능하지만 「v0 초안」으로 자체 정의를 좁히면 사용자 피드백 루프가 자연스럽게 유지됨
### 이렇게 하면 안 돼요
1. 「본문 전체를 자동으로 써 주는」 에이전트 만들지 않기 — 메모리에 박힌 규칙은 적용되지만, 새로 발견될 미세 어색함은 그대로 통과돼 품질이 떨어짐
2. 에이전트에게 메모리 갱신 권한 주지 않기 — 새 규칙을 박는 결정은 사용자와 메인 대화의 판단이 필요. 에이전트가 멋대로 규칙을 추가하면 일관성이 깨짐
3. 「판단이 모호한 작업」을 자동화하지 않기 — 같은 기호가 본문 서술인지 표 셀인지처럼 맥락 판단이 필요한 일도 에이전트가 잘하지만, 메인 대화 결정과 다를 수 있다는 점은 감수
## 🌍 다른 업무에 적용한다면?
- 회사 문서 작성 규칙(용어집·문체 가이드)이 누적된 환경에서, 신규 문서마다 grep 점검을 자동으로 돌리는 에이전트
- 법무·계약서 검토에서 「반드시 들어가야 할 조항 목록」을 점검하는 에이전트
- 디자인 시스템에서 컴포넌트 사용 규칙 위반 여부를 점검하는 에이전트
핵심은 「판단 기준이 메모리·문서 형태로 명확히 누적된 분야」에 적합하다는 점이다. 기준이 정리되지 않은 분야에는 에이전트보다 사용자 피드백 루프 자체를 더 자주 도는 편이 빠르다.
## 🚀 앞으로의 계획
- 후속 권의 첫 챕터 작성 시점에 4개 에이전트를 모두 한 번씩 호출해 운용 패턴 점검
- 운용 중 부족한 부분이 발견되면 시스템 프롬프트에 항목을 추가
- 권이 끝날 때마다 중복 탐지 에이전트를 호출해 권 사이 중복 정리
## 📋 재사용 가능한 프롬프트
### 프롬프트 1: 프로젝트 전용 보조 에이전트 설계 요청
> 우리가 진행 중인 프로젝트에서 누적해 온 [메모리 파일 / 규칙 문서] 내용을 적용해야 하는 새 [문서/챕터/컴포넌트]를 작성할 때, 매번 반복해야 하는 [기계적·반복적 작업]이 있어. 이 반복을 줄여 줄 보조 에이전트를 본 폴더 전용(`.claude/agents/`)으로 만들고 싶어.
>
> 다만 [사용자 피드백 루프 / 판단이 필요한 결정]은 자동화하지 말고, [기계적인 점검 / 사전 자료 정리 / 출력 양식 강제] 같은 일만 자동화하는 구조로 설계해 줘.
>
> 어떤 에이전트가 적합하고 어떤 에이전트는 만들지 말아야 할지 먼저 정리해 줘.
### 프롬프트 2: 시스템 프롬프트에 「완성본 자처 금지」 박기
> 이 에이전트는 [작업명]의 v0 초안만 만들어 반환한다. 완성본을 자처하지 않는다. 사용자 피드백 루프는 메인 대화에서 진행되므로, 자체 검증을 통과한 v0 초안 + 통과 보고만 반환하는 역할이다. 새로운 회피 표현이나 규칙을 발견해도 메모리에 박는 것은 메인 대화가 한다. 현재 메모리를 그대로 적용한다.
### 프롬프트 3: grep 점검 에이전트에게 판정까지 시키기
> 매칭 0건은 통과로 보고. 매칭이 있으면 한 줄씩 직접 Read로 확인 후 「회피 패턴 / 허용 패턴 / false positive」 세 가지로 판정. 절대 판정 없이 grep 결과만 던지지 않는다. 판정 없이 던지면 메인 대화가 매번 다시 판정해야 한다.




지난 글들에서 역할 분리와 개인 지식층을 계속 쌓아오신 흐름이 있었는데, 이번 글은 그걸 장기 글쓰기 프로젝트의 “작은 편집실”로 바꾼 사례처럼 읽혔어요. 특히 좋았던 건 에이전트를 더 많이 붙인 게 아니라, 무엇을 자동화하지 않을지를 먼저 정하신 점이었습니다.
본문 전체를 써주는 에이전트를 만들 수도 있었을 텐데, 첫 번째 권의 품질을 만든 핵심이 줄 단위 사용자 피드백 루프였다고 보고 그 루프를 일부러 남겨둔 판단이 되게 중요해 보여요. 작성 보조는 v0 초안까지만, 자료 검증은 근거 추출까지, grep 점검은 줄별 판정까지, 중복 탐지는 개념 위치 매핑까지 맡기는 식으로 역할을 자른 것도 명확했습니다.
저는 이 글의 포인트가 “Claude Code 서브에이전트를 만들었다”보다 “사람이 판단해야 할 일과 에이전트가 반복적으로 지켜줘야 할 일을 분리했다”에 가깝다고 느꼈어요. 프로젝트 전용
.claude/agents/로 둔 것도 좋은 선택 같아요. 특정 기획서, 문체 가이드, 원전 자료, 메모리 규칙에 묶인 에이전트라면 전역으로 퍼뜨리는 것보다 해당 폴더 안에서만 작동하게 하는 편이 훨씬 안전하니까요.후속 권 첫 챕터에서 실제로 돌려보실 때는 각 에이전트별로 “막아준 문제 / 못 막은 문제 / 사람 판단으로 남긴 문제”만 한 줄씩 남겨도 좋을 것 같아요. 그러면 지금 만든 4개 에이전트가 단순 편의 기능이 아니라, 장기 프로젝트 품질을 유지하는 운영 규칙으로 더 빨리 안정화될 것 같습니다.
기수 운영 하시느라 고생 하셨습니다.
너무 인상적이였습니다.