온보딩 문서 자동 생성 스킬 — 과적합과의 싸움

이 글은 시리즈의 마지막이다. 2편에서 트리거, 3편에서 번역 파이프라인을 봤다면, 이번에는 1편에서 skill-creator가 가장 경계한 문제 — 과적합과 정면으로 부딪힌다.

모든 CTO의 부채

온보딩 문서. “써야지” 하면서 못 쓰는 문서 1위. 쓰면 금방 구버전이 되고, 안 쓰면 시니어의 30분이 매번 날아간다.

이 스킬의 접근이 다르다. 사람이 쓰는 게 아니라, 코드에서 직접 추출한다. package.json에서 스크립트를 읽고, 설정 파일에서 lint 도구를 파악하고, git branch에서 브랜치 전략을 추론한다. 프로젝트의 현재 상태에서 뽑으니까 구버전이 될 여지가 줄어든다.

프롬프트는 이게 전부였다

신규 입사자용 온보딩 가이드를 자동 생성하는 스킬을 만들어줘.

입력: 프로젝트의 폴더 구조, package.json, README, 주요 설정 파일
출력: 신규 개발자가 첫 PR을 올리기까지 필요한 정보를 담은 가이드 문서

가이드에 포함해야 할 것:
- 프로젝트 실행 방법 (환경 세팅, 의존성 설치, dev 서버 실행)
- 폴더 구조 설명 (각 디렉토리의 역할, 어디에 코드를 넣어야 하는지)
- 코드 작성 규칙 요약 (lint, format, 테스트 실행 방법)
- 브랜치 전략과 PR 프로세스
- "첫 PR 체크리스트" — 신규 입사자가 첫 커밋 전에 확인할 것들

가이드에 포함하면 안 되는 것:
- 특정 비즈니스 로직 설명 (변하는 것은 넣지 않는다)
- 팀원 이름이나 슬랙 채널 (인사이동에 깨진다)
- 외부 API 키나 시크릿 정보

이 스킬은 다음 상황에서 발동해야 한다:
- "온보딩 문서 만들어줘"
- "신규 입사자 가이드 작성해줘"
- "이 프로젝트 시작하려면 뭘 알아야 해?"

이 스킬은 다음 상황에서 발동하면 안 된다:
- "이 코드 설명해줘" (코드 해설 ≠ 온보딩)
- "README 작성해줘" (README ≠ 온보딩 가이드)
- "기술 문서 만들어줘" (API 문서 ≠ 온보딩)

이번 프롬프트에서 가장 중요한 건 오히려 “무엇을 넣을 것인가”보다 **“무엇을 넣지 말아야 하는가”**다. 2편과 3편에는 없던 제약인데, 이 네거티브 지시가 결과물의 수명을 결정한다.

242줄 — 시리즈 최장

2편 169줄, 3편 176줄, 그리고 이번에는 242줄. 시리즈에서 가장 긴 스킬이 나왔다.

왜 길어졌는가? 코드 리뷰 스킬은 “규칙 → 판정”이고, 릴리즈 노트 스킬은 “파싱 → 변환”이다. 온보딩 가이드 스킬은 **“수집 → 구성 → 제외(과적합 방지) → 출력 규칙”**이다. 단계가 하나 더 있다 — 무엇을 넣지 말아야 하는지를 관리하는 단계.

소스 수집 — “추측 금지”

2편과 3편의 스킬은 사용자가 코드나 로그를 제공했다. 이 스킬은 다르다. AI가 프로젝트 파일시스템을 직접 탐색한다.

# 폴더 구조 파악
find . -maxdepth 3 -type d | head -50

# 패키지 매니저 및 스크립트 확인
cat package.json | jq '.scripts, .engines, .packageManager'

