Claude Code 기반 백엔드 개발: 포트폴리오 자동화

※ AI를 활용해, 개인적으로 활용하기 위한 내용을 정리하였습니다.

 

백엔드 개발 과정에서 생성형 AI 도구인 Claude Code를 도입하면 생산성이 대폭 향상된다. 하지만 개발 진행 중 겪은 수많은 트러블슈팅 경험, 아키텍처 의사결정, 코드 변경 사항을 포트폴리오 형태로 정리하려 할 때 체계적인 전략이 없다면 깔끔하게 정리하기 어렵다.

인터넷 상에서 Git Commit, GitHub Issue, CLAUDE.md, docs/ 폴더, PORTFOLIO.md 등의 기록 방식이 용어가 통일되지 않거나, 서로 충돌하는 등 혼선을 주곤 한다. 본 글에서는 이를 정돈하여, 개발 과정에서 자연스럽게 포트폴리오 데이터가 수집되도록 하는 단일 자동화 파이프라인으로 정리했다.

 

1. 역할 분담 및 용어 정립 (충돌 해결)

기록 매체 간의 역할 범위를 명확히 규정해야, 중복 기록이나 충돌을 방지할 수 있다.

기록 매체	핵심 질문	주요 기록 내용	포트폴리오에서의 역할
Git Commit	What & How	코드 단위 변경 사항, 기능 구현, 버그 수정, 리펙토링, 빌드/테스트 수정 사항	정확성 입증을 위한 자료
GitHub Issue	Why & Trial	문제 정의, 작업 목적, 기술 검토, 트러블슈팅, 시도했으나 실패한 대안 및 선회 이유	트러블슈팅 기록용 데이터
CLAUDE.md	Context & State	프로젝트 컨텍스트, 규칙, 진행 상황, 누적 의사결정 로그	AI의 단기/장기 기억 저장소
PORTFOLIO.md	Final Output	아키텍처, 기술 스택, 핵심 기능, 정제된 트러블슈팅 Top 3 요약	최종 제출용 정리 문서

💡 docs/ 폴더 vs CLAUDE.md 역할 충돌 해결
docs/troubleshooting.md나 docs/decision_log.md 생성을 할 수도 있지만, 클로드 코드가 작업 맥락을 실시간으로 파악하기에는 CLAUDE.md 단일 파일로 단권화하는 것이 훨씬 효율적이다. 파편화를 막기 위해 단기 트러블슈팅 기록은 CLAUDE.md 하단에 누적하고, 프로젝트 완료 시 PORTFOLIO.md로 한 번에 추출한다.

 

2. 자동화의 중심: CLAUDE.md 템플릿

프로젝트 루트 디렉토리에 위치하는 CLAUDE.md는 Claude Code가 작업을 수행할 때 지속적으로 읽고 업데이트하는 핵심 가이드 문서다. 개발 시작 시 아래 구조로 초기화해 둔다.

# [프로젝트 이름] 개발 가이드 및 상태판

## 1. 프로젝트 개요 & 기술 스택
- **목적**: [프로젝트에 대한 한 줄 설명]
- **Tech Stack**: [예: Java, Spring Boot, MySQL, Redis, Docker]
- **핵심 아키텍처**: [예: Layered Architecture / Event-Driven]

## 2. 실행 및 개발 명령어 (Build & Development Commands)
클로드는 작업을 검증하거나 테스트할 때 아래 명령어를 사용합니다.
- **의존성 설치**: `./gradlew build`
- **개발 서버 실행**: `./gradlew bootRun`
- **테스트 실행**: `./gradlew test`

## 3. 코드 스타일 및 아키텍처 가이드라인 (Style Guidelines)
- **언어 및 패러다임**: 객체지향 설계 준수, Layer 간 의존성 방향 엄격 유지.
- **에러 핸들링**: Custom Exception 정의 및 GlobalExceptionHandler를 통한 통합 처리.

## 4. 현재 진행 상황 및 로드맵 (Current Progress & Roadmap)
- [x] Milestone 1: 프로젝트 초기 세팅 및 DB 스키마 설계
- [/] Milestone 2: 핵심 API 연동 및 상태 관리 구현 (진행 중)
  - [x] GitHub Issue #1: JWT 인증 및 Authorization Filter 구현
  - [ ] GitHub Issue #2: Redis 기반 동시성 제어 로직 적용 (`working`)

