최초 프로젝트 업로드 (Script Auto Commit)

This commit is contained in:
2025-12-03 22:03:53 +09:00
commit 12b1305fb2
20 changed files with 1161 additions and 0 deletions

View File

@@ -0,0 +1,35 @@
<!--
단계별 구현 체크리스트
implementation_plan.md
-->
# Implementation Plan
이 문서는 프로젝트의 개발 진행 상황을 추적합니다. AI는 이 문서를 참조하여 현재 단계(Context)를 파악하고 작업을 수행해야 합니다.
## Phase 1: 환경 설정 및 기반 구축 (Setup) [ ]
- [ ] 프로젝트 폴더 구조 생성 및 Git 초기화
- [ ] `copilot-instructions.md``.env` 환경 변수 템플릿 설정
- [ ] 언어별 패키지 매니저 설정 (requirements.txt, package.json, go.mod 등)
- [ ] 기본 로깅(Logging) 및 설정(Config) 모듈 구현
## Phase 2: 코어 비즈니스 로직 (Core Domain) [ ]
- [ ] `project_requirements.md`의 핵심 기능을 담당하는 도메인 모델 설계
- [ ] 데이터 처리 및 비즈니스 로직 구현 (순수 함수 위주)
- [ ] 핵심 로직에 대한 단위 테스트(Unit Test) 작성 및 통과 확인
## Phase 3: 인터페이스 및 데이터 연동 (Integration) [ ]
- [ ] 외부 API 연동 또는 데이터베이스 연결 모듈 구현
- [ ] 사용자 인터페이스(UI) 또는 API 엔드포인트 구현
- [ ] 예외 처리(Exception Handling) 및 에러 응답 표준화
## Phase 4: 시스템 통합 및 실행 (System Interface) [ ]
- [ ] 메인 진입점(Entry Point) 구현 (main.py, index.js 등)
- [ ] 전체 프로세스 통합 테스트 (Integration Test)
- [ ] 로컬 환경에서의 End-to-End 실행 검증
## Phase 5: 최적화 및 리팩토링 (Refinement) [ ]
- [ ] 성능 병목 구간 분석 및 비동기/캐싱 적용
- [ ] `review_prompt.md` 기반 자가 점검 및 코드 품질 개선
- [ ] 최종 문서화 (README.md 작성)
- [ ] 프로그램 사용법 작성 (user_guide.md)

View File

@@ -0,0 +1,45 @@
<!--
기획 및 로직 설계서
project_requirements.md
-->
# Product Requirements Document (PRD)
## 1. Project Overview
- **프로젝트명:** [프로젝트 이름 입력]
- **해결하려는 문제:** [이 프로젝트가 해결하고자 하는 핵심 문제 정의]
- **목표:** [프로젝트의 최종 성공 기준]
- **주요 타겟 유저:** [사용자 페르소나 정의]
## 2. Core Features (User Stories)
*(우선순위가 높은 순서대로 작성)*
1. **[핵심 기능 1]:** [사용자는 ~할 수 있다. 이를 통해 ~를 얻는다.]
2. **[핵심 기능 2]:** [상세 설명]
3. **[핵심 기능 3]:** [상세 설명]
4. **[부가 기능]:** [상세 설명]
## 3. Tech Stack & Architecture
- **Frontend:** [예: React, Tailwind CSS]
- **Backend:** [예: Python FastAPI, Node.js]
- **Database:** [예: PostgreSQL, Redis]
- **Infra:** [예: AWS Lambda, Docker]
## 4. Data Flow & Logic
- **Input:** [데이터 입력 소스]
- **Process:**
1. [단계 1: 데이터 수집/수신]
2. [단계 2: 핵심 비즈니스 로직 처리]
3. [단계 3: 데이터 저장 또는 가공]
- **Output:** [최종 결과물 형태]
## 5. File Structure Plan (Suggested)
*(AI가 제안하거나 개발자가 미리 지정)*
- `/src/core/` : 핵심 비즈니스 로직
- `/src/api/` : 외부 인터페이스 및 API 핸들러
- `/src/utils/` : 공통 유틸리티
- `/tests/` : 단위 및 통합 테스트
## 6. Non-Functional Requirements
- **성능:** [예: 응답 속도 200ms 이내, 동시 접속 1000명 처리]
- **보안:** [예: 모든 데이터 전송은 HTTPS, 민감 정보 암호화]
- **안정성:** [예: 외부 API 실패 시 재시도(Retry) 로직 구현]

