5분
README.md - 프로젝트의 얼굴을 만들어라
Day 1: 기술 문서화 - 코드를 넘어 이야기를 남겨라
README.md - 프로젝트의 얼굴을 만들어라
발표 & 포트폴리오 > Day 1: 기술 문서화 - 코드를 넘어 이야기를 남겨라
학습 목표
- 채용 담당자가 README를 보는 순서를 이해한다
- 제조 AI 프로젝트에 최적화된 README 구조를 파악한다
- GitHub 배지와 시각 요소 활용법을 익힌다
채용 담당자의 눈으로 보는 README
GitHub 링크를 받은 채용 담당자. 이 사람이 프로젝트를 평가하는 데 걸리는 시간: 30초.
채용 담당자의 시선 흐름 (Eye-tracking 연구 기반)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1초 → 프로젝트 제목 + 배지 (신뢰감)
3초 → 한 줄 소개 (뭘 하는 프로젝트?)
5초 → 스크린샷/GIF (실제 동작하나?)
10초 → 기술 스택 표 (내가 아는 기술?)
20초 → 설치 방법 (실행 가능?)
30초 → 판단 완료 (면접 부를까 말까)
결론: README는 30초 안에 승부를 봐야 한다.제조 AI 프로젝트 README 구조
일반 프로젝트와 다른 점이 있다. 제조 도메인은 문제 정의가 핵심이다.
필수 섹션 (10개)
| 순서 | 섹션 | 핵심 질문 | 분량 |
|---|---|---|---|
| 1 | 프로젝트명 + 배지 | 신뢰할 수 있는 프로젝트인가? | 2줄 |
| 2 | 한 줄 소개 | 이게 뭔가? | 1줄 |
| 3 | 문제 정의 | 왜 만들었는가? | 3-5줄 |
| 4 | 스크린샷/데모 | 실제로 동작하는가? | 이미지 |
| 5 | 주요 기능 | 뭘 할 수 있는가? | 3-5개 |
| 6 | 아키텍처 | 어떻게 만들었는가? | 다이어그램 |
| 7 | 기술 스택 | 어떤 기술을 썼는가? | 표 |
| 8 | 설치 방법 | 어떻게 실행하는가? | 5-10줄 |
| 9 | 사용 예시 | 어떻게 쓰는가? | 코드 블록 |
| 10 | 성과 지표 | 얼마나 잘 동작하는가? | 표 |
문제 정의가 특히 중요한 이유
일반 프로젝트의 소개:
"AI 기반 챗봇 시스템입니다."
→ 그래서? 세상에 챗봇이 몇 개인데?제조 AI 프로젝트의 소개:
## 문제
- 연간 비계획 정지 시간: 평균 ___시간 (사내 설비 이력에서 집계)
- 설비 고장 시 조치 매뉴얼 검색: 평균 ___분 (본인 측정값)
- 숙련 기술자 은퇴로 트러블슈팅 지식 유실 위기
## 솔루션
Knowledge Graph + RAG 기반 트러블슈팅 어시스턴트
- 에러코드 입력 → ___초 내 조치 방법 제시 (본인 측정값)
- 과거 고장 이력 기반 패턴 분석
- 신입도 숙련자 수준의 문제 해결 가능차이가 느껴지는가? 자리마다 숫자가 들어가고, 그래서 문제가 구체적으로 읽힌다. 빈칸은 본인이 측정하거나 사내 이력에서 확인한 값으로 채운다. 채울 값이 아직 없으면 빈칸으로 두는 편이 낫다. 지어낸 숫자를 채우는 순간 README는 근거가 아니라 주장이 되고, 그 문서는 이력서와 면접에서 그대로 인용된다.
GitHub 배지 활용
# 기술 스택 배지 (shields.io)
# 라이선스 배지 (상태 배지는 CI가 만들 때만 단다)
배지에는 두 종류가 있다.
위의 기술 스택 배지와 라이선스 배지는 shields.io가 적어 준 글자를 그대로 그리는 정적 배지다.
빌드·테스트·커버리지는 CI가 실행 결과를 읽어 갱신하는 동적 배지일 때만 신호가 된다.
tests-42_passed를 정적 배지로 붙이면 테스트가 한 줄도 없어도 언제나 초록으로 표시되므로,
그것은 관리의 신호가 아니라 거짓 표시다.
테스트와 GitHub Actions 워크플로가 없다면 상태 배지도 달지 않는다.
기술 스택 표 작성법
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **LLM** | OpenAI GPT-4o | latest | 메인 추론 엔진 |
| **sLLM** | QLoRA Fine-tuned | Llama 4 Scout | 제조 특화 Q&A |
| **RAG** | LangChain + ChromaDB | 1.0+ | 문서 검색 증강 |
| **KG** | Neo4j + Cypher | 5.x | 설비-공정 관계 |
| **Agent** | LangGraph | 1.0+ | 멀티 에이전트 오케스트레이션 |
| **Backend** | FastAPI | 0.115+ | REST API |
| **Frontend** | Streamlit/Gradio | latest | 데모 UI |
| **Infra** | Docker Compose | latest | 컨테이너화 |핵심 정리
- README는 30초 안에 승부를 본다
- 제조 AI는 **문제 정의(Why)**가 차별화 포인트다
- 배지는 사실인 것만 단다. 상태 배지는 CI가 만들 때만 단다
- 직접 측정한 숫자만 적는다. 측정하지 않은 숫자는 설득이 아니라 위험이다
AI로 학습하기 — 꿀팁
제조 AI 포트폴리오 README 템플릿 생성AI 학습 팁
제조 AI 프로젝트에 최적화된 README 구조를 즉시 사용 가능한 마크다운 템플릿으로 만들어 놓으면 포트폴리오 작성 속도가 빠릅니다.
제조 AI 엔지니어 취업 포트폴리오용 GitHub README.md 템플릿을 작성해주세요. 프로젝트 예시: '압출기 이상 감지 예지보전 AI 시스템'. 템플릿에 포함할 섹션: (1) 30초 임팩트 요약(문제→해결→성과 수치), (2) 기술 스택 배지(Python/PyTorch/Streamlit/Pandas), (3) 아키텍처 다이어그램(ASCII 또는 Mermaid), (4) 핵심 성과 지표(정확도, 비용 절감 추정치, 처리 속도), (5) 빠른 시작(3단계 이내 실행), (6) 데이터 설명(출처, 형식, 전처리), (7) 모델 설명(알고리즘 선택 근거), (8) 한계점 및 향후 개선 계획. 채용 담당자가 5분 안에 평가할 수 있도록 구성해주세요.
이 팁이 도움이 됐나요?