skibidiskib/ai-codex

이 프로젝트는 전적으로 Claude Code (Anthropic의 AI 코딩 어시스턴트)에 의해 설계, 작성 및 게시되었습니다. 컨셉, 구현, 문서화 및 예제는 모두 단일 대화 세션에서 생성되었습니다.

AI 코딩 어시스턴트에게 프로젝트 구조에 대한 즉각적인 컨텍스트를 제공하는 컴팩트한 코드베이스 인덱스를 생성합니다. 매 대화 시작 시 파일 탐색에 50K 이상의 토큰을 낭비하는 대신, AI 어시스턴트가 미리 구축된 인덱스를 읽고 즉시 작업을 시작할 수 있습니다.

AI 코딩 어시스턴트(Claude Code, Cursor, GitHub Copilot 등)와 대화를 시작할 때마다, 어시스턴트는 파일을 읽고, 디렉토리를 스캔하고, 정신적 모델(mental model)을 구축하며 코드베이스를 탐색하는 데 수천 개의 토큰을 소비합니다. 이는 매 대화마다 발생합니다.

ai-codex는 다음과 같은 내용을 캡처하는 컴팩트하고 구조화된 참조 파일을 생성하여 이 문제를 해결합니다:

• HTTP 메서드가 포함된 모든 API 라우트 (API route)
• 렌더링 전략(클라이언트 vs 서버)이 포함된 모든 페이지 (page)
• 모든 라이브러리 함수 시그니처 (library function signature)
• 데이터베이스 스키마 (database schema) (주요 필드, 관계)
• Props가 포함된 컴포넌트 트리 (component tree)

결과: 매번 50K 이상의 탐색 토큰을 대체하는 5개의 작은 파일이 생성됩니다.

프로젝트 루트에서 실행하세요:

npx ai-codex

그게 전부입니다. 프레임워크를 자동으로 감지하고 인덱스를 생성합니다.

기본적으로 파일은 프로젝트 루트의 .ai-codex/에 작성됩니다:

파일	포함 내용
routes.md	리소스별로 그룹화된 API 라우트 및 HTTP 메서드
pages.md	클라이언트/서버 렌더링 태그가 포함된 페이지 트리
lib.md	라이브러리 내보내기(exports) -- 함수 시그니처, 클래스
schema.md	데이터베이스 스키마 -- 주요 필드, 외래 키(FK), 관계
components.md	기능별로 그룹화된 Props를 포함한 컴포넌트 인덱스

해당되지 않는 파일은 건너뜁니다 (예: Prisma를 사용하지 않으면 schema.md는 생성되지 않음).

npx ai-codex --output .claude/codex # 사용자 정의 출력 디렉토리
npx ai-codex --include src lib # 지정된 디렉토리만 스캔
npx ai-codex --exclude tests __mocks__ # 지정된 디렉토리 제외
...

프로젝트 루트에 codex.config.json을 생성하세요:

{
"output": ".ai-codex",
"include": ["src", "lib", "app"],
...
}

CLI 플래그가 설정 파일의 값을 덮어씁니다.

## 제품 (products)
GET,POST /api/products [인증(auth), 데이터베이스(db)]
GET,PUT,DELETE /api/products/:id [인증(auth), 데이터베이스(db)]
...

[클라이언트] /HomePage
[서버] /products ProductsPage
[클라이언트] /products/:id ProductDetailPage
...

## lib
cart-utils.ts
fn calculateTotal
...

## 제품 (Product)
id String PK
categoryId String
...

## components
(c) CartDrawer items, onRemove, onCheckout
(c) ProductCard product, onAddToCart
...

이 내용을 CLAUDE.md에 추가하세요:

:

## 코드베이스 인덱스 (Codebase Index)
사전 구축된 인덱스 파일은 `.ai-codex/`에 있습니다. 코드베이스를 탐색하기 전에 이것들을 먼저 읽으세요:
- `.ai-codex/routes.md` -- 모든 API 라우트
...

.ai-codex/ 디렉토리를 AI 어시스턴트의 컨텍스트 또는 규칙 파일에 추가하세요. 대부분의 AI 코딩 도구는 참조 파일을 포함하는 방법을 지원합니다.

# .git/hooks/pre-commit
npx ai-codex --quiet
git add .ai-codex/

{
"scripts": {
"codex": "npx ai-codex --quiet",
...

# GitHub Actions 예시
- name: 코드베이스 인덱스 업데이트 (Update codebase index)
run: npx ai-codex
...

프레임워크	자동 감지 여부	스캔 항목
Next.js (App Router)	예시(Yes)	app/ 또는 src/app/ (api/**/route.ts, **/page.tsx), lib/, components/
Next.js (Pages Router)	예시(Yes)	pages/ 또는 src/pages/ (api/**/*.ts, **/*.tsx excl. _app/_document/_error), lib/, components/
SvelteKit	예시(Yes)	src/routes/ (+server.ts 라우트, +page.svelte 페이지), src/lib/, components
일반 TypeScript (Generic TypeScript)	예시(Yes)	src/, lib/, utils/, components/

스키마 소스는 여러 ORM에서 자동 감지됩니다:

Prisma: prisma/schema.prisma
(또는 prisma/schema/ 아래에 중첩됨)
Drizzle: db/schema.ts, src/db/schema.ts, lib/db/schema.ts, src/lib/db/schema.ts, app/db/schema.ts, src/app/db/schema.ts, database/schema.ts, drizzle/schema.ts, 또는 src/lib/server/db/schema.ts

(SvelteKit 컨벤션 (convention)) — <base>/schema/가 .ts 파일들의 디렉토리인 파일 분할 레이아웃 (split-file layouts) 포함

두 ORM 중 하나에 대해 --schema <path>로 재정의 가능 (파일 확장자가 파서를 결정함).

런타임 (Runtime)	자동 감지 (Auto-detected)	감지 내용
Node.js	예 (기본값)	표준 Node 프로젝트
Cloudflare Workers	예 (SvelteKit)	svelte.config.js 내의 adapter-cloudflare, 또는 wrangler.jsonc / wrangler.toml — D1, R2, KV 바인딩을 추출함. Next.js 프로젝트는 항상 Node.js로 보고됨.

node_modules/, .next/, dist/, build/, .git/, .worktrees/, __pycache__/, .turbo/, .cache/, coverage/, .nyc_output/, .parcel-cache/, 그리고 ai-codex 자체 출력물 (.ai-codex/, .claude/)
.d.ts 선언 파일 (declaration files), .map 소스 맵 (source maps), .min.js / .min.css 압축 파일 (minified files)

• 백업 파일 (*.backup.*, *-backup-*)

• components/ui/ 내의 shadcn/radix UI 프리미티브 (primitives) (button, dialog 등)

• 리포지토리 (repo) 포크 (Fork)

• 기능 브랜치 (feature branch) 생성:
  git checkout -b my-feature

• 변경 사항 적용

• 실제 프로젝트에서 테스트:
  cd /path/to/your/project && npx tsx /path/to/ai-codex/src/generate-codex.ts

• 풀 리퀘스트 (pull request) 제출

• 더 많은 프레임워크 지원 (Remix, Astro)

• 더 많은 ORM 지원 (TypeORM, Knex)

• 지속적인 재생성을 위한 워치 모드 (watch mode, --watch)

• 출력물 내 토큰 수 (Token count) 추정

• Python 프로젝트 지원 (FastAPI, Django)

MIT