yapi777/create-doc

Create-doc — 슬라이드 제작 스킬에 전달할 구성안 만들기

연구 기록(실행 기록 md, 결과 CSV, 그림, 코드)을 읽고, 1장씩 「무엇을 말할지・어떤 형식으로 보여줄지・무엇을 실을지・무엇을 말할지」가 결정된 구성안을 Markdown으로 작성합니다.

전달 대상은 progress-report-deck 스킬(같은 research-slides 플러그인에 있으며, 이 스킬의 옆 폴더 ${CLAUDE_SKILL_DIR}/../progress-report-deck/에 있음)입니다. 이 스킬의 출력은 progress-report-deck이「## 제목 1개 = 슬라이드 1장」으로 읽고 템플릿 유형에 흘려 넣는 것을 전제로 만듭니다. 작업을 시작하기 전에 ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md를 읽고, 아래의 「슬라이드 제작 스킬과의 약속」과 충돌하지 않는지 확인합니다(상대방의 규칙이 변경되었다면 상대방에 맞춥니다). 발견되지 않으면 이 약속대로 작성하면 됩니다.

사용자 프로필 ~/.claude/yapi-skills/profile.md(성명・연구 분야・주요 청중・독자 규칙)이 있으면 먼저 읽습니다. 독자 규칙(색상・최소 글자 크기 등)은 아래 약속보다 우선하며, 구성안의「이 자료에 관하여」에도 옮겨 적습니다.

구성안 견본은 references/template.md에 있습니다. 서식이 헷갈리면 이에 맞춥니다.

슬라이드 제작 스킬과의 약속(progress-report-deck의 규칙에서 비롯된 것)

구성안은 다음을 지켜 작성해야 합니다. 지키지 않으면 슬라이드화 단계에서 삭제되거나 재작업이 발생할 수 있습니다.

항목	약속	이유(progress-report-deck 측 규칙)
제목	## 1개 = 슬라이드 1장. 보충을 포함해 ##는 슬라이드에만 사용합니다. 장의 구분에는 #를 사용합니다.	초안의 ##를 슬라이드로 읽음
골격	제목 → 이번에 한 일(목차) → 연구 배경(1/2)(2/2) → 연구 목적(이번 소목표) → 내용 → 정리・과제 → 감사합니다 순	템플릿 고정 골격
연구 배경	이전과 같으면「동일(기존 자료 그대로)」라고만 쓰고 내용은 쓰지 않음	연구 배경은 기본 동일
이번 소목표	연구 목적 슬라이드에「이번 소목표」문구를 반드시 작성(1~2줄)	상대방이 매번 사용자에게 묻는 항목. 미리 정해 둠
매수	최종 매수로 작성(상대방이 통합・분할하지 않아도 되도록)	상대방이 ##가 많으면 통합을 제안함
유형	내용 슬라이드에는 레이아웃 유형을 1개 지정(아래 표)	글머리 기호를 흘려 넣으면「하반부가 비어 있음」이라고 지적됨
색상	색상 의미는 2개만: 청색＝제안・대응・결론・주역 수치, 주황색＝기존 기법・문제・지적・주의. 기법마다 3번째 색상을 할당하지 않음. 표에서는 주역 행을「연청으로 강조」라고 작성	테마 청색 #156082와 주황색 #E97132 2색만
글자량	주장은 한글 30자 이내(전폭 18pt로 1행에 들어가는 양). 글머리 기호 1개 항목도 30자 내외까지. 1패널 3행까지. 길어지면 그림이나 표로 하거나 슬라이드를 나눔	글자는 16pt 이상 필수이며, 줄여서 채워 넣을 수 없음
글자 크기	「작게」「주석은 작은 글자로」등의 지시를 쓰지 않음. 각주도 16pt로 들어가는 길이(1행)로 함	16pt 미만 금지
수식	$...$(LaTeX 표기)로 쓰고,「수식(OMML)」이라고 명기	수식은 OMML로 조판
그림	출력 폴더의 images/에 복사한 png를 images/<이름>.png로 지정(pdf만 있으면 png로 변환하여 넣음). 리포지토리 내 경로나 ../는 쓰지 않음. 가로세로 비율 4:3 슬라이드에 들어가는지도 고려(가로로 긴 그림 2개를 세로로 나열하는 등)	pptx에는 png를 붙임. 슬라이드는 4:3. 슬라이드는 다른 폴더나 다른 기기에서 만들 수 있으며, 폴더 밖은 보이지 않음
모식도	그림 파일이 없고 도식으로 보여줄 것(처리 흐름, 타임라인, 기존→제안 대비)은 유형명과 그리는 방법을 구체적으로 작성	상대방이「도판 처리」를 사용자에게 묻지 않아도 됨
노트	말할 내용은「노트」에 작성. 슬라이드에는 싣지 않음	—
보충	질의응답용 보충 슬라이드는「감사합니다」뒤에 배치	클로징은 본편 마지막

