README.md 한 장)과 그 내용을 PDF로 굽는 docs-as-code 빌드 파이프라인(Python)이 한 저장소에 같이 들어 있다는 것. (저장소: bozhouDev/codex-orange-book · 주요 언어 HTML — 실상은 Markdown 책 + Python 빌드 · ★1.3k · 137 forks · 라이선스 파일 없음 · 버전 v0.1.0 · TrendShift Daily #12)이 저장소가 무엇을 하는 물건인가.
OpenAI 공식 문서는 영어라 막막하고, 블로그·영상은 파편적이라 길을 잃기 쉽다. 오렌지북은 개념 → 설치 → 핵심 기능 → 표준 워크플로 → 실전 5케이스를 하나의 동선으로 이어, 초보자가 "다음에 뭘 해야 하지?"에서 멈추지 않게 한다.
이 저장소는 코드 라이브러리가 아니라 한 권의 책이다. 정확히는 OpenAI의 코딩 에이전트 Codex를 처음부터 끝까지 다루는 비공식 중국어 사용 설명서로, 책 전체가 README.md 파일 한 장(약 186KB)에 들어 있고, 같은 내용을 온라인 페이지와 다운로드용 PDF로도 제공한다. 이름의 '橙皮书(오렌지북)'은 기술서를 표지색으로 부르는 관행(○○ 북)을 따른 별명이다.
중요한 단서가 하나 있다 — 표지에 "비공식(非官方)"이라고 못 박혀 있다. 버전은 v0.1.0, 최종 검증일은 2026-06-22. Codex는 업데이트가 빨라 모델명·요금·메뉴 위치가 수시로 바뀌므로, 이 책은 "그 시점에 실제로 만져본 화면"을 기준으로 정리했다고 밝힌다. 즉 학습 지도로 보되, 구체 수치는 OpenAI 공식 문서로 재확인하는 게 전제다.
트렌딩 이유 · 기존 방식 대비 장점.
화제의 핵심은 세 가지가 겹친 데 있다 — ① "엔지니어링 에이전트" 시대의 한복판(2026년 Codex·Claude Code 열풍), ② 중국어권에 체계적 무료 입문서가 비어 있었다는 점, ③ 온라인 읽기 + 다운로드 PDF를 동시에 주는 친절함. 공개 사흘 만에 ★1.3k·137 forks를 모으며 TrendShift 일간 상위에 올랐다.
가장 큰 장점은 "흩어진 지식을 하나의 동선으로 묶었다"는 것이다. 공식 문서는 기능별 레퍼런스라 "그래서 처음에 뭘 하지?"에 답하지 않고, 블로그는 단편적이다. 오렌지북은 설치 → Skill·MCP·AGENTS.md → 표준 6단계 워크플로 → 같은 브랜드(펫 간식)를 5개 케이스로 끝까지 끌고 가, 초보자가 멈추지 않게 설계됐다.
| 항목 | 기존 방식 (공식 문서 · 흩어진 블로그) | Codex 橙皮书 |
|---|---|---|
| 범위 | 기능 단위 레퍼런스 / 단편 팁 | 개념→설치→기능→워크플로→실전을 한 흐름으로 |
| 눈높이 | 영어 · 숙련자 전제 | 중국어 · 초보자 비유와 표 위주 |
| 실전 | 조각 예제 | 펫 간식 브랜드 1개를 5케이스로 일관 전개 |
| 형식 | 웹 페이지 | md 원고 + 온라인 + 다운로드 PDF 동시 |
| 최신성 | 수시 변경(공식) | "비공식·시점 고지" 명시(v0.1.0) |
또 하나, 이 책은 "한 줄 던지기"를 경계한다. "사이트 하나 만들어줘"처럼 통으로 맡기면 AI가 빠르게 고치지만 무엇을 고쳤는지 알 수 없어 믿고 배포하기 어렵다. 대신 책 전체가 "사람은 판단(拍板), AI는 실행(执行)"이라는 분업을 반복해서 강조한다.
요구를 한 문장으로 던지면 Codex는 빠르게 많은 파일을 고친다. 문제는 무엇이·왜 바뀌었는지 사람이 따라가지 못한다는 것. 방향이 어긋나도 늦게 발견하고, 결과를 믿고 배포하기 어렵다. 책은 이걸 "翻车(차가 뒤집힌다)"라고 부른다.
需求拆解(요구 분해) → 制定计划(계획) → 小步实现(작게 구현) → 测试(검증) → 代码审查(diff 리뷰) → 提交复盘(커밋·회고). 한 번에 한 조각만 바꾸니 되돌리기 쉽고, 매 단계에서 사람이 확인한다. "AI가 빨리"가 아니라 "안심하고 끝까지"가 목표다.
책의 '내용 스택' · PDF를 굽는 '빌드 스택' 두 갈래.
이 저장소는 두 개의 얼굴을 가진다. 하나는 책이 다루는 지식(콘텐츠) 스택 — Codex의 입구와 기능을 어떻게 분류했는가. 다른 하나는 그 원고를 PDF로 바꾸는 빌드(도구) 스택 — docs-as-code 파이프라인이다. 학습 가치는 둘 다에 있다.
| 레이어 | 기술 / 구성 | 역할 |
|---|---|---|
| 책 원고 | Markdown (README.md, 186KB) | 사람·기계가 같이 읽는 단일 소스(SSOT) |
| 다루는 입구 | Codex App · CLI · IDE 확장 · Web/Cloud | Codex를 쓰는 4개 진입점 |
| 다루는 기능 | 自动化 · 插件 · Skill · MCP · Git/GitHub · 云端 · 记忆(AGENTS.md) | Codex 활용 7대 갈래 |
| 빌드 언어 | Python 3 (tools/build_pdf.py) | 원고 → HTML → PDF 변환 스크립트 |
| MD 변환 | python-markdown (tables·fenced_code·sane_lists·attr_list) | Markdown → HTML5 본문 |
| 이미지 최적화 | Pillow (PIL) | PNG → JPEG 다운스케일(최대 1400px·품질 82) |
| PDF 렌더 | Chrome / Edge --headless --print-to-pdf | HTML을 브라우저가 직접 PDF로 인쇄 |
| 인쇄 CSS | CSS @page (A4 + named page) | 표지는 풀페이지, 본문은 여백 적용 |
| 산출물 | 고화질 PDF(38MB)·프리뷰(11MB)·book.html | 다운로드/미리보기용 결과물 |
| 온라인 호스팅 | GitHub Pages (index.html) | 브라우저로 바로 읽기 |
build_pdf.py를 실행하면 책이 다시 구워진다.README.md가 그 한 곳이다. 온라인 페이지도, PDF도, book.html도 모두 이 한 파일에서 파생되므로 내용이 서로 어긋날 일이 없다.책의 '지식 구조(5篇)' 한 장 → 'PDF 빌드' 한 줄기 추적.
먼저 숲을 보자. 이 책에는 두 개의 아키텍처가 있다. (A) 독자가 따라가는 지식 동선(5개 篇 + 부록), (B) 원고가 PDF로 변하는 빌드 파이프라인. 먼저 지식 구조부터.
| 篇 (파트) | 다루는 것 |
|---|---|
| 제0장 사용 설명 | 면책 고지 · 누구에게 맞나 · 3가지 읽기 루트(빠른 입문/개발자/고급) |
| 제1편 Codex가 뭔가 | 코딩 도구의 4단계 진화 · Codex가 할 수 있는 일 · 4개 입구 |
| 제2편 설치·설정 | App(추천)·CLI·IDE 확장·Web 각각 설치와 첫 사용 |
| 제3편 핵심 기능 | 자동화 · 플러그인 · Skill · MCP · Git/GitHub · 클라우드 · 기억(AGENTS.md) |
| 제4편 표준 워크플로 | 요구→계획→구현→검증→리뷰→커밋 6단계 · 작업 템플릿 모음 |
| 제5편 실전 케이스 | 펫 간식: 사이트→기능추가→관리자→투자유치 PPT→홍보영상 |
| 부록 | 제3자 모델 접속(DeepSeek·CC Switch 등, 비공식 확장) |
이제 (B) 빌드 파이프라인을 보자. tools/build_pdf.py를 실행하면 원고 한 장이 어떻게 PDF가 되는지, 전체 그림은 이렇다.
이제 대표 흐름인 build() 함수 한 줄기를 손으로 따라가 보자(곁가지·에러 처리는 접고 해피패스만).
# 터미널에서 한 줄 python tools/build_pdf.py # build() 안에서 순서대로 벌어지는 일 ① extract_cover() cover.html에서 표지 스타일·마크업을 꺼내 본문과 안 섞이게 손질 ② render_readme() README 읽고 → 네비 블록 제거 → python-markdown으로 HTML 변환 ③ prepare_pdf_assets() 본문 속 PNG 경로를 찾아 Pillow로 JPEG 사본 생성·링크 교체 ④ document 조립 표지 + BOOK_CSS + 본문을 하나의 HTML 문자열로 합침 ⑤ book.html 저장 저장소 루트에 씀(assets/ 상대경로가 풀리도록 루트에 둠) ⑥ resolve_chrome() mac/Windows/Linux의 Chrome·Edge 실행 파일을 자동 탐색 ⑦ subprocess.run() 크롬 헤드리스로 --print-to-pdf 실행 → preview.pdf 완성
이 저장소 특유의 "정상적인 모양새" 세 가지를 짚어두면 코드가 덜 낯설다.
README.md 한 장이 온라인 페이지 · 다운로드 PDF · 중간 book.html 셋으로 갈라진다. 원고만 고치면 전부 따라 바뀌니, 내용이 서로 어긋날 일이 없다. "한 곳만 고친다"는 docs-as-code의 정수.@page coverpage라는 이름 붙은 페이지를 따로 정의해, 표지는 여백 0(풀페이지), 본문은 A4 여백을 준다. 한 HTML 안에서 표지와 본문에 다른 인쇄 규칙을 입히는 CSS Paged Media의 실전 활용이다.preview.pdf만 만들고, 38MB 고화질 Codex橙皮书.pdf는 건드리지 않는다. "자동 생성물(프리뷰)"과 "사람이 관리하는 배포본"을 분리해 실수로 고화질본을 덮어쓰지 않게 한 안전장치.원고 한 장 · 산출물 · 빌드 도구로 깔끔히 갈린다.
코드 저장소치고 파일이 적다. 핵심은 원고(README.md) 하나, 거기서 나온 산출물(PDF·HTML), 그리고 그 변환을 맡는 도구(tools/) 셋으로 나뉜다.
| 경로 | 역할 |
|---|---|
| README.md | 책의 전부. 0장~5편+부록 전체 원고가 이 한 장에 들어 있음(이 저장소의 심장) |
| Codex橙皮书.pdf | 고화질 배포본. 빌드가 덮어쓰지 않도록 보호되는 "사람 관리" 파일 |
| *.preview.pdf | build_pdf.py가 만드는 경량본. 이미지가 JPEG로 줄어 용량이 작음 |
| book.html / cover.html | 전자는 빌드 중간산물(gitignore), 후자는 표지 원본 — 빌드 때 스타일·마크업을 추출당함 |
| assets/images/ | 책에 박히는 화면 캡처 108장. 원본 PNG는 고화질, 빌드 시 JPEG로 사본 생성 |
| tools/*.py | 빌드 1 + 테스트 2. 작은 저장소인데도 test_*를 둔 게 인상적인 포인트 |
이 책 한 권 + 빌드 코드에서 뽑아낼 수 있는 배움.
책의 1편이 던지는 가장 중요한 한 방은 관점 교정이다. Codex를 "코드 생성 버튼"으로 보면 과소평가하게 된다. AI 코딩 도구의 4단계 진화를 한 줄로 압축하면 이렇다.
2021 Copilot # 补 — 네가 시작하면 뒤를 채워줌(자동완성) 2022 ChatGPT # 想 — 묻고 답하는 대화 파트너(프로젝트 밖) 2023 Cursor # 改 — 에디터 안에서 같이 파일을 고침 2025 Codex # 执行 — 작업을 통째로 맡으면 끝까지 수행
실습 아이디어: 평소 "이거 어떻게 짜?"라고 묻던 것을, "이 작업을 끝까지 해서 리뷰할 수 있게 정리해줘"로 바꿔 말해보면 에이전트의 결이 달라진다.
3편의 백미. README.md가 사람에게 프로젝트를 설명한다면, AGENTS.md는 AI에게 "이 프로젝트에선 이렇게 일해라"를 적어두는 파일이다. 루트에 두면 프로젝트 전체, ~/.codex/AGENTS.md에 두면 내 모든 프로젝트에 적용된다.
# AGENTS.md (프런트엔드 프로젝트 예)
## 기술 스택
- React / Vite / Tailwind CSS
## 자주 쓰는 명령
- 설치: npm install
- 개발: npm run dev
- 빌드: npm run build
## 금지 사항
- 동의 없이 의존성 추가 금지
- 무관한 파일 건드리지 말 것
실습 아이디어: 내 프로젝트에 위 형식으로 AGENTS.md 한 장을 두고, 같은 요청을 파일 있/없을 때로 비교해 결과 차이를 본다.
초보자가 가장 자주 혼동하는 지점. 책의 정리가 명쾌하다 — "어떻게(怎么做)"는 Skill, "무엇과 연결(连接什么)"은 MCP.
# Skill — 반복하는 "작업 방법"을 고정 README 쓰기 / 코드 리뷰 / 랜딩페이지 생성 → Skill # MCP — 외부 "도구·데이터"에 연결 최신 API 문서 조회 / DB 연결 / Figma 읽기 / GitHub issue → MCP
비유로: Skill은 "정해진 레시피", MCP는 "기계에 끼우는 콘센트(어댑터)". 레시피는 일하는 순서고, 콘센트는 새 도구를 연결하는 통로다.
콘텐츠 말고 코드에서 배울 점. build_pdf.py는 무거운 라이브러리 없이 python-markdown + Pillow + 헤드리스 크롬만으로 책을 만든다. 내 블로그·리포트에도 그대로 쓸 수 있는 패턴이다.
# 의존성은 단 둘 pip install markdown Pillow # 원고를 PDF로 굽기 (크롬/엣지가 설치돼 있으면 됨) python tools/build_pdf.py # → README.md + cover.html → book.html → preview.pdf
실습 아이디어: 내 .md 문서로 build_pdf.py의 BOOK_CSS만 바꿔 "나만의 책 PDF"를 만들어 본다.
4편의 핵심. 큰 일을 한 입에 던지지 않고 단계로 쪼개는 습관이 AI 협업의 안전벨트다. 각 단계마다 사람이 확인 지점을 가진다.
① 需求拆解 요구를 잘게 분해(먼저 프로젝트 구조부터 파악) ② 制定计划 먼저 계획을 받고 → 확인 후 착수 ③ 小步实现 한 번에 한 조각만(되돌리기 쉽게) ④ 测试 실행·수동 검증으로 명백한 오류 제거 ⑤ 代码审查 diff를 읽고 "건드리면 안 될 것"을 점검 ⑥ 提交复盘 커밋 + 경험을 규칙으로 축적(→ AGENTS.md)
실습 아이디어: 다음 작업을 시작할 때 ①~②만이라도 강제해 "계획을 먼저 받기"를 습관화한다.
읽기만 하면 0, 빌드/실습은 가볍게.
| 항목 | 요구사항 / 메모 |
|---|---|
| 책 읽기 | 브라우저(온라인) 또는 PDF 뷰어. 설치 필요 없음 |
| PDF 빌드 | Python 3 + pip install markdown Pillow + Chrome/Chromium/Edge |
| 이미지 캐시 | 빌드가 .cache/pdf-assets/에 JPEG 사본을 자동 생성 |
| OS | 크로스플랫폼. build_pdf.py가 mac·Windows·Linux의 크롬 경로를 자동 탐색(CHROME_PATH로 지정 가능) |
| Codex 자체 사용 | OpenAI 계정(유료 플랜) + 입구별: App 설치 / CLI는 npm·Node / IDE 확장 / 웹 |
| 자료 시점 | v0.1.0 · 2026-06-22 기준 · 비공식 — 모델명·요금·메뉴는 공식 문서로 재확인 |
난이도별로 손을 움직여 보는 5가지.
온라인 페이지나 Codex橙皮书.preview.pdf로 0장~2편(개념·설치)을 먼저 읽는다. 또는 git clone 후 README.md를 열어 목차의 3가지 읽기 루트 중 "빠른 입문 루트"를 따라가 본다.
학습 2의 형식대로 기술 스택 · 자주 쓰는 명령 · 금지 사항 세 항목만으로 AGENTS.md를 만든다. AI가 이 규칙을 지키는지 같은 요청을 파일 있/없을 때로 비교한다.
pip install markdown Pillow 후 python tools/build_pdf.py를 실행해 preview.pdf를 재생성한다. 크롬 경로를 못 찾으면 CHROME_PATH 환경변수로 지정하는 것까지 경험한다.
5편의 첫 케이스(펫 간식 프런트 사이트)를 그대로 재현한다. 계획 모드로 먼저 계획을 받고 확인한 뒤 실행 → index.html 미리보기 → Git 저장소 생성까지 워크플로를 체득한다.
반복 작업(예: README 생성)을 Skill로 고정하고, 외부 도구(예: 문서·DB) 하나를 MCP로 연결해, 케이스 하나를 자기만의 표준 워크플로로 다시 만든다. 학습 3의 "怎么做=Skill / 连接什么=MCP" 판단을 실제로 적용해 본다.
이 책을 발판으로 6주 코스.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주 | Codex가 뭔가 + 4개 입구 · 코딩 에이전트 개념 | 책 1편, OpenAI Codex 공식 docs |
| 2주 | 설치·설정·환경 (App / CLI / IDE / Web) | 책 2편, Codex App·CLI 실제 설치 |
| 3주 | 핵심 기능: Skill · MCP · AGENTS.md 기억 | 책 3편, MCP 명세(modelcontextprotocol.io) |
| 4주 | 표준 6단계 워크플로 + 작업 템플릿 | 책 4편, 자기 프로젝트에 적용 |
| 5주 | 실전 5케이스(사이트→관리자→PPT→영상) | 책 5편 따라하기 |
| 6주 | docs-as-code: 내 문서를 책 PDF로 굽기 | tools/build_pdf.py · python-markdown · CSS Paged Media |
이 책에 등장하는 주요 용어 한눈에.
| 용어 | 의미 |
|---|---|
| Codex | OpenAI의 코딩 에이전트. 프로젝트에 들어가 읽고·고치고·실행·검사까지 수행 |
| coding agent | 작업을 통째로 맡으면 여러 단계를 스스로 밟아 끝내는 AI |
| Codex App/CLI/IDE/Web | Codex를 쓰는 4개 입구(데스크톱 앱·터미널·에디터 확장·웹/클라우드) |
| AGENTS.md | AI에게 "이 프로젝트에선 이렇게 일해라"를 적는 규칙 파일(프로젝트/유저 레벨) |
| Skill | 반복 작업의 "고정된 일하는 방법"(README 생성·리뷰 등). "어떻게"의 영역 |
| MCP | 외부 도구·데이터에 Codex를 잇는 표준 인터페이스. "무엇과 연결"의 영역 |
| 자동화(自动化) | 규칙대로 정기적으로 프로젝트를 점검·보고하게 하는 "AI 당직" |
| 云端运행 / Worktree | 클라우드 컨테이너에서 GitHub 코드를 처리 / 로컬 안전 사본에서 작업 |
| 계획 모드(plan mode) | 바로 고치지 않고 먼저 계획을 제시 → 사람이 확인 후 실행 |
| 표준 6단계 | 요구분해→계획→작게구현→검증→리뷰→커밋·회고 |
| docs-as-code | 문서를 Markdown+빌드 스크립트로 관리(여기선 README→PDF) |
| python-markdown | Markdown을 HTML로 바꾸는 파이썬 라이브러리(표·코드펜스 확장 사용) |
| Pillow (PIL) | 파이썬 이미지 처리 라이브러리. 여기선 PNG→JPEG 다운스케일 |
| headless print-to-pdf | 화면 없는 크롬으로 웹페이지를 그대로 PDF로 인쇄하는 기법 |
| @page (named page) | CSS 인쇄 규칙. 표지·본문에 다른 페이지 설정을 입힘(coverpage) |
| SSOT | 단일 진실원 — 정보를 한 곳(README.md)에서만 관리 |
| CC Switch / DeepSeek | 부록의 제3자 모델 접속 수단(비공식 확장, OpenAI 공식 기능 아님) |
원본 · 온라인 읽기 · 공식 문서.
Codex橙皮书.pdf (라이트 미리보기는 .preview.pdf)