AI 실습 교안, 수강생이 첫 프롬프트에서 멈추지 않게 — 실습 파일 준비 5단계와 빈 폴더 점검 스크립트

AI 실습 교안의 프롬프트가 @references/회사소개.txt처럼 파일을 가리킨다면, 그 파일은 수강생 폴더에 실제로 있어야 합니다. 실습 파일을 공개 저장소에 두고 모든 회차에서 같은 한 줄로 받게 하고, 교안을 빈 폴더 기준으로 점검하면 첫 프롬프트에서 멈추는 일을 막을 수 있습니다.

이 글은 이런 분께 필요합니다

• 코딩 에이전트나 AI 앱에 "이 파일을 읽고 정리해줘" 같은 실습을 시키는 강사·사내 교육 담당자
• 교안 리허설은 다 통과했는데, 막상 강의에서 수강생이 첫 단계부터 멈춘 경험이 있는 분
• 여러 회차짜리 과정에서 회차마다 실습 자료를 다시 나눠 주고 있는 분

준비물은 교안(마크다운 파일이면 Step 5 스크립트를 그대로 쓸 수 있습니다)과 Mac 또는 Python 3가 깔린 컴퓨터입니다. 이 글의 명령은 2026년 10월 7일에 직접 실행해 확인했습니다.

이런 일이 있었습니다. 6회차짜리 비개발자 대상 과정에서 교안 프롬프트는 이런 모양이었습니다.

@references/회사소개.txt 를 읽고 우리 회사를 세 문장으로 요약해줘
@references/지난제안서.md 의 구조를 추출해서 목차만 뽑아줘
@drafts/파트너미팅_회의록.txt 에서 결정사항과 담당자를 표로 정리해줘

내용은 강의 웹페이지에 "복사해서 붙여넣는 블록"으로 있었지만, 그걸 어디에 어떤 이름으로 저장하라는 지시가 없었습니다. 수강생이 @를 눌러도 자동완성 목록이 비어 있었고, 초보자는 손을 드는 대신 "내가 뭘 잘못 눌렀나" 하고 조용히 멈췄습니다. 그 지점이 2·3·4회차의 첫 프롬프트였습니다. 제 작업 폴더에는 파일이 다 있어서 리허설로는 끝까지 발견하지 못했습니다.

Step 1. 실습 파일을 작업 폴더 구조 그대로 한곳에 모읍니다

프롬프트가 파일 이름만이 아니라 경로까지 가리키기 때문에, 수강생 폴더와 똑같은 구조로 보관합니다. 파일 종류별(csv, txt, pdf)로 흩어 두면 수강생이 받은 뒤 다시 옮겨야 하고, 초보자는 바로 거기서 막힙니다.

저는 공개 저장소 datapopcorn-datahub의 business-docs 폴더에 이렇게 두었습니다. 2026년 10월 7일 기준 실제 구성입니다.

business-docs/
├─ references/   회사소개.txt, 지난제안서.md, 내부보고서양식.md, 발표양식.md, 가상메일.txt, 관련_RFP.pdf
├─ drafts/       파트너미팅_회의록.txt
└─ data/         실적_202608.csv, 03_월간업무현황_엑셀형_mock.csv

실제 공공기관 문서처럼 수강생마다 다른 파일을 받게 되는 자료는 가상 문서로 바꿉니다. 저는 긴 문서 실습용으로 발주기관·예산·일정까지 전부 창작한 가상 제안요청서(RFP)를 만들고 표지에 가상 문서임을 적었습니다. 모두가 같은 파일을 가져야 "필수 요구사항 10개를 찾았나" 같은 정답 기준으로 확인할 수 있습니다.

Step 2. 받는 문장을 하나로 정하고 모든 회차 첫 챕터에 넣습니다

필요한 회차에 필요한 파일만 받게 하면, 회차마다 받는 방법이 달라지고 수강생은 매번 새로 배워야 합니다. 그래서 1회차에 한 번에 전부 받게 하고, 각 회차 첫 챕터에 완전히 같은 문장을 넣었습니다. 코딩 에이전트에 이렇게 붙여 넣습니다.

https://github.com/team-datapopcorn/datapopcorn-datahub/tree/main/public-dataset/business-docs
의 파일을 지금 작업 폴더에 같은 폴더 구조·같은 파일 이름으로 받아줘.
이미 있으면 덮어써도 돼. 끝나면 폴더 안 파일 목록을 보여줘.

덮어쓰기라서 몇 번을 실행해도 결과가 같습니다. 지각한 사람, 파일을 지운 사람, 새 폴더에서 시작한 사람 모두 이 한 줄로 같은 상태가 됩니다.

AI 도구 없이 터미널로 받고 싶다면 아래 한 줄로도 같은 결과가 나옵니다. 빈 폴더에서 실행해 위 구조 그대로 받아지는 것을 확인했습니다.

curl -sL https://github.com/team-datapopcorn/datapopcorn-datahub/archive/refs/heads/main.tar.gz | tar -xz --strip-components=3 "datapopcorn-datahub-main/public-dataset/business-docs"

Step 3. 산출물은 회차·챕터별 폴더에 저장하게 합니다