지정 가능한 레이아웃 유형(progress-report-deck의 assets/template.pptx에 있는 실례):

유형	사용처	template.pptx의 실례
칩＋패널(문제→대응)	「기존 문제 → 이번 대응」「지적 → 대응」	p.7, p.11
번호 배지＋패널	①②③ 번호가 붙는 항목 열거(이점, 절차)	p.8-9
Before/After 모식도	기존 기법과 제안 기법 대비(왼쪽＝주황색 프레임, 오른쪽＝청색 프레임, 사이에 화살표)	p.10
타임라인 모식도	시간 방향 처리 흐름(실선／점선 상자＋커넥터)	p.12
2컬럼 칩＋패널＋하단 띠	2개 기법・설정을 나란히 비교, 수식 포함	p.13
표＋전폭 띠	결과 표와 그 아래「읽어낼 수 있는 것」띠(주역 1행은 진청색 칠)	p.14
KPI 타일(2×2)	수치나 결론 4개를 크게 보여줌	p.15
체크리스트(✓)	확인한 것・한 것의 열거	p.16
프레임 상자 2단	정리／향후 전망	p.17
그림＋전폭 띠	기존 그림을 크게 붙이고 아래에 읽어낼 수 있는 것을 띠로	(p.14의 표를 그림으로 대체)

목차(이번에 한 일)는 유형을 붙이지 않음(글머리 기호 그대로, 키워드만 굵게. 색상은 붙이지 않음).

진행 방법

1. 요구사항 듣기(AskUserQuestion, 1회로 정리)

대화나 요청문에서 알 수 있는 것은 묻지 않음. 모르는 것만 물음.

• 발표 종류와 길이: 진척 보고 / 세미나 / 학회. 매수 기준은 내용 슬라이드 1장 ≒ 1분(15분이면 내용 슬라이드 10장 내외 + 골격 5~6장)
• 청중: 연구실 멤버 / 학회 / 타 분야 사람. 전제 지식 양이 달라짐
• 포함할 주변 정보(복수 선택): 동기・경위, 비교 실험, 실패 분석, 기법 변천, 버그 수정 영향 등. 후보는 기록을 읽고 발견된 토픽에서 제시
• 연구 배경 동일하게 할지: 이전 자료에서 바꾼다면 바꿀 내용

사용자가 선택지에 없는 자유 기술로 답하면 그것도 요구사항으로 처리(예:「계기에 ○○도 넣어」).

2. 재료 모으기(읽기만. 실험 재실행은 하지 않음)