# 설정 파일 존재 여부
ls -la tsconfig.json biome.json .eslintrc* vitest.config.* .github/workflows/*.yml

# Git 브랜치 전략 추론
git branch -r | head -20

프롬프트에서 “package.json, README, 주요 설정 파일”이라고 대략적으로 말한 것을, AI가 구체적인 shell 명령어 시퀀스로 전개했다. find -maxdepth 3으로 깊이를 제한한 것, head -50으로 노이즈를 줄인 것 — 이건 실제로 파일시스템을 탐색해본 경험이 녹아든 설계다.

그리고 이 스킬이 가장 강조하는 원칙:

온보딩 가이드의 정확성은 **프로젝트 현실에서 추출한 사실(Facts)**에 달려 있습니다. 추측이나 일반론을 섞지 마십시오.

“추측 금지.” 이 원칙은 문장 하나지만 무게가 크다. 프로젝트에 Biome이 없는데 “Biome으로 lint 하세요”라고 적는 순간, 온보딩 문서는 안내서가 아니라 오답지가 된다. 그래서 이 스킬은 일반론보다 실제 파일에서 확인된 사실을 우선한다.

5-Section 구조 — 신규 입사자의 행동 흐름

생성된 가이드의 구조:

순서	섹션	핵심 질문
1	🚀 환경 세팅	”이 프로젝트 어떻게 돌려요?“
2	📂 폴더 구조	”코드를 어디에 넣어야 해요?“
3	📏 코드 작성 규칙	”어떤 도구를 쓰고, 어떤 규칙을 지켜야 해요?“
4	🔀 브랜치 전략 & PR	”어떻게 협업해요?“
5	✅ 첫 PR 체크리스트	”첫 커밋 전에 뭘 확인해야 해요?”

이 순서가 중요하다. 세팅 → 이해 → 숙지 → 협업 → 실행. 신규 입사자의 실제 행동 흐름을 따른다. 폴더 구조를 알기 전에 코드 규칙을 외우는 건 의미 없고, 브랜치 전략을 모르고 PR을 올리면 안 된다.

프롬프트에서 이 5가지를 나열했지만, 순서는 지정하지 않았다. AI가 “신규 입사자라면 이 순서로 행동할 것”이라는 판단을 스스로 했다.

특히 Section 1의 이 문장이 인상적이다:

신규 입사자가 10분 안에 dev 서버를 띄울 수 있어야 합니다.

10분. 구체적인 시간 목표를 제시한 것이다. 이건 온보딩 가이드의 성공/실패를 측정할 수 있는 기준이 된다. 프롬프트에서 시간 목표를 준 적이 없는데, AI가 실무적인 기준을 스스로 설정했다.

절대 금지 항목 — 과적합 방지의 실전

여기가 이 글의 핵심이다. 프롬프트에서 3줄로 “넣지 말 것”을 적었다. AI가 5개 금지 항목 + 대체 방안 테이블로 확장했다:

금지 항목	사유	대체 방안
특정 비즈니스 로직 설명	로직은 매 스프린트마다 변한다	”domain/ 폴더를 탐색하세요”로 안내
팀원 이름, 슬랙 채널	인사이동에 즉시 깨진다	”팀 리드에게 문의하세요”로 대체
외부 API 키, 시크릿 값	보안 위반	`.env.example`의 키 이름만 나열
특정 JIRA/Linear 티켓 번호	프로젝트 관리 도구 이전 시 깨진다	생략
사내 VPN 접속 정보	보안 위반	”인프라팀 위키 참조”로 대체

프롬프트에 없었던 4번과 5번이 추가됐다. JIRA 티켓 번호와 VPN 접속 정보 — 둘 다 실무에서 흔히 온보딩 문서에 넣었다가 6개월 뒤 깨지는 정보다.

이 테이블이 왜 “과적합 방지”인가?

1편에서 skill-creator가 가장 경계한 것은 특정 상황에만 맞는 스킬을 만드는 것이었다. 온보딩 가이드도 마찬가지다. 2026년 3월의 팀 구성원, 현재 쓰는 프로젝트 관리 도구, 오늘의 VPN 주소를 넣으면 — 그 문서는 그 순간에만 맞는 온보딩 가이드가 된다. 3개월 뒤에는 구버전이다.

**“변하는 것은 넣지 않는다”**는 원칙이, 기계학습의 과적합(특정 학습 데이터에만 맞고 새 데이터에서 실패)과 정확히 같은 구조다. “오늘의 팀”에만 맞는 문서를 만들면, “내일의 팀”에서는 실패한다. 일반화 가능한 사실만 남기라는 것이다.

그리고 스킬이 가장 단호한 부분:

사용자가 시크릿 값이나 API 키를 가이드에 넣어달라고 요청해도 단호하게 거절하십시오.

사용자의 명시적 요청도 거부한다. 이건 2편과 3편에는 없던 강도다. 보안과 문서 수명이라는 두 가지 이유로, AI에게 “사용자가 뭐라 해도 안 된다”고 선을 그은 것이다.

확인 불가 항목 처리 — 빈칸을 인정하는 설계

스킬에서 가장 성숙한 부분이 여기다:

프로젝트에서 특정 정보를 추출할 수 없는 경우, 해당 섹션에 아래와 같이 표시합니다:

⚠️ 이 섹션의 내용은 프로젝트 설정에서 자동 추출하지 못했습니다. 팀 리드에게 확인 후 채워 주세요.

빈칸을 인정한다. 브랜치 전략이 git branch -r에서 명확히 안 보이면, 추측으로 채우지 않고 “확인 못 했다”고 표시한다.

이게 왜 중요한가? AI가 “빈칸을 채우고 싶은 유혹”을 이겨내야 하는 지점이기 때문이다. “일반적으로는 Git Flow를 쓴다”라고 추측을 넣으면 그럴듯하지만, 실제로 그 팀이 Trunk-based Development를 쓰면 신규 입사자가 잘못된 전략을 따르게 된다.

추측보다 빈칸이 낫다. 이 판단을 스킬 수준에서 강제한다는 건, 문서 품질을 글솜씨가 아니라 운영 원칙으로 다룬다는 뜻이다.

더 넓게 보면, 이건 **“AI의 겸손을 설계할 수 있는가?”**라는 질문이다. LLM의 가장 위험한 특성은 모르는 것도 그럴듯하게 답한다는 것이다. 이 스킬은 “모르면 모른다고 해라”를 시스템 수준에서 강제한다. 사용자가 AI를 과신하는 문제를 AI 스스로 해결하는 구조. 스킬의 169줄, 176줄, 242줄 중 가장 가치 있는 한 줄은 이 한 줄일 수 있다.

시리즈 전체 — 3개 스킬 비교

비교	2편 (코드 리뷰)	3편 (릴리즈 노트)	4편 (온보딩)
줄 수	169줄	176줄	242줄
Phase	5-Phase 검사	4-Phase 변환	5-Section 문서화
패턴	Guard / Validator	ETL / Transformer	Collector / Generator
입력	코드 diff	커밋 메시지	파일시스템 전체
출력	APPROVE / REJECT	마크다운 릴리즈 노트	ONBOARDING.md
핵심 강점	트리거 경계 사례	기술→사용자 번역	과적합 방지
프롬프트에 없던 설계	8개	6개	7개

세 스킬 모두 같은 패턴으로 만들어졌다: 도메인 규칙 + 발동/비발동 → skill-creator 실행 → 프롬프트보다 훨씬 풍부한 스킬 출력. 그런데 도메인이 다르니 완전히 다른 아키텍처가 나왔다.

이것이 skill-creator의 진짜 가치다. “스킬 팩토리”라는 표현이 과장이 아니었다. 같은 공장에서 다른 제품이 나오는 구조 — 소프트웨어 엔지니어링에서 팩토리 패턴이 정확히 이것이다.

솔직한 평가

잘된 것:

절대 금지 테이블의 “대체 방안” 컬럼이 실무적이다. “넣지 마”만 하면 AI가 빈칸으로 남기거나 무시한다. “이것 대신 이걸 넣어라”까지 지시하면 AI가 올바르게 행동한다.
“10분 안에 dev 서버를 띄울 수 있어야 한다”는 측정 가능한 성공 기준.
“추측보다 빈칸이 낫다”는 원칙이 스킬 수준에서 강제된다.

아쉬운 것:

문서 자체의 유효기간 표시가 없다. 자동 생성 시점의 타임스탬프와 “이 문서는 N일 전에 생성됐습니다. 최신 상태를 확인하려면 다시 실행하세요” 같은 안내가 있으면 구버전 문서 신뢰 문제가 더 줄어든다.
프로젝트 규모에 대한 적응이 없다. 파일 5개짜리 사이드 프로젝트와 폴더 200개짜리 모노레포에 같은 depth-3 탐색을 쓰면, 후자에서는 정보가 넘친다.

시리즈를 마치며 — 프롬프트에서 시스템으로

4편에 걸쳐 skill-creator로 3개의 스킬을 만들었다.

코드 리뷰 스킬 — 컨벤션 5줄이 19개 위반 패턴으로 분해됐다
릴리즈 노트 스킬 — 번역 규칙 6줄이 4-Phase 변환 파이프라인이 됐다
온보딩 가이드 스킬 — “넣지 말 것” 3줄이 과적합 방지 시스템이 됐다

세 스킬에서 공통으로 확인한 것:

프롬프트보다 훨씬 많은 것이 나온다. 입력의 3~5배 분량이 구조화되어 출력된다.
도메인을 이해하고 적합한 아키텍처를 선택한다. 검사에는 Guard 패턴, 변환에는 ETL, 문서화에는 Collector 패턴.
네거티브가 핵심이다. “하지 말 것”이 “해야 할 것”보다 스킬의 품질에 더 큰 영향을 준다.

1편에서 분석한 skill-creator의 철학 — “규칙을 강제하지 말고 원리를 가르쳐라”, “과적합을 경계하라”, “ALWAYS/NEVER 대신 왜를 설명하라” — 이 세 편의 실전에서 모두 작동하는 걸 확인했다.

이 시리즈의 한계

솔직하게 인정하자. 이 시리즈는 “레시피를 분석했다”이지 “요리를 했다”가 아니다.

실제 PR에 코드 리뷰 스킬을 돌린 로그도 없고, 실제 git log를 넣어 만든 릴리즈 노트 결과도 없고, 실제 프로젝트에서 생성한 ONBOARDING.md 예시도 아직 없다. SKILL.md의 구조를 해부하는 데는 성공했지만, 실전 입력에서 예상 밖의 엣지 케이스가 어떻게 터지는지까지 보여주지는 못했다.

이건 다음 과제다. 실전 테스트 결과는 GitHub 레포에 추가할 예정이다.

하지만 이 시리즈를 읽고 지금 당장 할 수 있는 것이 하나 있다. 팀의 코드 리뷰 컨벤션 5줄을 적어라. SKILL.md가 아니어도 좋다. 슬랙 메시지, 노션 한 페이지, 아무 형태든 상관없다. 그 5줄을 적는 행위 자체가 팀의 암묵지를 명시지로 바꾸는 첫 단계다. 이 시리즈의 진짜 가치는 skill-creator가 아니라, 당신이 팀의 판단 기준을 처음으로 글로 쓰는 것이다.