취업용 GitHub 정리: Profile README · 저장소 README · pinned repository

커리어·포트폴리오 · 8 / 19

GitHub를 단순 코드 저장 공간이 아니라 프로젝트 근거를 빠르게 확인할 수 있는 공개 프로필로 정리합니다.

상단에서는 이 주제의 판단 기준을 가상 사례와 완성 예시로 연습합니다. 이전 회차의 문서는 필요 없습니다. 하단의 TaskFlow 누적 적용에서는 같은 기준으로 자신의 포트폴리오 자료를 이어서 만듭니다. TaskFlow는 학습용 프로젝트 사례이며 예시 경력·성과를 자신의 사실로 사용하지 않습니다.

이번 글에서 배우는 내용

• Profile README 역할
• GitHub profile의 pinned repositories
• 저장소 README 기본 구조
• 프로젝트 목적·실행 방법·기술 선택·검증·링크
• repository description/topics
• demo URL과 screenshot
• issue/PR/history가 보여 주는 작업 과정
• 불필요한 generated file·secret·임시 파일 정리
• archived/private repository 표기 기준
• README 장식보다 탐색성과 근거를 우선

선수 지식

GitHub 계정과 저장소의 차이를 이해하면 됩니다. 계정이 없어도 로컬 README 초안을 작성할 수 있으며 공개 업로드는 이 글의 완료 조건이 아닙니다.

목차

1. 프로필과 저장소 README의 역할
2. 독립 실습과 완성 예시
3. 자주 발생하는 문제와 해결
4. 학습 완료 체크리스트
5. TaskFlow 누적 적용
6. 완료 체크포인트
7. 다음 학습

프로필과 저장소 README의 역할

Profile README는 누구이며 어떤 작업을 볼지 안내하고, 저장소 README는 그 프로젝트의 목적·실행·검증·한계를 안내합니다. profile의 pinned 항목은 대표 저장소나 gist를 빠르게 찾게 합니다. 채용 평가를 보장하는 장식이 아닙니다.

GitHub 공식 문서에 따르면 사용자명과 같은 이름의 공개 저장소, 루트의 내용 있는 README.md가 있어야 Profile README가 표시됩니다. 관리형 사용자 계정에서는 이 기능을 사용할 수 없습니다. 프로필의 Customize your pins에서 저장소와 gist를 합해 최대 6개를 선택하고 Save pins로 저장합니다. 꼭 최대 개수를 채울 필요는 없습니다. Profile README 공식 안내, 고정 항목 공식 안내.

저장소 description/topics는 주제를 간단히 표현하고, demo와 캡처는 현재 동작·촬영 상태를 구분합니다. archived는 유지보수 상태를 설명하며 private 저장소는 방문자가 볼 수 있다고 안내하지 않습니다. 생성 파일은 프로젝트 정책에 따라 관리하고 비밀값을 단순히 화면에서 지웠다고 과거 이력까지 안전하다고 단정하지 않습니다.

독립 실습과 완성 예시

가상 저장소의 README에는 배지와 기술 이름만 있고 실행·검증 상태가 없습니다. 독자가 목적과 현재 상태를 바로 이해하도록 소개를 다시 써 보세요.

풀이와 판단 근거

완성 소개 예시: ‘TaskFlow는 입력과 상태 흐름을 학습하는 개인 프로젝트입니다. 현재 공개용 README를 작성 중이며 이 문서에는 실제 저장소 실행을 확인한 명령만 추가합니다. 데모와 테스트 결과는 확인 전이므로 제공하지 않습니다. 설계 판단은 케이스 스터디, 검증 자료는 증거 기록에서 구분해 관리합니다.’

실제 저장소에 적용할 때는 package.json의 스크립트와 lockfile을 읽어 패키지 매니저·설치·실행·검증 명령을 기록합니다. 존재하지 않는 npm test를 관성적으로 넣지 않습니다. 새 환경에서 재현하지 않았다면 그 한계를 표시합니다.

실행 안내의 완성 예시

가상 저장소의 제공 계약이 ‘Node.js 24, pnpm 11.19.0, pnpm-lock.yaml, dev·lint·build 스크립트, test 스크립트 없음’이라고 주어졌다고 가정합니다. 이 조건을 확인한 README는 다음처럼 작성합니다. 이 명령을 이번 글에서 실제 실행했다는 뜻은 아닙니다.

환경: Node.js 24 / pnpm 11.19.0
설치: pnpm install --frozen-lockfile
로컬 확인: pnpm dev
확인 주소: 터미널이 출력한 로컬 주소
정적 검사: pnpm lint
빌드: pnpm build
자동 테스트: test 스크립트가 없어 제공하지 않음
명령 실행 결과: 이 문서 예시에서는 실행하지 않음

독자는 자기 저장소의 계약이 다르면 명령도 바꿔야 합니다. build 성공은 접근성·실사용자 동작의 전체 검증을 뜻하지 않습니다.

자주 발생하는 문제와 해결

• 배지가 목적 설명을 가리면 소개를 먼저 둡니다.
• README에 없는 명령을 추측해 적지 말고 실제 스크립트를 확인합니다.
• 비공개 저장소와 미확인 demo를 누구나 볼 수 있는 근거로 안내하지 않습니다.

개인 프로젝트와 실무 경험은 분리합니다. 팀 작업은 내가 맡은 범위와 팀 전체 결과를 따로 쓰고, 근거가 없는 수치·기간·실행 결과는 추가하지 않습니다. 비공개 자료는 익명화만으로 공개 권한이 생기지 않으므로 허용 범위를 먼저 확인합니다.

학습 완료 체크리스트

• Profile README와 저장소 README의 목적을 구분했습니다.
• 사용자명 저장소 조건과 고정 항목의 역할을 이해했습니다.
• 실제 실행 확인 전 명령을 통과한 것처럼 적지 않았습니다.

# GitHub README 초안 묶음 — 가상 작성 예시

## Profile README 문안
개인 프로젝트로 화면·상태·검증 기록을 학습합니다.
대표 후보는 TaskFlow이며 본인 판단과 확인 가능한 근거를 정리 중입니다.
회사 운영·팀 협업 경력으로 소개하지 않습니다.
공개 링크는 권한과 접근 확인 후 실제 주소를 연결합니다.

## TaskFlow 저장소 README 문안
목적: 입력과 상태 흐름을 설명하는 개인 학습
주요 내용: 본인이 구현한 범위만 기능 목록에 반영
기술 선택: case-study.md의 대안과 제약 설명
가상 환경 계약: Node.js 24 / pnpm 11.19.0 / pnpm-lock.yaml
설치·실행: pnpm install --frozen-lockfile → pnpm dev
검사 명령: pnpm lint / pnpm build
자동 테스트: 가상 계약에 test 스크립트 없음
검증 상태: 실행 결과 미확인, 통과 주장 없음
데모: 이 문서 실습에서는 제공하지 않음
자료 연결 계획: evidence-log.md와 case-study.md
한계: 실제 저장소용 README로 제출하기 전 명령·주소 검증 필요

## 고정 후보
TaskFlow 1개 우선 검토. 공개 권한 확인 전 실제 고정 작업은 하지 않음.

career-step-08-github

다음 학습

09편 「개발자 포트폴리오 사이트 구성: 홈 · 프로젝트 목록 · 상세 페이지」로 이어집니다. 이번 문서의 사실과 미확인 항목을 다음 회차 입력으로 사용합니다.