Python으로 공부하는 OpenAI 22편 — 팀 프로젝트가 되면 README가 코드보다 더 중요해지는 순간이 옵니다

Python으로 공부하는 OpenAI 22편 — 팀 프로젝트가 되면 README가 코드보다 더 중요해지는 순간이 옵니다

혼자 만들 때는 솔직히 README가 좀 부실해도 버팁니다.
내가 만들었고, 내가 띄웠고, 내가 구조를 아니까요. 머릿속에 다 있죠.

근데 팀 프로젝트가 되는 순간 분위기가 완전히 달라집니다.

누군가는 처음 받아서 실행해야 하고,
누군가는 장애가 났을 때 어디부터 봐야 하고,
누군가는 .env에 뭘 넣어야 하는지 몰라서 30분을 날리고,
누군가는 “이거 왜 staging에서는 되는데 prod에서는 안 돼요?”를 물어봅니다.

이때 깨닫게 됩니다.

코드가 돌아가는 것과
프로젝트가 전달 가능한 상태인 것은 전혀 다른 문제라는 걸요.

FastAPI 공식 문서는 앱이 커질수록 여러 파일과 APIRouter, 설정 모듈, 의존성 모듈로 구조를 나누는 방식을 권장하고, 설정은 BaseSettings, .env, @lru_cache() 패턴으로 정리하는 흐름을 보여줍니다. OpenAI 쪽도 production best practices에서 키를 코드에 두지 말고 환경변수나 secret manager로 주입하라고 강조하고, quickstart 역시 API 키를 환경변수로 export해서 쓰는 흐름을 안내합니다. (OpenAI 개발자)

이번 글에서는 바로 이걸 다룹니다.

• README에 꼭 들어가야 하는 것
• .env.example는 어떻게 써야 하는지
• 아키텍처 설명은 어디까지 적어야 하는지
• 운영자가 보는 runbook은 어떻게 다르게 써야 하는지
• 혼자만 아는 구조가 되지 않게 문서화하는 법

---

1. README는 설명서가 아니라 “첫 30분을 줄여주는 문서”입니다

예전엔 README를 약간 형식적으로 생각했습니다.
“프로젝트 이름 쓰고, 설치 방법 조금 쓰고, 끝.” 이런 느낌이요.

근데 실제로 팀으로 일해보면 README의 역할은 훨씬 더 현실적입니다.

처음 보는 사람이 이 프로젝트를 30분 안에 이해하고 실행할 수 있게 만드는 문서

이게 핵심이에요.

OpenAI quickstart는 아주 기본적인 시작 흐름을 보여주는데, 여기서도 핵심은 똑같습니다.
API 키를 만들고, 안전한 곳에 저장하고, 환경변수로 주입하고, 그다음 SDK를 설치하고, 첫 호출을 해보는 식이죠. 즉, 좋은 시작 문서는 “무슨 기술인가”보다 어떻게 바로 시작하나를 먼저 보여줘야 합니다. (OpenAI 개발자)

그래서 README 첫 화면에서 제일 먼저 필요한 건 보통 이겁니다.

• 이 프로젝트가 뭘 하는지
• 어떤 기술을 쓰는지
• 어떻게 실행하는지
• 최소한 무엇이 필요한지

화려한 문장보다 이게 먼저예요.

---

2. README 첫 부분은 무조건 짧고 명확해야 합니다

처음부터 장문의 설명을 넣으면 잘 안 읽힙니다.
진짜로요. 대부분은 프로젝트를 열자마자 먼저 보는 게 이겁니다.

• 이거 뭔 프로젝트지?
• 어떻게 띄우지?
• 뭐가 있어야 하지?

그래서 README 상단은 이 정도가 제일 좋습니다.

# OpenAI FastAPI Backend

OpenAI Responses API를 기반으로 한 FastAPI 백엔드 예제입니다.  
채팅, RAG, 멀티모달 입력, tool calling, background jobs를 다룹니다.

## Stack
- Python 3.11+
- FastAPI
- OpenAI API
- Pydantic
- Redis (optional)
- PostgreSQL (optional)

## Quick Start
1. 가상환경 생성
2. 패키지 설치
3. `.env` 설정
4. 서버 실행

