Ch14. 트러블슈팅 & FAQ

즉시 대응:
1. 현재 실행 중인 작업 중단
2. 크레딧 사용 내역 확인: Settings → Usage
3. 비효율적인 패턴 식별

근본 해결:
- 컨텍스트 크기 제한 설정
- 파일 참조 최적화
- 프롬프트 효율성 개선

체크리스트:
□ 새로운 세션으로 재시작
□ 컨텍스트 정리 및 최적화
□ 네트워크 연결 상태 확인
□ Kiro 서버 상태 확인 (Discord 공지)
□ 다른 모델로 전환 테스트

// .kiro/config.json
{
  "autoBackup": {
    "enabled": true,
    "interval": 300,
    "maxBackups": 10,
    "backupPath": ".kiro/backups"
  },
  "crashRecovery": {
    "enabled": true,
    "saveInterval": 60,
    "autoRestore": true
  }
}

진단 단계:
1. 컨텍스트 크기 확인
   - 현재 컨텍스트: Settings → Context Info
   - 권장: 50,000 토큰 이하

2. 파일 참조 최적화
   - 불필요한 #File 참조 제거
   - 큰 파일은 관련 부분만 참조

3. MCP 서버 상태 확인
   - 응답 시간이 긴 MCP 서버 식별
   - 타임아웃 설정 조정

해결책:
- 컨텍스트 정리: "이전 대화 내용을 요약해주세요"
- 세션 분할: 복잡한 작업을 여러 세션으로 나누기
- 캐시 활용: 반복되는 작업은 결과를 저장

// 메모리 최적화 설정
{
  "performance": {
    "maxMemoryUsage": "2GB",
    "garbageCollection": {
      "enabled": true,
      "interval": 300,
      "threshold": "1.5GB"
    },
    "contextCaching": {
      "enabled": true,
      "maxCacheSize": "500MB",
      "ttl": 3600
    }
  }
}

네트워크 진단:
1. 연결 상태 확인
   ping kiro.dev
   curl -I https://kiro.dev/api/health

2. 프록시/방화벽 설정 확인
   - 회사 네트워크의 경우 IT 팀 문의
   - VPN 사용 시 연결 안정성 확인

3. DNS 설정 확인
   - 공용 DNS 사용 (8.8.8.8, 1.1.1.1)
   - DNS 캐시 초기화

해결책:
- 재시도 로직 활성화
- 타임아웃 값 조정
- 오프라인 모드 활용 (가능한 경우)

예방 전략:
1. 명확한 요구사항 제시
   ❌ "로그인 기능 만들어줘"
   ✅ "Express.js에서 JWT를 사용한 로그인 API를 만들어주세요. 
       이메일/비밀번호 검증, 토큰 발급, 에러 처리 포함"

2. 컨텍스트 제공
   - 기존 코드 스타일 참조
   - 사용 중인 라이브러리 명시
   - 프로젝트 구조 설명

3. 단계별 검증
   - 작은 단위로 나누어 요청
   - 각 단계마다 검토 및 테스트
   - 문제 발견 시 즉시 수정 요청

보안 체크리스트:
□ SQL 인젝션 방어 (Prepared Statement 사용)
□ XSS 방어 (입력 검증 및 이스케이프)
□ CSRF 토큰 구현
□ 민감 정보 하드코딩 방지
□ 적절한 인증/인가 로직
□ 안전한 암호화 알고리즘 사용

자동 보안 검사:
"생성된 코드를 OWASP Top 10 기준으로 보안 검토해주세요"

성능 최적화 요청 패턴:
"다음 요구사항을 만족하는 고성능 코드를 작성해주세요:
- 시간 복잡도: O(n) 이하
- 메모리 사용량 최소화
- 데이터베이스 쿼리 최적화
- 캐싱 전략 포함
- 비동기 처리 활용"

코드 리뷰 요청:
"작성된 코드의 성능을 분석하고 병목점을 찾아 개선해주세요"

# 진단 명령어
# MCP 서버 상태 확인
ps aux | grep mcp

# 로그 확인
tail -f ~/.kiro/logs/mcp-*.log

# 포트 사용 확인
netstat -tulpn | grep :8000

# 수동 테스트
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "ping"}'

