20 KiB
20 KiB
백엔드 포트폴리오 작성 컨벤션 컨텍스트
1. 문서 목적
이 문서는 백엔드 개발자 포트폴리오를 작성할 때 참고하는 작성 컨벤션 문서이다.
LLM 또는 문서 작성 도구는 프로젝트 소스 코드, README, API 문서, 설계 문서, 배포 파일, 테스트 코드 등을 분석한 뒤 이 컨벤션에 맞춰 포트폴리오 내용을 작성해야 한다.
포트폴리오의 목표는 단순히 “무엇을 만들었다”를 설명하는 것이 아니라, 다음 흐름을 명확히 보여주는 것이다.
문제 인식 → 설계 판단 → 구현 방식 → 기술 선택 이유 → 결과 및 회고
2. 적용 대상
이 컨벤션은 다음 유형의 프로젝트 포트폴리오 작성에 사용한다.
- 백엔드 프로젝트
- 백엔드 + 인프라 프로젝트
- 백엔드 + 설계 중심 프로젝트
- 풀스택 프로젝트 중 백엔드 기여를 강조해야 하는 경우
- 라이브러리형 프로젝트 중 API, 구조, 확장성, 사용성 설계를 강조해야 하는 경우
3. 핵심 작성 원칙
3.1 기능 나열보다 문제 해결 중심으로 작성한다
단순히 구현한 기능을 나열하지 않는다.
좋지 않은 표현:
프로젝트 생성 기능을 구현했습니다.
권장 표현:
사용자가 프로젝트 단위로 작업 공간을 분리해 관리할 수 있도록 프로젝트 생성 API를 설계하고 구현했습니다. 생성 시 요청 값을 검증한 뒤 프로젝트를 저장하고, 생성자를 관리자 멤버로 자동 등록하여 생성 직후 권한 기반 기능을 사용할 수 있도록 처리했습니다.
3.2 문장은 문제 → 선택 → 구현 → 결과 구조를 우선한다
가장 중요한 문장 구조는 다음과 같다.
저는 [문제]를 해결하기 위해 [기술/구조]를 선택했고, [구현 방식]으로 처리하여 [결과]를 만들었습니다.
예시:
저는 프로젝트 관련 API마다 권한 검증 로직이 반복되는 문제를 해결하기 위해 공통 권한 검증 필터를 설계했고, API 진입 시점에서 인증 사용자와 프로젝트 접근 권한을 먼저 검증하도록 처리하여 권한 검증 누락 가능성을 줄였습니다.
3.3 기술 스택은 이름보다 선택 이유를 강조한다
기술 이름만 나열하지 않는다.
좋지 않은 표현:
ASP.NET Core, PostgreSQL, Docker를 사용했습니다.
권장 표현:
ASP.NET Core는 인증, DI, 미들웨어 구성이 잘 통합되어 있어 API 서버 구조화에 적합하다고 판단했습니다. PostgreSQL은 사용자, 프로젝트, 참여자처럼 관계가 명확한 데이터를 안정적으로 관리하기 위해 선택했습니다. Docker Compose는 백엔드, DB, Redis 등 여러 서비스를 동일한 환경에서 실행하기 위해 사용했습니다.
3.4 백엔드 관점의 내부 흐름을 드러낸다
화면 기능보다 서버 내부 처리 흐름을 중심으로 작성한다.
반드시 드러내야 하는 요소:
- API 요청이 들어온 뒤 어떤 순서로 처리되는가
- 인증 사용자를 어떻게 식별하는가
- 권한을 어디에서 검증하는가
- 요청 DTO와 도메인 모델을 어떻게 분리하는가
- 데이터 저장 시 어떤 관계를 함께 처리하는가
- 비즈니스 실패와 시스템 예외를 어떻게 구분하는가
- 트랜잭션, 동시성, 상태 전이를 어떻게 고려했는가
- 비동기 작업이나 배포 환경을 어떻게 구성했는가
3.5 과장하지 않고 근거 기반으로 작성한다
수치가 없는 성과를 임의로 만들지 않는다.
수치가 있으면 수치로 작성한다.
파일 목록 조회 API 응답 시간을 평균 850ms에서 220ms로 개선했습니다.
수치가 없으면 구조적 개선으로 작성한다.
권한 검증 로직을 공통 필터로 분리하여 엔드포인트별 중복을 줄이고, 프로젝트 관련 API에 일관된 접근 제어를 적용할 수 있도록 했습니다.
4. 문체 컨벤션
4.1 기본 문체
- 한국어로 작성한다.
- 포트폴리오 본문은
했습니다,구현했습니다,설계했습니다형태의 존댓말 과거형을 사용한다. - 지나치게 감성적인 표현보다 구체적인 기술 표현을 사용한다.
- 한 문단은 너무 길게 작성하지 않는다.
- 한 문단에는 하나의 핵심 메시지만 담는다.
4.2 주어 사용
개인 기여를 강조해야 할 때는 저는을 사용한다.
권장:
저는 백엔드 개발자로 참여하여 인증/인가 흐름과 프로젝트 관리 API를 담당했습니다.
팀 전체 성과는 팀은 또는 프로젝트에서는으로 작성한다.
프로젝트에서는 Docker Compose 기반 실행 환경을 구성하여 팀원이 동일한 개발 환경을 빠르게 실행할 수 있도록 했습니다.
4.3 금지 표현
다음 표현은 구체성이 부족하므로 사용하지 않는다.
열심히 참여했습니다.
팀원들을 도왔습니다.
프로젝트 전반에 기여했습니다.
기능을 만들었습니다.
DB에 저장했습니다.
문제를 해결했습니다.
성능을 개선했습니다.
협업을 잘했습니다.
위 표현은 반드시 구체화한다.
예시:
프로젝트 생성, 초대 코드 발급, 초대 코드 기반 참여 API를 담당했으며, 프로젝트 도메인의 생성·조회·참여 흐름을 구현했습니다.
5. 포트폴리오 섹션 구조 컨벤션
포트폴리오는 기본적으로 다음 순서로 작성한다.
# 프로젝트명
## 1. 프로젝트 개요
## 2. 담당 역할
## 3. 주요 기여
## 4. 사용 기술 및 선택 이유
## 5. 구현 사항
## 6. 문제 해결 사례
## 7. 프로젝트 성과
## 8. 프로젝트 회고
6. 섹션별 작성 규칙
6.1 프로젝트 개요
목적
이 프로젝트가 왜 필요했고, 어떤 문제를 해결하려 했는지 설명한다.
반드시 포함할 내용
- 프로젝트 배경
- 기존 방식 또는 문제 상황
- 해결하고자 한 문제
- 프로젝트 목표
- 주요 기능 키워드
작성 형식
본 프로젝트는 [문제 상황]을 해결하기 위해 개발한 [서비스 유형]입니다.
기존에는 [기존 방식의 문제점]으로 인해 사용자가 [불편함/비효율]을 겪었습니다. 이를 해결하기 위해 [핵심 목표]를 중심으로 서비스를 설계했습니다.
주요 기능은 다음과 같습니다.
- [핵심 기능 1]
- [핵심 기능 2]
- [핵심 기능 3]
작성 기준
좋지 않은 표현:
책을 추천하는 프로그램입니다.
권장 표현:
사용자의 관심사와 독서 이력을 기반으로 도서를 추천하고, 추천 결과를 저장·관리할 수 있는 개인화 도서 추천 서비스입니다.
6.2 담당 역할
목적
팀 안에서 본인이 어떤 책임을 맡았는지 설명한다.
반드시 포함할 내용
- 본인의 역할
- 담당 도메인
- 팀 내 역할 분배
- 본인이 책임진 기능 범위
작성 형식
저는 백엔드 개발자로 참여하여 [담당 도메인] 영역을 주로 담당했습니다.
주요 역할은 다음과 같습니다.
- API 설계 및 구현
- 데이터베이스 모델링
- 인증/인가 흐름 설계
- 비즈니스 로직 구현
- 예외 처리 및 응답 구조 정리
- 배포 환경 구성
작성 기준
좋지 않은 표현:
팀원들을 도와 프로젝트를 수행했습니다.
권장 표현:
저는 백엔드 영역 중 사용자 인증, 프로젝트 생성, 초대 코드 기반 참여 기능을 담당했으며, API 요청부터 데이터 저장까지의 흐름을 설계하고 구현했습니다.
6.3 주요 기여
목적
업무 단위로 본인이 무엇을 구현했는지 구체적으로 설명한다.
반드시 포함할 내용
- 구현한 기능
- 기능별 책임 범위
- 사용한 기술
- 설계 판단
- 기여도
작성 형식
제가 담당한 주요 업무는 다음과 같습니다.
### 1. [기여 영역 1]
- [구현 내용]
- [설계 내용]
- [처리 흐름]
### 2. [기여 영역 2]
- [구현 내용]
- [설계 내용]
- [처리 흐름]
작성 기준
좋지 않은 표현:
프로젝트 전반적으로 기여했습니다.
권장 표현:
프로젝트 생성, 초대 코드 발급, 초대 코드 기반 참여 API를 담당했으며, 프로젝트 도메인의 핵심 생성·조회·참여 흐름을 구현했습니다.
6.4 사용 기술 및 선택 이유
목적
기술 스택을 단순 나열하지 않고, 프로젝트 요구사항과 연결해 설명한다.
반드시 포함할 내용
- 사용 기술
- 사용 목적
- 선택 이유
- 대안과 비교
- 프로젝트 요구사항과의 연결
작성 형식
| 기술 | 사용 목적 | 선택 이유 |
|---|---|---|
| [기술명] | [사용 목적] | [프로젝트 요구사항과 연결된 선택 이유] |
작성 기준
기술 선택 이유는 다음 질문에 답해야 한다.
왜 이 기술을 사용했는가?
이 프로젝트의 어떤 요구사항과 맞았는가?
다른 선택지 대신 이 기술을 고른 이유는 무엇인가?
이 기술을 사용해 어떤 구조적 이점을 얻었는가?
6.5 구현 사항
목적
기능을 단순 나열하지 않고, 사용자의 요청이 서버 내부에서 어떻게 처리되는지 설명한다.
반드시 포함할 내용
- 핵심 기능
- API 처리 흐름
- 데이터 처리 방식
- 인증/인가
- 예외 처리
- 트랜잭션 또는 상태 관리
작성 형식
### [기능명]
[사용자 요청 또는 문제 상황]이 발생하면 서버는 [처리 방식]으로 요청을 처리합니다.
구현 흐름은 다음과 같습니다.
1. [요청 검증]
2. [현재 사용자 식별]
3. [권한 검증]
4. [도메인 로직 실행]
5. [데이터 저장]
6. [응답 반환]
주요 고려사항은 다음과 같습니다.
- [고려사항 1]
- [고려사항 2]
- [고려사항 3]
작성 기준
좋지 않은 표현:
데이터베이스에 데이터를 저장했습니다.
권장 표현:
프로젝트 생성 시 Project와 ProjectUser를 함께 저장하여 생성자가 자동으로 관리자 권한을 갖도록 처리했습니다. 이를 통해 프로젝트 생성 직후 권한 기반 기능을 바로 사용할 수 있도록 설계했습니다.
6.6 문제 해결 사례
목적
단순 경험담이 아니라 문제 분석과 해결 과정을 보여준다.
반드시 포함할 내용
- 문제 상황
- 원인 분석
- 해결 방법
- 선택 이유
- 결과
작성 형식
### 문제 상황
[무슨 문제가 있었는지]
### 원인 분석
[왜 문제가 발생했는지]
### 해결 방법
[어떤 방식으로 해결했는지]
### 선택 이유
[왜 그 방법을 선택했는지]
### 결과
[해결 후 어떤 변화가 있었는지]
작성 기준
좋지 않은 표현:
캐싱 전략으로 문제를 해결했습니다.
권장 표현:
반복 조회되는 사용자 권한 정보를 매 요청마다 DB에서 조회하면서 응답 시간이 증가하는 문제가 있었습니다. 이를 해결하기 위해 권한 정보를 짧은 TTL로 캐싱하여 DB 조회 횟수를 줄였고, 권한 변경 시 캐시 무효화 전략을 함께 적용했습니다.
6.7 프로젝트 성과
목적
구현 결과가 프로젝트에 어떤 영향을 주었는지 설명한다.
반드시 포함할 내용
- 성능 개선 수치
- API 응답 시간 변화
- 코드 중복 감소
- 테스트 커버리지
- 배포 자동화
- 기능 완성도
- 협업 효율
작성 기준
수치가 있으면 수치 기반으로 작성한다.
파일 목록 조회 API 응답 시간을 평균 850ms에서 220ms로 개선했습니다.
수치가 없으면 구조적 성과로 작성한다.
공통 응답 DTO와 에러 응답 구조를 정리하여 API 응답 형식을 일관화했습니다.
6.8 프로젝트 회고
목적
단순한 감상이 아니라 백엔드 개발자로서 배운 점과 다음 개선 방향을 작성한다.
반드시 포함할 내용
- 배운 점
- 아쉬웠던 점
- 개선하고 싶은 점
- 다음 프로젝트에 적용할 점
작성 기준
좋지 않은 표현:
시간이 부족해서 모든 기능을 구현하지 못했습니다.
권장 표현:
초기에는 기능 구현을 우선하면서 테스트 자동화와 성능 측정을 충분히 진행하지 못했습니다. 이후에는 핵심 API부터 통합 테스트를 작성하고, 응답 시간 기준을 함께 정의하는 방식으로 개선하고자 합니다.
7. 백엔드 포트폴리오 강조 포인트
백엔드 개발자 포트폴리오에서는 화면보다 다음 내용을 우선한다.
- API를 어떻게 설계했는가
- 인증/인가를 어떻게 처리했는가
- 데이터 모델을 어떻게 설계했는가
- 트랜잭션이나 동시성 문제를 어떻게 고려했는가
- 예외와 에러 응답을 어떻게 구분했는가
- 성능 병목을 어떻게 발견하고 개선했는가
- 유지보수하기 쉬운 구조를 위해 어떤 선택을 했는가
- 배포 환경과 운영 고려사항을 어떻게 구성했는가
8. 백엔드 + 인프라 + 설계 프로젝트 작성 규칙
백엔드와 인프라, 설계 요소가 함께 있는 프로젝트는 다음 항목을 추가로 강조한다.
8.1 아키텍처 설계
다음 내용을 작성한다.
- 전체 시스템 구조
- API 서버의 책임
- DB, Cache, Storage, Worker, Reverse Proxy의 역할
- 모듈 간 의존성 분리
- Clean Architecture 또는 계층 분리 기준
작성 예시:
백엔드 API는 인증, 권한 검증, 도메인 로직, 메타데이터 관리를 담당하고, 업로드 서버는 대용량 파일 전송을 전담하도록 역할을 분리했습니다. 이를 통해 API 서버가 파일 청크 전송 부하를 직접 처리하지 않도록 설계했습니다.
8.2 데이터 모델링
다음 내용을 작성한다.
- 핵심 엔티티
- 엔티티 간 관계
- unique 제약 또는 인덱스
- soft delete 여부
- 상태 값과 상태 전이
- 정합성 보장 방식
작성 예시:
프로젝트와 참여자 관계를 별도 테이블로 분리하여 사용자별 참여 프로젝트를 조회할 수 있도록 설계했습니다. 생성자는 프로젝트 생성과 동시에 관리자 역할로 등록되도록 처리하여 권한 기반 기능을 바로 사용할 수 있게 했습니다.
8.3 인증/인가
다음 내용을 작성한다.
- 인증 방식
- 현재 사용자 식별 방식
- 권한 검증 위치
- 역할과 권한의 관계
- 권한 실패 시 응답 방식
작성 예시:
인증 사용자를 식별한 뒤 프로젝트 멤버 여부와 역할 기반 권한을 검증하도록 구성했습니다. 권한 검증은 개별 엔드포인트에 흩어지지 않도록 공통 필터로 분리하여 API 진입 시점에서 일관되게 처리했습니다.
8.4 예외 처리 및 응답 구조
다음 내용을 작성한다.
- 성공 응답 DTO
- 에러 응답 DTO
- 비즈니스 실패 처리 방식
- 시스템 예외 처리 방식
- 로깅 기준
작성 예시:
예상 가능한 비즈니스 실패는 Result 기반으로 반환하고, 예상하지 못한 시스템 예외는 예외 처리 미들웨어에서 일괄 처리하도록 분리했습니다. 이를 통해 클라이언트 응답 형식과 서버 로깅 책임을 명확히 나눴습니다.
8.5 배포 및 운영 환경
다음 내용을 작성한다.
- Docker Compose 구성
- Reverse Proxy 구성
- 환경 변수 관리
- DB/Redis 등 외부 의존성 실행 방식
- 로그/모니터링 고려사항
작성 예시:
Docker Compose를 사용해 API 서버, 데이터베이스, Redis를 동일한 실행 환경으로 구성했습니다. 이를 통해 신규 팀원이 로컬 개발 환경을 빠르게 구성할 수 있도록 했고, 배포 환경에서도 서비스 간 의존성을 명확히 관리할 수 있게 했습니다.
9. LLM이 프로젝트를 분석할 때 추출해야 하는 정보
LLM이 Claude Code, Codex, Cursor, 기타 코드 분석 도구를 통해 프로젝트를 읽을 때는 다음 정보를 우선 추출한다.
9.1 기본 정보
- 프로젝트명
- 프로젝트 유형
- 한 줄 설명
- 해결하려는 문제
- 주요 사용자
- 핵심 기능 목록
9.2 백엔드 구조
- 사용 언어 및 프레임워크
- 프로젝트 폴더 구조
- 계층 구조
- Controller / Endpoint 구조
- UseCase / Service 구조
- Repository 구조
- Domain 모델 구조
- DTO 구조
9.3 API 정보
- 주요 API endpoint
- HTTP method
- request DTO
- response DTO
- 인증 필요 여부
- 권한 필요 여부
- API 처리 흐름
- 실패 케이스
9.4 데이터 모델 정보
- 핵심 테이블 또는 엔티티
- 주요 필드
- 관계
- 인덱스
- 제약 조건
- 상태 enum
- soft delete 여부
- 트랜잭션이 필요한 흐름
9.5 인증/인가 정보
- 로그인 방식
- 토큰 또는 세션 방식
- 현재 사용자 식별 방식
- 역할 모델
- 권한 모델
- 권한 검증 위치
- 인증/권한 실패 응답
9.6 인프라 정보
- Docker Compose 구성
- DB 종류
- Cache/Queue 사용 여부
- Reverse Proxy 사용 여부
- Storage 사용 여부
- 배포 방식
- 환경 변수 구성
- 로그/모니터링 구성
9.7 품질 개선 정보
- 테스트 코드 존재 여부
- 통합 테스트 여부
- 성능 개선 사례
- 리팩토링 사례
- 중복 제거 사례
- 장애 또는 예외 처리 개선 사례
- CI/CD 구성 여부
10. LLM 출력 규칙
LLM은 프로젝트 분석 결과를 다음 순서로 출력한다.
# [프로젝트명] 포트폴리오 정리
## 1. 프로젝트 개요
## 2. 담당 역할
## 3. 주요 기여
## 4. 사용 기술 및 선택 이유
## 5. 주요 구현 사항
## 6. 문제 해결 사례
## 7. 프로젝트 성과
## 8. 프로젝트 회고
## 9. 포트폴리오에 강조하면 좋은 키워드
## 10. 추가로 확인하면 좋은 정보
11. 작성 품질 체크리스트
포트폴리오 초안을 작성한 뒤 다음 기준으로 검토한다.
- [ ] 프로젝트가 해결하려는 문제가 명확한가?
- [ ] 단순 기능 나열이 아니라 설계 판단이 드러나는가?
- [ ] 본인의 역할과 팀의 역할이 구분되어 있는가?
- [ ] 기술 스택마다 선택 이유가 작성되어 있는가?
- [ ] API 내부 처리 흐름이 설명되어 있는가?
- [ ] 인증/인가, DB 설계, 예외 처리 중 최소 하나 이상이 강조되어 있는가?
- [ ] 문제 해결 사례가 문제 → 원인 → 해결 → 결과 흐름으로 작성되어 있는가?
- [ ] 성과를 수치 또는 구조적 개선으로 설명했는가?
- [ ] 과장되거나 근거 없는 표현이 없는가?
- [ ] 면접에서 질문받아도 설명 가능한 내용인가?
12. 최종 작성 기준
최종 문서는 다음 기준을 만족해야 한다.
좋은 포트폴리오는 “무엇을 만들었는가”보다 “왜 그렇게 설계했고, 어떻게 문제를 해결했는가”를 보여준다.
따라서 모든 문장은 가능하면 다음 중 하나를 포함해야 한다.
- 문제 상황
- 설계 판단
- 구현 흐름
- 기술 선택 이유
- 결과
- 회고와 개선 방향
최종적으로 포트폴리오 문장은 다음 형태에 가까워야 한다.
저는 [문제]를 해결하기 위해 [기술/구조]를 선택했고, [구현 방식]으로 처리하여 [결과]를 만들었습니다.