문서 22기 자동화 4주차 스터디 자료 기반으로 새로운 문서 자동화 시작해보기

이건 22기 문서 자동화

클로드 코드 하네스
gpters 스터디 사례게시글이야


핵심 인사이트를 뽑을 수 있는대로 뽑아서 정리해줘

지피터스(GPTers) 22기 문서 자동화 스터디의 다양한 사례들에서 도출된 핵심 인사이트를 4가지 주요 테마로 정리해 드립니다. 단순한 '작성 자동화'를 넘어, 품질을 보장하고 실무에 즉시 적용할 수 있는 **'시스템적 접근법'**이 공통으로 강조되고 있습니다.

### 1. 결과물이 아닌 '시스템'을 교정하라 (파이프라인 설계)
* **산출물이 아닌 원칙을 수정:** AI가 만든 결과물에서 오류를 발견했을 때, 그 문서만 수동으로 고치면 다음번에도 같은 실수가 발생합니다. 오류를 발견하면 시스템 설정 파일이나 프롬프트에 규칙(Lint)을 추가하여 이후 생성되는 모든 산출물에 자동 반영되도록 해야 합니다.
* **통짜 지시 금지, 단계별 쪼개기:** "제안서 써줘"와 같은 포괄적인 지시 대신, [분석 → 전략 도출 → 초안 작성 → 검토]처럼 워크플로우를 작은 단위로 쪼개고 각 단계를 순차적으로 실행해야 품질이 보장됩니다.
* **적절한 '사람의 통제(Human-in-the-loop)' 개입:** 모든 것을 자동화하려 하지 말고, 다음 단계로 넘어가기 전 반드시 사람이 방향성을 승인하는 '게이트(체크포인트)'를 두어야 합니다. 방향이 어긋난 채로 끝까지 자동화되는 것을 막아줍니다.

### 2. 좋은 결과는 완벽한 '자산(Input)'에서 나온다
* **지식베이스(내부 위키)의 중요성:** AI가 똑똑한 답변을 내놓는 이유는 AI 자체의 능력보다, 사용자의 정체성, 이력, 회사 소개, 고객 페르소나 등이 한 곳에 완벽하게 정리되어 있기 때문입니다. 옵시디언(Obsidian) 등을 활용해 파일명만으로도 분류가 가능하도록 지식을 구조화하는 것이 중요합니다.
* **이유와 배경을 함께 학습시키기:** AI에게 단순히 "A는 B라고 쓰지 마"라는 금지 규칙만 주면 규칙이 흐릿해집니다. "왜 그런 규칙이 필요한지(예: 전문성을 의심받기 때문)" 배경을 함께 설명해야 AI가 원칙을 제대로 내재화합니다.

### 3. AI를 '작성자'가 아닌 '비판자(Critic)'로 활용하라
* **평균 점수보다 '이견' 찾기:** 델파이 기법을 적용해 단일 AI가 아닌 여러 AI(API, 페르소나)에게 독립적인 평가를 맡기고, 평균 점수보다는 평가자들 사이에서 '의견이 갈리는 애매한 지점'을 찾아내는 것이 문서 고도화의 핵심입니다.
* **다관점 레드팀 운영:** 심사위원, 경쟁사, 고객 등 구체적인 페르소나를 부여해 가설을 검증하고, 문서의 약점을 집요하게 공격하게 만들면 사람이 놓친 허점을 잡아낼 수 있습니다.
* **환각(Hallucination) 방지 장치:** AI가 내용을 보강할 때 존재하지 않는 사실을 지어내지 못하도록, 확실치 않은 근거는 임의로 작성하지 말고 반드시 **"[검증 필요]"**라고 별도 표시하도록 프롬프트에 강제해야 합니다.