1. 기본 확인
   - MCP 서버 프로세스 실행 여부
   - 포트 충돌 확인
   - 환경 변수 설정 확인

2. 설정 검증
   - .kiro/mcp.json 문법 확인
   - 명령어 경로 확인
   - 권한 설정 확인

3. 재시작 시도
   - MCP 서버 재시작
   - Kiro 재시작
   - 시스템 재부팅 (최후 수단)

// 성능 최적화 설정
{
  "mcpServers": {
    "slow-server": {
      "command": "uvx",
      "args": ["mcp-server-slow"],
      "timeout": 60,
      "retries": 3,
      "poolSize": 5,
      "caching": {
        "enabled": true,
        "ttl": 300,
        "maxSize": "100MB"
      },
      "rateLimiting": {
        "requestsPerSecond": 10,
        "burstLimit": 20
      }
    }
  }
}

# 디버깅용 MCP 서버 템플릿
import logging
import traceback
from mcp.server import Server

# 로깅 설정
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('mcp_server.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger(__name__)
app = Server("debug-server")

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    logger.info(f"Tool called: {name} with args: {arguments}")
    
    try:
        # 입력 검증
        if not arguments:
            raise ValueError("No arguments provided")
        
        # 도구 실행
        result = await execute_tool_safely(name, arguments)
        
        logger.info(f"Tool {name} completed successfully")
        return result
        
    except Exception as e:
        logger.error(f"Tool {name} failed: {str(e)}")
        logger.error(f"Traceback: {traceback.format_exc()}")
        
        # 사용자 친화적 에러 메시지
        return TextContent(
            type="text",
            text=f"Error in {name}: {str(e)}\nCheck logs for details."
        )

async def execute_tool_safely(name: str, arguments: dict):
    """안전한 도구 실행 래퍼"""
    # 타임아웃 설정
    import asyncio
    try:
        return await asyncio.wait_for(
            execute_tool_impl(name, arguments),
            timeout=30.0
        )
    except asyncio.TimeoutError:
        raise Exception(f"Tool {name} timed out after 30 seconds")

Spec 품질 체크리스트:
□ 명확한 요구사항 정의
□ 구체적인 기술 스택 명시
□ 예상 입출력 예시 포함
□ 제약사항 및 비기능 요구사항
□ 테스트 시나리오 정의
□ 외부 파일 참조 정확성

개선 방법:
1. Spec 템플릿 사용
2. 단계별 검증 포인트 추가
3. 팀 리뷰 프로세스 도입
4. 성공 사례 벤치마킹

# 동기화 스크립트 예시
#!/bin/bash
# sync-sessions.sh

echo "Starting session synchronization..."

# 1. 각 세션의 변경사항 확인
for session in session-*; do
    if [ -d "$session" ]; then
        echo "Checking $session..."
        cd "$session"
        git status --porcelain
        cd ..
    fi
done

# 2. 충돌 가능성 검사
echo "Checking for potential conflicts..."
find . -name "*.conflict" -type f

# 3. 자동 병합 시도
echo "Attempting automatic merge..."
git merge --no-commit --no-ff session-a/main session-b/main

# 4. 충돌 해결 가이드 표시
if [ $? -ne 0 ]; then
    echo "Conflicts detected. Manual resolution required:"
    git status --porcelain | grep "^UU"
fi

// Hook 디버깅 설정
{
  "hooks": {
    "debug": true,
    "logLevel": "verbose",
    "timeout": 30,
    "onError": "log",
    "testMode": false
  },
  "fileEdited": [
    {
      "name": "debug-hook",
      "patterns": ["**/*.ts"],
      "action": "askAgent",
      "prompt": "Debug: File edited - {{filename}}",
      "debug": {
        "logExecution": true,
        "validatePattern": true,
        "dryRun": false
      }
    }
  ]
}

#!/bin/bash
# kiro-health-check.sh

echo "=== Kiro Health Check ==="

# 1. 프로세스 상태
echo "1. Process Status:"
ps aux | grep -E "(kiro|mcp)" | grep -v grep

# 2. 메모리 사용량
echo "2. Memory Usage:"
free -h

# 3. 디스크 사용량
echo "3. Disk Usage:"
df -h ~/.kiro

# 4. 네트워크 연결
echo "4. Network Connectivity:"
ping -c 3 kiro.dev

# 5. MCP 서버 상태
echo "5. MCP Server Status:"
for port in 8000 8001 8002; do
    nc -z localhost $port && echo "Port $port: OK" || echo "Port $port: FAIL"
done

# 6. 로그 에러 확인
echo "6. Recent Errors:"
tail -n 50 ~/.kiro/logs/*.log | grep -i error | tail -10

# 7. 크레딧 사용량 (API 호출 필요)
echo "7. Credit Usage:"
echo "Check manually in Kiro Settings → Usage"

echo "=== Health Check Complete ==="

# kiro-metrics.py
import json
import time
import psutil
from datetime import datetime

class KiroMetrics:
    def __init__(self):
        self.metrics = {
            "timestamp": datetime.now().isoformat(),
            "system": {},
            "kiro": {},
            "mcp": {}
        }
    
    def collect_system_metrics(self):
        """시스템 메트릭 수집"""
        self.metrics["system"] = {
            "cpu_percent": psutil.cpu_percent(interval=1),
            "memory_percent": psutil.virtual_memory().percent,
            "disk_usage": psutil.disk_usage('/').percent,
            "network_io": psutil.net_io_counters()._asdict()
        }
    
    def collect_kiro_metrics(self):
        """Kiro 관련 메트릭 수집"""
        kiro_processes = [p for p in psutil.process_iter(['pid', 'name', 'memory_info', 'cpu_percent']) 
                         if 'kiro' in p.info['name'].lower()]
        
        self.metrics["kiro"] = {
            "process_count": len(kiro_processes),
            "total_memory_mb": sum(p.info['memory_info'].rss for p in kiro_processes) / 1024 / 1024,
            "total_cpu_percent": sum(p.info['cpu_percent'] or 0 for p in kiro_processes)
        }
    
    def collect_mcp_metrics(self):
        """MCP 서버 메트릭 수집"""
        mcp_processes = [p for p in psutil.process_iter(['pid', 'name', 'memory_info', 'cpu_percent']) 
                        if 'mcp' in p.info['name'].lower()]
        
        self.metrics["mcp"] = {
            "server_count": len(mcp_processes),
            "total_memory_mb": sum(p.info['memory_info'].rss for p in mcp_processes) / 1024 / 1024,
            "total_cpu_percent": sum(p.info['cpu_percent'] or 0 for p in mcp_processes)
        }
    
    def save_metrics(self, filepath="kiro_metrics.json"):
        """메트릭을 파일로 저장"""
        with open(filepath, 'a') as f:
            f.write(json.dumps(self.metrics) + '\n')
    
    def run(self):
        """전체 메트릭 수집 실행"""
        self.collect_system_metrics()
        self.collect_kiro_metrics()
        self.collect_mcp_metrics()
        self.save_metrics()
        return self.metrics

if __name__ == "__main__":
    metrics = KiroMetrics()
    result = metrics.run()
    print(json.dumps(result, indent=2))

#!/bin/bash
# emergency-reset.sh

echo "⚠️  EMERGENCY RESET - This will delete all Kiro data!"
read -p "Are you sure? (type 'YES' to continue): " confirm

if [ "$confirm" != "YES" ]; then
    echo "Reset cancelled."
    exit 1
fi

echo "1. Stopping all Kiro processes..."
pkill -f kiro
pkill -f mcp

echo "2. Backing up current configuration..."
mkdir -p ~/kiro-backup-$(date +%Y%m%d-%H%M%S)
cp -r ~/.kiro ~/kiro-backup-$(date +%Y%m%d-%H%M%S)/ 2>/dev/null || true

echo "3. Removing Kiro data..."
rm -rf ~/.kiro

echo "4. Reinstalling Kiro..."
curl -fsSL https://kiro.dev/install.sh | bash

echo "5. Reset complete. Please reconfigure Kiro."

// 최소 동작 설정 (emergency-config.json)
{
  "version": "1.0",
  "defaultMode": "vibe",
  "maxContextSize": 50000,
  "autoSave": true,
  "performance": {
    "maxMemoryUsage": "1GB",
    "timeout": 30
  },
  "mcpServers": {},
  "hooks": {},
  "steering": {
    "enabled": false
  }
}