28
docs/project_state.md Normal file
View File

@@ -0,0 +1,28 @@
# Current Session State
## 🎯 Current Phase
- **Phase:** xxx
- **Focus:** xxx
## ✅ Micro Tasks (ToDo)
- [x] xxx
- [x] xxx
- [x] xxx
- [x] xxx
## 📝 Context Dump (Memo)
### xxx 완료 내역:
- **xxx:** xxx
- **xxx:** xxx
- **xxx:** xxx
### 검증된 주요 컴포넌트:
1. **xxx:** xxx
1. **xxx:** xxx
1. **xxx:** xxx
### Next Phase (xxx):
- xxx
- xxx
- xxx

108
docs/review_prompt.md Normal file
View File

@@ -0,0 +1,108 @@
<!--
AI 코드 리뷰 지침
review_prompt.md
-->
<!-- 코드 리뷰 프롬프트(실무용, 핵심 위주) -->
<!--
# 코드 리뷰 프롬프트
다음 지침에 따라 코드를 검토하고 코드 리뷰 레포트(code_review_report.md)를 작성해주세요.
## [1. 분석 컨텍스트]
언어/환경: (예: Python 3.11, AWS Lambda)
코드 목적: (예: 결제 로직 처리)
핵심 요구: (예: 동시성 문제 해결, 성능 최적화)
## [2. 역할 및 원칙]
당신은 가장 까다로운 시니어 개발자입니다. 칭찬은 생략하고, 오직 **결함(Bug)**과 **위험 요소(Risk)**만 찾아내십시오.
- 원칙: 코드가 "문제없다"고 가정하지 마십시오. 숨겨진 논리적 오류, 예외 처리 누락, 보안 취약점을 집요하게 파고드십시오.
- 금지: 코드에 없는 내용을 추측하여 지적하지 마십시오(No Hallucination).
## [3. 중점 검토 항목]
1. 논리 오류: 엣지 케이스(Null, 0, 경계값)에서 로직이 깨지지 않는가?
2. 안정성: 예외가 발생했을 때 시스템이 안전하게 복구되거나 종료되는가? (Silent Failure 방지)
3. 보안: SQL 인젝션, XSS, 민감 정보(비번/키) 노출이 있는가?
4. 효율성: 불필요한 반복문(O(n²))이나 메모리 누수가 있는가?
## [4. 출력 형식]
발견된 문제가 없다면 "특이사항 없음"이라고 하십시오. 문제가 있다면 아래 양식으로 핵심만 적어주세요.
### 🚨 치명적 문제 (Critical)
- 위치: [라인 번호 또는 코드 스니펫]
- 이유: (왜 위험한지 기술적 설명)
- 해결책: (수정된 코드 블록)
### ⚠️ 개선 제안 (Warning)
- 위치: [라인 번호]
- 내용: (잠재적 위험 또는 가독성/성능 개선 제안)
-->
<!-- 코드 리뷰 프롬프트(심화버전) -->
# 코드 리뷰 프롬프트
다음 지침에 따라 코드를 검토하고 코드 리뷰 레포트(code_review_report.md)를 작성해주세요.
## [1. 분석 컨텍스트]
정확한 분석을 위해 아래 정보를 기반으로 코드를 검토하십시오.
- 언어/프레임워크: (예: Python 3.11, React 18, Spring Boot)
- 코드의 목적: (예: 사용자 인증, 데이터 파싱, 결제 트랜잭션)
- 주요 제약사항: (예: 높은 동시성, 메모리 최적화, 엄격한 보안 기준)
## [2. 역할 및 원칙]
당신은 '무관용 원칙'을 가진 수석 소프트웨어 아키텍트입니다.
- 목표: 칭찬보다는 결함(Bug), 보안 취약점, 성능 병목, 유지보수 저해 요소를 찾아내는 데 집중하십시오.
- 금지: 코드에 없는 내용을 추측하여 지적하지 마십시오(Zero Hallucination).
- 기준: "작동한다"에 만족하지 말고, "견고하고 안전한가"를 기준으로 판단하십시오.
## [3. 사전 단계: 의도 파악]
분석 전, 이 코드가 수행하는 핵심 로직을 3줄 이내로 요약하여, 당신이 코드를 올바르게 이해했는지 먼저 보여주십시오.
## [4. 심층 검토 체크리스트]
다음 항목을 기준으로 코드를 해부하십시오.
### 1. 논리 및 엣지 케이스 (Logic & Edge Cases)
- 가상 실행: 코드를 한 줄씩 추적하며 변수 상태 변화를 검증했는가?
- 경계값: Null, 빈 값, 음수, 최대값 등 극한의 입력에서 로직이 깨지지 않는가?
- 예외 처리: 에러를 단순히 삼키지 않고(Silent Failure), 적절히 처리하거나 전파하는가?
- 모듈성 및 API 설계: 함수/클래스의 공개 인터페이스(Public Interface)가 직관적이고 일관성이 있는가? 테스트 용이성(Testability)을 위해 의존성이 잘 분리되었는가?
### 2. 보안 및 안정성 (Security & Stability)
- 입력 검증: SQL 인젝션, XSS, 버퍼 오버플로우 취약점이 없는가?
- 정보 노출: 비밀번호, API 키, PII(개인정보)가 하드코딩되거나 로그에 남지 않는가?
- 자원 관리 및 메모리 안정성:
- 일반: 파일, DB 연결, 네트워크 소켓 등 모든 자원은 예외 발생 시에도 확실히 해제되는가?
- 언어별 핵심 원칙 (조건부 검증):
- (C++ 프로젝트인 경우): Raw pointer (`new`/`delete`)가 발견되지 않는가? 동적 자원은 스마트 포인터(RAII)로 관리되며, 함수가 예외 안전성을 제공하는가?
- (Python 프로젝트인 경우): 불필요한 참조 순환이나 메모리 누수 패턴이 없는가? 멀티스레딩 환경에서 동시성(Locking) 처리가 올바른가?
### 3. 동시성 및 성능 (Concurrency & Performance)
- 동기화: (해당 시) 경쟁 상태(Race Condition), 데드락, 스레드 안전성 문제가 없는가?
- 효율성: 불필요한 중첩 반복문(O(n²))이나 중복 연산이 없는가?
- 시스템 성능:
- I/O 병목: DB 쿼리나 네트워크 호출이 불필요하게 반복(N+1 쿼리)되거나 동기적으로 실행되어 시스템 전체를 막는 부분이 없는가?
- C++ (캐시 효율): 대용량 데이터 구조 설계 시 CPU 캐시 효율성(Cache Locality)이 고려되었는가?
## [5. 출력 형식: 결함 보고서]
발견된 문제가 없다면 "특이사항 없음"으로 명시하십시오. 문제가 있다면 아래 양식을 엄수해 주세요.
### 🚨 치명적 문제 (Critical Issues)
(서비스 중단, 데이터 손실/오염, 보안 사고 위험이 있는 경우)
[C-1] 문제 제목
├─ 위치: [파일경로:라인] 또는 [코드 스니펫 3~5줄]
├─ 원인: [기술적 원인 설명]
├─ 재현/조건: [문제가 발생하는 상황]
└─ 해결책: [수정된 코드 블록 (Auto-Fix)]
### ⚠️ 개선 제안 (Warnings & Improvements)
(성능 저하, 유지보수성 부족, 잠재적 버그)
[W-1] 문제 제목
├─ 위치: [파일경로:라인] 또는 [코드 스니펫]
├─ 분석: [문제점 설명]
└─ 권장 조치: [리팩토링 제안]
### ✅ 잘된 점 (Strengths)
(핵심적인 장점 1~2가지만 간결하게)