### 4. 도구 최적화 및 문제 해결(Troubleshooting) 전략
* **도구의 강점에 따른 역할 분담:** 하나의 도구로 모든 것을 해결하려 하지 마세요. 클로드(Claude)는 구조 설계와 논리 다듬기에, 노트북LM(NotebookLM)은 다량의 소스 기반 리서치에, 파이썬/구글 슬라이드 등은 시각화나 문서 포맷팅에 특화되어 있습니다.
* **"고쳐줘" 대신 "왜 그런지 원인을 찾아줘":** 코딩 자동화(Claude Code 등) 중 에러나 성능 저하가 발생했을 때, 무작정 수정해 달라고 하기 전에 코드를 읽고 원인이 무엇인지 먼저 파악하게 하면 훨씬 빠르고 정확하게 문제를 해결할 수 있습니다.
* **공식 서식(HWPX, PDF 등)의 구조적 제어:** 한글(HWPX)과 같은 공식 서식에 맞게 문서를 자동화할 때는 단순 텍스트 치환이 아니라 XML 문단 편집 등 원본의 구조와 스타일 ID를 그대로 유지하면서 데이터를 넣어야 서식이 깨지지 않습니다.

**💡 총평 요약:** 
가장 성공적인 문서 자동화 사례들의 공통점은 **"품질이 먼저, 자동화는 그다음"**이라는 점입니다. 글을 대신 써주는 마법 버튼을 찾는 것이 아니라, 기획-분석-작성-비판-검증으로 이어지는 '좋은 문서가 만들어지는 업무의 구조' 자체를 AI 파이프라인으로 구현해 내는 것이 핵심입니다.

지피터스(GPTers) 22기 문서 자동화 스터디 사례에서 도출된 핵심 인사이트를 요청하신 대로 **12가지**로 세분화하여 정리해 드립니다.

**1. 산출물이 아닌 '시스템'을 교정하라**
오류가 발생했을 때 생성된 문서(결과물)만 수동으로 고치면 다음번에도 같은 실수가 반복됩니다,. 오류나 주의사항을 문서 본문에 남기지 말고, 시스템 설정 파일(프롬프트나 규칙)에 반영하여 이후 생성되는 모든 문서에 자동 적용되게 만들어야 합니다,.

**2. 자동화의 질은 '완벽한 지식베이스(자산)'가 결정한다**
AI가 뛰어난 분석과 제안을 내놓는 이유는 사용자의 정체성, 회사 소개, 고객 페르소나, 주요 이력 등이 한 곳에 잘 구조화되어 있기 때문입니다,. 폴더명이나 파일명만으로도 내용 분류가 가능하게끔 지식베이스(예: 옵시디언)를 구축해 두는 것이 자동화의 8할을 차지합니다,.

**3. 통짜 지시 대신 '단계별 쪼개기'와 '사람의 통제(게이트)'를 설계하라**
"문서를 써줘"라고 한 번에 지시하는 대신 기획 → 리서치 → 취합 → 장표 구성 등 5~11단계로 워크플로우를 잘게 쪼개야 합니다,. 특히 각 단계가 넘어갈 때마다 사람이 직접 방향성을 확인하고 승인하는 체크포인트를 두어야 AI가 엉뚱한 방향으로 폭주하는 것을 막을 수 있습니다,,. 

**4. '글을 써줘'가 아니라 '구조를 설계해줘'로 시작하라**
처음부터 내용 작성을 요구하기보다, "전체 프로세스 구조를 설계해 줘" 혹은 "평가 기준을 먼저 구조화해 줘"라고 요구하는 것이 훨씬 효과적입니다,. 기획과 뼈대가 잘 잡혀야 빈틈없는 산출물이 나옵니다.

**5. AI에게 규칙의 '이유와 배경'까지 함께 학습시켜라**
AI에게 단순히 "A는 B라고 쓰지 마"라는 단편적 금지 규칙만 주면 규칙이 금방 흐릿해집니다,. "이 부분은 전문성을 의심받을 수 있으니 쓰지 마"처럼 도메인 상식과 배경을 함께 설명해야 AI가 원칙을 명확히 내재화합니다,.