## 5. 의사결정 및 트러블슈팅 로그 (Decision & Troubleshooting Log)
*포트폴리오 추출을 위해 아키텍처 결정 사항이나 버그 해결 내역을 누적 기록합니다.*
- **[2026-08-12] #1 이슈 해결**: JWT 토큰 만료 시 Refresh Token 갱신 로직 예외 처리 구조 개선

 

3. 단계별 실전 작업 워크플로우 (3-Step Pipeline)

Step 1. 작업 시작: GitHub Issue 생성 및 계획 수립

브라우저를 열지 않고 터미널 내 클로드 코드 환경에서 GitHub CLI(gh)를 연동하여 이슈를 즉시 생성하고 계획을 수립한다.

프롬프트 템플릿:
"현재 구현하려는 [기능/버그 이름]에 대한 GitHub Issue를 생성해 줘.
제목은 '[Feat] 기능 이름'으로 하고, 본문에는 요구사항을 담아줘.
이슈가 생성되면 이슈 번호를 확인하고, 그 이슈를 해결하기 위한 단계별 구현 계획(/plan)을 세워줘."

Step 2. 작업 진행: 시행착오 및 트러블슈팅 실시간 기록

개발 중 에러나 기술 검토(Why)가 발생하면, 이슈의 댓글(Comment)로 기록을 남기도록 프롬프트를 실행한다.

프롬프트 템플릿:
"방금 발생한 에러와 해결 과정(선택한 대안, 수정된 로직 등)을
방금 생성한 GitHub Issue에 댓글(Comment)로 등록해 줘.
나중에 포트폴리오를 작성할 때 이 '왜(Why)'에 대한 기록이 중요하니 구체적으로 남겨줘."

Step 3. 작업 완료: 커밋, 이슈 종료 및 CLAUDE.md 누적

구현이 완료되면 이슈를 닫고, 지금까지의 맥락을 CLAUDE.md의 로그 섹션에 반영한다.

프롬프트 템플릿:
"구현이 완료되었으니 코드를 커밋해 줘.
커밋 메시지 끝에는 Closes #[이슈번호]를 붙여서 이 이슈가 자동으로 닫히도록 해줘.
그리고 이 이슈에 남은 대화 내용과 최종 코드를 요약해서
프로젝트 루트의 CLAUDE.md 파일의 'Decision & Troubleshooting Log' 섹션에 누적해 줘."

Step 4. 컨텍스트 비우기 (Context Reset)

한 작업 단위(3 Step)가 종료되면 터미널을 새로 열거나 /compact 명령으로 컨텍스트를 초기화한다. 모든 주요 의사결정 사항과 진행 상황이 CLAUDE.md 및 GitHub Issue에 수집되어 있으므로 이전 맥락이 손실되지 않으며, 클로드의 토큰 소모를 줄이고 응답 속도와 분석 정확도를 높일 수 있다.

 

4. 최종 포트폴리오 문서 자동 추출

개발 프로젝트가 완료되면 누적된 자료를 바탕으로 제출용 포트폴리오 문서를 자동 생성한다.

최종 추출 프롬프트:
"그동안 CLAUDE.md에 누적된 '의사결정 로그'와 GitHub Issue 내역을 기반으로,
취업/이직 제출용 전문 마크다운 포트폴리오 파일(PORTFOLIO.md)을 생성해 줘.

포함할 내용:
1. 프로젝트 개요 및 전체 디렉토리 구조
2. API 스펙 문서 요약 (주요 요청/응답 예시 및 에러 코드)
3. 아키텍처 및 기술 스택 선택 이유
4. 핵심 트러블슈팅 3가지 사례 (문제 상황 -> 원인 분석 -> 해결책 -> 성과/배운점)

추가로, PORTFOLIO.md 작성이 완료되면 이를 바탕으로 Web 상에서 바로 배포하거나 확인할 수 있는 원페이지 포트폴리오 HTML 파일(index.html)도 생성해줘."

 

6. 요약: 자동화 파이프라인 핵심 체크리스트

• 코드 중심 기록(Fact) -> Git Commit
• 시행착오 및 이유(Why) -> GitHub Issue (댓글로 추적)
• 프로젝트 진행 및 의사결정 현황 -> CLAUDE.md 단권화
• 작업 마감 시 컨텍스트를 비우고, 프로젝트 완료 시 PORTFOLIO.md 및 index.html 일괄 추출