이런 느낌이면 충분합니다.
처음부터 철학을 다 쓰지 않아도 돼요.

---

3. Quick Start는 “복붙해서 바로 되는 흐름”이어야 합니다

이건 진짜 중요합니다.
README에서 제일 유용한 부분은 거의 항상 Quick Start입니다.

FastAPI 설정 문서는 .env와 BaseSettings를 함께 쓰는 패턴을 보여주고, OpenAI quickstart는 환경변수 export 후 SDK를 설치해 첫 호출을 하는 순서를 보여줍니다. 즉, README Quick Start도 이 흐름을 그대로 따라가면 됩니다. (OpenAI 개발자)

예를 들면:

## Quick Start

### 1. Python 가상환경 생성
```bash
python -m venv .venv
source .venv/bin/activate

2. 패키지 설치

pip install -r requirements.txt

3. 환경변수 파일 생성

cp .env.example .env

4. .env 값 채우기

• OPENAI_API_KEY
• DATABASE_URL
• OPENAI_MODEL

5. 서버 실행

uvicorn app.main:app --reload

이 정도만 있어도 훨씬 낫습니다.  
특히 `cp .env.example .env`는 정말 체감이 큽니다.  
이 한 줄이 없으면 처음 세팅하는 사람이 어디서부터 값을 넣어야 할지 헤맬 가능성이 높아요.

---

## 4. `.env.example`는 “문서” 역할도 같이 합니다

이건 단순한 샘플 파일이 아닙니다.  
사실상 환경설정 문서예요.

FastAPI 문서는 환경변수를 코드 밖에서 관리하라고 설명하고, OpenAI production best practices는 키를 코드나 공개 저장소에 두지 말고 환경변수나 secret manager로 주입하라고 강조합니다. 그러니까 `.env.example`는 실제 비밀을 넣는 파일이 아니라, **무슨 설정이 필요한지 알려주는 계약 문서**처럼 쓰는 게 맞습니다. :contentReference[oaicite:3]{index=3}

좋은 `.env.example`는 이런 식입니다.

```env id="env_example_22"
APP_NAME=OpenAI FastAPI App
APP_ENV=dev

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.4-mini
OPENAI_VECTOR_STORE_ID=

DATABASE_URL=
REDIS_URL=

LOG_LEVEL=INFO
ENABLE_DOCS=true

여기서 중요한 건 두 가지입니다.

첫째, 실제 값은 넣지 않는다
둘째, 필수 키를 빠뜨리지 않는다

그리고 README에는 각 변수 설명도 짧게 붙여두는 게 좋습니다.

## Environment Variables

- `OPENAI_API_KEY`: OpenAI API 키
- `OPENAI_MODEL`: 기본 모델명
- `OPENAI_VECTOR_STORE_ID`: RAG용 벡터 스토어 ID
- `DATABASE_URL`: 운영 DB 연결 문자열
- `REDIS_URL`: 캐시/큐용 Redis 주소

이 정도만 있어도 누가 봐도 방향이 잡힙니다.

---

5. README에는 “프로젝트 구조”가 꼭 들어가는 편이 좋습니다

이건 특히 AI 백엔드에서 중요합니다.
파일 수가 빨리 늘어나거든요.

FastAPI Bigger Applications 문서는 라우터와 공통 의존성, 설정을 여러 파일로 나누는 구조를 예시로 보여줍니다. 이걸 README에 간단히 설명해두면 팀원이 구조를 훨씬 빨리 이해합니다. (OpenAI 개발자)

예를 들면:

## Project Structure

app/
├── main.py
├── core/
│   ├── config.py
│   └── dependencies.py
├── api/
│   └── routers/
├── schemas/
├── services/
├── adapters/
├── repositories/
└── workers/

그리고 이 아래에 짧게 역할을 써주는 거죠.

- `api/routers`: FastAPI 엔드포인트
- `schemas`: 요청/응답 Pydantic 모델
- `services`: 유스케이스 로직
- `adapters`: OpenAI/외부 서비스 연동
- `repositories`: DB/Redis 접근
- `workers`: 백그라운드 작업 처리