104
docs/user_guide.md Normal file
View File

@@ -0,0 +1,104 @@
# xxx 사용 가이드
## 개요
xxx
## 1. 사전 준비 (필수)
### 1.1 xxx
1. xxx
2. xxx
3. xxx
### 1.2 xxx
- xxx
- xxx
- xxx
### 1.3 환경변수 설정 (`.env` 파일)
```bash
# xxx
xxx
# xxx
xxx
```
⚠️ `.env` 파일을 `.gitignore`에 추가하여 비밀 정보를 저장소에 커밋하지 마세요.
## 2. config.json 설정
### 2.1 기본 설정 (신중하게)
```json
{
xxx
}
```
### 2.2 각 항목 설명
#### xxx
- xxx
- xxx
- xxx
#### xxx
- xxx
- xxx
- xxx
## 3. xxx
### xxx
- [ ] xxx
- [ ] xxx
- [ ] xxx
### xxx
- [ ] xxx
- [ ] xxx
- [ ] xxx
## 4. xxx
### 4.1 xxx
1. xxx
2. xxx
3. xxx
### 4.2 xxx
1. xxx
2. xxx
3. xxx
## 5. 운영 (Troubleshooting)
### xxx
1. xxx
2. xxx
3. xxx
### xxx
1. xxx
2. xxx
3. xxx
## 6. 성능/안정성 팁
1. xxx:
- xxx
- xxx
- xxx
2. xxx:
- xxx
- xxx
- xxx
## 7. FAQ
**Q: xxx**
A: xxx
**Q: xxx**
A: xxx

