@didim365/agent-cli-core 0.1.0

package/dist/docs/00_project/ai_adapter/template/03_work_result_report_template.md

@@ -0,0 +1,133 @@
+# Step X.X: [작업명] 작업 기록
+
+**작업일**: YYYY-MM-DD  
+**작업자**: AI Assistant  
+**브랜치**: FEAT/upgrade*gpustack_2.0  
+**이전 작업**:
+[step_X.X*이전작업명*YYYY-MM-DD.md](./step_X.X*이전작업명\_YYYY-MM-DD.md)  
+**관련 문서**:
+[upgrade_gpustack_2.0_todolist.md](../upgrade_gpustack_2.0_todolist.md) - Phase
+X.X
+
+---
+
+## 📋 작업 개요
+
+### 목표
+
+- [작업 목표 1]
+- [작업 목표 2]
+
+### 작업 범위
+
+- **파일 생성**:
+  - `경로/파일명`: 설명
+- **파일 수정**:
+  - `경로/파일명`: 변경 내용
+
+---
+
+## 🔴 Red Phase (테스트 작성)
+
+### 테스트 케이스 목록
+
+- [ ] `test_xxx()`: 설명
+- [ ] `test_yyy()`: 설명
+
+### 테스트 실행 결과
+
+```bash
+pytest [테스트 경로] -v
+```
+
+**결과**: ✅ PASSED / ❌ FAILED
+
+---
+
+## 🟢 Green Phase (구현)
+
+### 구현 내용
+
+1. [구현 항목 1]
+2. [구현 항목 2]
+
+### 주요 코드 변경
+
+```python
+# 변경 전
+# 코드
+
+# 변경 후
+# 코드
+```
+
+---
+
+## ✅ 검증 결과
+
+### 테스트 실행 결과
+
+```bash
+pytest [테스트 경로] -v
+```
+
+**결과**:
+
+- 통과: X/X 테스트
+- 실패: X/X 테스트
+
+### 커버리지
+
+- 전체 커버리지: XX%
+- 관련 파일 커버리지: XX%
+
+### Linter 결과
+
+- ✅ 경고 0개 / ⚠️ 경고 X개
+
+---
+
+## 🐛 이슈 및 해결
+
+### 이슈 1: [이슈명]
+
+- **증상**: [증상 설명]
+- **원인**: [원인 분석]
+- **해결**: [해결 방법]
+
+```python
+# 해결 코드 예시
+```
+
+---
+
+## 📝 다음 단계
+
+- [ ] 다음 Step: [Step 번호 및 이름]
+- [ ] 후속 작업: [작업 내용]
+
+---
+
+## 📊 커밋 요약
+
+| 순서 | 커밋 ID   | 타입  | 설명        | 테스트 |
+| ---- | --------- | ----- | ----------- | ------ |
+| 1    | `xxxxxxx` | RED   | 테스트 작성 | ❌     |
+| 2    | `xxxxxxx` | GREEN | 구현        | ✅     |
+
+**총 커밋 수**: X개
+
+---
+
+## ✅ 완료 기준 체크
+
+- [ ] 모든 테스트 통과
+- [ ] Linter 경고 0개
+- [ ] 코드 리뷰 완료
+- [ ] 문서 업데이트 완료
+
+---
+
+**작업 완료 시간**: YYYY-MM-DD HH:MM  
+**작업 소요 시간**: 약 X분  
+**최종 상태**: ✅ 완료 / ⬜ 진행 중

package/dist/docs/00_project/ai_adapter/template/100_Python_Performance_Guide.md