**6. 단일 점수보다 여러 평가자 사이의 '이견'을 찾아라**
문서를 평가할 때 단일 AI 모델에 의존하면 그 모델의 편향이 개입될 수 있습니다. 서로 다른 관점을 가진 여러 AI나 API를 독립적으로 평가에 참여시킨 뒤, 평균 점수보다는 '평가자들 사이에서 의견이 갈리는 애매한 지점'을 찾는 것이 문서 품질 고도화의 핵심입니다,,.

**7. 다관점 비평(Red Team/Critic)을 적극 활용하라**
완성된 초안은 심사위원, 경쟁사, 고객, 리스크 담당자 등 다양한 페르소나를 부여한 AI '레드팀'에게 다각도로 비판받게 하세요,,,. 사람이 놓칠 수 있는 맹점이나 치명적인 약점을 찾아 우선순위(A/B/C/D급)를 매겨 보완할 수 있습니다.

**8. 환각 방지를 위해 '[검증 필요]' 표시를 강제하라**
AI에게 내용을 보강하게 하면 존재하지 않는 참고문헌이나 사실을 지어낼 위험이 큽니다. 이를 막기 위해 확실하게 검증되지 않은 근거는 임의로 작성하지 말고 반드시 **"[검증 필요]"**라고 별도 표시하도록 프롬프트로 강제하여, 최종 제출 전 사람이 확인할 수 있도록 안전장치를 만들어야 합니다,.

**9. 도구별 강점에 맞춰 역할을 분리하라**
하나의 도구가 모든 것을 완벽하게 해낼 수는 없습니다. 구조 설계와 논리 교정은 클로드(Claude)에게, 다량의 소스 리서치와 요약은 노트북LM(NotebookLM)에게, 시각화나 문서는 구글 슬라이드/파이썬에 맡기는 식으로 도구별 강점을 조합하는 것이 유리합니다,.

**10. 코딩 자동화 시 "고쳐줘" 전에 "원인을 찾아줘"라고 질문하라**
에러나 성능 저하가 발생했을 때, 무작정 수정해 달라고 하기보다는 AI에게 먼저 코드를 읽게 하고 "왜 느린지 혹은 왜 에러가 나는지 원인을 찾아줘"라고 질문하세요,. 진단이 정확하면 해결책도 훨씬 빠르고 정확하게 도출됩니다.

**11. 한글(HWPX) 등 공식 서식의 형태는 '텍스트'가 아닌 '구조'로 제어하라**
정부 사업이나 공공기관 제출용 공식 빈 서식을 채울 때 텍스트만 치환하면 양식이 깨지기 쉽습니다. 서식 구조를 유지하려면 XML 문단 편집, 테두리, 스타일 ID 등을 분석하고 그대로 재사용하는 방식을 활용해야 합니다,. 

**12. 해결 방향이 여러 개일 땐 한 번에 묶어서 지시하라**
문제 해결을 위해 여러 개선 사항을 적용해야 할 때, 하나씩 순서대로 지시하지 말고 "A, B, C를 모두 반영해 줘"처럼 방향을 묶어 한 번에 지시하면 AI가 맥락을 이해하고 관련 파일에 동시 반영하여 속도와 효율이 크게 올라갑니다,.

이러한 인사이트를 바탕으로 새로운 프로젝트를 진행하려고 해


'동기부여'를 해주는 만능 글쓰기 에이전트를 만들고 싶은데


클로드 코드 하네스 구조로 만들고 싶어 그리고 에이전트를 최소 5개로 구성하고 싶은데


자세한 진행방법과 claude.md, claude에게 명령할 내용 등을 알려줘


클로드 코드로 할거야

제안하신 **'동기부여 만능 글쓰기 에이전트'**는 스터디에서 도출된 핵심 인사이트(다관점 평가, 시스템적 파이프라인, 휴먼 인 더 루프)를 완벽하게 적용할 수 있는 훌륭한 프로젝트입니다. 

