Skip to content

vibe-coding-tutorial.md

Latest commit

 

History

History
458 lines (324 loc) · 10.9 KB

vibe-coding-tutorial.md

File metadata and controls

458 lines (324 loc) · 10.9 KB

바이브 코딩 튜토리얼: hwp2md 프로젝트 사례

이 문서는 Claude Code를 활용한 실제 프로젝트 개발 과정을 정리한 바이브 코딩 튜토리얼입니다. hwp2md 프로젝트의 작업 로그를 기반으로, 효과적인 프롬프트 작성법과 AI 협업 패턴을 학습할 수 있습니다.

목차

  1. 프로젝트 시작
  2. 기술 조사 및 설계
  3. 구현 단계
  4. 디버깅 및 문제 해결
  5. 기능 확장
  6. 문서화 및 릴리즈
  7. 프롬프트 패턴 정리

1. 프로젝트 시작

1.1 초기 조사 요청

프롬프트:

이 프로젝트는 hwp 문서를 markdown으로 변환해주는 도구를 구현하기 위해서 만들어졌어.
hwp는 버전마다 호환되지 않는 포멧을 가진것으로 악명높아.
PRD를 작성하기전에 먼저 hwp의 포멧에 대한 조사를 퍼플렉시티로 진행하고 조사 결과를 문서화해줘.

의도:

  • 프로젝트 배경 설명
  • 기술 조사 선행 요청
  • 문서화 요청

결과:

  • Perplexity MCP를 통한 HWP 포맷 조사
  • HWP 3.x, 5.x, HWPX 포맷 차이점 정리
  • docs/hwpx-schema.md 문서 생성

1.2 기존 솔루션 조사

프롬프트:

HWP를 markdown으로 변환하는 라이브러리가 존재하는지 퍼플렉시티로 조사해줘.
영어와 한국어 각각 쿼리를 해줘.

의도:

  • 중복 개발 방지
  • 기존 솔루션의 한계 파악

패턴: 한국어 관련 자료는 영문/한국어 양쪽으로 검색 요청

1.3 기존 도구 검증

프롬프트:

unhwp 가 이미 있으니 이게 충분히 쓸만하다면 새로 만들 필요가 있나 싶어.
unhwp의 변환 능력을 검증하는것을 먼저 해 보자.

의도:

  • 기존 도구로 충분한지 검증
  • 불필요한 개발 방지

결과:

변환이 되긴 하는데 전혀 포멧이 일치하질 않아.
직접 구현하는게 좋을것 같아. 다만 테크스택은 파이썬 보다는 Go언어가 좋을것 같아.

2. 기술 조사 및 설계

2.1 PRD 작성

프롬프트:

이제 이 프로젝트를 위한 PRD를 작성해줘.

결과: docs/PRD.md 생성

2.2 기술 스택 결정

프롬프트:

이제 테크 스택 문서를 작성해줘.
완성된 도구는 CLI형태로 제공되고 windows, mac, linux에서 모두 사용 가능해야해.

의도:

  • 크로스 플랫폼 요구사항 명시
  • CLI 도구 형태 명시

결과: docs/tech-stack.md 생성, Go 언어 선택

2.3 아키텍처 제안 및 수정

프롬프트:

만들고자 하는 변환기는 표가 있는 복잡한 문서들은 텍스트 중심으로 뽑아낸 다음
llm을 사용해서 포메팅을 할 수있게끔 하는게 좋을것 같아. 어떻게 생각해?

의도:

  • 2단계 파이프라인 아키텍처 제안
  • AI 의견 확인

후속 프롬프트:

수정하자. 그리고 LLM은 OpenAI, Anthropic, Gemini 등의 다양한 LLM을 사용할 수 있게끔
plugin 형태로 확장 가능하게 설계해줘.

패턴: 제안 → 의견 확인 → 수정 요청

3. 구현 단계

3.1 이슈 기반 개발

프롬프트:

이제 작업을 위한 이슈를 생성해줘.
git push시에 테스트 및 lint가 동작하도록 하고 이를 모두 통과해야만 push가 가능하도록 git hook을 구성해줘.

