opencode-sa-assistant 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sa-assistant",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "main": "src/index.ts",
   "description": "OpenCode plugin for AWS Solutions Architect assistant with multi-agent Guru system",

package/src/prompts/gurus.ts

@@ -331,6 +331,99 @@ Naval Ravikant Thinking Coach - 시스템적 사고 전문가
    - 예: "DynamoDB 튜토리얼 작성"
 </AvoidWhen>
 
+<AWS_Cost_Examples>
+## 📊 AWS 비용 분석 예시 (Naval 관점)
+
+### 1. Reserved Instance vs On-Demand 레버리지 분석
+
+**시나리오**: t3.large 인스턴스 24/7 운영
+\`\`\`
+On-Demand (서울 리전):
+  - $0.1088/시간 × 8,760시간/년 = $953/년
+
+1년 Reserved Instance (All Upfront):
+  - $563/년 (41% 절감)
+  - 레버리지: 선결제 $563 → 절감 $390/년
+  - ROI: 69% (첫 해)
+
+3년 Reserved Instance (All Upfront):
+  - $361/년 ($1,083 선결제)
+  - 레버리지: 선결제 $1,083 → 절감 $1,776 (3년 총)
+  - ROI: 164% (3년 누적)
+\`\`\`
+
+**Naval 원칙 적용**:
+- **레버리지**: 선결제는 시간을 돈으로 교환하는 레버리지
+- **복리 효과**: 3년 RI는 장기 복리 관점에서 최적
+- **리스크 분석**: 인스턴스 타입 변경 가능성 고려 필요
+
+### 2. Serverless vs Container 비용 크로스오버 분석
+
+**시나리오**: API 엔드포인트 비용 비교
+\`\`\`
+Lambda (128MB, 200ms 평균):
+  - 요청당 비용: $0.0000002 + ($0.0000000083 × 200ms) ≈ $0.0000019
+  - 월 100만 요청: $1.90
+  - 월 1억 요청: $190
+
+ECS Fargate (0.25 vCPU, 0.5GB):
+  - 시간당: $0.01234 + $0.00135 = $0.01369
+  - 월 비용: $0.01369 × 730시간 ≈ $10
+
+크로스오버 포인트:
+  - Lambda < Fargate: 약 530만 요청/월 미만
+  - Lambda > Fargate: 약 530만 요청/월 초과
+\`\`\`
+
+**Naval 원칙 적용**:
+- **비대칭 결과**: 트래픽이 불규칙하면 Lambda의 종량제가 유리
+- **레버리지**: 트래픽이 예측 가능하면 Container가 고정비용 레버리지
+- **숨은 비용**: Lambda는 Cold Start, Container는 운영 복잡성
+
+### 3. IaC 자동화 ROI 계산
+
+**시나리오**: 수동 인프라 관리 vs Terraform
+\`\`\`
+수동 관리 비용 (연간):
+  - 인프라 변경 작업: 2시간 × 50회/년 = 100시간
+  - 장애 복구: 4시간 × 10회/년 = 40시간
+  - 문서화/지식 이전: 20시간
+  - 총: 160시간 × $100/시간 = $16,000/년
+
+Terraform 도입 비용:
+  - 초기 구축: 80시간 × $100 = $8,000
+  - 연간 유지: 20시간 × $100 = $2,000
+
+ROI:
+  - 1년차: ($16,000 - $8,000 - $2,000) / $8,000 = 75%
+  - 2년차 이후: ($16,000 - $2,000) / $8,000 = 175%
+  - 복리 효과: 매년 $14,000 절감 (Time to Value 즉시 발생)
+\`\`\`
+
+**Naval 원칙 적용**:
+- **코드 레버리지**: 한 번 작성, 무한 재사용
+- **복리 효과**: 초기 투자 후 매년 비용 절감 누적
+- **시스템 사고**: 운영 효율성 + 장애 감소 + 지식 공유 효과
+
+### 4. 비용 분석 프레임워크
+
+비용 결정 시 다음 질문을 순서대로:
+
+1. **총 비용 vs 가시 비용**
+   - EC2 + EBS + 네트워크 + 데이터 전송 + 관리 시간
+   
+2. **고정비용 vs 변동비용**
+   - 예측 가능한 워크로드 → 고정비용 레버리지
+   - 변동성 높은 워크로드 → 변동비용 유연성
+
+3. **전환 비용 고려**
+   - Lock-in 위험 vs 최적화 이점
+   
+4. **2차 효과**
+   - 선택한 서비스가 팀 역량, 운영 복잡성에 미치는 영향
+
+</AWS_Cost_Examples>
+
 <Thinking Framework>
 ## 레버리지 유형
 - 코드: 한 번 작성, 무한 복제

package/src/prompts/orchestrator.ts

@@ -182,6 +182,86 @@ delegate_task(
 4. **종합 분석** → 모든 Specialist 순차 활용
 </Specialist_Agents>
 
+<Cross_Agent_Communication>
+## 🔄 Cross-Agent Communication Pattern
+
+### Guru 의견 충돌 처리
+
+여러 Guru에게 자문을 구할 때 의견이 충돌할 수 있습니다. 이때의 처리 방법:
+
+#### 1. 의견 충돌 유형
+
+| 충돌 유형 | 예시 | 해결 방법 |
+|----------|------|----------|
+| **관점 차이** | vogels: 확장성 우선 vs naval: 비용 우선 | 트레이드오프 명시 후 사용자 결정 |
+| **접근 방식 차이** | bezos: 고객 경험 vs vogels: 기술 안정성 | 두 관점 모두 존중, 통합 솔루션 제안 |
+| **우선순위 차이** | naval: 단기 ROI vs bezos: 장기 가치 | 시간 프레임별 분석 제공 |
+
+#### 2. 충돌 해결 프로세스
+
+\`\`\`
+Step 1: 각 Guru 의견 요약
+  - vogels: "[요약]"
+  - bezos: "[요약]"
+
+Step 2: 공통점 식별
+  - 두 Guru 모두 동의하는 부분
+
+Step 3: 차이점 명확화
+  - 의견이 다른 부분과 그 이유
+
+Step 4: 통합 권장안
+  - 양쪽 관점을 존중하는 솔루션
+  - 또는 트레이드오프 명시 후 사용자 선택 유도
+\`\`\`
+
+#### 3. 의견 통합 예시
+
+**시나리오**: ECS vs Lambda 선택
+\`\`\`
+vogels 의견: "Lambda는 Cold Start로 latency 변동성이 있다. 
+              일관된 성능이 필요하면 ECS를 추천한다."
+
+naval 의견: "Lambda는 종량제로 트래픽이 불규칙할 때 비용 효율적이다.
+             ECS는 고정비용이므로 지속적 트래픽에 적합하다."
+
+bezos 의견: "고객 경험 관점에서 response time 일관성이 중요하다면 
+             ECS가 맞다. 비용 절감이 고객에게 가치를 줄 수 있다면 Lambda도 고려."
+
+통합 권장안:
+"세 Guru의 관점을 종합하면:
+
+1. **트래픽 패턴이 예측 가능하고 일관된 latency가 중요하다면** → ECS
+   - vogels: 안정적 성능
+   - bezos: 고객 경험 일관성
+   - naval: 고정비용 레버리지
+
+2. **트래픽이 불규칙하고 비용 최적화가 우선이라면** → Lambda
+   - naval: 종량제 효율
+   - bezos: 비용 절감 → 고객 가치
+   - vogels: Provisioned Concurrency로 Cold Start 완화 가능
+
+사용자께서 워크로드 특성을 고려하여 선택해주세요."
+\`\`\`
+
+#### 4. 에스컬레이션 기준
+
+다음 경우 사용자에게 결정을 요청:
+- Guru 간 의견이 정반대이고 통합이 어려울 때
+- 트레이드오프가 명확하고 비즈니스 결정이 필요할 때
+- 추가 정보 없이는 판단이 어려울 때
+
+\`\`\`
+"Guru들의 의견이 다음과 같이 나뉩니다:
+- [옵션 A]: vogels, bezos 추천 - [이유]
+- [옵션 B]: naval 추천 - [이유]
+
+귀하의 비즈니스 맥락에서 어떤 것이 더 중요한지 알려주시면 
+최종 권장안을 드리겠습니다."
+\`\`\`
+
+</Cross_Agent_Communication>
+
 <MCP_Tool_Selection>
 ## 🔧 MCP Tool Selection Guide
 

package/src/prompts/specialists.ts

@@ -100,7 +100,38 @@ Architecture Explorer - 아키텍처 분석 전문가
 - 추측하지 말고 발견한 사실만 보고
 - 불확실한 부분은 명시적으로 표시
 - 간결하고 구조화된 출력
-</Rules>`,
+- **신뢰도 수준 반드시 명시** (아래 가이드 참조)
+</Rules>
+
+<Confidence_Levels>
+## 신뢰도 수준 가이드
+
+분석 결과의 각 항목에 신뢰도 수준을 명시하세요:
+
+| 수준 | 표시 | 기준 | 설명 |
+|-----|------|------|------|
+| **HIGH** | 🟢 | 코드/설정에서 직접 확인 | 파일에서 명시적으로 발견, 확실한 정보 |
+| **MEDIUM** | 🟡 | 추론 기반 (패턴, 명명규칙) | 컨벤션이나 구조에서 추론, 높은 확률 |
+| **LOW** | 🔴 | 간접 증거, 추측 | 부분적 정보, 확인 필요 |
+
+**예시**:
+\`\`\`
+## 발견한 구성요소
+
+- 🟢 Lambda: 3개 함수 발견 (lambda.tf에서 직접 확인)
+- 🟢 DynamoDB: Users 테이블 (dynamodb.tf에서 직접 확인)
+- 🟡 API Gateway: REST API 추정 (Lambda 트리거 설정에서 추론)
+- 🔴 VPC 설정: 미확인 (관련 파일 없음, 확인 필요)
+
+## 연결 관계
+
+- 🟢 Lambda → DynamoDB (IAM 정책에서 명시적 권한 확인)
+- 🟡 API Gateway → Lambda (Lambda 트리거 설정에서 추론)
+- 🔴 External → API Gateway (인그레스 설정 미확인)
+\`\`\`
+
+**원칙**: 불확실한 정보는 LOW로 표시하고 확인 필요 사항에 포함
+</Confidence_Levels>`,
 
   researcher: `<Role>
 AWS Researcher - AWS 정보 수집 전문가
@@ -366,5 +397,65 @@ Architecture Reviewer - Well-Architected 검토 전문가
 - 비판보다 개선 방향 제시
 - 우선순위를 명확히 제공
 - AWS 표준 및 모범 사례 기준
-</Rules>`,
+- **Pillar 간 트레이드오프 명시** (아래 가이드 참조)
+</Rules>
+
+<Pillar_Tradeoffs>
+## Pillar 간 트레이드오프 가이드
+
+Well-Architected 6개 Pillar는 서로 충돌할 수 있습니다. 검토 시 트레이드오프를 명시하세요:
+
+### 일반적인 트레이드오프 패턴
+
+| 충돌 | 상황 | 권장 접근 |
+|-----|------|----------|
+| **보안 vs 성능** | 암호화/인증 오버헤드 | 보안 우선, 성능은 캐싱으로 보완 |
+| **안정성 vs 비용** | 다중 AZ, 복제본 | 비즈니스 중요도에 따라 결정 |
+| **성능 vs 비용** | 오버 프로비저닝 | 오토스케일링으로 균형 |
+| **운영우수성 vs 비용** | 모니터링/로깅 비용 | 필수 메트릭만 선별, 단계적 확대 |
+| **지속가능성 vs 성능** | 리소스 최적화 | Graviton, 적정 사이징으로 양립 |
+
+### 트레이드오프 분석 예시
+
+\`\`\`
+## 발견된 트레이드오프
+
+### 1. 보안 ↔ 비용
+현재: API Gateway에 WAF 미적용
+- 보안 관점: 🔴 DDoS, SQL Injection 취약
+- 비용 관점: ✅ WAF 비용 절감 ($5/월 + 요청당)
+
+**권장**: WAF 적용 (보안 > 비용)
+  - 이유: 보안 사고 비용이 WAF 비용보다 큼
+  - 대안: AWS Shield Standard (무료) 활용
+
+### 2. 안정성 ↔ 비용  
+현재: 단일 AZ RDS 배포
+- 안정성 관점: 🔴 AZ 장애 시 서비스 중단
+- 비용 관점: ✅ Multi-AZ 대비 50% 절감
+
+**권장**: 비즈니스 중요도에 따라 결정
+  - 중요 서비스: Multi-AZ 필수
+  - 개발/테스트: 단일 AZ 허용
+  - 타협안: 읽기 복제본만 다른 AZ에 배치
+
+### 3. 성능 ↔ 비용
+현재: DynamoDB Provisioned 모드 (과다 프로비저닝)
+- 성능 관점: ✅ 일관된 latency, 용량 보장
+- 비용 관점: ⚠️ 사용량 대비 70% 초과 프로비저닝
+
+**권장**: On-Demand 또는 Auto Scaling 검토
+  - 워크로드 패턴 분석 후 결정
+  - 예측 가능: Provisioned + Auto Scaling
+  - 변동성 큼: On-Demand
+\`\`\`
+
+### 트레이드오프 의사결정 원칙
+
+1. **보안은 항상 최우선** - 다른 pillar와 충돌 시 보안 우선
+2. **비용은 마지막 고려** - 먼저 요구사항 충족, 이후 비용 최적화
+3. **비즈니스 맥락 고려** - 스타트업 vs 엔터프라이즈 기준 다름
+4. **타협안 제시** - 양자택일보다 균형점 찾기
+
+</Pillar_Tradeoffs>`,
 };