클로드 코드(Claude Code) 하네스 구조를 활용하여, 단순히 글을 대신 써주는 것을 넘어 작성자의 의욕을 고취하고 품질을 끌어올리는 5개의 멀티 에이전트 파이프라인 구축 방법을 상세히 안내해 드립니다.

---

### 1. 에이전트 구성 (최소 5개)
단일 AI에 의존하지 않고, 각기 다른 페르소나를 부여하여 서로의 의견을 교차 검증하고 조율하도록 설계합니다.

1. **치어리더 에이전트 (Motivator):** 사용자의 초안이나 아이디어에서 '강점과 독창성'을 최우선으로 찾아내어 칭찬하고, 글을 완성했을 때의 기대효과를 제시해 동기를 부여합니다.
2. **구조 설계자 (Architect):** 파편화된 사용자의 아이디어를 SCQA(상황-문제-질문-해결) 등 논리적 프레임워크와 목차로 구조화합니다.
3. **다관점 비판자 (Red Team/Critic):** 글의 논리적 허점, 독자(고객) 관점에서의 반발, 부족한 근거를 집요하게 공격합니다. 지적 사항은 반드시 A/B/C/D 급으로 우선순위를 나눕니다.
4. **팩트체커 (Fact-Checker):** 존재하지 않는 사실이나 문헌을 지어내는 환각(Hallucination)을 막기 위해, 확실치 않은 내용은 본문에 단정 짓지 않고 반드시 **"[검증 필요]"** 꼬리표를 답니다.
5. **통합 조율자 (Coordinator/Gatekeeper):** 위 4명 에이전트의 의견을 종합하여 사용자에게 최종 리포트를 제시하고, 사용자의 '승인(Human-in-the-loop)'을 요청하는 문지기 역할을 합니다.

---

### 2. 프로젝트 진행 방법 (하네스 구조 세팅)
클로드 코드가 일관된 품질을 내도록 워크스페이스(폴더 및 파일 구조)를 먼저 설계해야 합니다. 

* **Step 1: 폴더 구조 자동 생성** 
  클로드 코드를 실행하고 가장 먼저 폴더 구조를 생성하게 합니다. 입력(초안), 진행(에이전트 토론), 출력(완성본)을 분리해야 상태 보존과 버전 관리가 가능합니다.
* **Step 2: 정본 단일화 및 MOC(Map of Content) 작성** 
  `00_개요_MOC.md` 파일을 만들어 현재 어느 단계인지, 최신 버전의 파일이 무엇인지 클로드 코드가 항상 추적하도록 만듭니다.
* **Step 3: 시스템 규칙(`claude.md`) 셋업**
  매번 프롬프트를 길게 치지 않도록, 클로드 코드가 작업 디렉토리에서 항상 참고하는 전역 지침서(`claude.md` 또는 `system_prompt.md`)를 심어둡니다.

---

### 3. `claude.md` (클로드 코드 전역 지침서) 작성 내용
프로젝트 루트 폴더에 `claude.md` 파일을 만들고 아래 내용을 저장해 둡니다. 클로드 코드가 디렉토리를 읽을 때 이 원칙을 시스템 규칙으로 삼게 됩니다.

