Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
AI 코딩 어시스턴트의 토큰 낭비를 줄이기 위해 코드베이스의 핵심 구조를 컴팩트한 인덱스로 생성해주는 도구입니다. API 라우트, 페이지 트리, DB 스키마 등을 구조화된 파일로 만들어 AI가 즉시 컨텍스트를 파악하도록 돕습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기이 프로젝트는 전적으로 Claude Code (Anthropic의 AI 코딩 어시스턴트)에 의해 설계, 작성 및 게시되었습니다. 컨셉, 구현, 문서화 및 예제는 모두 단일 대화 세션에서 생성되었습니다.
AI 코딩 어시스턴트에게 프로젝트 구조에 대한 즉각적인 컨텍스트를 제공하는 컴팩트한 코드베이스 인덱스를 생성합니다. 매 대화 시작 시 파일 탐색에 50K 이상의 토큰을 낭비하는 대신, AI 어시스턴트가 미리 구축된 인덱스를 읽고 즉시 작업을 시작할 수 있습니다.
AI 코딩 어시스턴트(Claude Code, Cursor, GitHub Copilot 등)와 대화를 시작할 때마다, 어시스턴트는 파일을 읽고, 디렉토리를 스캔하고, 정신적 모델(mental model)을 구축하며 코드베이스를 탐색하는 데 수천 개의 토큰을 소비합니다. 이는 매 대화마다 발생합니다.
ai-codex는 다음과 같은 내용을 캡처하는 컴팩트하고 구조화된 참조 파일을 생성하여 이 문제를 해결합니다:
결과: 매번 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