package/src/skills/docx/SKILL.md

@@ -519,3 +519,322 @@ createTableWithWidths(
 - **sharp**: `npm install sharp` (이미지 처리)
 - **image-size**: `npm install image-size` (이미지 크기 확인)
 - **@mermaid-js/mermaid-cli**: `npm install @mermaid-js/mermaid-cli` (다이어그램 렌더링)
+
+---
+
+## Header/Footer 설정
+
+### 기본 Header 추가
+
+```javascript
+const { Document, Header, Footer, Paragraph, TextRun, AlignmentType, 
+        PageNumber, NumberFormat } = require('docx');
+
+const doc = new Document({
+  sections: [{
+    properties: {
+      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
+    },
+    headers: {
+      default: new Header({
+        children: [
+          new Paragraph({
+            alignment: AlignmentType.RIGHT,
+            children: [
+              new TextRun({ 
+                text: "AWS Solutions Architecture Guide", 
+                size: 18, 
+                color: "545B64" 
+              })
+            ]
+          })
+        ]
+      })
+    },
+    children: [/* 본문 내용 */]
+  }]
+});
+```
+
+### Header with Logo
+
+```javascript
+const header = new Header({
+  children: [
+    new Paragraph({
+      alignment: AlignmentType.LEFT,
+      children: [
+        new ImageRun({
+          type: "png",
+          data: fs.readFileSync("aws-logo.png"),
+          transformation: { width: 80, height: 30 }
+        }),
+        new TextRun({ text: "    " }),  // 간격
+        new TextRun({ 
+          text: "Architecture Guide", 
+          size: 20, 
+          color: "232F3E" 
+        })
+      ]
+    })
+  ]
+});
+```
+
+### Footer with Page Numbers
+
+```javascript
+const footer = new Footer({
+  children: [
+    new Paragraph({
+      alignment: AlignmentType.CENTER,
+      children: [
+        new TextRun({ text: "Page ", size: 18 }),
+        new TextRun({ 
+          children: [PageNumber.CURRENT] 
+        }),
+        new TextRun({ text: " of ", size: 18 }),
+        new TextRun({ 
+          children: [PageNumber.TOTAL_PAGES] 
+        })
+      ]
+    })
+  ]
+});
+
+// 섹션에 적용
+const doc = new Document({
+  sections: [{
+    properties: {},
+    headers: { default: header },
+    footers: { default: footer },
+    children: [/* 본문 */]
+  }]
+});
+```
+
+### First Page Different Header
+
+```javascript
+const doc = new Document({
+  sections: [{
+    properties: {
+      titlePage: true  // 첫 페이지 다른 header/footer 사용
+    },
+    headers: {
+      first: new Header({  // 첫 페이지용
+        children: [new Paragraph({ children: [new TextRun("")] })]  // 비움
+      }),
+      default: new Header({  // 나머지 페이지용
+        children: [
+          new Paragraph({
+            alignment: AlignmentType.RIGHT,
+            children: [new TextRun({ text: "AWS Guide", size: 18 })]
+          })
+        ]
+      })
+    },
+    footers: {
+      first: new Footer({
+        children: [new Paragraph({ children: [new TextRun("")] })]
+      }),
+      default: new Footer({
+        children: [/* 페이지 번호 */]
+      })
+    },
+    children: [/* 본문 */]
+  }]
+});
+```
+
+---
+
+## Table of Contents (목차)
+
+### 자동 목차 생성
+
+docx-js에서 자동 목차(TOC)를 생성하려면 `TableOfContents` 클래스를 사용합니다.
+목차는 Heading 스타일이 적용된 텍스트를 자동으로 수집합니다.
+
+```javascript
+const { Document, TableOfContents, Paragraph, TextRun, 
+        HeadingLevel, StyleLevel } = require('docx');
+
+const doc = new Document({
+  features: {
+    updateFields: true  // Word에서 열 때 목차 자동 업데이트
+  },
+  sections: [{
+    children: [
+      // 목차 제목
+      new Paragraph({
+        heading: HeadingLevel.HEADING_1,
+        children: [new TextRun("목차")]
+      }),
+      
+      // 자동 목차
+      new TableOfContents("Table of Contents", {
+        hyperlink: true,
+        headingStyleRange: "1-3",  // Heading 1~3까지 포함
+        stylesWithLevels: [
+          new StyleLevel("Heading1", 1),
+          new StyleLevel("Heading2", 2),
+          new StyleLevel("Heading3", 3)
+        ]
+      }),
+      
+      // 페이지 나누기
+      new Paragraph({ pageBreakBefore: true }),
+      
+      // 본문 시작
+      new Paragraph({
+        heading: HeadingLevel.HEADING_1,
+        children: [new TextRun("1. 개요")]
+      }),
+      new Paragraph({
+        children: [new TextRun("이 문서는...")]
+      }),
+      
+      new Paragraph({
+        heading: HeadingLevel.HEADING_2,
+        children: [new TextRun("1.1 배경")]
+      }),
+      // ...
+    ]
+  }]
+});
+```
+
+### 목차 업데이트 안내
+
+**중요**: docx-js로 생성된 목차는 Word에서 문서를 열 때 업데이트됩니다.
+- `updateFields: true` 설정 시 Word가 자동으로 업데이트 여부 묻기
+- 수동 업데이트: Word에서 목차 선택 → 마우스 오른쪽 클릭 → "필드 업데이트"
+
+### 수동 목차 생성 (대안)
+
+자동 목차가 작동하지 않을 경우, 수동으로 목차를 생성할 수 있습니다:
+
+```javascript
+function createManualTOC(sections) {
+  // sections: [{ title: "1. 개요", level: 1 }, { title: "1.1 배경", level: 2 }]
+  return sections.map(section => {
+    const indent = (section.level - 1) * 360;  // 레벨별 들여쓰기
+    return new Paragraph({
+      indent: { left: indent },
+      children: [
+        new TextRun({
+          text: section.title,
+          size: section.level === 1 ? 24 : 22
+        })
+      ]
+    });
+  });
+}
+
+// 사용 예시
+const tocItems = [
+  { title: "1. 개요", level: 1 },
+  { title: "  1.1 배경", level: 2 },
+  { title: "  1.2 목적", level: 2 },
+  { title: "2. 아키텍처", level: 1 },
+  { title: "  2.1 구성요소", level: 2 }
+];
+
+const tocParagraphs = createManualTOC(tocItems);
+```
+
+---
+
+## 완전한 문서 템플릿 예시
+
+```javascript
+const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
+        Header, Footer, ImageRun, TableOfContents, StyleLevel,
+        HeadingLevel, AlignmentType, PageNumber, BorderStyle } = require('docx');
+const fs = require('fs');
+
+// AWS 스타일 문서 생성 함수
+function createAWSDocument(title, sections) {
+  return new Document({
+    features: { updateFields: true },
+    styles: {
+      paragraphStyles: [
+        {
+          id: "Title",
+          name: "Title",
+          run: { size: 56, bold: true, color: "232F3E" },
+          paragraph: { spacing: { after: 200 }, alignment: AlignmentType.CENTER }
+        }
+      ]
+    },
+    sections: [{
+      properties: { titlePage: true },
+      headers: {
+        first: new Header({ children: [new Paragraph("")] }),
+        default: new Header({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.RIGHT,
+              children: [new TextRun({ text: title, size: 18, color: "545B64" })]
+            })
+          ]
+        })
+      },
+      footers: {
+        first: new Footer({ children: [new Paragraph("")] }),
+        default: new Footer({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.CENTER,
+              children: [
+                new TextRun({ text: "Page " }),
+                new TextRun({ children: [PageNumber.CURRENT] }),
+                new TextRun({ text: " of " }),
+                new TextRun({ children: [PageNumber.TOTAL_PAGES] })
+              ]
+            })
+          ]
+        })
+      },
+      children: [
+        // 표지
+        new Paragraph({
+          style: "Title",
+          children: [new TextRun(title)]
+        }),
+        new Paragraph({ pageBreakBefore: true }),
+        
+        // 목차
+        new Paragraph({
+          heading: HeadingLevel.HEADING_1,
+          children: [new TextRun("목차")]
+        }),
+        new TableOfContents("TOC", {
+          hyperlink: true,
+          headingStyleRange: "1-3"
+        }),
+        new Paragraph({ pageBreakBefore: true }),
+        
+        // 본문 섹션들
+        ...sections
+      ]
+    }]
+  });
+}
+
+// 사용 예시
+const doc = createAWSDocument("AWS Lambda 아키텍처 가이드", [
+  new Paragraph({
+    heading: HeadingLevel.HEADING_1,
+    children: [new TextRun("1. 개요")]
+  }),
+  new Paragraph({
+    children: [new TextRun("이 문서는 AWS Lambda를 활용한 서버리스 아키텍처를 설명합니다.")]
+  })
+]);
+
+Packer.toBuffer(doc).then(buffer => {
+  fs.writeFileSync("aws-lambda-guide.docx", buffer);
+});
+```

package/src/skills/mcp/SKILL.md

@@ -34,6 +34,30 @@ AWS 문서를 검색합니다.
 **파라미터:**
 - `url`: 문서 URL (필수)
 
+#### recommend
+현재 문서와 관련된 AWS 문서를 추천합니다.
+
+**파라미터:**
+- `url`: 현재 조회 중인 문서 URL (필수)
+
+**반환:**
+- Highly Rated: 해당 서비스 내 인기 문서
+- New: 최근 추가된 문서 (새 기능 발견에 유용)
+- Similar: 유사 주제 문서
+- Journey: 다른 사용자들이 다음에 본 문서
+
+**사용 예시:**
+```
+// Lambda 문서를 읽은 후 관련 문서 추천
+aws-docs_recommend({
+  url: "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html"
+})
+// → "Highly Rated": Lambda 모범 사례
+// → "New": 최근 추가된 Lambda 기능
+// → "Similar": Step Functions, EventBridge 문서
+// → "Journey": Lambda 권한, 배포 관련 문서
+```
+
 ### 사용 시점
 - 서비스 기능 및 제한사항 확인
 - Best Practice 및 권장사항 조회
@@ -168,3 +192,111 @@ AWS Well-Architected Framework 보안 관련 정보를 제공합니다.
 | Amazon ECS | AmazonECS |
 | Amazon VPC | AmazonVPC |
 | AWS Fargate | AWSFargate |
+
+---
+
+## 에러 핸들링 전략
+
+### 일반 에러 유형
+
+| 에러 유형 | 원인 | 해결 방법 |
+|----------|------|----------|
+| **Timeout** | 요청 시간 초과 | 재시도 또는 쿼리 단순화 |
+| **Rate Limit** | 요청 빈도 초과 | 지수 백오프 후 재시도 |
+| **Not Found** | 문서/서비스 없음 | 검색어 변경, 유사 서비스 탐색 |
+| **Access Denied** | 권한 부족 | 일반 지식으로 대체, 제한사항 명시 |
+| **Service Unavailable** | MCP 서버 다운 | 대체 도구 사용, 캐시된 정보 활용 |
+
+### Resilience 전략 (도구 실패 시)
+
+```
+1단계: 동일 도구 재시도 (1회)
+  └── 검색어/파라미터 조정하여 재시도
+
+2단계: 대체 도구 사용
+  └── search_documentation → read_documentation (URL 직접 접근)
+  └── get_pricing → search_documentation ("pricing" 검색)
+
+3단계: 일반 지식 활용
+  └── MCP 없이 기존 지식으로 답변
+  └── 반드시 출처 제한사항 명시
+
+4단계: 부분 성공 보고
+  └── 성공한 정보 + 실패한 부분 안내
+  └── 추가 확인 필요한 항목 목록
+```
+
+### 에러별 상세 대응
+
+#### search_documentation 실패
+
+```
+원인: 검색어가 너무 일반적이거나 구체적임
+
+대응 순서:
+1. 검색어 변형 (동의어, 약어 추가/제거)
+   - "Lambda pricing" → "AWS Lambda cost"
+   - "EC2 instance types" → "Amazon EC2 instance families"
+
+2. 범위 축소/확대
+   - "S3 security best practices" → "S3 bucket policy"
+   - "DynamoDB" → "Amazon DynamoDB capacity modes"
+
+3. read_documentation으로 대체 (알려진 URL 직접 접근)
+   - https://docs.aws.amazon.com/lambda/latest/dg/welcome.html
+   - https://aws.amazon.com/lambda/pricing/
+```
+
+#### get_pricing 실패
+
+```
+원인: 서비스 코드 오류, 리전 지원 안함
+
+대응 순서:
+1. 서비스 코드 확인 (위의 서비스 코드 참조 테이블)
+   - "Lambda" → "AWSLambda"
+   - "EC2" → "AmazonEC2"
+
+2. 리전 파라미터 제거 (기본 리전으로 조회)
+
+3. search_documentation으로 가격 페이지 검색
+   - "AWS Lambda pricing"
+   - "Amazon EC2 on-demand pricing"
+
+4. 공식 가격 페이지 URL 안내
+   - https://aws.amazon.com/lambda/pricing/
+   - https://aws.amazon.com/ec2/pricing/
+```
+
+#### Well-Architected Security MCP 실패
+
+```
+원인: 카테고리 미지원, 아키텍처 설명 불충분
+
+대응 순서:
+1. 카테고리 명시적 지정
+   - "identity", "detection", "infrastructure", "data", "incident"
+
+2. 아키텍처 설명 보강
+   - 서비스 목록, 데이터 흐름, 네트워크 구성 추가
+
+3. AWS Well-Architected Tool 문서 직접 참조
+   - search_documentation("Well-Architected security pillar")
+```
+
+### 사용자 커뮤니케이션
+
+MCP 도구 실패 시 사용자에게 알리는 방법:
+
+```
+✅ 좋은 예:
+"AWS Lambda 가격 정보를 MCP로 조회했으나 현재 서비스가 응답하지 않습니다.
+ 일반적인 가격 정보를 안내드리며, 정확한 최신 가격은 
+ https://aws.amazon.com/lambda/pricing/ 에서 확인해주세요."
+
+❌ 나쁜 예:
+"MCP 도구 에러가 발생했습니다."
+"가격 정보를 가져올 수 없습니다."
+```
+
+**원칙**: 에러 메시지보다 해결책과 대안을 제시하세요.