```markdown
# 만능 동기부여 글쓰기 에이전트 파이프라인 규칙

## 1. 기본 원칙 (핵심)
- **품질 최우선:** 글을 무작정 완성하지 마라. 기획-평가-수정-완성의 파이프라인을 엄격히 지킨다.
- **사람의 통제 (Human-in-the-loop):** 각 단계(목차 생성, 비판 수용, 최종 완성)가 넘어갈 때마다 반드시 사용자에게 방향성 승인을 요청하라.
- **이유와 배경 설명:** 사용자에게 글의 수정을 제안할 때는 "왜 이렇게 고쳐야 하는지" 인지공학적/논리적 배경을 반드시 함께 설명하라.

## 2. 5대 에이전트 페르소나 및 역할
클로드 코드는 요청 시 아래 5명의 에이전트 역할을 병렬 또는 순차적으로 수행해야 한다.
1. [Motivator]: 사용자의 원본 아이디어에서 긍정적 가치를 3가지 이상 찾아 구체적으로 칭찬하고 의욕을 고취한다.
2. [Architect]: 내용 작성 전, 구조(SCQA 등)와 목차를 먼저 설계한다. 
3. [Critic]: 독자, 경쟁사, 심사위원의 다관점으로 약점을 비판하고, 수정 우선순위를 A/B/C/D급으로 분류한다.
4. [Fact-Checker]: 사실 확인이 불분명한 근거나 문헌은 임의로 지어내지 말고 텍스트 옆에 반드시 **"[검증 필요]"**라고 별도 표시한다.
5. [Coordinator]: 모든 의견을 취합하여 사용자에게 최종 브리핑을 제공하고 승인을 대기한다.

## 3. 워크플로우 진행 순서
- 단계 1: 사용자가 초안이나 아이디어를 `00_inputs/`에 업로드.
- 단계 2: [Motivator]가 동기부여 리포트 제공 & [Architect]가 뼈대(목차) 제안. (사용자 승인 대기)
- 단계 3: 승인된 뼈대를 바탕으로 글 작성.
- 단계 4: [Critic]과 [Fact-Checker]가 초안을 집요하게 검증 및 비판.
- 단계 5: [Coordinator]가 비판 내용을 수용하여 글을 다듬고 최종 완성본을 `11_final_outputs/`에 저장.
```

---

### 4. 클로드 코드에게 실행할 핵심 프롬프트(명령어)

터미널에서 클로드 코드(`claude`)를 실행한 뒤, 아래 순서대로 대화하듯 명령을 내립니다.

**명령 1: 초기 인프라 셋업 (한 번만 실행)**
> "현재 디렉토리에 동기부여 글쓰기 에이전트를 위한 폴더 구조를 만들어줘. `00_inputs`, `01_drafts`, `02_agent_debates`, `11_final_outputs` 폴더를 생성하고, 전체 작업의 상태를 추적할 `00_MOC.md` 파일을 만들어줘. 그리고 내가 작성해둔 `claude.md`의 규칙을 읽고 숙지해 줘."

**명령 2: 작업 시작 및 1차 파이프라인 가동**
> "`00_inputs/` 폴더에 내 아이디어 메모(또는 초안)를 올려뒀어. `claude.md`에 명시된 워크플로우 2단계에 따라, [Motivator] 관점의 동기부여 브리핑과 [Architect] 관점의 글 구조/목차 초안을 표 형식으로 제시해 줘. 내가 승인할 때까지 다음 단계로 넘어가지 마."

**명령 3: 멀티 에이전트 비판 및 토론 실행 (다이나믹 워크플로우 활용)**
> "(목차 승인 후) 작성된 초안을 바탕으로 [Critic]과 [Fact-Checker] 에이전트를 동시 가동해서 꼼꼼하게 평가해 줘. [Critic]은 평가 기준에 따라 A/B/C/D로 수정 우선순위를 매기고, [Fact-Checker]는 확실치 않은 부분에 **'[검증 필요]'** 태그를 붙여. 논의된 전체 로그는 `02_agent_debates/`에 마크다운으로 저장해 줘."

**명령 4: 문제 발생 시 트러블슈팅 프롬프트**
(에러가 나거나 의도한 대로 에이전트가 작동하지 않을 때 무작정 다시 해달라고 하지 마세요)
> "방금 생성된 비판 리포트에서 [Fact-Checker]의 역할이 제대로 수행되지 않은 것 같아. 왜 누락되었는지 원인을 코드를 읽고 먼저 진단해 줘. 해결 방향을 확인한 뒤에 수정해."

이러한 구조를 거치면, **동기부여를 받아 자신감 있게 글을 시작하면서도, AI의 냉철한 검증 게이트를 거쳐 팩트와 논리가 완벽한 글을 완성**하는 이상적인 자동화 시스템을 경험하실 수 있을 것입니다.