70
docs/workflow.md Normal file
View File

@@ -0,0 +1,70 @@
<!-- 사용 방법 (워크플로우) -->
# Automated Development Workflow Protocol
이 문서는 AI가 프로젝트를 **자동으로 진행**하기 위한 행동 수칙을 정의합니다.
사용자가 **"워크플로우로 진행해줘"**라고 명령하면, AI는 아래 **[Execution Loop]**를 따릅니다.
## 🔄 Execution Loop (반복 실행 규칙)
AI는 다음 순서를 엄격히 준수해야 합니다.
1. **Status Check (상태 확인):**
- `implementation_plan.md`를 읽고, **체크되지 않은( `[ ]` ) 가장 첫 번째 Phase**를 식별합니다.
2. **Proposal & Approval (제안 및 승인 요청):**
- 사용자에게 현재 진행해야 할 Phase와 수행할 작업 내용을 요약하여 보고합니다.
- **"Phase X 작업을 시작하시겠습니까?"** 라고 묻고, **사용자의 승인(Yes/Go)을 대기**합니다. (즉시 코드를 작성하지 마십시오.)
3. **Execution (실행):**
- 사용자가 승인하면, 아래 **[Phase Detail Prompts]**에 정의된 해당 단계의 지침에 따라 코드를 작성합니다.
- 이때 반드시 `copilot-instructions.md`의 C++/Python 규칙과 `project_requirements.md`의 요구사항을 준수합니다.
4. **Update Plan (플랜 업데이트):**
- 작업이 완료되면 `implementation_plan.md`의 해당 항목을 체크(`[x]`) 표시하여 업데이트합니다.
5. **Self-Correction (자가 점검):**
- 작성된 코드가 `review_prompt.md`의 기준(성능, 예외 처리 등)을 충족하는지 확인하고, 부족한 점이 있다면 스스로 수정합니다.
---
## 📋 Phase Detail Prompts (단계별 수행 지침)
AI는 실행 단계(Execution)에서 현재 Phase에 맞는 아래 지침을 수행합니다.
### Phase 1: 환경 설정 (Setup)
- **목표:** 프로젝트 기반 마련 및 의존성 설정
- **지침:**
1. `copilot-instructions.md`의 Tech Stack을 확인하여 폴더 구조 생성.
2. Python(`requirements.txt`, `.env`) 및 C++(`CMakeLists.txt`) 설정 파일 작성.
3. `.gitignore` 및 기본 설정 파일 생성.
### Phase 2: 코어 로직 구현 (Core Domain)
- **목표:** 비즈니스 로직 및 데이터 모델 구현
- **지침:**
1. 코딩 전, **알고리즘 설계와 시간 복잡도**를 주석으로 먼저 작성.
2. `copilot-instructions.md`의 **Core Principles**를 준수하여 순수 함수/클래스 구현.
3. 반드시 **단위 테스트(Unit Test)** 코드를 함께 작성.
### Phase 3: 인터페이스 연동 (Integration)
- **목표:** 외부 API, DB, UI 연동
- **지침:**
1. 외부 시스템과의 통신 로직 구현.
2. **Error Handling:** 네트워크 실패, 타임아웃 등을 대비한 방어 코드(`try-except`, `RAII`) 작성.
3. `project_requirements.md`의 데이터 흐름(Data Flow) 준수 확인.
### Phase 4: 시스템 통합 (System Interface)
- **목표:** 메인 진입점 및 전체 프로세스 연결
- **지침:**
1. `main.py` 또는 `main.cpp` 진입점 구현.
2. 전체 모듈을 연결하고 통합 테스트(Integration Test) 시나리오 작성.
3. 실제 실행 가능한 상태인지 검증.
### Phase 5: 최적화 및 리팩토링 (Refinement)
- **목표:** 품질 향상 및 안정화
- **지침:**
1. `review_prompt.md`를 기준으로 전체 코드 리뷰 수행.
2. 성능 병목(O(N^2) 이상) 및 메모리 누수 점검.
3. 최종 문서(README.md) 작성.
---
## 🛑 Exception Handling
- 작업 중 에러가 발생하거나 정보가 부족하면 즉시 중단하고 사용자에게 구체적인 질문을 하십시오.
- 사용자가 "중단" 또는 "수정"을 요청하면 즉시 루프를 멈추고 지시를 따르십시오.

