스킬문서- '시스템이 어떤 규칙으로 돌아가야 하는가'를 자세하게 정의해둔 문서

'스킬 문서(또는 기능 명세서/Rulebook)'에 작성하는 내용

 

결국 기획서, 스킬 문서, 요구사항 명세서 등으로 부르는 명칭만 다를 뿐, "시스템이 어떤 규칙으로 돌아가야 하는가"를 디테일하게 정의해둔 문서라는 본질은 완벽히 같다.

💡  AI 시대에 '스킬 문서'가  강조되는 이유

전통적인 개발 환경에서도 스킬 문서 역할을 하는 문서(기획서, 기능정의서 등)는 있었지만, AI와 함께 개발하는 바이브 코딩 시대에는 스킬 문서의 역할과 비중이 완전히 달라졌기 때문이다.

• 과거: 스킬 문서를 작성해 사람 개발자에게 주면, 개발자가 맥락과 상식을 알아서 고려해 코딩했다. (예: "30초 제한시간"이라고만 적어도, 개발자가 알아서 "30초가 지나면 입력 버튼을 비활성화하고 에러 메시지를 띄워야겠구나" 하고 눈치껏 구현함)
• AI 시대: 그러나 AI는 눈치가 없습니다. 스킬 문서에 명시되지 않은 '당연한 예외 상황'이나 '세부 타이밍'은 AI 마음대로 넘겨짚거나 빼먹고 구현해 버린다. 알아서 하지 않고 딱 시키는 것만 한다. 알아서 하라고 하면 엉망으로 해버린다.

🤖 AI에게 먹히는 '스킬 문서' 작성의 핵심 포인트

바이브 코딩을 할 때는 스킬 문서를 단순히 기능 나열용이 아니라, AI가 그대로 코드로 옮길 수 있는 '기계적인 지침서' 수준으로 아주 촘촘하게 잡아두는 것이 핵심이다.

1. '숫자'와 '경계 조건(Edge Case)'을 명확히 명시

• ❌ "제한시간이 지나면 다음으로 넘어간다."
• ⭕ "각 투구/샷당 제한시간은 엄격히 30초이다. 카운트다운이 0초가 되는 즉시 입력은 차단되며, 잔여 시간 이월이나 시간 합산(Time Pool)은 절대 존재하지 않는다."

2. '예외 처리'와 '실패 시 동작'까지 포함

• ❌ "점수를 계산하여 스코어보드에 표시한다."
• ⭕ "점수 계산 공식에 따라 산출된 점수를 표기하되, 통신 오류로 점수 전송이 실패할 경우 기존 데이터를 유지하고 즉시 재시도 팝업을 띄운다."

3. AI에게 스킬 문서를 '헌법'으로 주입하기

이렇게 완성된 스킬 문서는 AI와 대화할 때 최상위 지침(System Prompt 또는 Context)으로 계속 입력해 주면된다.

"이 스킬 문서는 우리 시스템의 절대적인 규칙이다. 앞으로 네가 만드는 모든 코드와 테스트는 이 스킬 문서의 규칙을 단 하나도 위반해서는 안 된다."

📌 결론

결국  스킬 문서가 곧 AI 시대의 '최상위 기획서이자 검증 기준서'이다.

 

스킬 문서에 규칙과 예외 상황을 구체적으로 적어둘수록, AI가 헛소리(환각)를 하거나 엉뚱한 코드를 짜는 일이 획기적으로 줄어들게 된다. 그래서 바이브코딩이 아니라바이브스킬링이다.