AI 코딩 에이전트로 연구 자동화 도구 라이브러리 만들기

#blog

#📝️/✒️

AI 코딩 에이전트로 연구 자동화 도구 라이브러리 만들기

문제: 임상연구에서 반복되는 문서 작업

병원에서 임상연구를 하다 보면 비슷한 형식의 문서를 반복해서 만들게 됩니다.

이런 작업을 Claude Code와 함께 하면서 자연스럽게 Python 스크립트들이 하나씩 생겼는데, 문제는 이 스크립트들이 프로젝트 폴더 안에 하드코딩된 채로 흩어져 있다는 것이었습니다.

research/
├── temporaryfiles/
│   ├── create_cpet_protocol.py        # CPET 전용, 400줄
│   ├── create_cpet_pdf.py             # CPET PDF 전용, 380줄
│   ├── create_icg_lymphography_protocol.py  # ICG 전용, 400줄
│   └── create_icg_protocol.py         # ICG 전용, 380줄
└── FSHD/
    └── build_commented_docx.py        # FSHD CRF 전용, 320줄

5개 스크립트, 총 1,900줄. 그런데 90%가 같은 패턴입니다.

해결: pytool — 범용 자동화 도구 라이브러리

Step 1. 공통 패턴 추출

프로토콜 생성 스크립트 3개를 비교해보면 구조가 동일합니다:

[제목] → [헤더 테이블] → [3열 본문 테이블 (섹션 병합)] → [비고]

차이점은 데이터만 다르다는 것. 색상 코드, 테이블 구조, 폰트 설정은 모두 같습니다.

Step 2. Config-driven 범용 함수로 변환

하드코딩된 내용을 config dict로 분리하면, 하나의 함수로 어떤 프로토콜이든 생성 가능합니다:

from pnuh_protocol_generator import generate_protocol

config = {
    "title": "심폐운동부하검사 (CPET) 시행 프로토콜",
    "header_title": "CPET 시행 프로토콜",
    "department": "재활의학과",
    "sections": [
        {
            "label": "검사 전\n확인",
            "rows": [
                ("검사 의뢰 확인", "E2EFDA", ["처방전 확인"]),
                ("절대적 금기", "FCE4EC", [
                    "① 급성 심근경색 (2일 이내)",
                    "② 불안정 협심증",
                    # ...
                ]),
            ],
        },
    ],
    "notes": [("※ 진료지원업무 수행 간호사는 ...", False, False)],
}

generate_protocol(config, "CPET_protocol.docx")

3개의 400줄짜리 스크립트 → 1개의 320줄 범용 함수 + config만 바꿔 호출

Step 3. Word Comment 주입도 범용화

docx에 실제 Word 주석을 프로그래밍으로 삽입하는 건 꽤 까다로운 작업이었습니다. python-docx가 Comment를 지원하지 않기 때문에 ZIP 내부 XML을 직접 조작해야 합니다:

docx (ZIP 파일)
├── word/comments.xml         ← 주석 본문 (새로 생성)
├── word/document.xml         ← 주석 위치 마커 삽입
├── word/_rels/document.xml.rels  ← 관계 등록
└── [Content_Types].xml       ← 콘텐츠 타입 등록

이것도 범용화하면 어떤 docx든 주석을 달 수 있습니다:

from docx_comment_injector import inject_comments

comments = [
    {"id": 0, "anchor": "Subject ID",   "text": "병록번호 항목 추가 필요"},
    {"id": 1, "anchor": "Body weight",  "text": "BMI 자동 계산 추가"},
    {"id": 2, "anchor": "NRS score",    "text": "야간 통증 항목 추가"},
]

inject_comments("CRF_draft.docx", "CRF_reviewed.docx", comments,
                author="이재현 (PI)")

CLI로도 사용 가능합니다:

python3 docx_comment_injector.py input.docx output.docx comments.json

pytool 폴더 구조

최종적으로 정리된 구조:

research/pytool/
├── README.md                      # 도구 목록, 사용법, 의존성
├── pnuh_protocol_generator.py     # 프로토콜 제출서 docx 생성 (범용)
└── docx_comment_injector.py       # Word Comment 주입 (범용)
도구 기능 의존성 원본
pnuh_protocol_generator.py 프로토콜 제출서 docx 생성 python-docx temporaryfiles/ 3개 스크립트
docx_comment_injector.py 기존 docx에 Word 주석 삽입 lxml FSHD/build_commented_docx.py