86
docs/workflow_manual.md Normal file
View File

@@ -0,0 +1,86 @@
<!-- 사용 방법 (워크플로우) -->
# Manual Usage & Prompt Guide
이 문서는 **자동 워크플로우(`workflow.md`)를 사용하지 않거나**, 특정 단계만 **수동으로 실행/재실행**해야 할 때 사용하는 프롬프트 모음집입니다. 상황에 맞는 프롬프트를 선택하여 AI에게 복사-붙여넣기 하세요.
---
## 1. 프로젝트 시작 및 초기화 (Initialization)
**상황:** 새로운 세션을 시작하거나, AI가 프로젝트 문맥을 잊어버렸을 때 사용합니다.
### 📂 Step 1: 문맥 주입 (Context Loading)
> "첨부된 `copilot-instructions.md`, `project_requirements.md`, `implementation_plan.md`를 모두 읽고, 이 프로젝트의 목표와 내가 구축하려는 시스템의 아키텍처를 요약해주세요. 그리고 `implementation_plan.md`의 단계들이 적절한지 검토해주세요."
### 🔍 Step 2: 계획 검증 (Plan Validation)
> "`implementation_plan.md`의 내용이 충분히 구체적인가? 만약 부족한 부분이 있다면 Python/C++ 프로젝트 표준에 맞춰서 수정해주세요. (수정이 없다면 이 단계는 생략)"
---
## 2. 단계별 실행 프롬프트 (Phase Execution)
**상황:** `implementation_plan.md`의 특정 단계를 실행할 때 사용합니다. (원하는 단계만 골라서 사용 가능)
### 🚀 Phase 1: 환경 설정 (Setup)
> "`implementation_plan.md`의 **[Phase 1]** 작업을 시작한다.
> `copilot-instructions.md`의 **Tech Stack**에 맞춰 폴더 구조를 잡고, 필요한 설정 파일(.env, requirements.txt, CMakeLists.txt 등)을 작성해줘.
> 작성 후에는 `implementation_plan.md`의 해당 항목을 체크(x)해주세요."
### 🧩 Phase 2: 코어 로직 구현 (Core Domain)
> "`implementation_plan.md`의 **[Phase 2]** 작업을 수행한다.
> `copilot-instructions.md`의 **Core Principles**를 준수하여 비즈니스 로직과 도메인 모델을 구현해주세요.
> **중요:** 코드를 작성하기 전에 **로직 설계와 시간 복잡도**를 먼저 설명하고, 반드시 **단위 테스트(Unit Test)** 코드를 함께 작성해주세요."
### 🔌 Phase 3: 인터페이스 연동 (Integration)
> "`implementation_plan.md`의 **[Phase 3]** 작업을 수행한다.
> 외부 API 연동, DB 연결, 또는 UI 컴포넌트를 구현해주세요.
> **Error Handling:** 예외 상황(네트워크 실패, DB 연결 끊김 등)에 대한 처리를 `try-except`(Python) 또는 `RAII/Exception Safety`(C++) 규칙에 맞춰 견고하게 작성해주세요."
### 🖥️ Phase 4: 시스템 통합 (System Interface)
> "`implementation_plan.md`의 **[Phase 4]** 작업을 수행한다.
> 전체 모듈을 하나로 묶는 메인 진입점(Main Entry Point)을 작성하고, 전체 프로세스가 유기적으로 동작하는지 검증하는 **통합 테스트(Integration Test)** 시나리오를 작성해주세요."
### ⚡ Phase 5: 최적화 및 리팩토링 (Refinement)
> "`implementation_plan.md`의 **[Phase 5]** 작업을 수행한다.
> 현재 코드에서 **성능 병목(O(N^2) 이상)**이 발생할 수 있는 구간이나 **메모리 누수** 가능성을 분석해주세요.
> 그 후, `review_prompt.md`의 기준에 따라 스스로 코드를 리뷰하고 개선안을 적용해주세요."
---
## 3. 자동 진행 및 복구 (Auto-Pilot & Recovery)
**상황:** 다음 할 일을 AI가 스스로 찾게 하거나, 꼬인 상황을 풀 때 사용합니다.
### 🤖 Auto-Pilot (알아서 다음 단계 진행)
> "`implementation_plan.md`를 확인해서 **아직 완료되지 않은(체크되지 않은) 가장 첫 번째 작업**을 수행해주세요.
> `copilot-instructions.md`의 규칙을 철저히 지켜서 코드를 작성하고, 작업이 끝나면 플랜 파일을 업데이트해주세요."
### 🚑 Troubleshooting (품질/방향성 교정)
**Q. AI가 엉뚱하거나 질 낮은 코드를 작성할 때**
> "방금 작성한 코드를 멈추고, `review_prompt.md`를 기준으로 다시 리뷰해주세요. 치명적인 결함이나 개선할 점을 찾아서 보고하고 코드를 수정해주세요."
**Q. 진행 상황(체크박스)이 실제와 다를 때**
*(사용자가 파일을 직접 수정한 뒤 명령)*
> "`implementation_plan.md` 파일을 다시 읽어봐. 내가 현재 진행 상황을 업데이트했으니, 체크되지 않은 항목부터 다시 작업을 이어가주세요."
copilot-instructions.md 지침을 따라서 작업해주세요.
project_requirements.md 파일에 작성된 템플릿에 맞춰 프로그램 요구사항을 작성한 후
implementation_plan.md 파일에 작성된 템플릿에 맞춰 작업계획을 작성해주세요.
프로그램 요구사항과 작업계획을 작성하기전에 필요한 데이터가 부족하면 나한테 물어보고 데이터 준비가 완료되면 작성해주세요.
프로그램에 요구되는 기능은 다음과 같습니다.
xxx
더 필요한 내용이 있다면 물어봐주세요.
workflow.md 지침에 따라 작업을 진행해주세요.
review_prompt.md 지침에 따라 코드를 검토해주세요.
이 프로그램을 사용하는 방법을 user_guide.md 파일에 작성해줘.