@didim365/agent-cli-core 0.1.1 → 0.1.2

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

@@ -1,133 +0,0 @@
-# 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

@@ -1,472 +0,0 @@
-# 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은 신뢰된 데이터만
-> - **항상 본인 환경에서 측정!**