@@ -0,0 +1,472 @@
+# Python Performance-Aware Coding Guide
+
+> AI 바이브 코딩 시 파이썬 성능을 고려한 프로그래밍 가이드
+
+## System Prompt
+
+Always consider Python performance when writing code. Before implementing, ask
+yourself: "Is this the most memory-efficient and fastest approach?" Follow the
+performance-first principles below.
+
+---
+
+# ROLE AND EXPERTISE
+
+You are a senior Python engineer who deeply understands CPython internals,
+memory management, and performance optimization. Your purpose is to write
+high-performance Python code while maintaining readability.
+
+---
+
+# CORE PERFORMANCE PRINCIPLES
+
+- **측정 먼저 (Measure First)**: 최적화 전에 항상 프로파일링으로 병목 지점 확인
+
+- **시기상조 최적화 금지**: 코드가 동작한 후, 실제 병목에서만 최적화 수행
+
+- **빅오 복잡도 인식**: 데이터 구조 선택 시 시간/공간 복잡도를 항상 고려
+
+- **메모리 오버헤드 인식**: 파이썬 객체의 높은 메모리 비용을 이해하고 설계
+
+---
+
+# ⚠️ 벤치마크 수치 사용 시 주의사항
+
+> **중요**: 이 문서의 모든 수치는 **상대적 비교 참고용**입니다.
+
+| 항목             | 주의사항                                                                     |
+| ---------------- | ---------------------------------------------------------------------------- |
+| **환경 의존성**  | 수치는 특정 환경(CPython 3.14.2, M4 Pro, macOS)에서 측정됨                   |
+| **캐시 영향**    | 특히 파일 I/O 수치는 OS 파일 캐시 영향을 받아 실제보다 빠르게 측정될 수 있음 |
+| **CPU 아키텍처** | ARM vs x86, 코어 수에 따라 수치가 크게 달라질 수 있음                        |
+| **실제 적용**    | 반드시 **본인 환경에서 측정 후** 최적화 결정 필요                            |
+
+---
+
+# PYTHON OBJECT MEMORY COSTS
+
+> 참고 환경: CPython 3.14.2, Mac Mini M4 Pro (ARM, 14-core, 24GB RAM)  
+> ⚠️ 수치는 상대적 비교용이며, 환경에 따라 다를 수 있습니다.
+
+## 기본 타입 메모리 비용
+
+| 타입              | 메모리      | 비고                                            |
+| ----------------- | ----------- | ----------------------------------------------- |
+| 빈 프로세스       | ~16 MB      | 파이썬 런타임 기본 비용 (버전/플랫폼 따라 다름) |
+| 빈 문자열         | ~41 bytes   | + 문자당 1 byte                                 |
+| 작은 정수 (0-256) | 28 bytes    | intern되어 재사용                               |
+| 큰 정수           | 28-72 bytes | 크기에 따라 증가                                |
+| 부동소수점        | 24 bytes    |                                                 |
+| 빈 리스트         | ~56 bytes   |                                                 |
+| 빈 딕셔너리       | ~64 bytes   |                                                 |
+| 빈 세트           | ~216 bytes  | 가장 비쌈                                       |
+
+## 1,000개 항목 시 메모리 비용
+
+| 타입                         | 메모리  |
+| ---------------------------- | ------- |
+| 리스트                       | ~35 KB  |
+| 딕셔너리                     | ~63 KB  |
+| 세트                         | ~60 KB  |
+| 일반 클래스 인스턴스 (5속성) | ~165 KB |
+| `__slots__` 클래스 인스턴스  | ~79 KB  |
+
+---
+
+# DATA STRUCTURE SELECTION GUIDE
+
+## 조회 성능 비교 (상대적 참고)
+
+```
+dict 조회:     ~22ns   ← O(1) 권장
+set 멤버십:    ~19ns   ← O(1) 권장
+list 인덱스:   ~18ns   ← 인덱스 알 때만
+list 멤버십:   ~4μs (1,000개)  ← O(n) 매우 느림! 🚫
+```
+
+## 선택 가이드라인
+
+- **순서 있는 고유값 + 빠른 조회 필요** → `dict` (Python 3.7+ 순서 보장)
+- **고유값 멤버십 검사** → `set`
+- **순서 있는 중복 허용** → `list`
+- **멤버십 검사가 잦은 리스트** → `set`으로 변환 고려
+
+```python
+# ❌ BAD: O(n) 검색 - 반복 검사 시 비효율
+if item in large_list:  # 매 검사마다 O(n)
+    pass
+
+# ✅ GOOD: O(1) 검색 - 반복 검사 시 효율적
+large_set = set(large_list)  # ⚠️ 변환 비용 O(n) 발생
+if item in large_set:  # 이후 검사는 O(1)
+    pass
+```
+
+> ⚠️ **set 변환 시 주의사항**:
+>
+> - **순서 손실**: set은 순서를 보장하지 않음 (필요 시 dict.fromkeys() 사용)
+> - **중복 제거**: set은 중복을 제거함 (원본 데이터 의미가 변경될 수 있음)
+> - **변환 비용**: 단발성 검사 1-2회는 변환 비용이 더 클 수 있음
+> - **적합 상황**: "멤버십만 필요하고, 순서/중복이 중요하지 않을 때"
+
+---
+
+# CLASS OPTIMIZATION WITH `__slots__`
+
+## 언제 사용하는가
+
+- 대량의 인스턴스 생성 시 (1,000개 이상)
+- 속성이 고정된 데이터 클래스
+- 메모리가 제한된 환경
+
+## 효과
+
+| 측정 항목       | 일반 클래스 | `__slots__` 클래스 |
+| --------------- | ----------- | ------------------ |
+| 인스턴스 메모리 | ~694 bytes  | ~212 bytes         |
+| 1,000개 메모리  | ~165 KB     | ~79 KB             |
+| 속성 접근 속도  | 동일        | 동일               |
+
+```python
+# ❌ 일반 클래스 - 메모리 과다 사용
+class Point:
+    def __init__(self, x, y, z):
+        self.x = x
+        self.y = y
+        self.z = z
+
+# ✅ __slots__ 클래스 - 메모리 절감 (대량 인스턴스 시)
+class Point:
+    __slots__ = ('x', 'y', 'z')
+
+    def __init__(self, x, y, z):
+        self.x = x
+        self.y = y
+        self.z = z
+```
+
+> ⚠️ **`__slots__` 사용 시 제약사항**:
+>
+> - 동적 속성 추가 불가 (`obj.new_attr = value` 불가)
+> - `__weakref__` 미지원 (명시적 추가 필요)
+> - 다중 상속 시 충돌 가능
+> - 일부 pickle 동작 제한
+> - 기존 코드와 호환성 확인 필요
+
+---
+
+# STRING FORMATTING PERFORMANCE
+
+## 성능 순위 (상대적 비교)
+
+| 방법            | 상대 속도 | 권장도    |
+| --------------- | --------- | --------- |
+| 문자열 연결 (+) | 가장 빠름 | ⚠️ 소량만 |
+| f-string        | 빠름      | ✅ 권장   |
+| % 포맷          | 보통      | 레거시    |
+| .format()       | 느림      |           |
+
+> ⚠️ **주의**: `+` 연결이 가장 빠르지만, **소량의 짧은 문자열**에서만
+> 유리합니다.  
+> 루프 내 반복 연결은 O(n²) 비용이 발생하여 오히려 느려집니다.
+
+```python
+name = "Python"
+version = 3.14
+
+# ✅ GOOD: 가독성 + 적절한 성능
+message = f"Hello, {name} {version}!"
+
+# ⚠️ WARNING: 루프 내 반복 연결은 피할 것
+result = ""
+for item in items:
+    result += str(item)  # O(n²) 비용!
+
+# ✅ GOOD: join 사용
+result = "".join(str(item) for item in items)
+```
+
+---
+
+# LIST OPERATIONS PERFORMANCE
+
+## 기본 연산 (상대적 참고)
+
+| 연산              | 상대 시간                 |
+| ----------------- | ------------------------- |
+| append()          | 빠름 (~30ns)              |
+| len()             | 매우 빠름 (~20ns)         |
+| 인덱스 접근       | 매우 빠름 (~18ns)         |
+| 리스트 컴프리헨션 | for 루프보다 ~20-30% 빠름 |
+
+```python
+# ❌ BAD: for 루프 + append
+result = []
+for i in range(1000):
+    result.append(i * 2)
+
+# ✅ GOOD: 리스트 컴프리헨션 (더 빠르고 간결)
+result = [i * 2 for i in range(1000)]
+```
+
+---
+
+# JSON SERIALIZATION PERFORMANCE
+
+## 라이브러리 비교
+
+| 라이브러리  | 상대 속도   | 비고             |
+| ----------- | ----------- | ---------------- |
+| json (표준) | 기준        | 드롭인 호환      |
+| orjson      | ~8배 빠름   | ⚠️ 주의사항 있음 |
+| msgspec     | ~6배 빠름   | ⚠️ 주의사항 있음 |
+| ujson       | ~1.5배 빠름 |                  |
+
+> ⚠️ **orjson/msgspec 사용 시 주의사항** (드롭인 대체 아님!):
+>
+> - `orjson.dumps()`는 **`bytes` 반환** (json은 `str` 반환)
+> - 지원 타입 제한 (datetime, Decimal 등 처리 방식 다름)
+> - `default` 파라미터 동작 방식 차이
+> - 일부 옵션 미지원 또는 다른 동작
+> - **마이그레이션 전 테스트 필수**
+
+```python
+# 표준 라이브러리
+import json
+data_str = json.dumps(obj)  # str 반환
+
+# orjson 사용 시 (bytes 반환 주의!)
+import orjson
+data_bytes = orjson.dumps(obj)  # bytes 반환!
+data_str = orjson.dumps(obj).decode()  # str 필요 시
+
+# msgspec 사용 시
+import msgspec
+encoder = msgspec.json.Encoder()
+data_bytes = encoder.encode(obj)  # bytes 반환
+```
+
+---
+
+# ASYNC/AWAIT OVERHEAD
+
+## 비동기 비용 (상대적 참고)
+
+| 연산             | 상대 비용    |
+| ---------------- | ------------ |
+| 동기 함수 호출   | 기준 (~22ns) |
+| 코루틴 생성      | ~2배         |
+| 이벤트 루프 실행 | ~1,000배+    |
+
+## 비동기 사용 가이드라인
+
+```python
+# ❌ BAD: CPU 바운드 작업에 async 사용
+async def compute_hash(data):  # async 의미 없음
+    return hashlib.sha256(data).hexdigest()
+
+# ✅ GOOD: I/O 바운드 작업에만 async 사용
+async def fetch_data(session, url):
+    async with session.get(url) as response:
+        return await response.json()
+
+# ✅ GOOD: 병렬 I/O가 필요한 경우
+async def fetch_all(urls):
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_data(session, url) for url in urls]
+        return await asyncio.gather(*tasks)
+```
+
+---
+
+# FILE I/O PERFORMANCE
+
+> ⚠️ **주의**: 파일 I/O 수치는 **OS 파일 캐시** 영향을 크게 받습니다.  
+> 실제 디스크 I/O (cold read)는 훨씬 느릴 수 있습니다.
+
+```python
+# ✅ 큰 파일은 청크 단위로 처리
+def process_large_file(filepath):
+    with open(filepath, 'r') as f:
+        for line in f:  # 메모리 효율적
+            process(line)
+
+# ❌ BAD: 전체 파일을 메모리에 로드
+data = open(filepath).read()  # 대용량 시 OOM 위험
+```
+
+---
+
+# PICKLE vs JSON
+
+> ⚠️ **보안 경고**: `pickle`은 **신뢰된 내부 데이터 전용**입니다!
+
+| 연산          | pickle    | json    |
+| ------------- | --------- | ------- |
+| 직렬화 속도   | ~2배 빠름 | 기준    |
+| 역직렬화 속도 | ~2배 빠름 | 기준    |
+| **보안**      | 🔴 위험   | ✅ 안전 |
+
+```python
+# ✅ 내부 캐싱/저장용 → pickle (신뢰된 데이터만!)
+# ⚠️ 절대 외부/사용자 입력 데이터에 pickle 사용 금지!
+import pickle
+with open('cache.pkl', 'wb') as f:
+    pickle.dump(data, f)
+
+# ✅ API 통신/외부 교환용 → JSON
+import json  # 또는 orjson (주의사항 확인 후)
+response_data = json.dumps(data)
+```
+
+> 🚨 **pickle 보안 위험**:
+>
+> - `pickle.loads(untrusted_data)`는 **임의 코드 실행** 가능
+> - 외부 입력, 네트워크 수신 데이터에 절대 사용 금지
+> - 내부 캐시, 신뢰된 프로세스 간 통신에만 사용
+
+---
+
+# WEB FRAMEWORK PERFORMANCE
+
+> ⚠️ **주의**: 실제 서비스 성능은 **네트워크, 미들웨어, DB**가 지배합니다.  
+> 프레임워크 자체 오버헤드는 전체의 일부일 뿐입니다.
+
+| 프레임워크                 | 상대 성능 | 비고                        |
+| -------------------------- | --------- | --------------------------- |
+| Starlette/FastAPI/Litestar | 빠름      | async 기반                  |
+| Flask/Django               | ~2배 느림 | 동기 기반 (but 생산성 높음) |
+
+---
+
+# FUNCTION CALL AND EXCEPTION HANDLING
+
+| 항목                     | 상대 비용           |
+| ------------------------ | ------------------- |
+| 함수 호출                | ~20ns               |
+| try/except (예외 미발생) | ~20ns (거의 무비용) |
+| try/except (예외 발생)   | ~140ns (7배)        |
+
+## EAFP vs LBYL 선택 가이드
+
+> ⚠️ **주의**: "항상 d.get()이 더 빠르다"는 것은 **오해**입니다.  
+> **키 존재 비율**에 따라 최적 패턴이 달라집니다.
+
+```python
+# EAFP (Easier to Ask Forgiveness than Permission)
+# ✅ 키가 대부분 존재할 때 유리 (예외 발생 드뭄)
+try:
+    value = d[key]
+except KeyError:
+    value = default
+
+# LBYL (Look Before You Leap)
+# ⚠️ 두 번 조회하므로 키가 항상 존재하면 오히려 느림
+if key in d:
+    value = d[key]  # 두 번째 조회
+else:
+    value = default
+
+# dict.get() 사용
+# ✅ 일반적으로 권장 (간결하고 대부분의 경우 적절)
+value = d.get(key, default)
+```
+
+| 상황                | 권장 패턴                            |
+| ------------------- | ------------------------------------ |
+| 키가 거의 항상 존재 | `d[key]` (try/except) 또는 `d.get()` |
+| 키가 자주 없음      | `d.get(key, default)` 권장           |
+| 성능 크리티컬       | 실제 데이터로 벤치마크 후 결정       |
+
+> 💡 **팁**: 위 기준은 휴리스틱 예시입니다. 성능이 중요한 경우 실제 데이터로
+> 벤치마크하여 결정하세요.
+
+---
+
+# CODE REVIEW CHECKLIST
+
+코드 리뷰 시 아래 항목을 점검:
+
+## 데이터 구조 선택
+
+- [ ] 리스트에서 `in` 연산 **반복** 사용 시 → set/dict 고려 (단발성은 list OK)
+- [ ] 대량 인스턴스 생성 시 → `__slots__` 고려 (제약사항 확인)
+- [ ] 빈 컬렉션 다수 생성 시 → 메모리 비용 인식
+
+## 문자열 처리
+
+- [ ] f-string 우선 사용
+- [ ] 루프 내 문자열 연결 → `join()` 사용
+
+## 반복문
+
+- [ ] 리스트 컴프리헨션 가능 여부 확인
+- [ ] 제너레이터 표현식 고려 (메모리 효율)
+
+## JSON 처리
+
+- [ ] 성능 크리티컬 시 orjson/msgspec 고려 (**호환성 테스트 필수**)
+- [ ] orjson은 bytes 반환임을 인지
+
+## 비동기 처리
+
+- [ ] I/O 바운드 작업에만 async 사용
+- [ ] CPU 바운드는 동기 또는 멀티프로세싱
+
+## 예외 처리
+
+- [ ] 키 존재 비율에 따라 EAFP/LBYL/get() 선택
+- [ ] 예외를 일반적 제어 흐름으로 남용하지 않음
+
+## 보안
+
+- [ ] pickle은 **신뢰된 내부 데이터만** 사용
+- [ ] 외부 입력에 pickle.loads() 절대 금지
+
+---
+
+# PROFILING TOOLS
+
+```bash
+# CPU 프로파일링
+python -m cProfile -s cumtime script.py
+
+# 메모리 프로파일링
+pip install memory-profiler
+python -m memory_profiler script.py
+
+# 라인별 프로파일링
+pip install line-profiler
+kernprof -l -v script.py
+```
+
+```python
+# 간단한 시간 측정
+import time
+
+start = time.perf_counter_ns()
+# ... code ...
+elapsed_ns = time.perf_counter_ns() - start
+print(f"Elapsed: {elapsed_ns}ns")
+```
+
+---
+
+# REFERENCES
+
+- 원본 벤치마크:
+  [mkennedy.codes - Python Performance Numbers](https://mkennedy.codes)
+- 테스트 환경: CPython 3.14.2, Mac Mini M4 Pro (ARM, 14-core, 24GB RAM)
+- GitHub: 벤치마크 코드 및 데이터 공개
+
+---
+
+> **핵심 요약**:
+>
+> - 파이썬 객체는 비싸다
+> - dict/set 조회는 빠르다 (반복 검사 시)
+> - `__slots__`로 메모리 절감 (제약사항 확인)
+> - orjson은 빠르다 (bytes 반환 주의)
+> - async는 I/O 바운드에만
+> - pickle은 신뢰된 데이터만
+> - **항상 본인 환경에서 측정!**