프로젝트 문서 생성기
코드베이스를 분석하여 구조화된 프로젝트 문서를 생성합니다. 실제 코드를 반영한 문서를 만들며, 이상적인 아키텍처가 아닌 현재 상태를 기준으로 합니다.
사용 시점
- 새 프로젝트에 초기 문서가 필요할 때
- 문서가 누락되었거나 최신 상태가 아닐 때
- 코드베이스에 누군가를 온보딩할 때
- 리팩터 후 문서를 새로 고칠 때
워크플로우
1. 프로젝트 유형 감지
프로젝트 루트를 스캔하여 어떤 종류의 프로젝트인지 확인합니다:
| 표시기 | 프로젝트 유형 |
|---|---|
wrangler.jsonc / wrangler.toml | Cloudflare Worker |
vite.config.ts + src/App.tsx | React SPA |
astro.config.mjs | Astro 사이트 |
next.config.js | Next.js 앱 |
package.json에 hono 포함 | Hono API |
src/index.ts에 Hono 포함 | API 서버 |
drizzle.config.ts | 데이터베이스 계층 존재 |
schema.ts 또는 schema/ | 데이터베이스 스키마 존재 |
pyproject.toml / setup.py | Python 프로젝트 |
Cargo.toml | Rust 프로젝트 |
2. 생성할 문서 선택 요청
어떤 문서를 생성할까요?
1. ARCHITECTURE.md — 시스템 개요, 스택, 디렉토리 구조, 주요 흐름
2. API_ENDPOINTS.md — 라우트, 메서드, 파라미터, 응답 형태, 인증
3. DATABASE_SCHEMA.md — 테이블, 관계, 마이그레이션, 인덱스
4. 모두 생성
프로젝트에 맞는 문서만 제안합니다. 정적 사이트에 API_ENDPOINTS.md를 제안하지 않고, 데이터베이스가 없으면 DATABASE_SCHEMA.md를 제안하지 않습니다.
3. 코드베이스 스캔
요청된 각 문서에 대해 관련 소스 파일을 읽습니다:
ARCHITECTURE.md — 스캔 대상:
package.json/pyproject.toml(스택, 의존성)- 진입점 (
src/index.ts,src/main.tsx,src/App.tsx) - 설정 파일 (
wrangler.jsonc,vite.config.ts,tsconfig.json) - 디렉토리 구조 (상위 2레벨)
- 주요 모듈 및 내보내기
API_ENDPOINTS.md — 스캔 대상:
- 라우트 파일 (
src/routes/,src/api/, 또는 index 인라인) - 미들웨어 파일 (인증, CORS, 로깅)
- 요청/응답 타입 또는 Zod 스키마
- 오류 처리 패턴
DATABASE_SCHEMA.md — 스캔 대상:
- Drizzle 스키마 파일 (
src/db/schema.ts,src/schema/) - 마이그레이션 파일 (
drizzle/,migrations/) - 원시 SQL 파일 (존재하는 경우)
- 시드 파일 (존재하는 경우)
4. 문서 생성
각 문서를 docs/ 디렉토리에 작성합니다 (디렉토리가 없으면 생성). 프로젝트에 이미 문서가 있으면 덮어쓰지 않고 업데이트를 제안합니다.
docs/ 디렉토리가 없는 소규모 프로젝트의 경우 프로젝트 루트에 작성합니다.
문서 템플릿
ARCHITECTURE.md
# 아키텍처
## 개요
[한 문단: 이 프로젝트의 기능과 구조]
## 스택
| 계층 | 기술 | 버전 |
|-------|-----------|---------|
| 런타임 | [예: Cloudflare Workers] | — |
| 프레임워크 | [예: Hono] | [버전] |
| 데이터베이스 | [예: D1 (SQLite)] | — |
| ORM | [예: Drizzle] | [버전] |
| 프론트엔드 | [예: React 19] | [버전] |
| 스타일링 | [예: Tailwind v4] | [버전] |
## 디렉토리 구조
[주석이 포함된 트리 — 상위 2레벨, 목적 설명 포함]
## 주요 흐름
### [흐름 1: 예: "사용자 인증"]
[단계별: 요청 → 미들웨어 → 핸들러 → 데이터베이스 → 응답]
### [흐름 2: 예: "데이터 처리 파이프라인"]
[시스템을 통한 단계별 흐름]
## 설정
[주요 설정 파일 및 제어 내용]
## 배포
[배포 방법, 필요한 환경 변수, 빌드 명령어]
API_ENDPOINTS.md
# API 엔드포인트
## 기본 URL
[예: `https://api.example.com` 또는 상대 경로 `/api`]
## 인증
[방식: Bearer 토큰, 세션 쿠키, API 키, 없음]
[토큰 출처, 획득 방법]
## 엔드포인트
### [그룹: 예: 사용자]
#### `GET /api/users`
- **인증**: 필수
- **파라미터**: `?page=1&limit=20`
- **응답**: `{ users: User[], total: number }`
#### `POST /api/users`
- **인증**: 필수 (관리자)
- **본문**: `{ name: string, email: string }`
- **응답**: `{ user: User }` (201)
- **오류**: 400 (유효성 검사), 409 (이메일 중복)
[각 엔드포인트에 대해 반복]
## 오류 형식
[표준 오류 응답 형태]
## 속도 제한
[해당되는 경우]
DATABASE_SCHEMA.md
# 데이터베이스 스키마
## 엔진
[예: Cloudflare D1 (SQLite), PostgreSQL, MySQL]
## 테이블
### `users`
| 열 | 타입 | 제약 조건 | 설명 |
|--------|------|-------------|-------------|
| id | TEXT | PK | UUID |
| email | TEXT | UNIQUE, NOT NULL | 사용자 이메일 |
| name | TEXT | NOT NULL | 표시 이름 |
| created_at | TEXT | NOT NULL, DEFAULT now | ISO 타임스탬프 |
### `posts`
[동일 형식]
## 관계
[외래 키, 조인 패턴, 캐스케이딩 규칙]
## 인덱스
[기본 키가 아닌 인덱스와 존재 이유]
## 마이그레이션
- 생성: `npx drizzle-kit generate`
- 로컬 적용: `npx wrangler d1 migrations apply DB --local`
- 원격 적용: `npx wrangler d1 migrations apply DB --remote`
## 시드 데이터
[시드 스크립트가 있는 경우 참조]
품질 규칙
- 계획된 것이 아닌 존재하는 것을 문서화 — 실제 코드를 읽고, 엔드포인트나 테이블을 임의로 만들지 마세요
- 버전 포함 — 기억에 의존하지 말고 package.json/lock 파일에서 추출하세요
- 실제 응답 형태 표시 — 코드의 TypeScript 타입 또는 Zod 스키마에서 복사하세요
- 스캔 가능하게 유지 — 단락보다 표, 산문보다 코드 블록을 선호하세요
- CLAUDE.md를 복제하지 마세요 — 아키텍처 정보가 이미 CLAUDE.md에 있으면 ARCHITECTURE.md로 옮기거나 참조하세요
- 간격 표시 — 명확한 목적이 없는 문서화되지 않은 라우트나 테이블을 발견하면
<!-- TODO: 목적 문서화 -->로 표시하세요
기존 문서 업데이트
이미 문서가 있는 경우:
- 기존 문서 읽기
- 현재 코드베이스와 차이점 비교
- 변경된 내용을 사용자에게 표시 (새 엔드포인트, 제거된 테이블, 업데이트된 스택)
- 사용자가 직접 작성한 메모나 섹션을 보존하면서 업데이트 적용
사용자가 문서에 추가한 커스텀 콘텐츠를 절대 자동으로 덮어쓰지 마세요.