받는 한 줄을 붙이고 나서 다른 문제가 드러났습니다. 결과물이 전부 폴더 맨 위에 쌓이다 보니, 뒷 회차 챕터가 앞 회차와 같은 이름의 파일을 다시 만들어 앞의 결과를 조용히 덮어썼습니다.

그래서 프롬프트에 저장 위치를 넣었습니다.

결과는 drafts/ch07/ 폴더에 저장해줘.

입력 폴더(references/, data/)는 입력 전용으로 두고, 산출물은 drafts/ch07/, drafts/ch08/처럼 나눕니다. 그러면 Step 2의 한 줄을 다시 돌려도 산출물은 지워지지 않습니다.

Step 4. 교안 문장을 초보자 기준 규칙 5개로 고칩니다

이 과정에서 생긴 교안 작성 규칙입니다.

규칙	실제로 있었던 문제	이렇게 고칩니다
파일명·경로를 챕터끼리 똑같이	한 챕터는 @메일.txt, 다른 챕터는 @references/가상메일.txt	실제 파일 경로 하나로 통일합니다
(주제) 같은 괄호 빈칸 금지	초보자가 괄호째 붙여 넣습니다	실제 예시값을 넣고, 바꾸고 싶은 사람만 바꾸게 합니다
숫자가 들어가는 문서엔 근거 데이터를 같이	양식만 주면 AI가 숫자를 지어냅니다	data/실적_202608.csv처럼 근거 파일을 같이 줍니다
완료 확인은 내용 기준으로	"파일이 생겼다"는 아무것도 확인하지 않습니다	"담당자 이름이 들어갔나", "CSV와 숫자가 같나"로 확인합니다
회차 마지막엔 다시 쓸 지시서를 남기게	회차마다 일회성 초안만 남습니다	"방금 한 절차를 지시서로 써 줘"를 마지막 미션으로 둡니다

Step 5. 빈 폴더에서 교안 속 파일 경로를 점검합니다

강사 폴더에서 하는 리허설은 파일이 이미 있어서 이 문제를 절대 잡지 못합니다. 그래서 빈 폴더에 Step 2로만 파일을 받은 뒤, 교안 속 @경로가 전부 있는지 스크립트로 대조합니다.

아래 내용을 check-practice-files.py로 저장합니다.

#!/usr/bin/env python3
"""교안(.md)의 프롬프트에 나오는 @경로가 실습 폴더에 실제로 있는지 확인합니다.
사용법: python3 check-practice-files.py <교안 폴더> <빈 상태에서 준비한 실습 폴더>"""
import re, sys
from pathlib import Path

lecture_dir, work_dir = Path(sys.argv[1]), Path(sys.argv[2])
pattern = re.compile(r"@([\w가-힣./\-]+\.[A-Za-z0-9]+)")
missing = 0
for md in sorted(lecture_dir.rglob("*.md")):
    for lineno, line in enumerate(md.read_text(encoding="utf-8").splitlines(), 1):
        for ref in pattern.findall(line):
            exists = (work_dir / ref).is_file()
            missing += not exists
            print(f"{'✅' if exists else '❌'} {md.name}:{lineno}  @{ref}")
print(f"\n없는 파일 {missing}개" if missing else "\n모든 파일이 있습니다.")
sys.exit(1 if missing else 0)

실행은 이렇게 합니다.

python3 check-practice-files.py 교안 fresh

위의 세 줄 프롬프트가 든 교안으로 실제 돌려본 결과입니다. 먼저 회사소개.txt 하나만 있는 폴더에서 돌렸을 때입니다.

✅ ch02.md:3  @references/회사소개.txt
❌ ch02.md:4  @references/지난제안서.md
❌ ch02.md:5  @drafts/파트너미팅_회의록.txt

없는 파일 2개

빈 폴더에 Step 2의 한 줄로 공개 세트를 받은 뒤 다시 돌린 결과입니다.

✅ ch02.md:3  @references/회사소개.txt
✅ ch02.md:4  @references/지난제안서.md
✅ ch02.md:5  @drafts/파트너미팅_회의록.txt

모든 파일이 있습니다.

❌가 하나라도 있으면 강의 전에 파일을 추가하거나 교안 경로를 고칩니다.

오류가 나면 여기부터 확인하세요

증상	확인할 것
수강생 화면에서 @를 눌러도 목록이 빔	지금 열린 폴더가 작업 폴더가 맞는지, Step 2를 실행했는지 확인합니다
스크립트가 아무 줄도 출력하지 않음	교안 폴더 경로가 맞는지, 교안이 .md 파일인지 확인합니다
경로가 맞는데 ❌가 나옴	파일 이름의 띄어쓰기·밑줄·확장자가 교안과 같은지 확인합니다
앞 회차 결과물이 사라짐	Step 3처럼 저장 위치를 챕터별 폴더로 지정했는지 확인합니다
회사 hwp·pptx로 실습하고 싶다는 요청	마크다운으로 바꿔 쓸 수 있지만 표가 많은 문서는 변환 품질 편차가 커서 사람이 손봐야 합니다

정리

화면에 보여 준 자료와 폴더에 파일로 있는 자료는 다른 상태입니다. 실습 파일을 한곳에 같은 구조로 두고, 모든 회차에서 같은 한 줄로 받게 하고, 강의 전에 빈 폴더 기준으로 점검하면 첫 프롬프트에서 멈추는 수강생이 사라집니다.