Skill로 기능 명세서 자동화하기 - 문서화 지옥에서 탈출한 이야기
한줄 요약
개발 후 기능 명세서 작성이 번거로워서, Skill을 만들어 프롬프트 하나로 일관된 명세서를 자동 생성하게 만들었습니다.
이런 분들께 도움돼요
- 바이브코딩할 때 문서 작업이 귀찮으신 분
- 기능 추가/변경할 때마다 문서 동기화가 스트레스인 분
- 여러 기능의 명세서를 일관된 양식으로 관리하고 싶은 분
- Skill과 Sub-agent 중 뭘 써야 할지 고민인 분
소개: 시도하고자 했던 것과 그 이유
문제 상황
저는 바이브코딩을 할 때 문서를 굉장히 중요하게 생각하는 사람입니다. 하지만 문서 → 개발 → 문서 재수정 사이클이 너무 번거로웠습니다.
특히 1차 개발을 다 한 후 기능 변경이나 추가가 생기면, 기존 문서에 반영하는 작업이 정말 손이 많이 갔습니다. 여러 기능의 명세서를 작성할 때마다 양식도 제각각이라 관리도 어려웠고요.
해결하고 싶었던 것
개발이 완료된 후, 일관된 양식으로 기능 명세서를 자동 생성해주는 도구를 만들고 싶었습니다.
진행 방법: 어떤 도구를 사용했고, 어떻게 활용했나요?
사용한 도구
- Gemini CLI - Skill vs Sub-agent 선택 자문
- Claude Code - Skill 생성 및 실행
Step 1: Skill vs Sub-agent 선택 자문
처음에는 이걸 agent로 만들어야 할지 skill로 만들어야 할지 감이 안 왔습니다. 그래서 Gemini CLI에 물어봤습니다.
나는 subagent 혹은 skills 를 만들고 싶다.
현재 내가 forge라는 기능을 만들었는데 내부에는 큰틀에서는 xp와 화폐에 관련된 기능이다.
세부 기능들에 대해서 자동으로 적어주는 subagent혹은 skill을 만들고싶은데 둘중어떤걸로 만드는게 좋을지 물어보고 싶다.
AI가 명확하게 정리해줘서 언제 skill을 써야 할지, sub-agent를 써야 할지 머릿속에 정리가 됐습니다.
Step 2: Skill 생성 및 수정
제안받은 대로 skill을 만들어달라고 했더니, 제가 원래 사용했던 문서 양식의 일관성을 갖추면서 제대로 작성해주더라고요.
하지만 처음에는 forge 기능에 한정된 skill이 나왔습니다. 다른 기능(linka 등)에도 쓰고 싶어서 수정을 요청했습니다.
이게 지금은 forge 기능을 문서화하는 작업에 사용하지만 linka 라는 기능을
추출할때도 사용하고싶다 (linka 기능은 아직 구현은 안됨)
즉, 재활용하고싶다는건데 현재 forge-spec이라는 name과 forge 프로젝트에 대한
기능명세서를 작성하라고나와있어서 forge 기능에 한정되어있다.이렇게 해서 어떤 기능에도 재사용 가능한 feature-spec skill이 완성됐습니다.
Step 3: 실제 사용
완성된 skill을 아래 프롬프트로 실행했습니다.
feature-spec skill을 활용해서 각 세부 기능에 대해서 명세서를 작성할 것이다.
봇과 웹ui, 백엔드 모든 기능을 확인하고
forge 기능은 @docs/function/forge, 기본 기능은 @docs/function/basic 에
각 기능별 폴더를 만든 후 spec.md 파일로 명세서를 작성하라.결과와 배운 점
결과물
- 각 기능별로 동일한 포맷의 spec.md 파일이 자동 생성됨
- forge, basic 등 여러 기능의 명세서를 프롬프트 하나로 일괄 생성
- 문서 관리가 훨씬 쉬워짐
배운 점
- 간단한 skill 하나로도 업무 효율이 크게 올라갈 수 있다
- 문서화 작업을 일관성 있게 한 번에 끝낼 수 있다는 것 자체가 큰 변화
- AI에게 "뭘로 만들어야 할지" 물어보는 것도 좋은 시작점
재사용 가능한 프롬프트
1. Skill vs Sub-agent 선택 자문
나는 subagent 혹은 skills 를 만들고 싶다.
[현재 상황 설명]
[하고 싶은 것 설명]
둘 중어떤걸로 만드는게 좋을지 물어보고 싶다.2. Skill 재사용성 확보 요청
이게 지금은 [특정 기능]에 사용하지만 [다른 기능]에도 사용하고 싶다.
즉, 재활용하고 싶다는건데 현재 [제한된 부분] 때문에 한정되어 있다.
3. 명세서 일괄 생성
[skill명] skill을 활용해서 각 세부 기능에 대해서 명세서를 작성할 것이다.
[범위 지정]하고[기능A]는 @[경로A], [기능B]는 @[경로B]
각 기능별 폴더를 만든 후 spec.md 파일로 명세서를 작성하라.향후 계획
- 하나의 skill로 효과를 봤으니, 다른 반복 작업도 자동화해보고 싶습니다
- skill과 sub-agent의 차이를 알았으니, 적절한 상황에 sub-agent도 활용해볼 예정입니다
- 더 많은 공부를 통해 업무 효율을 방대하게 증가시키고 싶다는 생각이 들었습니다
마무리
아직은 하나의 skill을 통해서 자동화를 했지만, 이 작은 시작이 앞으로의 자동화의 시작을 알렸고 한번 직접 이해를 하면서 만들어보니 어떻게 해야할지 감을 잡았습니다. 문서화가 번거로우신 분들, skill 하나 만들어보면서 체감을 해야지 더욱 발전할 수 있는 계기가 되지 않을가 싶습니다.