이런 설명이 있으면 처음 온 사람도 “아, OpenAI 호출 코드는 adapters 쪽에 있겠구나” 하고 감이 옵니다.

---

6. README에는 “무엇이 구현되어 있는지”도 써야 합니다

이건 은근히 빠뜨리기 쉽습니다.

프로젝트를 열어보는 사람은 종종 이렇게 생각합니다.

• 채팅만 되나?
• RAG도 있나?
• 스트리밍 있나?
• 멀티모달 있나?
• background job도 있나?

그래서 feature list를 짧게라도 써두는 게 좋습니다.

## Features

- OpenAI Responses API 기반 채팅
- Structured Outputs + Pydantic 검증
- RAG (vector store 기반 문서 검색)
- 멀티모달 입력 (텍스트 + 이미지 + 파일)
- Tool calling / function calling
- Background jobs
- Usage / observability logging

이건 사실 팀원뿐 아니라 미래의 나를 위해서도 좋습니다.
몇 주 지나면 나도 “이 프로젝트 어디까지 했더라…” 하게 되거든요.

---

7. 운영 문서(runbook)는 README와 다르게 써야 합니다

여기서 많이 헷갈립니다.

README는 처음 이해하고 실행하는 문서에 가깝고,
runbook은 운영 중 문제 생겼을 때 보는 문서에 가깝습니다.

즉, 목적이 다릅니다.

README

• 프로젝트 소개
• 실행 방법
• 구조 설명
• 개발 시작용 정보

Runbook

• 장애 시 확인 순서
• 로그 위치
• 재시작 방법
• queue stuck 시 대응
• API 키 교체 절차
• vector store 문제 대응
• 비용 급증 시 확인 포인트

OpenAI production best practices는 보안, 운영, 키 관리, 배포 전 점검을 강조하고, FastAPI deployment concepts는 startup, restart, replication, memory 같은 운영 관점을 따로 다룹니다. 그러니까 운영 문서는 “설치 설명”과 분리되는 게 맞아요. (OpenAI 개발자)

예를 들면 runbook 첫 부분은 이렇게 갈 수 있습니다.

# Runbook

## 1. 서버가 응답하지 않을 때
- 앱 컨테이너 상태 확인
- worker 프로세스 상태 확인
- 최근 배포 여부 확인
- OpenAI API 키/조직 설정 변경 여부 확인

## 2. RAG 답변 품질이 급격히 나빠졌을 때
- vector store ID가 올바른지 확인
- 최근 업로드된 테스트 문서가 섞였는지 확인
- retrieved chunk count / latency 로그 확인

## 3. 비용이 급증했을 때
- output tokens 평균 증가 여부 확인
- cached input 비율 하락 여부 확인
- 특정 endpoint 사용량 급증 여부 확인

이런 문서는 진짜 운영 때 도움 됩니다.

---

8. 아키텍처 그림은 “예쁘게”보다 “빠르게 이해되게”가 중요합니다

반응형

문서에서 종종 아키텍처 다이어그램을 넣고 싶어지죠.
좋습니다. 넣는 게 훨씬 낫습니다.

다만 중요한 건, 너무 예쁘게 만들려다가 시간 쓰는 것보다
요청이 어디로 흐르는지 한 번에 보이게 만드는 것이 더 중요하다는 점이에요.

예를 들면 이 정도 ASCII 다이어그램도 충분합니다.

Client
  ↓
FastAPI Router
  ↓
Service
  ↓
OpenAI Adapter ─────→ OpenAI API
  ↓
Repository ────────→ PostgreSQL / Redis
  ↓
Worker (optional) ─→ Background Jobs

혹은 RAG 흐름이면:

User Question
  ↓
FastAPI Router
  ↓
RAG Service
  ├─ Retrieval Service → Vector Store
  ├─ Context Builder
  └─ OpenAI Adapter → Responses API
  ↓
Answer + Sources

이 정도만 있어도 사람들 이해 속도가 확 올라갑니다.

---

9. “어떻게 개발하면 되는지”도 README에 있어야 합니다

이 부분도 은근 중요합니다.
팀 프로젝트가 되면 단순 실행 방법만으로는 부족합니다.

예를 들면 이런 정보가 있으면 좋습니다.