핵심: CLAUDE.md에 워크플로 규칙 등록

이 과정을 한 번으로 끝내지 않고 앞으로도 자동으로 반복되게 하려면, AI 에이전트의 행동 규칙으로 등록해야 합니다.

CLAUDE.md에 다음 규칙을 추가했습니다:

## pytool 자동화 도구 관리

연구/임상 업무 중 반복 사용 가능한 Python 스크립트가 생성되면
자동으로 `/workspace/research/pytool/`에 정리:

1. **판단 기준**: 다른 프로젝트에도 재사용 가능한 스크립트
2. **범용화**: 하드코딩 → 파라미터/config dict로 분리
   - 함수 import + CLI 양쪽 지원
3. **저장**: `/workspace/research/pytool/`에 저장
4. **README 업데이트**: 도구 목록 테이블에 새 항목 추가
5. **사용자 확인**: 저장 전 "pytool에 범용화해서 저장할까요?" 확인

이렇게 하면 앞으로 대화 중에 재사용 가능한 스크립트가 만들어질 때마다:

  1. Claude가 자동으로 pytool 후보임을 인식
  2. "이 스크립트를 pytool에 범용화해서 저장할까요?" 질문
  3. 승인하면 범용화 → pytool 저장 → README 업데이트

한 번 규칙을 만들어두면, 도구 라이브러리가 자동으로 성장합니다.

설계 원칙

이 워크플로를 만들면서 적용한 원칙들:

1. Dual Interface (함수 import + CLI)

모든 도구는 두 가지 방식으로 사용 가능하게 작성합니다:

# Python에서 import
from pnuh_protocol_generator import generate_protocol
generate_protocol(config, "output.docx")

# CLI에서 직접 실행
python3 pnuh_protocol_generator.py

if __name__ == "__main__" 블록에 예시를 넣어두면 CLI 실행과 동시에 사용법 문서 역할도 합니다.

2. Config-driven Design

하드코딩 대신 config dict를 받는 구조로 만들면:

3. 원본 스크립트 추적

README에 "원본 스크립트" 섹션을 두어 범용화의 출처를 기록합니다. 나중에 "이 도구가 원래 뭐였지?" 할 때 역추적이 가능합니다.

4. 점진적 성장

처음부터 도구 라이브러리를 설계한 게 아닙니다:

일회성 스크립트 작성 → 패턴 발견 → 범용화 → pytool 등록 → 규칙화

실제 필요에서 출발해서 자연스럽게 라이브러리가 만들어졌습니다.

실전 적용 사례

사례 1: FSHD 연구 CRF 리뷰

전공의가 작성한 미완성 CRF(HWP 파일)에 PI의 리뷰 주석 18개를 자동 삽입:

hwp 파일 → olefile 텍스트 추출 → markdown 정리 → pandoc → docx
→ docx_comment_injector로 18개 Word Comment 삽입
→ 전공의에게 주석 달린 docx 전달

사례 2: 신규 프로토콜 제출서 작성

ICG 림프관조영술 프로토콜을 새로 만들 때:

config = {
    "title": "ICG 림프관조영술 시행 프로토콜",
    "sections": [
        {"label": "검사 전 준비", "rows": [...]},
        {"label": "검사 수행", "rows": [...]},
        {"label": "검사 후 관리", "rows": [...]},
    ],
}
generate_protocol(config, "ICG_lymphography_protocol.docx")

400줄 새로 코딩하는 대신, config 20줄만 작성하면 됩니다.

정리

Before After
프로젝트마다 비슷한 스크립트 복사-붙여넣기 config만 바꿔서 호출
스크립트가 여기저기 흩어져 있음 /research/pytool/에 중앙 관리
다음에 쓰려면 어디 있는지 찾아야 함 README.md에 목록 + 사용법
한 번 쓰고 잊어버림 CLAUDE.md 규칙으로 자동 축적

핵심은 AI 에이전트의 행동 규칙(CLAUDE.md)에 도구 관리 워크플로를 등록하는 것입니다. 한 번 등록하면 앞으로 만들어지는 모든 자동화 스크립트가 자동으로 라이브러리에 추가됩니다.

도구가 쌓이면, 다음 연구 프로젝트에서는 이미 만들어진 도구들을 조합하는 것만으로 문서 작업의 상당 부분을 자동화할 수 있게 됩니다.

Comments