의도:

  • 체계적인 작업 관리
  • CI/CD 설정

3.2 구현 시작

프롬프트:

구현을 시작해

진행시켜

다음 이슈를 진행해

패턴: 간결한 진행 명령어 사용

3.3 CLI 사용법 확인

프롬프트:

내가 직접 테스트를 해 볼게. make 파일로 테스트 하는 방법을 알려줘.

@testdata/한글 테스트.hwpx 를 사용해서 1단계 변환과 2단계 변환을 해 보려면?

패턴: 파일 참조(@파일명)로 컨텍스트 제공

4. 디버깅 및 문제 해결

4.1 옵션 오류

프롬프트:

-llm 옵션이 동작하지 않음.
 hwp2md "testdata/한글 테스트.hwpx" -llm
Error: unknown shorthand flag: 'l' in -llm

결과: --llm (더블 대시) 사용법 안내

4.2 테이블 포맷 문제

프롬프트:

@phase1.md 이 Stage 1 결과물이야. 테이블 포멧이 깨져있음을 확인할 수 있어.
디벙깅 로그등을 활용해서 이 문제를 해결해줘.

의도:

  • 파일 참조로 문제 상황 전달
  • 디버깅 방법 제시

4.3 특정 위치 지정

프롬프트:

@phase1.md 의 나. 응시자격요건 [최종시험(면접시험) 예정일(2024.3.18.) 기준] 테이블이 이상해.

64라인의 응시자격요건 고려사항의 경우, 표가 아니라 항목형으로 표시하는게 더 가독성이 좋을것 같아.

패턴: 라인 번호나 특정 섹션 명시

4.4 포맷 한계 인식

프롬프트:

markdown에서는 셀병합이 안되는구나. 그렇지?

의도: 기술적 한계 확인 결과: HWPX-Markdown 차이점 문서화로 이어짐

5. 기능 확장

5.1 병합 셀 처리 개선

프롬프트:

병합된 셀을 내장파서에서 마크다운으로 변환하는 경우 맨 위 하나의 셀에만 내용이 들어 있어.
이것을 각각의 셀에 모두 내용이 들어가게 바꿔줘.

후속 조사:

병합셀 처리시에 같은 내용을 넣지 말고 "상동" 이라고 넣으면 어떨까?
혹은 더 좋은 문구가 있는지도 조사해줘.

최종 결정:

세로셀은 〃 으로 처리하고 가로셀은 빈칸을 유지해

패턴: 문제 발견 → 대안 조사 → 최종 결정

5.2 LLM 프로바이더 확장

프롬프트:

LLM 프로바이더에 새로운 프로바이더를 추가하고 각 모델들이 bedrock이나 로컬 서버와 같은
프라이빗 테넌시를 지정할수 있게 해줘.

5.3 설정 단순화

프롬프트:

환경 변수에서 HWP2MD_PROVIDER 는 필요 없지 않아? HWP2MD_MODEL 로 충분할것 같아.

의도: API 단순화, 사용자 경험 개선

6. 문서화 및 릴리즈

6.1 비교 결과 문서화

프롬프트:

테스트 파일의 stage 1 과 stage 2 생성물을 git에 등록하고
이를 리드미에 링크를 걸어 변환기의 품질을 확인 할 수 있게 해줘.

스테이지2 결과도 여러 종류의 LLM으로 생성한 결과물을 올리고
링크를 걸어서 비교할 수 있게 해줘.

6.2 차이점 문서화

프롬프트:

방금 처리한 이중 테이블처럼 hwpx와 markdown간의 차이로 인해 발생하는 차이점을 별도 문서로 정리하고
리드미에 링크를 걸어줘. 향후에도 이 문서가 자동으로 업데이트 될 수 있도록 클로드 스킬을 만들어줘.

결과:

  • docs/hwpx-markdown-differences.md 생성
  • .claude/skills/update-hwpx-differences.md 스킬 생성

6.3 릴리즈 자동화

프롬프트:

버저닝과 릴리즈 노트 생성을 자동으로 하는 스킬을 만들어줘.