• 브랜치 전략
• migration 실행 방법
• 테스트 실행 방법
• lint/format 명령
• live API 테스트는 어떻게 돌리는지
• 개발 시 주의사항

README에 이런 식으로 들어가면 좋습니다.

## Development Commands

### 테스트 실행
```bash
pytest

live OpenAI smoke test 실행

pytest -m live

코드 포맷팅

ruff check .
ruff format .

이건 나중에 팀원이 “어떻게 검증하고 올려야 하지?”를 묻는 시간을 줄여줍니다.

---

## 10. 문서화는 “무엇을 하지 말아야 하는지”도 같이 적는 게 좋습니다

이건 진짜 실무에서 중요합니다.

OpenAI production best practices는 키를 코드/공개 저장소에 두지 말고 환경변수나 secret manager로 관리하라고 하고, quickstart도 환경변수 export 흐름을 기본으로 보여줍니다. 이걸 문서로도 남겨야 팀이 같은 실수를 덜 합니다. :contentReference[oaicite:6]{index=6}

예를 들면 README나 CONTRIBUTING에 이런 문장을 적어두는 거죠.

```md id="rules_example"
## Rules

- `.env` 파일은 커밋하지 않습니다.
- OpenAI API 키는 코드에 직접 넣지 않습니다.
- production vector store ID를 local/staging에 사용하지 않습니다.
- 실제 OpenAI API를 부르는 테스트는 `-m live`로만 실행합니다.

이런 문장은 진짜 사소해 보이는데,
한두 번 사고를 막아주면 이미 값어치를 합니다.

---

11. 운영자가 보는 문서엔 “어디를 봐야 하는지”가 먼저 나와야 합니다

운영 문서는 설명보다 행동 순서가 중요합니다.

예를 들어 장애가 났을 때 운영자가 필요한 건 이겁니다.

• 어떤 로그를 볼지
• 어떤 메트릭을 볼지
• 어떤 재시작 명령을 쓸지
• 어디서 API 키를 바꿀지
• 어떤 job queue를 확인할지

그래서 runbook은 종종 이런 형식이 더 좋습니다.

## Incident Checklist

### OpenAI 401/403 발생 시
1. 현재 프로젝트 키가 맞는지 확인
2. staging/prod 환경변수 교차 여부 확인
3. 서비스 계정 권한 변경 이력 확인

### RAG 검색 결과 이상 시
1. 현재 `OPENAI_VECTOR_STORE_ID` 확인
2. 최근 업로드 문서 목록 확인
3. retrieval 로그의 source 파일명 확인

### Background job 적체 시
1. worker 상태 확인
2. queue depth 확인
3. 최근 failed jobs 확인

이런 문서는 멋있진 않아도, 진짜 쓸모가 있습니다.

---

12. README와 runbook 외에도 있으면 좋은 문서들

프로젝트가 조금 더 커지면 이런 문서들도 유용합니다.

CONTRIBUTING.md

• 브랜치 전략
• 커밋 규칙
• PR 작성 규칙
• 테스트 기준

ARCHITECTURE.md

• 더 자세한 구조 설명
• request 흐름
• background job 구조
• OpenAI 연동 전략

RUNBOOK.md

• 운영 대응 절차
• 장애 대응 순서
• 점검 체크리스트

CHANGELOG.md

• 배포 이력
• 모델 변경 이력
• vector store 구조 변경 이력

특히 OpenAI 모델은 pinned version을 쓸지, 최신 family alias를 쓸지에 따라 동작 안정성이 달라질 수 있으니, 모델 변경 이력을 남기는 게 꽤 중요합니다. OpenAI API Overview도 일관성을 원하면 pinned model versions와 evals를 권장합니다. (OpenAI 개발자)

---

13. 자주 하는 실수들

실수 1. README가 너무 길기만 하고 실행 흐름이 없다

설명은 많은데, 처음 보는 사람이 뭘 해야 하는지 안 보입니다.

실수 2. .env.example에 실제 값 비슷한 걸 넣는다

샘플 파일은 비밀을 담는 곳이 아닙니다.

실수 3. README와 실제 구조가 다르다

파일 구조가 바뀌었는데 문서가 업데이트되지 않으면 신뢰가 떨어집니다.

