freestylefly/CodexGuide 딥다이브
— "코드 한 줄 없는 코드 저장소", 문서가 곧 제품인 OpenAI Codex 실전 지식베이스

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Codex는 OpenAI가 만든 "코딩을 대신 해 주는 AI 에이전트"다. 단순 채팅이 아니라 실제로 내 저장소를 읽고, 파일을 고치고, 명령을 실행하고, 결과를 검증한다. 들어가는 입구가 여러 개라는 게 핵심 난점인데 — 데스크탑 App, 터미널의 CLI, VS Code 같은 IDE 확장, 브라우저의 Cloud, ChatGPT 모바일 앱까지 — CodexGuide는 "당신 상황엔 어느 입구가 맞는가"부터 정리해 준다.

레포의 정체를 한 문장으로 정의하면 이렇다: "마크다운 문서 60여 개 + 그걸 검색·SEO·RSS까지 갖춘 사이트로 만드는 빌드 설정". 언어 통계가 이를 그대로 증언한다 — JavaScript/TypeScript 빌드 설정이 일부, 나머지 대부분은 docs 폴더의 .md 콘텐츠다. 즉 이 레포는 두 갈래로 읽을 수 있다. ① 콘텐츠로서의 Codex 지식(config.toml, AGENTS.md, 샌드박스, MCP/Skills), ② 엔지니어링으로서의 문서 사이트(VuePress 2, theme-hope, 커스텀 SEO, Vercel 배포).

2왜 주목받는가

트렌딩 이유 · 경쟁 대비 장점.

2026년 들어 "코딩 에이전트"는 폭발적으로 늘었지만(Claude Code·Codex·Gemini CLI·opencode…), 사람들이 막상 켜면 길을 잃는다. 입구가 너무 많고, 설정(config.toml)·권한(샌드박스)·프로젝트 규칙(AGENTS.md)·확장(MCP/Skills) 개념이 처음엔 안개 같다. CodexGuide가 트렌딩에 오른 이유는 정확히 이 빈틈을 메우기 때문이다. 세 가지로 정리된다. 첫째, "명령어 치트시트"가 아니라 "실전 과업 중심"이다. 둘째, 16개의 실제 케이스(PPT 생성·Figma 읽기·CI 자동수정·임상 문헌 리뷰…)로 "그래서 뭘 할 수 있는데?"에 답한다. 셋째, 공식 자료 우선 + 최종 확인 날짜 명시로 신뢰도를 관리한다.

개발 관점에서 또 하나의 매력은 "잘 만든 문서 사이트의 레퍼런스 구현"이라는 점이다. JSON-LD 구조화 데이터, OGP, 사이트맵 클린 URL 재작성, 클라이언트 사이드 전문 검색, RSS/Atom/JSON 피드, 카피라이트 자동 삽입 — 블로그·기술 문서를 직접 만들려는 사람에게는 그대로 베껴 쓸 수 있는 설정 모음이다.

3기술 스택 전체 지도

이 레포를 떠받치는 부품들 — 빌드·테마·플러그인·배포.

일반 앱과 달리 이 레포엔 "백엔드 서버"가 없다. 대신 빌드 타임에 모든 페이지를 굽고, CDN(Vercel)에 정적 파일로 올린다. 그래서 스택은 "콘텐츠 → 빌드 → 배포" 파이프라인으로 읽는 게 정확하다.

① 빌드 엔진 (정적 사이트 생성)

② 콘텐츠 강화 플러그인

③ 배포 & 패키지 관리

4아키텍처 심화 분석

콘텐츠가 사이트가 되는 흐름 + 핵심 설계 패턴.

전체 빌드 파이프라인

핵심 설계 패턴 ① — "단일 진실원" SEO 엔진 (seo.ts)

이 레포에서 가장 배울 만한 코드가 docs/.vuepress/seo.ts다. 모든 페이지의 메타 설명을 한 파일의 객체(pageDescriptions)에 모아두고, 빌드 훅(extendsPage)이 각 페이지에 자동 주입한다. 글마다 frontmatter에 description을 손으로 쓰는 대신, "경로 → 설명" 맵 하나로 관리하는 구조다.

// seo.ts — 경로별 메타 설명을 한 곳에 모음(단일 진실원)
export const pageDescriptions: Record<string, string> = {
  "/": siteDescription,
  "/configuration/config-file.html":
    "Codex config.toml 配置指南，说明模型、沙盒、审批、profiles、MCP …",
  "/guide/15-agents-md.html":
    "AGENTS.md 项目规则指南，说明如何写入项目命令、代码风格 …",
  // …60+ 경로
};

// 경로를 .html/슬래시 변형까지 정규화해 안전하게 조회
export const getPageDescription = (path: string): string => {
  const cleanPath = toCleanPath(path);
  // 정확 일치 → 정규화 일치 → 디렉토리 일치 → 폴백(siteDescription)
  return pageDescriptions[path] ?? pageDescriptions[cleanPath]
       ?? pageDescriptions[directoryPath] ?? siteDescription;
};

핵심 설계 패턴 ② — JSON-LD로 "학습 자료"임을 선언