깃헙 액션을 통해 릴리즈가 github에서 퍼블리시 될 수 있도록 해줘.
릴리즈 내용에 대한 요약도 표시하고.

6.4 문서 개선

프롬프트:

리드미 사용법 섹션에서 convert 생략 가능함을 명시해줘.

리드미나 문서 변경은 깃헙 액션즈가 CI/CD를 생략하고 빠르게 종료되도록 해줘.

리드미의 아키텍처도 머메이드를 사용해서 좀 더 구체적으로 설명해줘.

6.5 커밋 및 릴리즈

프롬프트:

커밋하고 푸시해줘.

커밋하고 푸시&버전업&릴리즈 해줘.

마이너버전업하고 릴리즈해

체인지로그 한국어로 바꿔줘.

6.6 이슈 관리

프롬프트:

이슈 처리사항 확인하고 완료된것을 닫아줘.

이슈 15 진행상황을 업데이트해줘.

7. 프롬프트 패턴 정리

7.1 파일 참조 패턴

@파일명 을 분석해줘
@파일명 의 N라인을 수정해줘

파일을 명시적으로 참조하여 컨텍스트 제공

7.2 조사 요청 패턴

퍼플렉시티로 조사해줘
영어와 한국어 각각 쿼리를 해줘
한국어로 쿼리를 해야 해

웹 검색이 필요한 경우 명시적으로 요청

7.3 단계적 진행 패턴

진행시켜
진행해
다음 이슈를 진행해

간결한 진행 명령어 사용

7.4 에러 보고 패턴

[명령어 실행 결과]
Error: [에러 메시지 전체]

에러 메시지를 그대로 복사하여 전달

7.5 대안 조사 패턴

~하면 어떨까? 혹은 더 좋은 방법이 있는지 조사해줘.

제안 + 대안 조사 요청

7.6 확인 패턴

~이 맞지?
~인거지?

이해한 내용 확인

7.7 복합 요청 패턴

커밋하고 푸시&버전업&릴리즈 해줘.

여러 작업을 한 번에 요청

7.8 결정 패턴

[옵션 A]로 처리하고 [옵션 B]는 [처리 방식]으로 해

명확한 결정 전달

8. 교훈 및 팁

8.1 효과적인 협업

  1. 컨텍스트 제공: 파일 참조(@)나 라인 번호로 정확한 위치 지정
  2. 단계적 진행: 복잡한 작업은 단계별로 나누어 진행
  3. 검증 요청: AI 응답 후 직접 테스트하여 결과 확인
  4. 피드백 제공: 결과가 기대와 다르면 구체적으로 피드백

8.2 조사 및 의사결정

  1. 사전 조사: 구현 전 기존 솔루션 조사
  2. 대안 비교: 여러 옵션에 대해 조사 요청
  3. 기술적 한계 인식: 포맷 간 차이점 등 한계 파악
  4. 문서화: 발견한 차이점이나 결정 사항 문서화

8.3 프로젝트 관리

  1. 이슈 기반 개발: GitHub 이슈로 작업 추적
  2. 진행상황 업데이트: 주기적으로 이슈 상태 업데이트
  3. 자동화: 반복 작업은 스킬이나 액션으로 자동화
  4. 릴리즈 관리: 버전 관리와 변경 이력 유지

9. 프로젝트 타임라인

단계 주요 작업 프롬프트 예시
1. 조사 HWP 포맷 조사, 기존 도구 검증 "퍼플렉시티로 조사해줘"
2. 설계 PRD, 기술 스택 문서 작성 "PRD를 작성해줘"
3. 구현 파서, LLM 연동 구현 "구현을 시작해"
4. 디버깅 테이블 포맷 수정 "@phase1.md 테이블이 이상해"
5. 확장 병합 셀 처리, LLM 프로바이더 "옵션을 추가하고자해"
6. 문서화 README, 차이점 문서 "문서로 정리해줘"
7. 릴리즈 버전업, GitHub 릴리즈 "릴리즈해줘"

이 튜토리얼은 hwp2md 프로젝트의 실제 개발 과정을 기반으로 작성되었습니다. 마지막 업데이트: 2026-01-10