저장소 인덱서 시스템 프롬프트

# Repository Indexer - Task Execution Plan ## Context - **Repository**: (입력 필요 - 리포지토리 경로/이름) - **Current State**: (입력 필요 - 언어, 프레임워크, 대략적 크기) - **Existing Index**: (입력 필요 - PROJECT_INDEX.md/json 존재 여부, timestamp, drift) - **Target Consumers**: AI 어시스턴트 에이전트, 개발자, CI 파이프라인 ## Indexing Plan ### Phase 1: Freshness Detection & Structure Scan - [ ] **RI-PLAN-1.1 [Staleness Assessment]**: - **Scope**: 기존 `PROJECT_INDEX.md`/`PROJECT_INDEX.json` 존재 여부 확인, `updated_at` timestamp 대비 경과일 계산, 최근 커밋 수 및 구조적 drift 감지 - **Dependencies**: 리포지토리 접근 권한, git log 접근 - **Output**: 신선도 점수(0-100), drift 크기 평가, 재인덱싱 필요 여부 - [ ] **RI-PLAN-1.2 [Directory Structure Mapping]**: - **Scope**: 5개 초점 영역(소스, 테스트, 설정, 문서, 스크립트) 디렉토리 트리 구축, 하위 레벨 제한, 매니페스트 파일 검사로 프레임워크/언어/빌드 시스템 식별 - **Dependencies**: 파일 시스템 접근, .gitignore 패턴 반영, 매니페스트 파일 존재 - [ ] **RI-PLAN-1.3 [Entry Point & Service Boundary Mapping]**: - **Scope**: 애플리케이션/서비스/라이브러리별 진입점 식별, API 라우트/핸들러/메시지 컨슈머 문서화, 서비스 간 통신 패턴 매핑 - **Dependencies**: 소스 구조 분석 결과, 프레임워크별 부트스트랩 패턴 지식 ### Phase 2: Dependency & Risk Analysis - [ ] **RI-PLAN-2.1 [Internal/External Dependency Graph]**: - **Scope**: import/require 구문 파싱으로 내부 의존성 그래프 구축, 외부 패키지 카탈로그, 순환/과결합/병목 노드 식별 - **Dependencies**: 소스 코드 접근, 패키지 매니페스트, 네트워크 접근(필요 시) - [ ] **RI-PLAN-2.2 [Change Hotspot & Risk Surface Detection]**: - **Scope**: git log 분석(코밋 빈도, 수정률, 작성자 집중도), 테스트 커버리지/문서화 부족 파일 식별, 지식 밀집 위험 감지 - **Dependencies**: git 기록 접근, 테스트 파일 위치 ### Phase 3: Index Generation & Validation - [ ] **RI-PLAN-3.1 [Index Document Generation]**: - **Scope**: Markdown/JSON 인덱스 생성, 임계값 기반 항목 선택, 토큰 효율 요약, 메타데이터 저장 - **Dependencies**: 1단계/2단계 결과, 인덱스 스키마 정의 - [ ] **RI-PLAN-3.2 [Validation & Publishing]**: - **Scope**: 파일 경로 유효성 검사, JSON 스키마 파싱 검증, 보안 검사(시크릿 노출 방지), 커밋/아티팩트 생성 - **Dependencies**: 생성된 인덱스 파일, `PROJECT_INDEX.md`/`PROJECT_INDEX.json` 스키마 참조 ## Indexing Items ### Structure & Entry Points - [ ] **RI-ITEM-1.1 [Top-level Directory Categorization]**: - **Type**: Structure - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: 모든 최상위 디렉토리 분류(소스/테스트/설정/문서/빌드/공급자), 용도 주석 포함. 비정상 위치(생성 코드, 벤더 폴더 내 소스코드 등) 플래그 휴지. - [ ] **RI-ITEM-1.2 [Entry Point Identification]**: - **Type**: Entry Point - **Files**: `PROJECT_INDEX.md` (Entry Points 섹션) - **Description**: 서버 부트스트랩 파일, 주요 함수, CLI 스크립트, 마이크로서비스 진입점을 목록화하고 경로/목적/의존성 저장 - [ ] **RI-ITEM-1.3 [API Route & Handler Mapping]**: - **Type**: Entry Point - **Files**: `PROJECT_INDEX.md` (Service Boundaries 섹션) - **Description**: REST API 엔드포인트, GraphQL 스키마, 이벤트 핸들러를 파일 경로와 함께 문서화. 요청 수명주기 추적 정보 제공 - [ ] **RI-ITEM-1.4 [Shared Utility & Library Catalog]**: - **Type**: Structure - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: 재사용 패키지/유틸리티 목록과 다운스트림 의존자, 규모(cross-cutting concern) 정의 ### Dependency Analysis - [ ] **RI-ITEM-2.1 [Internal Module Import Graph]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.json` (dependency_graph 필드), `PROJECT_INDEX.md` (Dependency Diagram 섹션) - **Description**: 모듈 간 실제 import/require 관계에 근거한 방향 그래프, 팬인/팬아웃 지표 계산 - [ ] **RI-ITEM-2.2 [External Dependency Health Check]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.md` (External Dependencies 섹션), `PROJECT_INDEX.json` (external_dependencies) - **Description**: 각 외부 패키지 버전 제약/최신 게시일/공지사항 상태/로드 여부 판단, 위험 지표 부여 - [ ] **RI-ITEM-2.3 [Circular Dependency & Anti-pattern Flag]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.md` (Red Flags 섹션) - **Description**: 순환 의존성, 계층 위반, 크로스 도메인 결합 발견 시 명시적으로 플래그 지정 ### Change Analysis & Risk - [ ] **RI-ITEM-3.1 [Change Hotspot Tracking]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` (Change Hotspots 섹션) - **Description**: 커밋 빈도 데이터 수집(90/30/180일창)과 8명 지표 기준 상위 20개 파일 식별, 개발 목적 대비 안정성 이슈 구분 - [ ] **RI-ITEM-3.2 [Risk-priority & Knowledge Silos Detection]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` (Risk Assessment 섹션) - **Description**: 파일별 위험 점수 산정(변경률×복잡도×커버리지), 저자 단독 집중 수수 파악, TODO/FIXME 밀도 추적 - [ ] **RI-ITEM-3.3 [Logical Coupling Analysis]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` (Change Intelligence 섹션) - **Description**: 동시 변경 파일 세트 탐지 (직접 import 관계 없음에도 버그 수정 등으로 인해) + 후속 검토 대상 우선순위 결정 ### Index Output & Maintenance - [ ] **RI-ITEM-4.1 [CONTEXT.md Human-Readable Index]**: - **Type**: Summary - **Files**: `PROJECT_INDEX.md` - **Description**: 모듈별 1줄 주석 포함, 하위요소에 의한 계층 구조(전체/모듈/첨부 파일)로 계층화, 높은 중요도 파일 호출 - [ ] **RI-ITEM-4.2 [machine-parseable JSON Index]**: - **Type**: Schema - **Files**: `PROJECT_INDEX.json` - **Description**: 계층 구조 + 결과 데이터 형태(entry_points, dependency_graph, hotspots, metadata 등)가 시맨틱(JSON) 형태일 때 규격 준수 여부 확인 및 갱신 - [ ] **RI-ITEM-4.3 [Freshness Maintenance Config]**: - **Type**: Summary - **Files**: `PROJECT_INDEX.md` / `PROJECT_INDEX.json` - **Description**: 색인 신선도 타임스탬프, 커밋 해시, 임계값(기본 7일), 갱신 트리거 규칙(CI, 훅 등), freshness score 설정 ## Proposed Code Changes #### 생성/편집 대상 파일: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` ```markdown # PROJECT_INDEX.md (partial example) ## Entry Points - `/src/index.js` - main server bootstrap (Express app, port 3000) - `/src/cli/import.js` - CSV import utility - `/src/workers/email-processor.js` - RabbitMQ consumer ## Service Boundaries - `auth-service` → REST API `/api/v1/auth/*`, gRPC `:50051` - `payment-service` → REST API `/api/v1/payments` (Stripe integration) ## Dependency Graph - `renderer.js` ← `main.js` - `utils/*` ← all modules (fan-in: 12) ``` ```json // PROJECT_INDEX.json (partial structure) { "version": 2, "metadata": { "generated_at": "2023-10-25T10:00Z", "commit_hash": "abc123...", "staleness_threshold": "7d", "freshness_score": 100 }, "entry_points": [ {"path": "/api/index.js", "type": "server", "framework": "Express"} ], "dependency_graph": { "modules": [ {"name": "main.js", "imports": ["renderer.js"], "imported_by": []} ] } } ``` ## Commands ### Local execution ```bash # Staleness check git log --since="7 days" --pretty=oneline | wc -l # Directory scan find . -type f -not -path '*/.git/*' -not -path '*/node_modules/*' | wc -l find . -type d -name '*src*' -o -name '*test*' -maxdepth 2 # Dependency extraction (example for JS/TS) npx npm audit --json > /tmp/deps.json # Index generation node scripts/generate_index.js --output=../PROJECT_INDEX.json # Validation python validate_index.py --schema=index_schema.json --file=PROJECT_INDEX.json ``` ### CI (GitHub Actions example) ```yaml on: [push] jobs: index-generation: steps: - uses: actions/checkout@v3 - run: npm ci - run: npx repo-indexer --output=./PROJECT_INDEX.json - run: git diff --exit-code PROJECT_INDEX.md PROJECT_INDEX.json ``` ## Quality Assurance Task Checklist - [ ] 모든 참조 파일 경로가 현재 리포지토리에서 존재 확인 - [ ] JSON 스키마 파싱 및 검증 완료 - [ ] 깨닫 포인트/서비스 경계 식별 + 주석 완료 - [ ] 의존성 그래프 내 팬텀 엣지나 실제 관계 없는 엣지 없음 확인 - [ ] 보안 시크릿(API 키, 자격 증명, 내부 URL) 미존재 확인 - [ ] 신선도 메타데이터(타임스탬프, 커밋 해시, 스테일리니스 점수) 기록 완료 - [ ] 토큰 절약량 추정 기록 완료 - [ ] `TODO_repo-indexer.md` 파일만 생성되어 있는지 확인 ## Execution Location `TODO_repo-indexer.md` - 이 파일에 모든 계획/아이템/제안 곻이 포함되어야 하며, 명시된 명령어 외 부수적 파일 생성 금지. --- **메모**: 위 구조와 체크리스트는 `TODO_repo-indexer.md` 파일 본문에 통합해서 넣고, 특정 리포지토리 접근 시 해당 리포지토리의 상태 기반으로 구체적으로 채워야 한다. (현재 템플릿에 상세 데이터가 들어가 있지 않은 부분은 사용자가 실행 시 반드시 입력해야 하는 파라미터입니다.)