검색엔진에게 "이 사이트는 단순 페이지가 아니라 강의·학습 자료"라고 알려주는 구조화 데이터를 theme.ts에서 동적으로 만든다. 홈페이지면 Organization + WebSite + LearningResource/Course 그래프를, 내부 페이지면 일반 article 그래프를 주입한다.

// theme.ts — 홈에서만 Course 스키마를 주입(teaches 배열로 커리큘럼 명시)
{
  "@type": ["LearningResource", "Course"],
  name: "CodexGuide：OpenAI Codex 中文教程与实战指南",
  educationalLevel: "Beginner to Intermediate",
  teaches: [
    "Codex 桌面 App 使用", "Codex CLI 安装与登录",
    "OpenAI Codex 配置", "AGENTS.md 项目规则", "Codex 实战案例",
  ],
  provider: { "@id": `${siteUrl}/#organization` },
}

핵심 설계 패턴 ③ — 빌드 후처리 훅(onGenerated)으로 사이트맵 교정

cleanUrls: true(주소에서 .html 제거)를 쓰면, 자동 생성된 sitemap.xml엔 여전히 .html이 남는 불일치가 생긴다. CodexGuide는 직접 만든 작은 플러그인으로 빌드 직후(onGenerated) 사이트맵의 URL을 정규식으로 다시 써서 이 틈을 메운다. "프레임워크가 안 해주는 한 끗"을 훅으로 보완하는 전형적 패턴이다.

// config.ts — 빌드가 끝난 뒤 sitemap.xml 의 URL 을 cleanUrls 로 재작성
const rewriteSitemapCleanUrlsPlugin = {
  name: "codexguide-clean-sitemap-urls",
  onGenerated: (app) => {
    const sitemap = readFileSync(app.dir.dest("sitemap.xml"), "utf-8");
    const cleaned = sitemap.replace(/<loc>(https:\/\/codexguide\.ai[^<]*)<\/loc>/gu,
      (_, url) => `<loc>${toSiteUrl(new URL(url).pathname)}</loc>`);
    writeFileSync(app.dir.dest("sitemap.xml"), cleaned);
  },
};

5디렉토리 구조 해부

어디에 무엇이 있는가 — 설정(.vuepress)과 콘텐츠(docs)의 분리.

구조의 핵심은 "두뇌(.vuepress)와 몸통(콘텐츠 폴더)의 분리"다. .vuepress/는 사이트가 어떻게 보이고 작동하는지(설정·테마·SEO)를, 나머지 7개 폴더는 무엇을 가르치는지(콘텐츠)를 담당한다. 새 글을 추가할 때는 해당 콘텐츠 폴더에 .md를 넣고 sidebar/navbar에 한 줄 등록하면 끝이다.

6학습 포인트 (기술별)

이 레포에서 실제로 무엇을 배울 수 있는가. 두 갈래로 읽자.

A. 문서 사이트 엔지니어링 (레포의 "코드"에서 배우기)

B. Codex 사용법 (레포의 "콘텐츠"에서 배우기)

# 학습용 예시 — 실제 필드는 공식 config reference 기준
model = "gpt-5.1-codex-max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]   # 낯선 레포 분석용(안전)
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.coding]     # 일상 코딩용
sandbox_mode = "workspace-write"
approval_policy = "on-request"

7시스템 요구사항 & 빌드

이 레포를 직접 띄우려면 / Codex를 쓰려면.

CodexGuide 사이트를 로컬에서 빌드

# 1) 의존성 설치(재현 가능)
pnpm install --frozen-lockfile
# 2) 개발 서버(HMR) — 0.0.0.0 바인딩이라 같은 네트워크에서 접속 가능
pnpm dev
# 3) 정적 사이트 빌드 → docs/.vuepress/dist/
pnpm build
# 4) 캐시/임시/dist 정리
pnpm clean

Codex 자체를 쓰려면 (콘텐츠가 전제하는 환경)

8직접 해볼 수 있는 실습 과제

난이도별 — 읽기만 하지 말고 손으로.

9관련 기술 심화 학습 로드맵

이 레포를 발판 삼아 4주 코스. 두 트랙을 병행한다.

10핵심 키워드 사전

이 레포를 읽을 때 자주 나오는 용어.

11참고 링크

원본과 더 깊이 파고들 자료.

프로젝트 원본

· GitHub 저장소: github.com/freestylefly/CodexGuide
· 온라인 사이트: codexguide.ai (검색·사이드바·스크린샷 완비)
· 학습 경로(overview): codexguide.ai/guide/00-overview

레포가 쓰는 기술

· VuePress 2: v2.vuepress.vuejs.org
· vuepress-theme-hope: theme-hope.vuejs.press
· Vite: vitejs.dev · pnpm: pnpm.io
· Vercel 배포: vercel.com/docs
· schema.org(JSON-LD): schema.org

Codex 공식 자료(콘텐츠 출처)

· OpenAI Codex 제품: openai.com/codex
· Codex CLI 시작하기: help.openai.com
· Codex 설정·AGENTS.md 문서: developers.openai.com/codex
· openai/codex 저장소: github.com/openai/codex