• 슬라이드 제작 스킬: ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md(위 약속 확인)
• 기록: 실행기록_*.md, *결과*.md, README.md, 방침서 등. 날짜가 새로운 것부터 읽음
• 수치: summary/*.csv, *.md의 표. 발표에 실을 수치는 반드시 여기서 전사
• 그림: 기존 png를 ls로 탐색. 일본어 라벨 그림이 있으면 우선. 사용할 그림의 원래 경로를 기록(절차4에서 images/에 복사, 출처에도 작성)
• 설정값: 보충 슬라이드에 실을 하이퍼파라미터・상수・모델 구성은 기록 md가 아니라 코드의 실제 값(상수, argparse 기본값, 실행 시 저장된 설정 json)에서 취함. 기록과 코드가 다르면 코드를 올바른 것으로 하고 사용자에게 전달

3. 구성 결정

골격(progress-report-deck 템플릿에 맞춤):

1. 제목
2. 이번에 한 일(목차. 내용 슬라이드 제목을 짧게 나열)
3. 연구 배경 (1/2)
4. 연구 배경 (2/2)
5. 연구 목적(목적＋이번 소목표)
6. ~ 내용 슬라이드
7. 정리・과제
8. 감사합니다
9. 보충 슬라이드(질의응답용)

내용 슬라이드는 대체로 이 흐름으로(매수에 맞춰 가감):

1. 동기・과제(왜 이것을 했는가) → 칩＋패널
2. 제안・변경 내용과 이점 → Before/After 모식도 또는 번호 배지＋패널
3. 기법 상세(처리 흐름) → 타임라인 모식도
4. 정확성 담보・검증 → 체크리스트
5. 파라미터 결정 방법 → KPI 타일 또는 표＋띠
6. 실험 설정(데이터, 비교 기법, 평가 지표) → 2컬럼 또는 표＋띠
7. 결과(주장 1개당 1장) → 표＋띠, 그림＋띠
8. 비용・제약 → 표＋띠 또는 KPI 타일

보충 슬라이드(질의응답용)를 반드시 첨부. 발표 시간에는 포함하지 않음.

• 상세 설정(모델・최적화・상수 표)
• 데이터・시뮬레이션 설정
• 비교 기법 상세(수식은 OMML 지정)
• 평가 지표 엄밀한 정의
• 파라미터 탐색 등 전체 결과 표
• 예상 질문과 답변 예(8문항 내외): 이것만은 슬라이드로 하지 않음(# 장으로 구성안末尾에 배치, 발표자 핸드아웃용).「차이가 작지 않은가」「1회 시행으로 말할 수 있는가」「왜 이 비교 대상인가」「계산 비용은」「미검증 주장의 근거는」등, 약점을 찌르는 질문을 우선

4. 작성(폴더에 정리하여 출력)

슬라이드는 progress-report-deck에서 다른 폴더나 다른 기기(PowerPoint가 있는 PC 등)에서 만들 수 있습니다. 따라서 구성안과 사용할 이미지를 1개 폴더에 정리하여 출력하고, 그 폴더만 가져가면 슬라이드를 만들 수 있도록 합니다.

슬라이드-제작-문서-<날짜>/
├── 슬라이드-제작-문서-<날짜>.md   ← 구성안
└── images/
    ├── speed_sweep.png
    └── ...

• 폴더명과 md 파일명은 **슬라이드-제작-문서-<날짜>**로 통일(예: 슬라이드-제작-문서-2026-10-15/). 날짜는 작성일을 YYYY-MM-DD로 작성. 같은 날 다른 발표용을 만드는 등 이름이 충돌할 때는 날짜 뒤에 짧은 식별자를 추가(예: 슬라이드-제작-문서-2026-10-15-세미나/). 기존 폴더는 덮어쓰지 않음. 프로젝트 루트 직하에 생성
• 이미지: 구성안에서 사용할 그림을 모두 images/에 복사(이동이 아닌 복사. 원본 파일은 건드리지 않음)
  • 파일명은 원래 이름 그대로. 이름이 충돌하거나 내용을 알기 어려운 이름(fig1.png 등)일 때는 내용을 알 수 있는 영문자 이름으로 변경(예: velocity_field_f195.png). 공백은 사용하지 않음
  • pdf만 있는 그림은 png로 변환하여 넣음(예: pdftoppm -png -r 200 -singlefile in.pdf images/name, 또는 PyMuPDF로 200 dpi)
  • 구성안 안에서는 images/<이름>.png로 참조
  • 원래 경로는「출처」장에「images/xxx.png ← 원래 경로」형식으로 남김(나중에 그림을 다시 만들 때 추적할 수 있도록)
• 모식도(그림 파일이 없는 것)는 이미지를 만들지 않고 구성안에 그리는 방법을 작성

앞부분의「이 자료에 관하여」(# 장, 슬라이드로 하지 않음)에 progress-report-deck에 대한 지시를 작성:

• 발표 종류・길이・매수・청중
• 각 슬라이드 서식(아래)
• 수치는 변경・반올림하지 말 것
• 이 폴더를 작업 폴더로 하여 progress-report-deck을 실행할 것. 그림은 이 폴더의 images/에 있으며 images/<이름>.png로 지정했음. 새 그림은 만들지 않음(모식도는 지정대로 그림)
• 기법명 표기 규칙, 색상 할당(청색＝제안, 주황색＝기존・비교 기법)
• 연구 배경 동일하게 할지 여부

각 슬라이드 서식:

## 슬라이드N — <제목>

- **유형**: <레이아웃 유형(위 표에서 1개)>
- **주장**: <한글 30자 이내 1문장. 이 슬라이드에서 가장 말하고 싶은 것>
- **본문**: <글머리 기호. 1개 항목 30자 내외, 3~4개 항목까지>
- **표** / **그림**: <표는 Markdown으로, 강조할 행・열을 작성. 그림은 `상대경로.png`(무슨 그림인지)>
- **수식(OMML)**: <있으면 $...$로>
- **노트**: <말할 내용. 슬라이드에는 싣지 않음>

작성 시 규칙:

• 주장은 결론을 씀.「결과①」「○○에 관하여」「○○을 보여줌」이 아니라「속도가 빨라질수록 차이가 벌어짐」. '-습니다'체로 끝내지 않음
• 평가어는 수치로 뒷받침.「대폭」「유효」「우수한」이라고 쓰면 같은 슬라이드에 비교 대상・지표・시행 횟수를 배치.「동등」「보증」은 과장되기 쉬움(「거의 동등」「확인함」)
• 생성된 문장에 흔한 어휘(매우／획기적인／~할 수 있음／시임리스 등)는 사용하지 않음. 목록과 대체 예는 ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md
• 본문 글머리 기호는 1개 항목 1문장(「。」로 연결되는 2문장은 분리)
• 미검증 사항은 미검증이라고 씀. 기대되는 성질과 실험으로 보여준 것을 섞지 않음. 해당 슬라이드 본문이나 띠에 1줄 넣고, 정리・과제의「향후」에도 실음
• 공정한 비교를 위한 조건(수렴시킨 설정을 사용한 등)은 각주 1줄로 작성. 경위에 대한 긴 설명은 사용자가 포함하겠다고 한 경우만 작성
• 슬라이드에 다 실을 수 없는 상세한 설명은 노트나 보충 슬라이드로 돌림. 본문을 길게 하지 않음
• 마지막에「출처」표(내용 → 파일)를 # 장으로 첨부

5. 검증(반드시 수행)

1. 수치 기계 대조: 구성안에 나오는 소수를 모두 정규표현식으로 추출하고, 출처 md / CSV(CSV는 4자리・2자리로 반올림한 값)에 포함되는지 대조. 발견되지 않은 것은 자신이 계산한 차이인지, 전사 오류인지, 반올림 불일치인지 하나씩 확인하여 수정. 대조 스크립트는 scratchpad에 배치
2. 폴더 자체 완결성: 구성안 내 그림 참조가 모두 images/ 아래 png이며, 해당 파일이 실제로 존재할 것. ../나 절대 경로, 리포지토리 내 경로가 남아 있지 않을 것. 반대로 images/에 참조되지 않은 불필요한 파일이 없을 것. 폴더 전체 크기도 보고
3. 그림 내용: 그림에 대해 말하는 문장(「○○에서 크다」등)은 그림을 실제로 열어보고 맞는지 확인
4. 약속 기계 점검: ## 수가 예상 슬라이드 매수와 일치, 모든 슬라이드에「유형」이 있음(골격 슬라이드 제외), 3번째 색상 지시가 없음. 주장 길이(한글 30자 이내)・주장이 결론인지・AI 냄새나는 어휘・표기 불일치는 슬라이드 제작 스킬의 검사 스크립트로 조사:

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<구성안.md>" > check_doc.txt
   

   출력을 Read로 읽고 WARN을 수정(연구상 올바른 표현이면 남겨도 됨). 마지막 행이 DONE: …이 아니면 검사가 실패한 것이므로 0건으로 간주하지 않음. 스크립트를 찾을 수 없으면 이 항목은 눈으로 확인
5. 매수: 본편이 요구사항 매수에 들어가는지 셈

6. 보고

• 1행에 예상 독자(예:「예상 독자: progress-report-deck 스킬(그 너머에 연구실 세미나 청중)」)
• 출력한 폴더 경로와 내용(md 1개＋이미지 개수・전체 크기)
• 구성(각 슬라이드를 1행씩)과 보충 내용
• 검증 결과(대조한 수치 개수, 그림 확인, 약속 점검)
• 발표 전에 사용자가 알아야 할 점: 미검증 주장, 지적받기 쉬운 수치와 그 이유, 사용한 결과가 언제・어떤 코드의 것인지
• 다음 단계: 「이 폴더에서(다른 기기면 폴더째 복사한 후) progress-report-deck을 실행하면 슬라이드화할 수 있습니다」라고 전달. 휴대 방법(USB, Box/OneDrive, zip으로 압축 후 보내기 등)은 사용자에게 맡김
• 커밋은 하지 않음(요청받으면 함)