실수 4. 운영 문서를 README에 전부 섞어 넣는다

개발 시작용 문서와 장애 대응 문서는 목적이 다릅니다.

실수 5. 아키텍처를 머릿속으로만 공유한다

혼자 이해한 구조는 팀에선 구조가 아닙니다. 그냥 암묵지예요.

---

14. 지금 단계에서 추천하는 가장 현실적인 문서 세트

주니어 개발자가 팀 프로젝트로 OpenAI 백엔드를 운영하기 시작할 때는 이 정도가 가장 좋습니다.

1) README.md

• 프로젝트 소개
• Quick Start
• .env.example 설명
• 주요 기능
• 프로젝트 구조
• 개발 명령

2) .env.example

• 필요한 변수 전체
• 실제 값 없음

3) RUNBOOK.md

• 장애 대응 순서
• 로그/메트릭/큐 확인 포인트
• 재시작/복구 절차

4) 필요 시 ARCHITECTURE.md

• RAG 흐름
• background job 흐름
• tool calling 흐름
• 데이터 저장 구조

이 정도만 있어도 “혼자만 아는 프로젝트”에서 훨씬 빨리 벗어날 수 있습니다.

---

15. 오늘 글의 핵심 요약

이번 글에서 꼭 가져가야 할 건 이것입니다.

팀 프로젝트에서 좋은 문서란 예쁜 설명이 아니라, 처음 보는 사람이 빨리 실행하고, 구조를 이해하고, 운영 중 문제를 해결할 수 있게 만드는 문서다.

정리하면:

• FastAPI는 설정과 큰 앱 구조를 여러 파일과 BaseSettings, APIRouter, 공통 의존성 모듈로 정리하는 패턴을 권장합니다. (OpenAI 개발자)
• OpenAI quickstart와 production best practices는 API 키를 환경변수나 secret manager로 주입하고, 코드/저장소에 두지 말라고 강조합니다. (OpenAI 개발자)
• OpenAI API Overview는 pinned model versions와 evals를 권장하므로, 모델 변경 이력과 운영 구조를 문서화해두는 편이 좋습니다. (OpenAI 개발자)

결국 문서는 “좋아 보이기 위한 것”보다
다른 사람이 바로 움직일 수 있게 만드는 도구에 더 가깝습니다.
저는 이걸 깨닫고 나서부터 README를 훨씬 더 진지하게 쓰게 됐어요.

---

다음 편 예고

다음 글에서는 여기서 한 단계 더 들어가겠습니다.

Python + FastAPI에서 OpenAI 프로젝트를 실제 배포 가능한 MVP에서 운영형 SaaS 구조로 확장하는 전체 로드맵

이 주제로,

• 주니어가 어디까지를 MVP로 잡아야 하는지
• 어떤 기능부터 붙이고 무엇은 뒤로 미뤄야 하는지
• 혼자 만드는 단계에서 팀 개발 단계로 넘어가는 기준
• 블로그 시리즈 전체를 실제 서비스 설계 로드맵으로 정리

까지 이어가보겠습니다.

---

출처

• FastAPI Settings and Environment Variables — BaseSettings, .env, @lru_cache() 기반 설정 구조. (OpenAI 개발자)
• OpenAI Production best practices — API 키를 코드/공개 저장소에 두지 말고 환경변수나 secret manager로 주입. (OpenAI 개발자)
• OpenAI Developer quickstart — API 키를 환경변수로 export해서 사용하는 시작 흐름. (OpenAI 개발자)
• OpenAI Python API library — OPENAI_LOG 같은 환경변수 기반 로깅 설정 가능. (OpenAI 개발자)
• FastAPI Bigger Applications — APIRouter, 공통 dependencies 모듈, 여러 파일 구조 예시. (OpenAI 개발자)
• OpenAI API Overview / docs navigation — pinned model versions, evals, production 관련 가이드 구조. (OpenAI 개발자)

Python, OpenAI, FastAPI, README 작성법, runbook, .env.example, 프로젝트 문서화, 운영 문서, 팀 개발, AI 백엔드 문서화, BaseSettings, APIRouter, 주니어 개발자, OpenAI 프로젝트 구조, SaaS 준비