파생상품감사보고서 자동화 서비스 구축: 문서 체계화 및 예시파일 일관성 검토
2026.06.01
📝 한 줄 요약
"앞에서부터 1개씩 질문해줘"라는 한 마디가 수십 개 파일의 일관성 검토를 체계적인 작업으로 바꿨고, 지시 방식이 달라지자 AI가 하는 일의 깊이가 완전히 달라졌습니다.
---
바쁘시면 이것만 읽어도 돼요:
- AI에게 "찾아줘"가 아니라 "규칙을 먼저 정의하고, 앞에서부터 1개씩 질문해줘"라고 하면 체계적인 검토가 됩니다.
- 파일명에 분류 기준을 담으면, 폴더 없이도 내용이 보입니다.
- 해결 방향 3가지를 직접 정리해서 "모두 반영해줘"라고 하면 한 번에 구현됩니다.
- Word 다운로드는 백엔드 없이 CDN 한 줄로 됩니다.
- 공식 문서가 없는 API는 Playwright로 요청을 캡처하면 역공학이 됩니다.
---
🎯 이런 분들께 도움돼요
- AI에게 지시했는데 결과가 피상적이어서 답답했던 분
- 문서 파일들이 쌓여 있는데 정리할 엄두가 안 나는 실무자
- API 문서가 없는 사이트에서 데이터를 뽑아야 하는 개발자
- Word/Excel 다운로드 기능을 "나중에 서버 만들면"으로 미루고 있는 분
- DOCX 파일을 Markdown으로 깔끔하게 변환하고 싶은 분
---
😫 문제 상황 (Before)
여러 문서 파일을 관리하고 있었는데 세 가지 문제가 있었습니다.
첫째, 파일명에 분류 정보가 없었습니다. 파일을 열어봐야 어떤 방법론인지, 어떤 버전인지 알 수 있었습니다.
둘째, 원본 DOCX 파일들이 변환되지 않은 채 쌓여 있었습니다. 내용은 있는데 검색도 안 되고 편집도 불편한 상태였습니다.
셋째, 같은 내용을 설명하는 섹션임에도 파일마다 그림이 있는 것, 없는 것, 플레이스홀더만 있는 것이 뒤섞여 있었습니다. 일관성이 없었습니다.
플랫폼 쪽에서는 API 한도 초과 오류가 나도 원인을 알 수 없었고, 다운로드 버튼을 눌러도 alert만 떴습니다.
---
🛠️ 사용한 도구
- Claude Code CLI — 전체 작업 실행
- pandoc — DOCX → Markdown 변환
- html-docx-js (CDN) — 브라우저에서 DOCX 생성
- Playwright (Python) — 사이트 API 역공학
---
🔧 작업 과정
---
Phase 1 — 파일명에 분류 기준 넣기: 열기 전에 내용이 보여야 한다
기존 파일명에는 분류 정보가 없었습니다. 이렇게 요청했습니다.
▎ "파일명을 '(문서유형)_(대상)_(방법론)_(번호)' 형식으로 수정해줘. 방법론에는 A, B, C 등이 들어갈 거야."
AI가 파일 내용을 직접 읽고 각 파일의 방법론을 확인한 뒤 리네임했습니다. 한 문장 지시가 전체 분류 체계를 만들었고, 이후 새로 추가되는 파일들도 같은 규칙으로 자연스럽게 이름이 붙었습니다.
Before: 문서_1.md, 문서_2.md, 문서_3.md
After: 문서_대상A_방법론X_1.md
문서_대상A_방법론Y_2.md
문서_대상B_방법론X_1.md
---
Phase 2 — DOCX → MD 변환: pandoc이 하고, 정리는 "넣어줘" 한 줄
쌓여 있던 DOCX 파일들을 하나씩 가리키며 이렇게 요청했습니다.
▎ "해당 파일도 지정 폴더 안에 MD 파일로 정리해서 넣어줘."
지시는 단순했지만 실제 작업은 달랐습니다. pandoc이 DOCX를 변환하면 세 가지 문제가 생깁니다.
┌────────────────────────────────┬──────────────────────────┐
│ pandoc 변환 결과 │ 실제 처리 │
├────────────────────────────────┼──────────────────────────┤
│ 표가 그리드 형식으로 깨짐 │ 마크다운 테이블로 재구성 │
├────────────────────────────────┼──────────────────────────┤
│ 알고리즘 단계가 단락으로 뭉침 │ 번호 목록으로 분리 │
├────────────────────────────────┼──────────────────────────┤
│ 수식 이미지 자리에 참조만 남음 │ 실제 이미지 연결 │
└────────────────────────────────┴──────────────────────────┘
pandoc은 시작점이지 완성본이 아닙니다. 변환 이후 정리가 본 작업입니다.
---
Phase 3 — 일관성 검토: "규칙을 주고 1개씩 질문하게 한 것"
이번 주 작업 중 가장 효과적인 지시 방식이었습니다.
처음엔 "누락된 부분 찾아줘"라고 할 뻔했습니다. 대신 이렇게 요청했습니다.
▎ "파일들을 읽고 누락된 부분이 있는지 확인해줘. 예를 들어 동일한 방법론을 설명하는 섹션에는 동일한 설명과 그림이 있어야 해. 빠져있는 부분이 있으면 앞에서부터 1개씩 질문해줘."
두 가지가 달랐습니다.
첫째, 검토 기준(규칙)을 먼저 정의했습니다.
"동일한 방법론에는 동일한 설명과 그림"이라는 원칙 하나가 체크리스트 없이도 비교 기준이 됐습니다. AI가 이 기준을 가지고 파일들을 스스로 순회했습니다.
둘째, "1개씩 질문해줘"라고 했습니다.
한꺼번에 목록을 뽑는 게 아니라, 하나씩 확인하고 응답을 받으면서 진행됐습니다. 덕분에 각 항목에 추가 맥락을 줄 수 있었습니다.
예를 들어 같은 이미지를 두 파일에 넣어야 하는지 묻는 질문이 왔을 때, 두 파일의 성격이 다르다는 걸 설명하면서 지시했습니다.
▎ "전자는 A 상황에 해당하는 설명이고, 후자는 B 상황이야. 각각 다르게 처리해줘."
단순히 같은 이미지를 복사하는 게 아니라, 각 파일에 성격 차이를 명시하는 주석까지 달아서 처리됐습니다.
---
Phase 4 — 다른 파일을 참조하게 하기: 다시 설명하지 않아도 된다
새로운 파일을 작성할 때 이렇게 요청했습니다.
▎ "개인정보는 모두 지우고, 저번에 정리했던 Python 코드를 기반으로 내용을 다시 작성해줘. 작성할 내용이 없으면 공란으로 놔둬줘."
세 가지 지시가 한 문장에 들어갔습니다. AI가 이전에 작업했던 Python 파일을 직접 읽고 구조를 파악해서 새 문서를 작성했습니다. 내용을 다시 설명할 필요가 없었습니다.
작업 간에 참조 관계를 연결해주는 것만으로 충분합니다.
---
Phase 5 — API 방어 코드: 방향 3개를 묶어서 한 번에
API 한도 초과 문제를 분석하고 해결 방향을 직접 정리해서 요청했습니다.
▎ "방법 1: 전송 데이터 크기 줄이기. 방법 2: 중복 호출 방지 플래그 추가. 방법 3: 한도 초과 에러 구분 안내. 3가지 방법 모두 반영해줘."
하나씩 순서대로 요청하는 대신, 방향 3개를 묶어서 한 번에 주니 관련 파일 전체에 동시에 적용됐습니다.
// 방법 1: 전송 크기 절반으로
text.slice(0, 9000) → slice(0, 4000)
// 방법 2: 중복 호출 방지
let isSending = false;
async function run() {
if (isSending) return;
isSending = true;
try { /* API 호출 */ }
catch (e) { isSending = false; }
}
// 방법 3: 429 에러 구분 안내
const is429 = e.status === 429 || e.message?.includes('RESOURCE_EXHAUSTED');
if (is429) { /* "잠시 후 다시 시도해주세요" 안내 */ }
---
Phase 6 — Word 다운로드: CDN 한 줄로 해결
다운로드 버튼이 alert만 띄우는 상태였습니다. 백엔드 없이 브라우저에서 실제 DOCX를 생성하는 방법이 필요했습니다.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-docx.js"></script>
한 가지 주의할 점이 있었습니다. CSS 변수(var(--color))는 DOCX에서 동작하지 않습니다. DOM에서 innerHTML을 뽑는 대신, 데이터 변수로 명시적인 색상값을 넣어 HTML을 직접 빌드했습니다.
const html = `<!DOCTYPE html><html>
<head><style>
th { background-color: #e8edf5; } /* CSS 변수 대신 직접 색상값 */
</style></head>
<body>${데이터로 직접 빌드한 내용}</body>
</html>`;
const blob = htmlDocx.asBlob(html);
const a = document.createElement('a');
a.download = '파일명.docx';
a.click();
---
Phase 7 — API 역공학: 문서 없이 API 찾기
공식 API 문서가 없는 사이트에서 데이터를 가져와야 했습니다. Playwright로 page.on("request")를 걸어 실제 POST body를 캡처했습니다.
async def on_request(req):
if "특정엔드포인트" in req.url:
post_body = req.post_data or ""
print(post_body) # ← 여기서 실제 요청 구조가 드러남
page.on("request", on_request)
await page.goto("https://대상사이트.kr/")
await page.wait_for_timeout(10000)
사이트가 headless 브라우저를 감지해 Selenium이 막혔을 때, Playwright로 전환하니 우회됐습니다. 캡처된 POST body 구조를 그대로 requests로 재현하면 API 명세서 없이도 데이터를 가져올 수 있습니다.
▎ 요청을 "역공학"하는 게 아니라 "관찰"하는 것입니다.
---
✅ 결과 (After)
┌────────────────┬─────────────────────────┬─────────────────────────────────┐
│ 항목 │ Before │ After │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ 파일명 │ 내용 알려면 열어봐야 함 │ 파일명에 분류 정보 포함 │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ DOCX 파일 │ 변환 안 된 채 방치 │ 전부 MD로 정리 │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ 파일 간 일관성 │ 그림·섹션 불일치 │ 규칙 기반 검토로 20개 이상 보완 │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ API 오류 안내 │ 원인 불명, alert │ 429·일반 오류 구분 안내 │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ 다운로드 기능 │ alert만 표시 │ 실제 DOCX 생성·다운로드 │
├────────────────┼─────────────────────────┼─────────────────────────────────┤
│ 외부 API │ 구조 불명 │ Playwright 캡처로 구조 파악 │
└────────────────┴─────────────────────────┴─────────────────────────────────┘
---
💬 이 과정에서 배운 AI 활용 팁
1. "찾아줘" 대신 "규칙을 주고 1개씩 질문해줘"
규칙 없는 "찾아줘"는 피상적인 목록이 나옵니다. 검토 기준을 먼저 정의하고, 결과를 순서대로 받으면 각 항목에 맥락을 추가할 수 있습니다. 이 방식은 파일 검토, 코드 리뷰, 데이터 정합성 확인 등 어디에든 적용됩니다.
2. 방향을 여러 개 제시하고 "모두 반영해줘"
문제를 분석해서 방향 여러 개를 직접 정리한 뒤 한 번에 주면, AI가 관련 파일 전체에 동시에 적용합니다. 하나씩 요청하는 것보다 훨씬 빠릅니다.
3. 다른 파일을 참조하게 하면 다시 설명할 필요가 없다
"저번에 작업한 파일 기반으로"라고 하면 AI가 직접 파일을 읽고 구조를 파악합니다. 내용을 다시 설명하는 수고가 없어집니다. 작업 간 참조 관계를 연결해주는 것이 핵심입니다.
4. API 문서가 없으면 "캡처해줘"
"엔드포인트 알려줘"가 아니라 "실제 사이트에서 요청을 캡처해줘"라고 하면 Playwright가 실제 POST body를 가져옵니다. 문서 없이도 API 구조를 파악할 수 있습니다.
---
이렇게 하면 안 돼요
1. "전체 검토해줘"로 한 번에 처리하려 하기 — 기준 없는 검토는 피상적인 결과만 나옵니다.
2. 지시를 하나씩 순서대로 내리기 — 방향을 묶어서 한 번에 주면 훨씬 빠릅니다.
3. pandoc 변환을 완성으로 착각하기 — 변환 후 정리가 본 작업입니다.
4. CDN 라이브러리를 "서버 만들면 할게"로 미루기 — html-docx-js 한 줄이 Word 다운로드를 즉시 해결했습니다.
---
🌍 다른 업무에 적용한다면?
"규칙을 주고 1개씩 질문해줘" 패턴:
[파일 목록]을 읽고 아래 규칙을 기준으로 누락된 부분을 확인해줘.
규칙: [검토 기준]
앞에서부터 1개씩 질문해줘.
계약서 검토, 코드 리뷰, 데이터 정합성 확인 등 반복 검토가 필요한 모든 업무에 적용됩니다.
"방향 묶어서 한 번에" 패턴:
[문제 상황]에 대한 해결 방향이 [N]가지야:
방법 1: [조치]
방법 2: [조치]
방법 3: [조치]
모두 반영해줘.
"참조하게 하기" 패턴:
[이전 작업 파일]을 기반으로 [새 작업]을 해줘.
[특별 조건]이 있으면 공란으로 처리해줘.
---
📋 재사용 가능한 프롬프트
프롬프트 1: 규칙 기반 일관성 검토
[파일 목록]을 전부 읽고 아래 규칙을 기준으로 누락된 부분을 확인해줘.
규칙:
- 동일한 [기준]을 다루는 섹션에는 동일한 [요소]가 있어야 한다
- 동일한 유형의 파일에는 동일한 구조가 있어야 한다
빠져있는 부분이 있으면 앞에서부터 1개씩 질문해줘.
프롬프트 2: 방향 묶어서 한 번에
[문제]에 대한 해결 방향이 [N]가지야:
방법 1: [구체적 조치]
방법 2: [구체적 조치]
방법 3: [구체적 조치]
[대상 파일들]에 모두 반영해줘.
프롬프트 3: API 역공학
[사이트]에서 [데이터]를 가져오고 싶어.
Playwright로 실제 요청을 캡처해줘:
1. 메인 페이지 접속 → 쿠키 획득
2. [대상 페이지] 접속 후 XHR POST 요청 캡처
3. 캡처된 요청 구조를 requests로 재현해서 데이터 조회
사이트가 headless를 감지하면 옵션을 조정해줘.
---
이번 주의 핵심은 결과보다 지시 방식이었습니다. 같은 작업을 요청해도 규칙을 먼저 주고 순서대로 받으면, AI가 감사자처럼 체계적으로 움직입니다. 다음 주는 이 방식을 더 복잡한 자동화 작업에 적용해볼 예정입니다.




시스템을 수정 개선 보완하고 있는 것 같다는 생각이 들었습니다. 맞습니다. 지금 하고 계신 것 처럼 계속해서 시스템을 진화시켜 가시면 원하는 품질의 보고서가 나오게 될 것입니다.
아주 잘하고 계십니다.
스터디 시간에는 다른 스터디원들 보고 감을 잡게 시스템도 보여주실 수 있는데까지 보여주시면 좋을 것 같습니다.
감사합니다. 👍 🔥 💪