.cursorrules

# Cursor Rules for Tech Blog

Last updated: 2026-02-07

## 프로젝트 개요
이 프로젝트는 Jekyll 기반의 기술 블로그입니다. DevSecOps, DevOps, FinOps, 블록체인 전문 콘텐츠를 다루며, 보안 중심의 실무 경험과 최신 트렌드를 공유합니다.

- **프로덕션 URL**: https://tech.2twodragon.com (Vercel)
- **백업 URL**: https://twodragon0.github.io/tech-blog (GitHub Pages)
- **GitHub**: https://github.com/Twodragon0/tech-blog

## 핵심 원칙

### 1. 보안 우선 (Security First)
- 모든 코드, 설정, 아키텍처 제안은 보안을 최우선으로 고려
- 최소 권한 원칙(Principle of Least Privilege) 적용
- Defense in Depth 전략 고려
- 민감한 정보(API 키, 비밀번호, 토큰 등)는 절대 하드코딩하지 않음
- 보안 모범 사례를 항상 제안

### 2. 실무 중심 (Practical Focus)
- 이론보다 실무 경험과 실제 사용 사례 중심
- 구체적인 코드 예제와 설정 파일 제공
- 문제 해결 과정과 트러블슈팅 포함
- 실제 운영 환경에서의 고려사항 언급

### 3. 구조화된 문서 (Structured Documentation)
- 모든 포스트는 일관된 구조를 따름
- 명확한 섹션 구분과 계층 구조
- 코드 블록은 적절한 언어 태그 사용
- 이미지와 다이어그램을 활용한 시각화

### 4. Opus 4.6 최적화 (Opus 4.6 Optimization)
- **반복 지시 불필요**: Opus 4.6는 처음부터 지시사항을 더 꼼꼼하게 따르므로 같은 말을 반복할 필요가 없습니다.
- **맥락 제공 우선**: 복잡한 작업 전에 관련 파일, 문서, 시스템 구조를 먼저 공유하면 출력 품질이 향상됩니다.
- **의도 설명 포함**: 규칙뿐만 아니라 지시의 의도를 설명하면 넓은 범위에 적용할 수 있는 맥락을 갖게 됩니다.
- **확인 지점 설정**: 복잡한 다단계 작업의 경우 단계별 확인 지점을 설정하여 협업 효율성을 높입니다.
- **대안 탐색 요청**: "이걸 접근하는 세 가지 방법이 뭐가 있을까?" 같은 질문으로 더 나은 해결책을 찾을 수 있습니다.
- **스타일 예시 제공**: 글쓰기 작업의 경우 원하는 스타일의 샘플을 제공하면 일관성 있는 출력을 얻을 수 있습니다.

**프롬프트 작성 가이드**:
- ✅ 좋은 예: "보안을 최우선으로 고려하여 API 키는 환경 변수로 관리하고, 로그에는 민감 정보가 노출되지 않도록 마스킹을 적용해줘. 이렇게 하면 실수로 커밋되거나 로그에 노출되는 위험을 방지할 수 있어."
- ❌ 나쁜 예: "API 키는 환경 변수로 관리해줘. 그리고 잊지 말고 로그에는 마스킹을 적용해줘. 그리고 API 키는 절대 하드코딩하지 말아줘."

### 5. Claude Code / Cursor 작업 시 자동 확인 (Auto-Yes)
- **프로젝트 내 또는 tmp 관련 작업**: 확인 프롬프트는 항상 **yes**로 진행한다.
- **스크립트 실행 시**: 확인을 묻는 스크립트는 가능한 한 `--yes` 또는 `-y` 플래그를 붙여 실행한다.
- **환경 변수**: `TECH_BLOG_AUTO_YES=1` 또는 `CI=1`이 설정되면 확인 없이 진행하는 스크립트 동작을 따른다.
- **적용 대상**: 이 리포지토리 루트 또는 그 하위, 또는 `/tmp`(및 시스템 tmp) 경로에서 실행되는 모든 스크립트/명령.

## 포스트 작성 규칙

### 파일명 형식
- 형식: `YYYY-MM-DD-제목.md`
- 예시: `2025-11-04-Zscaler_완벽_가이드_SSL_검사_샌드박스_AI_광고_유해_사이트_완벽_차단.md`
- 파일명은 영문과 언더스코어만 사용 (한글 제외)

### Front Matter (YAML 헤더)
모든 포스트는 다음 형식의 front matter를 포함해야 합니다:

```yaml
---
layout: post
title: "제목 (한글 가능)"
date: YYYY-MM-DD HH:MM:SS +0900
category: [카테고리]
categories: [카테고리1, 카테고리2]
tags: [태그1, 태그2, 태그3]
excerpt: "포스트 요약 (150-200자 권장)"
comments: true
original_url: https://twodragon.tistory.com/[번호]  # 선택사항
image: /assets/images/[파일명].svg
---
```

### 카테고리 목록
- `security`: 보안 관련 글
- `devsecops`: DevSecOps 관련
- `devops`: DevOps 관련
- `cloud`: 클라우드 관련
- `kubernetes`: Kubernetes 관련
- `finops`: FinOps 관련
- `incident`: 보안 사고 분석

### 포스트 구조
1. **Front Matter** (YAML 헤더)
2. **포스팅 요약** (구조화된 요약 박스)
   - 제목, 카테고리, 태그
   - 핵심 내용 (3-5개 bullet points)
   - 주요 기술/도구
   - 대상 독자
3. **서론** (배경 및 목적)
   - 문제 상황 설명
   - 해결 방법 개요
   - 포스팅의 목적
4. **본문** (주제별 섹션)
   - 명확한 제목과 계층 구조
   - 코드 예제 (필요시)
   - 이미지/다이어그램 (필요시)
   - 실무 팁 및 주의사항
   - 단계별 가이드 제공
5. **결론** (요약 및 다음 단계)
   - 핵심 내용 요약
   - 추가 학습 자료 (선택)
   - 원본 포스트 링크 (있는 경우)

### 포스팅 요약 형식
HTML 형식의 AI 요약 카드 사용 (권장, 기존 마크다운 형식도 허용):

```html
<div class="ai-summary-card">
<div class="ai-summary-header">
  <span class="ai-badge">AI 요약</span>
</div>
<div class="ai-summary-content">
  <div class="summary-row">
    <span class="summary-label">제목</span>
    <span class="summary-value">[제목]</span>
  </div>
  <div class="summary-row">
    <span class="summary-label">카테고리</span>
    <span class="summary-value"><span class="category-tag security">Security</span> <span class="category-tag cloud">Cloud</span></span>
  </div>
  <div class="summary-row">
    <span class="summary-label">태그</span>
    <span class="summary-value tags">
      <span class="tag">[태그1]</span>
      <span class="tag">[태그2]</span>
      <span class="tag">[태그3]</span>
    </span>
  </div>
  <div class="summary-row highlights">
    <span class="summary-label">핵심 내용</span>
    <ul class="summary-list">
      <li>[핵심 포인트 1]</li>
      <li>[핵심 포인트 2]</li>
      <li>[핵심 포인트 3]</li>
    </ul>
  </div>
  <div class="summary-row">
    <span class="summary-label">기술/도구</span>
    <span class="summary-value">[기술1, 기술2, 기술3]</span>
  </div>
  <div class="summary-row">
    <span class="summary-label">대상 독자</span>
    <span class="summary-value">[대상 독자]</span>
  </div>
</div>
<div class="ai-summary-footer">
  이 포스팅은 AI가 쉽게 이해하고 활용할 수 있도록 구조화된 요약을 포함합니다.
</div>
</div>
```

또는 마크다운 형식:
```markdown
## 📋 포스팅 요약

> **제목**: [제목]
> 
> **카테고리**: [카테고리]
> 
> **태그**: [태그1, 태그2, 태그3]
> 
> **핵심 내용**: 
> - [핵심 포인트 1]
> - [핵심 포인트 2]
> - [핵심 포인트 3]
> 
> **주요 기술/도구**: [기술1, 기술2, 기술3]
> 
> **대상 독자**: [대상 독자]
> 
> ---
> 
> *이 포스팅은 AI(Cursor, Claude 등)가 쉽게 이해하고 활용할 수 있도록 구조화된 요약을 포함합니다.*
```

## 코드 작성 규칙

### HTML/CSS 코드 품질 규칙

#### CSS 작성 규칙
- **중복 코드 제거**: 동일한 속성이나 규칙이 중복 선언되지 않도록 주의
- **CSS 변수 활용**: 하드코딩된 색상 값은 CSS 변수(`var(--color-*)`)로 대체
- **성능 최적화**: 
  - 애니메이션이나 트랜지션이 있는 요소에 `will-change` 속성 적절히 사용
  - `backdrop-filter` 사용 시 `-webkit-backdrop-filter`도 함께 추가 (Safari 호환성)
- **호환성**: `-webkit-line-clamp` 사용 시 표준 `line-clamp` 속성도 함께 선언
- **중복 제거 체크리스트**:
  - 동일한 `@media` 쿼리 블록이 여러 곳에 있는지 확인
  - 동일한 선택자에 중복된 속성 선언이 있는지 확인
  - `:focus-visible` 같은 접근성 스타일이 중복되지 않는지 확인

#### HTML 접근성 규칙
- **ARIA 속성 필수**: 
  - 네비게이션: `role="navigation"`, `aria-label` 추가
  - 버튼: `aria-label`, `aria-expanded`, `aria-controls`, `aria-pressed` 등 상황에 맞게 추가
  - 다이얼로그: `role="dialog"`, `aria-labelledby`, `aria-modal="true"` 추가
  - 메뉴: `role="menu"`, `role="menuitem"`, `aria-checked` 추가
  - 로그/동적 콘텐츠: `role="log"`, `aria-live="polite"` 추가
- **SVG 아이콘**: 모든 장식용 SVG에 `aria-hidden="true"` 추가
- **버튼 타입**: 모든 버튼에 `type="button"` 명시 (폼 제출 버튼 제외)
- **활성 링크**: 현재 페이지 링크에 `aria-current="page"` 추가
- **외부 링크**: `target="_blank"` 사용 시 `rel="noopener noreferrer"` 필수
- **접근성 체크리스트**:
  - 모든 인터랙티브 요소에 적절한 ARIA 속성 추가
  - 스크린 리더 사용자를 고려한 시맨틱 HTML 사용
  - 키보드 네비게이션 지원 확인

#### JavaScript 코드 품질 규칙
- **엄격 모드**: 모든 JavaScript 파일 상단에 `'use strict';` 추가
- **이벤트 리스너**: 가능한 경우 `passive: true` 옵션 추가 (성능 최적화)
- **에러 핸들링**: 
  - 모든 비동기 작업에 `.catch()` 핸들러 추가
  - 개발 환경에서만 상세 로그 출력
  - 프로덕션 환경에서는 최소한의 로그만 기록
- **리소스 로딩**: 
  - `requestIdleCallback` 사용 시 `timeout` 옵션 추가
  - 스크립트 로드 실패 시 `onerror` 핸들러 추가

#### Service Worker 규칙
- **에러 핸들링**: 모든 캐시 작업에 에러 핸들링 추가
- **응답 타입 검증**: `response.type === 'basic'` 확인 후 캐시
- **개발 환경 로깅**: 개발 환경에서만 에러 로깅 (`self.location.hostname` 확인)
- **오프라인 응답**: 적절한 HTTP 헤더 포함 (`charset=utf-8`, `statusText`)

#### CSP (Content Security Policy) 규칙
- **보안 우선**: 기본적으로 `unsafe-eval` 사용 금지
- **외부 스크립트 호환성**: Google Ads 등 외부 스크립트가 `eval()`을 사용하는 경우:
  - `unsafe-eval` 허용 시 주석으로 보안 고려사항 명시
  - 가능한 한 외부 스크립트 사용 최소화 권장
  - 보안 위험을 인지하고 문서화
- **CSP 문서화**: CSP 정책 변경 시 주석으로 이유와 보안 고려사항 명시

### 코드 블록 처리 원칙
- **가독성 향상**: 긴 코드 블록(10줄 이상 또는 500자 이상)은 GitHub 링크로 대체하고 원본은 주석 처리
- **짧은 예시 유지**: 짧은 코드 블록(3줄 이상, 10줄 미만)은 유지하되 관련 GitHub 링크 추가
- **매우 짧은 코드**: 3줄 미만의 매우 짧은 예시 코드는 원본 유지
- 언어 태그 필수: ````python`, ````bash`, ````yaml` 등
- 보안 관련 코드는 민감 정보 제거 필수
- **단순한 설정이나 데이터 나열은 표 형태로 변환 고려**
- **실제 구현 예시는 가능한 한 실제 존재하는 GitHub 리포지토리 링크로 대체**
- **더미 링크(`github.com/example/*`) 사용 금지**: 실제 존재하는 리소스로만 링크

### 코드 블록 링크 매핑 규칙
각 코드 타입에 맞는 적절한 GitHub 저장소 또는 공식 문서 링크를 사용:

- **AWS 관련 코드**: `https://github.com/aws-samples` 또는 구체적인 예제 저장소
- **Terraform/HCL**: `https://github.com/terraform-aws-modules` (AWS 관련), `https://registry.terraform.io/` (일반)
- **Kubernetes YAML**: `https://github.com/kubernetes/examples` (Kubernetes 리소스), `https://kubernetes.io/docs/` (공식 문서)
- **Minikube**: `https://minikube.sigs.k8s.io/docs/` (공식 문서), `https://github.com/kubernetes/minikube` (GitHub 저장소)
- **K9s**: `https://k9scli.io/` (공식 문서), `https://github.com/derailed/k9s` (GitHub 저장소)
- **Python (AWS)**: `https://github.com/aws-samples`
- **Python (일반)**: `https://docs.python.org/3/`
- **Bash/Shell**: `https://www.gnu.org/software/bash/manual/bash.html` (공식 문서)
- **JSON**: `https://www.json.org/json-en.html` (공식 문서)
- **GitHub Actions/Dependabot**: `https://docs.github.com/en/actions`, `https://docs.github.com/en/code-security/dependabot`
- **CodeQL**: `https://docs.github.com/en/code-security/code-scanning/using-codeql-code-scanning-with-your-ci`
- **npm 보안**: `https://github.com/gensecaihq/Shai-Hulud-2.0-Detector`, `https://github.com/rapticore/OreNPMGuard`
- **블록체인 보안**: `https://github.com/crytic/slither`, `https://github.com/ConsenSys/mythril`
- **AI 보안**: `https://owasp.org/www-project-top-10-for-large-language-model-applications/`, `https://atlas.mitre.org/`
- **자동차 보안**: `https://github.com/falcosecurity/falco`, `https://github.com/SonarSource/sonarqube`
- **SBOM**: `https://github.com/CycloneDX/cyclonedx-cli`, `https://github.com/spdx/tools`

### 코드 블록 링크 형식
```markdown
> **참고**: [설명]은 [관련 링크 텍스트](링크 URL) 및 [추가 링크 텍스트](링크 URL)를 참조하세요.

```language
# 짧은 코드 예시...
```
```

긴 코드 블록의 경우:
```markdown
> **참고**: 전체 코드는 [관련 링크 텍스트](링크 URL)를 참조하세요.
> 
> ```language
> # 코드 미리보기...
> ```

<!-- 전체 코드는 위 링크 참조
```language
[전체 코드 내용]
```
-->
```

### 코드 예제 모범 사례
```markdown
```bash
# 좋은 예: 설명이 포함된 명령어
aws ec2 describe-instances --filters "Name=tag:Name,Values=production-*"

# 나쁜 예: 민감한 정보 포함
aws ec2 describe-instances --region us-east-1 --profile my-secret-profile
```
```

### Terraform 코드
- 변수 사용 권장 (하드코딩 지양)
- 보안 그룹 규칙은 최소 권한 원칙 적용
- 리소스 태깅 규칙 준수
- 주석으로 보안 고려사항 설명

### YAML/JSON 설정
- 들여쓰기 일관성 유지 (스페이스 2칸)
- 주석으로 각 설정의 목적 설명
- 보안 관련 설정 강조

## 이미지 및 시각화

### 이미지 파일명 규칙
- **⚠️ 필수 규칙**: 모든 이미지 파일명은 반드시 영어로만 작성해야 합니다
- **한글 사용 절대 금지**: 한글이 포함된 이미지 파일명은 절대 사용하지 않음
- **파일명 형식**: `YYYY-MM-DD-[영문_제목].svg` 또는 `.png`, `.jpg`
- **영문만 허용**: 파일명에는 영문자, 숫자, 언더스코어(`_`), 하이픈(`-`)만 사용 가능
- **예시**: `2025-06-05-Email_Delivery_Trust_Improve_SendGrid_SPF_DKIM_DMARC_Setup_Complete_Guide.svg`
- **자동 변환**: 한글 파일명이 발견되면 `scripts/rename_images_to_english.py` 스크립트를 사용하여 자동 변환
- **검증 필수**: 이미지 생성/추가 시 파일명이 영어로만 작성되었는지 반드시 확인

### 이미지 생성
- `GEMINI_IMAGE_GUIDE.md`와 `POST_VISUALIZATION_CHECKLIST.md` 참조
- nano banana 스타일 일러스트 사용
- 모든 이미지는 `/assets/images/` 디렉토리에 저장
- **파일명 규칙**: `YYYY-MM-DD-[영문_포스트제목].svg` 또는 `.png`
- **⚠️ 필수**: 이미지 파일명은 반드시 영어로만 작성 (한글 절대 금지)
- **파일명 검증**: 이미지 생성 후 파일명이 영어로만 작성되었는지 확인 필수

### 이미지 파일명 영어 변환
한글이 포함된 이미지 파일명을 영어로 변환하는 경우:

1. **자동 변환 스크립트 사용**:
   ```bash
   python3 scripts/rename_images_to_english.py
   # 또는 자동 확인 없이 실행
   python3 scripts/rename_images_to_english.py --yes
   ```

2. **변환 프로세스**:
   - 포스팅 파일의 `image:` 필드에서 이미지 파일명 확인
   - 한글 부분을 영어로 번역 (한글-영어 사전 사용)
   - 이미지 파일명 변경
   - 포스팅 파일의 모든 이미지 참조 자동 업데이트:
     - `image:` 필드
     - `<img src>` 태그
     - 마크다운 이미지 링크 `![...](...)`

3. **변환 후 검증**:
   - 모든 이미지 파일명이 영어로 변경되었는지 확인
   - 포스팅 파일의 이미지 경로 참조가 올바르게 업데이트되었는지 확인
   - 한글이 포함된 이미지 경로 참조가 없는지 확인

### 이미지 삽입 형식
```markdown
![이미지 설명](assets/images/[영문_파일명].svg)
*그림 1: 이미지 설명*
```

**⚠️ 중요**: 이미지 파일명은 반드시 영어로만 작성되어야 합니다. 한글이 포함된 파일명은 사용하지 않습니다.

### SVG 이미지 텍스트 규칙
- **⚠️ 중요**: SVG 이미지 내의 모든 텍스트는 반드시 영어로만 작성해야 합니다
- 한글 텍스트는 인코딩 문제로 인해 깨질 수 있으므로 사용하지 않음
- SVG 파일의 `<text>` 요소에는 영어만 사용
- 제목, 라벨, 설명 등 모든 텍스트 요소를 영어로 작성
- 예시:
  - ❌ "클라우드 보안 과정" → ✅ "Cloud Security Course"
  - ❌ "보안 방어" → ✅ "Security Defense"
  - ❌ "정적 분석" → ✅ "Static Analysis"
  - ❌ "민감 정보 탐지" → ✅ "Sensitive Data Detection"
- SVG 생성 시 한글 텍스트가 포함되지 않도록 주의
- 기존 SVG 파일에 한글 텍스트가 있으면 영어로 변경

### SVG 파일 인코딩 및 특수 문자 규칙
- **⚠️ 중요**: SVG 파일은 반드시 UTF-8 인코딩으로 저장되어야 합니다
- **특수 문자 사용 금지**: 다음 특수 문자는 인코딩 문제를 일으킬 수 있으므로 사용하지 않음
  - ❌ `·` (middle dot) → ✅ `|` 또는 `&amp;`
  - ❌ `•` (bullet) → ✅ `-` 또는 `*`
  - ❌ `—` (em dash) → ✅ `-` 또는 `--`
  - ❌ `–` (en dash) → ✅ `-`
  - ❌ `"` `"` (curly quotes) → ✅ `"` 또는 `&quot;`
  - ❌ `'` `'` (curly apostrophes) → ✅ `'` 또는 `&apos;`
  - ❌ `…` (ellipsis) → ✅ `...`
- **안전한 ASCII 문자 사용**: 불릿 포인트는 `-` 또는 `*` 사용
- **XML 검증**: 모든 SVG 파일은 `xmllint --noout` 명령으로 검증 가능해야 함
- **인코딩 검증**: 파일 저장 후 UTF-8 인코딩 오류가 없는지 확인
- **문제 발견 시**: 깨진 문자나 인코딩 오류가 발견되면 파일을 완전히 다시 작성

### 시각화 요소
- 아키텍처 다이어그램: 네트워크 구조, 시스템 구조
- 흐름도: 프로세스, 워크플로우
- 타임라인: 이벤트 순서, 장애 타임라인
- 비교표: Before/After, 솔루션 비교
- 차트: 데이터 시각화 (필요시)

## 보안 관련 작성 규칙

### 민감 정보 처리
- API 키, 비밀번호, 토큰은 절대 실제 값 사용 금지
- 예시: `YOUR_API_KEY`, `your-secret-key`, `***` 사용
- 환경 변수나 시크릿 관리 도구 사용 예시 제공
- 로그 파일에 민감 정보가 기록되지 않도록 주의
- API 키는 환경 변수로 관리: `export CLAUDE_API_KEY="your-key"`

### 민감 정보 마스킹 패턴
코드나 로그에서 민감 정보를 마스킹할 때 다음 패턴 사용:
- API 키: `sk-***MASKED***`, `AIza***MASKED***`
- 비밀번호: `***MASKED***`
- 토큰: `***TOKEN_MASKED***`
- 실제 IP 주소: 예시 IP 사용 (예: `192.0.2.0`)

### 보안 모범 사례 강조
- 코드 예제에 보안 주석 추가
- 취약점 및 대응 방법 명시
- 보안 체크리스트 제공 (필요시)
- Defense in Depth 전략 설명
- 최소 권한 원칙 적용 예시

### API 키 및 시크릿 관리
- 절대 Git에 커밋하지 않음
- `.gitignore`에 환경 변수 파일 포함
- AWS Secrets Manager, HashiCorp Vault 등 시크릿 관리 도구 사용
- 로컬 개발 시 `.env` 파일 사용 (Git 제외)
- Vercel 환경 변수로 관리 (프로덕션)
- 서버리스 함수에서만 사용 (클라이언트 노출 금지)

### 로그 보안
- **민감 정보 필터링**: password, token, secret, api_key 등 자동 필터링
- **로그 레벨 제한**: warn, error만 전송 (Free 티어 최적화)
- **프로덕션만 수집**: 개발/프리뷰 환경 제외
- **로그 길이 제한**: 1,000자 초과 시 잘라서 전송
- **샘플링 적용**: Vercel Log Drains 10% 샘플링

### 모니터링 보안
- **할당량 관리**: Sentry Free 티어 제한 내에서 운영 (월 5,000 이벤트)
- **이벤트 모니터링**: `scripts/monitor_sentry_quota.sh` 사용
- **로그 검증**: `scripts/verify_sentry_logs.js` 사용
- **민감 정보 마스킹**: 로그에 민감 정보 포함 금지

### 보안 경고 박스
```markdown
> **⚠️ 보안 주의사항**
> 
> [주의해야 할 보안 관련 내용]
> 
> - [주의사항 1]
> - [주의사항 2]
```

## 마크다운 작성 규칙

### 제목 계층
- `#` (H1): 포스트 제목 (front matter에서 처리)
- `##` (H2): 주요 섹션
- `###` (H3): 하위 섹션
- `####` (H4): 세부 항목 (최소한으로 사용)

### 리스트
- 순서 없는 리스트: `-` 사용
- 순서 있는 리스트: 숫자 사용
- 중첩 리스트는 2칸 들여쓰기

### 강조
- **굵게**: 중요한 개념, 키워드
- *기울임*: 강조 (최소한으로 사용)
- `코드`: 명령어, 파일명, 변수명

### 인용 블록
```markdown
> **💡 실무 팁**
> [팁 내용]

> **⚠️ 주의사항**
> [주의사항]

> **📌 핵심 요약**
> [요약 내용]
```

### 표
- 마크다운 표 형식 사용
- 헤더 행 명확히 구분
- 내용은 간결하고 읽기 쉽게
- **체크리스트나 리스트 형태의 내용은 가능한 한 표로 변환하여 가독성 향상**
- **코드 블록이 단순한 설정이나 데이터를 나열하는 경우 표 형태로 변환 고려**
- 표에 포함된 내용과 중복되는 텍스트 설명은 제거하여 중복 방지

## 파일 구조 이해

### 디렉토리 구조
```
tech-blog/
├── _posts/          # 블로그 포스트 (Markdown)
├── _layouts/        # Jekyll 레이아웃 파일
├── _includes/        # 재사용 가능한 컴포넌트
├── assets/           # CSS, JS, 이미지 등 정적 파일
│   ├── css/
│   ├── js/
│   └── images/      # 포스트 이미지 저장
├── _config.yml       # Jekyll 설정 파일
├── Gemfile          # Ruby 의존성 관리
└── scripts/         # 유틸리티 스크립트
```

### 주요 파일
- `_config.yml`: 사이트 설정, 카테고리, 네비게이션
- `GEMINI_IMAGE_GUIDE.md`: 이미지 생성 가이드
- `POST_VISUALIZATION_CHECKLIST.md`: 시각화 체크리스트
- `README.md`: 프로젝트 개요

## 작업 시 주의사항

### 새 포스트 작성 시
1. `_posts/` 디렉토리에 올바른 파일명으로 생성
2. Front matter 형식 확인
3. 포스팅 요약 섹션 포함
4. 이미지 필요 시 `POST_VISUALIZATION_CHECKLIST.md` 참조
5. 코드 예제는 보안 고려사항 포함
6. **링크는 반드시 실제 존재하는 리소스로만 사용** (example 링크 사용 금지)
7. **프로세스/워크플로우 설명은 표 형식으로 작성** (단계, 프로세스, 설명, 결과)
8. **위험도별 정책은 표 형식으로 작성** (위험도, 접근 권한, 추가 조치, 설명)
9. **모니터링 대상은 표 형식으로 작성** (모니터링 대상, 설명, 목적)
10. **체크리스트나 리스트는 가능한 한 표 형태로 변환하여 가독성 향상**
11. **표에 포함된 내용과 중복되는 텍스트 설명 제거**

### 기존 포스트 수정 시
1. Front matter 형식 유지
2. 기존 구조와 일관성 유지
3. 이미지 경로 확인 (영어 파일명 사용 확인)
4. **SVG 이미지 내 텍스트 확인 (영어로만 작성되어 있는지 확인)**
5. **SVG 파일 XML 검증** (`xmllint --noout` 명령으로 검증)
6. **SVG 파일 특수 문자 확인** (`·`, `•`, `—`, `"`, `'` 등이 있는지 확인하고 안전한 ASCII 문자로 변경)
7. **링크 검증 및 개선**: 모든 링크가 실제 존재하는 리소스를 가리키는지 확인
   - `github.com/example/*` 같은 더미 링크는 실제 리소스로 교체
   - 존재하지 않는 링크는 제거하거나 실제 관련 리소스로 교체
   - 웹 검색을 통해 실제 존재하는 GitHub 리포지토리나 문서 링크 찾기
   - **부적절한 링크 교체**: 코드 내용과 무관한 링크는 적절한 링크로 교체
     - 예: GitHub Actions 워크플로우 코드에 `kubernetes/examples` → `docs.github.com/en/actions`
     - 예: npm 보안 코드에 `kubernetes/examples` → npm 보안 도구 링크
     - 예: AI 보안 코드에 `kubernetes/examples` → OWASP, MITRE ATLAS 링크
   - **잘못된 참조 링크 패턴 수정**: `.yml...`, `.설정...`, `참조하세요...yml` 같은 잘못된 패턴 제거
   - **중복 참조 링크 제거**: 동일한 참조 링크가 반복되는 경우 하나만 유지
8. **코드 블록 링크 개선**: 긴 코드 블록은 GitHub 링크로 대체하고 원본은 주석 처리
   - 10줄 이상 또는 500자 이상: 링크로 대체 + 주석 처리
   - 3줄 이상 10줄 미만: 링크 추가 + 코드 유지
   - 3줄 미만: 원본 유지
9. **중복 내용 제거**: 표에 포함된 내용과 중복되는 텍스트 설명 제거
10. **표 형식 변환**: 프로세스/워크플로우, 위험도별 정책, 모니터링 대상, 체크리스트를 표로 변환하여 가독성 향상
    - 프로세스 설명: 단계별 표 (단계, 프로세스, 설명, 결과)
    - 위험도별 정책: 정책 표 (위험도, 접근 권한, 추가 조치, 설명)
    - 모니터링 대상: 모니터링 표 (모니터링 대상, 설명, 목적)
    - 체크리스트: 체크리스트 표 (항목, 설명, 상태)
11. **코드 블록 검토**: 단순한 설정이나 데이터 나열은 표 형태로 변환 고려
12. 한글 이미지 파일명이 있으면 `scripts/rename_images_to_english.py` 실행
13. SVG 이미지에 한글 텍스트가 있으면 영어로 변경
14. SVG 파일에 인코딩 오류가 있으면 파일을 완전히 다시 작성
15. **모니터링 관련 내용**: Sentry 로그, Vercel 로그 관련 내용이 있으면 최적화 규칙 확인
16. **AI 채팅 위젯 관련**: API 키 보호, Rate Limiting, 타임아웃 설정 확인
17. **문맥 오류 검증**: 섹션의 주제와 맞지 않는 문장이 있는지 확인
    - Kubernetes 관련 문장이 AWS 섹션에 들어가지 않았는지 확인
    - 컨테이너 보안 문장이 비-Kubernetes 포스트에 들어가지 않았는지 확인
    - 각 섹션의 주제와 일치하는 내용인지 확인
18. **중복 문장 제거**: 동일한 설명이 반복되는 경우 하나만 유지
    - 특히 "User Namespaces는 컨테이너 내 root 사용자를..." 같은 패턴 확인
    - "컨테이너 보안은 여러 레이어로 구성된 Defense in Depth 전략을 통해 강화됩니다:" 같은 패턴 확인
    - "Pod Security Standards는 세 가지 보안 레벨을 제공합니다:" 같은 패턴 확인
19. **설명 부족 문장 제거**: 표 다음에 홀로 있는 설명 없는 문장 제거
    - 예: 표 다음에 "Pod Security Standards는 세 가지 보안 레벨을 제공합니다:"만 있는 경우
    - 설명이 필요하면 상세한 설명 추가, 불필요하면 제거
20. **섹션별 문맥 일치 확인**: 각 섹션의 제목과 내용이 일치하는지 확인
    - 예: "K9s 보안 고려사항" 섹션에 컨테이너 보안 일반 설명이 들어가지 않았는지 확인
    - 예: "AWS Security Hub" 섹션에 Kubernetes 관련 내용이 들어가지 않았는지 확인

### 코드 변경 시
1. 보안 취약점 확인
2. 하드코딩된 민감 정보 제거
3. 주석으로 보안 고려사항 설명
4. 테스트 가능한 예제 제공
5. **CSS 중복 코드 확인**: 동일한 속성이나 규칙이 중복되지 않았는지 확인
6. **CSS 변수 활용**: 하드코딩된 색상 값을 CSS 변수로 대체
7. **HTML 접근성 확인**: ARIA 속성, SVG aria-hidden, 버튼 type 등 확인
8. **JavaScript 품질**: 'use strict', 에러 핸들링, 이벤트 리스너 옵션 확인
9. **Service Worker 안정성**: 에러 핸들링, 응답 타입 검증 확인

### 모니터링 설정 변경 시
1. Sentry 로그 레벨 확인 (warn, error만)
2. 프로덕션 환경 필터 확인
3. 민감 정보 필터링 패턴 확인
4. 할당량 모니터링 스크립트 실행
5. Vercel Log Drains 설정 확인

### AI 채팅 위젯 변경 시
1. API 키가 환경 변수로 관리되는지 확인
2. Rate Limiting 설정 확인 (10회/분)
3. 타임아웃 설정 확인 (8초)
4. 입력 검증 로직 확인
5. XSS 방지 적용 확인
6. Vercel 프리티어 제한 내에서 작동하는지 확인

## AI 어시스턴트 활용 가이드

### 포스트 작성 요청 시
- 제목, 카테고리, 태그, 핵심 내용을 명확히 전달
- 필요한 이미지/다이어그램 요구사항 명시
- 대상 독자 레벨 지정
- 원본 URL이 있으면 `original_url` 필드에 포함

### 코드 작성 요청 시
- 사용 기술 스택 명시
- 보안 요구사항 명시
- 실행 환경 및 제약사항 명시
- 민감 정보는 환경 변수나 플레이스홀더 사용

### 이미지 생성 요청 시
- `GEMINI_IMAGE_GUIDE.md`의 템플릿 참조
- 스타일: nano banana
- 레이아웃: 가로형 (블로그 포스트용)
- **⚠️ 필수 규칙 1**: 이미지 파일명은 반드시 영어로만 작성 (예: `2025-06-05-Email_Delivery_Trust_Improve_SendGrid_SPF_DKIM_DMARC_Setup_Complete_Guide.svg`)
- **⚠️ 필수 규칙 2**: SVG 이미지 내의 모든 텍스트는 영어로만 작성 (한글 텍스트 사용 금지)
- **파일명 검증**: 이미지 생성 후 파일명이 영어로만 작성되었는지 확인 필수

## AI 프롬프트 엔지니어링

### 포스팅 개선 프롬프트 구조
AI 기반 포스팅 개선 시 다음 구조를 따릅니다:

```markdown
당신은 기술 블로그 전문 작가입니다. 다음 정보를 바탕으로 상세하고 실용적인 기술 블로그 포스팅 본문을 작성해주세요.

제목: [제목]
카테고리: [카테고리]
태그: [태그]
요약: [excerpt]
원본 URL: [original_url]

요구사항:
1. 실무 중심의 구체적인 내용으로 작성
2. 코드 예제와 설정 예시 포함
3. 보안 모범 사례 강조
4. 단계별 가이드 제공
5. 문제 해결 섹션 포함
6. 마크다운 형식으로 작성
7. 한글로 작성

다음 구조로 작성해주세요:
## 서론
[배경 및 목적 설명]

## 1. 개요
[주요 개념 및 배경]

## 2. 핵심 내용
[상세한 설명 및 실전 가이드]

## 3. 실전 적용
[구체적인 설정 방법 및 코드 예제]

## 4. 모범 사례
[보안 및 운영 모범 사례]

## 5. 문제 해결
[일반적인 문제 및 해결 방법]

## 결론
[요약 및 마무리]

원본 포스트: [original_url]
```

### 카테고리별 프롬프트 커스터마이징
- **보안 관련**: 보안 모범 사례, 위협 대응, 취약점 분석 강조
- **클라우드 관련**: 아키텍처 설계, 비용 최적화, 운영 모범 사례 강조
- **DevSecOps 관련**: CI/CD 통합, 자동화, 보안 스캔 통합 강조
- **Kubernetes 관련**: 최신 Kubernetes 버전(1.32-1.35) 보안 기능, Minikube/K9s 활용, 실전 테스트 시나리오, 보안 모범 사례 강조

### 포스팅 개선 기준
다음 조건을 만족하는 포스팅은 개선 대상입니다:
- 본문이 1500자 미만인 포스팅
- "서론" 또는 "1." 섹션이 없는 포스팅
- 원본 링크만 있고 본문이 거의 없는 포스팅

### AI 도구 활용 순서
1. **Claude API** (1순위): 가장 고품질의 콘텐츠 생성
2. **Gemini API** (2순위): Claude 실패 시 사용
3. **Cursor 분석** (3순위): API 키 없이도 작동, 파일 구조 분석 기반 개선

## 검증 체크리스트

### 포스트 작성 완료 후 확인
- [ ] Front matter 형식 올바름
- [ ] 포스팅 요약 섹션 포함 (HTML 또는 마크다운 형식)
- [ ] 이미지 경로 올바름 (`/assets/images/` 디렉토리)
- [ ] **⚠️ 필수**: 이미지 파일명이 영어로만 작성되었는지 확인 (한글 파일명 절대 금지)
- [ ] **파일명 검증**: 영문자, 숫자, 언더스코어(`_`), 하이픈(`-`)만 사용되었는지 확인
- [ ] **SVG 이미지 내 텍스트가 영어로만 작성되었는지 확인** (한글 텍스트 사용 금지)
- [ ] **SVG 파일이 유효한 XML 형식인지 확인** (`xmllint --noout` 검증)
- [ ] **SVG 파일에 특수 문자(`·`, `•`, `—`, `"`, `'` 등)가 없는지 확인**
- [ ] **SVG 파일이 UTF-8 인코딩으로 저장되었는지 확인**
- [ ] **모든 링크가 실제 존재하는 리소스를 가리키는지 확인** (더미 링크 사용 금지)
- [ ] **부적절한 링크 확인**: 코드 내용과 무관한 링크가 없는지 확인
  - GitHub Actions 워크플로우 → GitHub Actions 문서 링크
  - npm 보안 → npm 보안 도구 링크
  - AI 보안 → OWASP, MITRE ATLAS 링크
  - 각 코드 타입에 맞는 적절한 링크 사용 확인
- [ ] **잘못된 참조 링크 패턴 확인**: `.yml...`, `.설정...`, `참조하세요...yml` 같은 패턴이 없는지 확인
- [ ] **중복 참조 링크 확인**: 동일한 참조 링크가 반복되지 않는지 확인
- [ ] **코드 블록 링크 개선 확인**: 긴 코드 블록은 링크로 대체되었는지 확인
  - 10줄 이상 또는 500자 이상: 링크로 대체 + 주석 처리
  - 3줄 이상 10줄 미만: 링크 추가 + 코드 유지
- [ ] **프로세스/워크플로우 설명이 표 형식으로 작성되었는지 확인** (단계, 프로세스, 설명, 결과)
- [ ] **위험도별 정책이 표 형식으로 작성되었는지 확인** (위험도, 접근 권한, 추가 조치, 설명)
- [ ] **모니터링 대상이 표 형식으로 작성되었는지 확인** (모니터링 대상, 설명, 목적)
- [ ] **표에 포함된 내용과 중복되는 텍스트 설명이 없는지 확인**
- [ ] **체크리스트나 리스트가 표 형태로 변환 가능한지 검토**
- [ ] **문맥 오류 확인**: 각 섹션의 주제와 내용이 일치하는지 확인
  - Kubernetes 관련 문장이 AWS 섹션에 들어가지 않았는지 확인
  - 컨테이너 보안 문장이 비-Kubernetes 포스트에 들어가지 않았는지 확인
  - 각 섹션의 제목과 내용이 일치하는지 확인
- [ ] **중복 문장 확인**: 동일한 설명이 반복되지 않는지 확인
  - "User Namespaces는 컨테이너 내 root 사용자를..." 같은 패턴 중복 확인
  - "컨테이너 보안은 여러 레이어로 구성된 Defense in Depth 전략을 통해 강화됩니다:" 같은 패턴 중복 확인
  - "Pod Security Standards는 세 가지 보안 레벨을 제공합니다:" 같은 패턴 중복 확인
- [ ] **설명 부족 문장 확인**: 표 다음에 홀로 있는 설명 없는 문장이 없는지 확인
- [ ] 코드에 민감 정보 없음 (API 키, 비밀번호, 토큰)
- [ ] 보안 고려사항 명시
- [ ] 마크다운 형식 올바름
- [ ] 링크 및 참조 확인
- [ ] 한글/영문 혼용 일관성
- [ ] 서론 섹션 포함
- [ ] 본문 길이 1500자 이상 (권장)
- [ ] 원본 포스트 링크 포함 (있는 경우)

### 코드 검토 체크리스트
- [ ] 하드코딩된 민감 정보 제거
- [ ] 환경 변수 사용 예시 제공
- [ ] 보안 주석 포함
- [ ] 최소 권한 원칙 적용
- [ ] 에러 처리 포함
- [ ] **CSS 중복 코드 제거**: 동일한 속성이나 규칙이 중복되지 않았는지 확인
- [ ] **CSS 변수 활용**: 하드코딩된 색상 값을 CSS 변수로 대체했는지 확인
- [ ] **CSS 성능 최적화**: will-change, -webkit-backdrop-filter 등 적절히 사용
- [ ] **HTML 접근성**: ARIA 속성, SVG aria-hidden, 버튼 type 등 확인
- [ ] **JavaScript 품질**: 'use strict', 에러 핸들링, 이벤트 리스너 옵션 확인
- [ ] **Service Worker 안정성**: 에러 핸들링, 응답 타입 검증 확인

### Kubernetes 관련 포스트 검토 체크리스트
- [ ] 최신 Kubernetes 버전 정보 반영 (1.32-1.35)
- [ ] Minikube 최신 버전(1.37.0+) 기능 반영
- [ ] K9s best practices (2024-2025) 포함
- [ ] 보안 모범 사례 적용 (User Namespaces, Security Context, Resource Limits)
- [ ] 실전 테스트 시나리오 포함
- [ ] 공식 문서 및 GitHub 저장소 링크 포함
- [ ] 코드 예제에 보안 컨텍스트 포함
- [ ] Pod Security Standards 고려
- [ ] Network Policy 고려
- [ ] RBAC 최소 권한 원칙 적용

### AI 개선 후 검토
- [ ] 생성된 본문이 포스트 주제와 일치하는가?
- [ ] 코드 예제가 실제로 작동하는가?
- [ ] 보안 모범 사례가 포함되었는가?
- [ ] 실무 중심의 내용인가?
- [ ] 원본 포스트 링크가 유지되었는가?

### 모니터링 및 로깅 체크리스트
- [ ] Sentry 로그 레벨이 올바르게 설정되었는가? (warn, error만)
- [ ] 프로덕션 환경에서만 로그가 수집되는가?
- [ ] 민감 정보 필터링이 적용되었는가?
- [ ] Vercel Log Drains가 올바르게 설정되었는가?
- [ ] Sentry 할당량이 Free 티어 제한 내에 있는가?

### AI 채팅 위젯 체크리스트
- [ ] API 키가 환경 변수로 관리되고 있는가?
- [ ] 클라이언트에 API 키가 노출되지 않는가?
- [ ] Rate Limiting이 설정되었는가? (10회/분)
- [ ] 입력 검증이 구현되었는가? (최대 2000자)
- [ ] 타임아웃이 8초로 설정되었는가?
- [ ] XSS 방지가 적용되었는가?

### 표 형식 변환 체크리스트
- [ ] 프로세스/워크플로우 설명이 표로 변환되었는가?
- [ ] 위험도별 정책이 표로 정리되었는가?
- [ ] 모니터링 대상이 표로 정리되었는가?
- [ ] 체크리스트가 표로 변환 가능한지 검토되었는가?
- [ ] 표에 포함된 내용과 중복되는 텍스트 설명이 제거되었는가?

## AI 기반 포스팅 개선 워크플로우

### 자동 개선 스크립트 활용
프로젝트에는 AI 기반 포스팅 개선 스크립트가 포함되어 있습니다:

1. **AI 기반 개선** (`scripts/ai_improve_posts.py`):
   - Claude API, Gemini API 활용
   - 실무 중심의 상세한 본문 생성
   - 카테고리별 맞춤 콘텐츠 생성

2. **기본 템플릿 개선** (`scripts/smart_improve_posts.py`):
   - API 키 없이도 작동
   - 기본 템플릿 기반 개선

### 개선 프로세스
1. 포스팅 분석: 본문 길이, 구조 확인
2. 개선 필요 여부 판단: 1500자 미만, 구조 부재 등
3. AI 콘텐츠 생성: Claude → Gemini → Cursor 분석 순서
4. 파일 업데이트: 기존 본문 교체 또는 추가
5. 로그 기록: 모든 작업은 `ai_improvement_log.txt`에 기록

### 실행 방법
```bash
# API 키 설정
./scripts/setup_ai_keys.sh

# 즉시 실행 (1시간)
./scripts/run_ai_improvement.sh

# 백그라운드 실행
./scripts/start_ai_background.sh

# 로그 확인
tail -f ai_improvement_log.txt
```

## 스크립트 및 자동화

### 주요 스크립트

#### 포스팅 개선 스크립트
- `scripts/ai_improve_posts.py`: AI 기반 포스팅 개선
- `scripts/enhance_all_posts.py`: 모든 포스팅 요약 섹션 보강
- `scripts/smart_improve_posts.py`: 지능형 포스팅 개선
- `scripts/fix_summary_format.py`: 요약 형식 표준화
- `scripts/continuous_improve_posts.py`: 지속적인 포스팅 개선

#### 이미지 관리 스크립트
- `scripts/rename_images_to_english.py`: 한글 이미지 파일명을 영어로 변환 및 포스팅 참조 업데이트
- `scripts/check_images.py`: 이미지 파일 검증
- `scripts/generate_og_banner.py`: OG 이미지 생성
- `scripts/fetch_tistory_images.py`: 티스토리 이미지 가져오기

#### 링크 관리 스크립트
- `scripts/replace_code_blocks_with_links.py`: 코드 블록을 GitHub 링크로 대체하는 스크립트
- `scripts/fix_github_links.py`: 부적절한 GitHub 링크를 검증하고 개선하는 스크립트
- `scripts/fix_all_links.py`: 모든 포스트의 부적절한 링크를 일괄 수정하는 스크립트

#### 모니터링 및 로깅 스크립트
- `scripts/setup_vercel_log_drains.sh`: Vercel Log Drains 설정
- `scripts/verify_sentry_logs.js`: Sentry 로그 검증
- `scripts/monitor_sentry_quota.sh`: Sentry 할당량 모니터링
- `scripts/check-vercel-logs.sh`: Vercel 로그 확인
- `scripts/monitor_vercel_builds.sh`: Vercel 빌드 모니터링
- `scripts/setup-sentry.sh`: Sentry 설정

#### AI 채팅 위젯 스크립트
- `scripts/add-deepseek-key.sh`: DeepSeek API 키 추가
- `scripts/check-vercel-logs.sh`: 채팅 위젯 로그 확인

#### 소셜 공유 스크립트
- `scripts/share_sns.py`: SNS 자동 공유
- `scripts/auto_share_new_posts.sh`: 새 포스트 자동 공유
- `scripts/setup_linkedin_keys.sh`: LinkedIn API 키 설정

### 스크립트 작성 시 주의사항
- 모든 로그는 민감 정보 마스킹 필수
- API 키는 환경 변수에서만 읽기
- 예외 처리 시 민감 정보 포함 여부 확인
- 파일 작업 전 백업 권장

## 링크 및 참조 관리 규칙

### 링크 검증 원칙
- **모든 링크는 실제 존재하는 리소스로만 사용**
- `github.com/example/*` 같은 더미 링크는 절대 사용하지 않음
- 링크 추가 전 웹 검색을 통해 실제 존재 여부 확인
- GitHub 링크는 실제 리포지토리, 문서, 도구 링크만 사용

### 링크 교체 전략
1. **더미 링크 발견 시**:
   - 웹 검색을 통해 관련 실제 리소스 찾기
   - 공식 문서, 오픈소스 프로젝트, 실제 GitHub 리포지토리 우선
   - 관련 리소스를 찾을 수 없으면 링크 제거하고 텍스트 설명으로 대체

2. **참고 자료 섹션**:
   - 실제 존재하는 공식 문서, GitHub 리포지토리, 표준 스펙 링크 추가
   - 각 링크에 명확한 설명 포함

3. **코드 예제 링크**:
   - 실제 구현 예시는 가능한 한 실제 GitHub 리포지토리 링크로 대체
   - 공식 문서나 예제 리포지토리 우선 사용

### 표 형식 변환 가이드
- **프로세스/워크플로우 변환**: 단계별 프로세스 설명은 표로 변환 (단계, 프로세스, 설명, 결과)
- **정책/규칙 변환**: 위험도별, 레벨별 정책은 표로 변환 (위험도, 접근 권한, 추가 조치, 설명)
- **체크리스트 변환**: 보안 체크리스트, 기능 목록 등을 표로 변환
- **모니터링 대상 변환**: 모니터링 항목은 표로 변환 (모니터링 대상, 설명, 목적)
- **리스트 변환**: 반복적인 구조의 리스트는 표로 변환하여 가독성 향상
- **코드 블록 검토**: 단순한 설정이나 데이터 나열은 표 형태로 변환 고려
- **중복 제거**: 표에 포함된 내용과 중복되는 텍스트 설명은 제거

### 표 형식 예시

#### 프로세스/워크플로우 표
```markdown
| 단계 | 프로세스 | 설명 | 결과 |
|------|---------|------|------|
| 1 | 사용자 요청 | 사용자가 리소스 접근 요청 | - |
| 2 | Identity Verification | 사용자 신원 확인 | 인증 성공/실패 |
| 3 | Device Trust Assessment | 디바이스 신뢰성 평가 | 디바이스 상태 확인 |
```

#### 위험도별 정책 표
```markdown
| 위험도 | 접근 권한 | 추가 조치 | 설명 |
|--------|----------|----------|------|
| **Low** | Full Access | 없음 | 신뢰할 수 있는 사용자/디바이스 |
| **Medium** | Limited Access | MFA 필수 | 부분적 신뢰, 제한적 접근 |
| **High** | Block + Alert | 보안 팀 알림 | 의심스러운 활동, 접근 차단 |
```

#### 모니터링 대상 표
```markdown
| 모니터링 대상 | 설명 | 목적 |
|-------------|------|------|
| **Identity Verification** | 사용자 인증 상태 지속 확인 | 세션 하이재킹 방지 |
| **Device Trust Assessment** | 디바이스 상태 실시간 모니터링 | 디바이스 변조 탐지 |
| **Context Analysis** | 사용자 행동 패턴 분석 | 이상 행위 탐지 |
```

#### 체크리스트 표
```markdown
| 보안 영역 | 체크리스트 항목 | 설명 |
|----------|---------------|------|
| 하드웨어 보안 | Secure Boot 구현 | 부팅 시 펌웨어 무결성 검증 |
| | 하드웨어 루트 오브 트러스트 | 신뢰할 수 있는 하드웨어 기반 보안 체인 구축 |
```

## 모니터링 및 로깅 규칙

### Sentry 통합
- **브라우저 로그**: warn, error 레벨만 전송 (Free 티어 최적화)
- **프로덕션만 수집**: 개발/프리뷰 환경 제외
- **민감 정보 필터링**: password, token, secret, api_key 등 자동 필터링
- **로그 길이 제한**: 1,000자 초과 시 잘라서 전송
- **샘플링**: Vercel Log Drains 10% 샘플링

### Vercel 로그 관리
- **Log Drains 설정**: Sentry 통합을 통한 서버 로그 전송
- **환경 변수**: `SENTRY_DSN`, `SENTRY_ENVIRONMENT` 설정 필수
- **로그 검증**: `scripts/verify_sentry_logs.js` 스크립트 사용
- **할당량 모니터링**: `scripts/monitor_sentry_quota.sh` 스크립트 사용

### 성능 모니터링
- **실행 시간 모니터링**: 5초 이상인 경우만 로깅
- **메모리 사용량 추적**: 평균 50-100MB 목표
- **에러율 모니터링**: Rate limiting 및 타임아웃 추적

## AI 채팅 위젯 규칙

### DeepSeek API 통합
- **API 키 보호**: 서버리스 함수에서만 사용, 클라이언트에 노출 금지
- **환경 변수**: `DEEPSEEK_API_KEY`는 Vercel 환경 변수로 관리
- **입력 검증**: 메시지 길이 제한 (최대 2000자)
- **Rate Limiting**: 세션당 10회/분 제한 (프리티어 최적화)

### Vercel Serverless Functions
- **타임아웃**: 8초로 설정 (프리티어 안전 마진)
- **메모리**: 1024MB로 제한
- **응답 크기**: 최대 토큰 수 1500으로 제한
- **로깅 최소화**: 프로덕션 환경에서 최소한의 로그만 기록

### 보안 고려사항
- **XSS 방지**: 입력 및 출력 정제
- **CORS 설정**: 적절한 CORS 헤더 설정
- **민감 정보 마스킹**: 로그에 민감 정보 포함 금지
- **API 키 로테이션**: 정기적인 API 키 교체 권장

## 표 형식 변환 강화

### 프로세스 설명 표 형식
프로세스나 워크플로우를 설명할 때는 표 형식을 사용하여 가독성을 향상시킵니다:

```markdown
| 단계 | 프로세스 | 설명 | 결과 |
|------|---------|------|------|
| 1 | 사용자 요청 | 사용자가 리소스 접근 요청 | - |
| 2 | Identity Verification | 사용자 신원 확인 | 인증 성공/실패 |
```

### 위험도별 정책 표
보안 정책이나 접근 제어를 설명할 때는 위험도별로 표로 정리:

```markdown
| 위험도 | 접근 권한 | 추가 조치 | 설명 |
|--------|----------|----------|------|
| **Low** | Full Access | 없음 | 신뢰할 수 있는 사용자/디바이스 |
| **Medium** | Limited Access | MFA 필수 | 부분적 신뢰, 제한적 접근 |
| **High** | Block + Alert | 보안 팀 알림 | 의심스러운 활동, 접근 차단 |
```

### 모니터링 대상 표
모니터링이나 체크리스트를 설명할 때는 표 형식 사용:

```markdown
| 모니터링 대상 | 설명 | 목적 |
|-------------|------|------|
| **Identity Verification** | 사용자 인증 상태 지속 확인 | 세션 하이재킹 방지 |
| **Device Trust Assessment** | 디바이스 상태 실시간 모니터링 | 디바이스 변조 탐지 |
```

### 표 변환 우선순위
1. **프로세스/워크플로우**: 단계별 설명은 표로 변환
2. **정책/규칙**: 위험도별, 레벨별 정책은 표로 변환
3. **체크리스트**: 보안 체크리스트, 기능 목록은 표로 변환
4. **비교표**: Before/After, 솔루션 비교는 표로 변환
5. **모니터링 대상**: 모니터링 항목은 표로 변환

## Vercel 프리티어 최적화 규칙

### 함수 최적화
- **타임아웃**: 최대 8초 (프리티어 안전 마진)
- **메모리**: 1024MB로 제한
- **빠른 실패**: 입력 검증 및 Rate limiting을 먼저 수행
- **응답 크기**: 최대 토큰 수 제한 (1500 토큰)

### Rate Limiting
- **세션당 최대 요청**: 10회/분
- **윈도우**: 60초
- **메모리 기반**: 프리티어용 간단한 구현
- **프로덕션 권장**: Redis 또는 Vercel KV 사용

### 로깅 최적화
- **프로덕션**: 최소한의 로그만 기록
- **개발 환경**: 상세 로그 활성화
- **실행 시간 모니터링**: 5초 이상인 경우만 로깅

## Sentry Free 티어 최적화 규칙

### 로그 레벨 필터링
- ✅ **warn**: 경고 로그만 전송
- ✅ **error**: 에러 로그만 전송
- ❌ **log**: 일반 로그 제외
- ❌ **info**: 정보 로그 제외
- ❌ **debug**: 디버그 로그 제외
- ❌ **trace**: 추적 로그 제외

### 샘플링 설정
- **Vercel Log Drains**: 10% 샘플링
- **트레이스**: 5% 샘플링
- **프로덕션만 수집**: 개발/프리뷰 환경 제외

### 할당량 관리
- **월 5,000 이벤트** 제한 내에서 운영
- **30일 데이터 보존** 고려
- **이벤트 수 모니터링**: `scripts/monitor_sentry_quota.sh` 사용

## OpenCode 통합

### OpenCode Sisyphus 모드 및 Ralph Loop

이 프로젝트는 OpenCode의 Sisyphus 모드와 Ralph Loop를 사용하여 자동화된 콘텐츠 개선을 수행합니다.

#### 빠른 시작
```bash
# OpenCode Sisyphus 모드 시작
opencode sisyphus

# Ralph Loop 커맨드 실행
/improve-posts      # 포스트 개선 (Opus 4.5)
/collect-news       # 뉴스 수집 (Sonnet 4, 비용 효율적)
/validate-posts     # 포스트 검증 (Sonnet 4, 비용 효율적)
/generate-images    # 이미지 생성 (Opus 4.5)
/security-audit     # 보안 감사 (Sonnet 4, 비용 효율적)
/write-code         # 코드 작성 (Opus 4.5)
/refactor           # 코드 리팩토링 (Opus 4.5)
/fix-bugs           # 버그 수정 (Opus 4.5)
```

#### 모델 선택 전략
- **고품질 작업** (Opus 4.5 ⭐): 콘텐츠 생성, 코드 작성, 이미지 생성
- **비용 효율적 작업** (Sonnet 4 💰): 검증, 분석, 읽기 전용 작업

#### 비용 최적화
1. **캐시 우선**: API 호출 전 `_data/collected_news.json` 확인 (7일 TTL)
2. **로컬 스크립트**: `python3 scripts/*.py` 사용 (API 비용 없음)
3. **Gemini CLI**: 무료 OAuth 2.0 (최우선)
4. **배치 처리**: 여러 작업을 그룹화하여 API 호출 최소화

#### 보안
- 모든 에이전트는 최소 권한 원칙 준수
- 로그에서 민감 정보 자동 마스킹
- 모든 커맨드에 입력 검증
- 보안 감사 커맨드: `/security-audit`

자세한 내용은 `.opencode/README.md` 참조.

## 참고 문서
- `README.md`: 프로젝트 개요
- `BEST_PRACTICES.md`: 포스팅 작성 모범 사례
- `GEMINI_IMAGE_GUIDE.md`: 이미지 생성 가이드
- `POST_VISUALIZATION_CHECKLIST.md`: 시각화 체크리스트
- `.opencode/README.md`: OpenCode 설정 및 사용법
- `AGENTS.md`: AI 에이전트 코딩 가이드라인
- `CLAUDE.md`: Claude Code 지침
- `scripts/README_AI_IMPROVEMENT.md`: AI 기반 개선 가이드
- `scripts/README_IMPROVEMENT.md`: 기본 개선 가이드
- `scripts/QUICK_START.md`: 빠른 시작 가이드
- `_config.yml`: Jekyll 설정 및 카테고리 목록
- `SECURITY.md`: 보안 정책
- `README_CHAT_WIDGET.md`: DeepSeek 채팅 위젯 설정 가이드
- `README_SENTRY_LOGS.md`: Sentry 로그 설정 가이드
- `VERCEL_FREE_TIER_OPTIMIZATION.md`: Vercel 프리티어 최적화 가이드

## 이미지 파일명 관리 규칙

### 핵심 원칙
1. **모든 이미지 파일명은 영어로 작성**: 한글 파일명 사용 금지
2. **일관된 파일명 형식**: `YYYY-MM-DD-[영문_제목].확장자`
3. **자동 변환 도구 사용**: 한글 파일명 발견 시 `scripts/rename_images_to_english.py` 사용

### 파일명 변환 프로세스
1. **포스팅 파일 분석**: 포스팅 파일의 `image:` 필드에서 이미지 파일명 확인
2. **한글-영어 번역**: 한글 부분을 영어로 번역 (내장 사전 사용)
3. **파일명 변경**: 이미지 파일명을 영어로 변경
4. **참조 업데이트**: 포스팅 파일의 모든 이미지 참조 자동 업데이트
   - Front matter의 `image:` 필드
   - HTML `<img src>` 태그
   - 마크다운 이미지 링크 `![...](...)`

### 사용되지 않는 스크립트 정리
- 중복 기능의 스크립트는 제거하여 유지보수성 향상
- `fix_all_duplicates.py`가 가장 포괄적이므로 중복 스크립트 제거
- 사용되지 않는 문서 파일도 정기적으로 정리

## Kubernetes 관련 작성 가이드

### Kubernetes 포스트 작성 시 고려사항

#### 최신 버전 정보 반영
- **Kubernetes 1.32-1.35 (2024-2025)**: 최신 보안 기능 및 개선사항 반영
  - Kubernetes 1.32 (2024년 12월): Bound Service Account Tokens (Stable), Projected Service Account Tokens for Kubelet
  - Kubernetes 1.33 (2025년 4월): ClusterTrustBundles (Beta), User Namespaces in Pods (Beta)
  - Kubernetes 1.34 (2025년 9월): Dynamic Resource Allocation (Stable), Structured Authentication Configuration
  - Kubernetes 1.35 (2025년 12월): User Namespaces (Beta-by-Default), mTLS Pod Certificates (Beta), Robust Image Pull Authorization (Beta)

#### Minikube 관련
- **최신 버전**: Minikube 1.37.0+ 기능 반영
  - containerd 기본 런타임 (Docker에서 변경)
  - krunkit 드라이버: macOS AI 워크로드 지원
  - AMD GPU 지원 (`--gpus=amd` 플래그)
  - kubetail addon 추가
  - Podman 드라이버 안정화

#### K9s 관련
- **Best Practices (2024-2025)**:
  - 네임스페이스 기반 리소스 관리
  - 성능 최적화 (대규모 클러스터 대응)
  - 보안 고려사항 (읽기 전용 모드, RBAC)
  - 커스텀 뷰 설정
  - 단축키 활용

#### 보안 모범 사례
- **Pod Security Standards**: 네임스페이스 레벨 보안 정책 적용
- **User Namespaces**: `hostUsers: false` 설정으로 컨테이너 격리 강화
- **Bound Service Account Tokens**: 토큰을 특정 Pod에 바인딩
- **Network Policies**: 네트워크 트래픽 제어
- **Resource Limits**: 리소스 제한 설정
- **Security Context**: `runAsNonRoot`, `capabilities.drop: ALL` 설정

#### 실전 테스트 시나리오 포함
- Pod/Deployment/Service 배포 예제
- ConfigMap/Secret 관리
- 문제 해결 시나리오 (로그 분석, 리소스 모니터링, 네트워크 디버깅)
- HPA (Horizontal Pod Autoscaler) 설정
- Network Policy 적용

#### 참고 자료 링크
- [Kubernetes 공식 문서](https://kubernetes.io/docs/)
- [Kubernetes GitHub 저장소](https://github.com/kubernetes/kubernetes)
- [Kubernetes 공식 예제](https://github.com/kubernetes/examples)
- [Kubernetes 보안 Best Practices](https://kubernetes.io/docs/concepts/security/best-practices/)
- [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/)
- [Minikube 공식 문서](https://minikube.sigs.k8s.io/docs/)
- [Minikube GitHub 저장소](https://github.com/kubernetes/minikube)
- [K9s 공식 문서](https://k9scli.io/)
- [K9s GitHub 저장소](https://github.com/derailed/k9s)
- [Kubernetes 릴리스 노트](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/)

#### 코드 예제 작성 시
- YAML 파일은 보안 컨텍스트 포함
- 리소스 제한 (requests/limits) 명시
- 보안 모범 사례 주석 추가
- 실제 작동하는 예제 제공
- Minikube/K9s 명령어는 최신 버전 기준으로 작성

#### 보안 체크리스트
Kubernetes 관련 포스트 작성 시 다음 항목 확인:
- [ ] User Namespace 설정 (`hostUsers: false`)
- [ ] Security Context 설정 (`runAsNonRoot`, `capabilities.drop`)
- [ ] Resource Limits 설정
- [ ] Network Policy 고려
- [ ] RBAC 최소 권한 원칙 적용
- [ ] Service Account 토큰 바인딩 고려
- [ ] 이미지 풀 정책 및 자격 증명 검증
- [ ] Pod Security Standards 준수

## 보안 강화 가이드라인

### 1. 보안 헤더 (vercel.json)

#### CSP (Content Security Policy)
```
default-src 'self'; 
script-src 'self' 'unsafe-inline' 'unsafe-eval' [허용된 도메인들];
style-src 'self' 'unsafe-inline' [허용된 도메인들];
img-src 'self' data: https:;
font-src 'self' https://fonts.gstatic.com data:;
frame-src 'self' https://giscus.app [Google Ads 도메인들];
connect-src 'self' [API 및 분석 도메인들];
base-uri 'self';
form-action 'self' https://buttondown.com;
upgrade-insecure-requests;
```

**⚠️ 보안 주의사항**: `unsafe-eval`은 Google Ads 호환성을 위해 허용되었으나, 보안 위험이 있으므로 주기적으로 검토 필요. 가능하면 제거 고려.

#### 기타 보안 헤더
- `Strict-Transport-Security`: max-age=31536000; includeSubDomains; preload
- `X-Content-Type-Options`: nosniff
- `X-Frame-Options`: SAMEORIGIN
- `Referrer-Policy`: strict-origin-when-cross-origin
- `Permissions-Policy`: geolocation=(), microphone=(), camera=()
- `X-DNS-Prefetch-Control`: on
- `X-Download-Options`: noopen
- `X-Permitted-Cross-Domain-Policies`: none

### 2. 입력 검증 및 XSS 방지

#### 필수 검증 패턴
```javascript
// XSS 패턴 감지
const XSS_PATTERNS = [
  /<script[^>]*>.*?<\/script>/gi,
  /javascript:/gi,
  /on\w+\s*=/gi,
  /<iframe[^>]*>/gi,
  /<object[^>]*>/gi,
  /<embed[^>]*>/gi
];

// Injection 패턴 감지
const INJECTION_PATTERNS = [
  /eval\s*\(/gi,
  /exec\s*\(/gi,
  /Function\s*\(/gi,
  /setTimeout\s*\(/gi,
  /setInterval\s*\(/gi
];
```

#### 입력 정제 함수
- 모든 사용자 입력은 정제 후 사용
- HTML 이스케이프: `&`, `<`, `>`, `"`, `'` 처리
- URL 검증: 허용된 프로토콜만 (`http://`, `https://`)
- 파일 업로드: 확장자 및 MIME 타입 검증

### 3. API 보안

#### Rate Limiting 구현
- 세션당 10회/분 제한
- IP 기반 차단 (필요시)
- 토큰 기반 인증 (향후 확장)

#### 에러 처리 보안
- 상세 에러 정보는 개발 환경에서만 표시
- 프로덕션에서는 일반화된 메시지 사용
- 스택 트레이스는 로그에만 기록 (클라이언트 노출 금지)

### 4. 의존성 보안

#### 정기적 검사
```bash
# npm 패키지 취약점 검사
npm audit --audit-level=moderate

# Ruby gem 취약점 검사
bundle audit --update

# GitHub Dependabot 활성화 필수
```

#### 업데이트 전략
- Critical/High 취약점: 즉시 업데이트
- Medium 취약점: 7일 이내 업데이트
- Low 취약점: 정기 업데이트 (월 1회)

## 비용 최적화 전략

### 1. API 비용 관리

#### 우선순위 (비용 순)
1. **Gemini CLI** (OAuth 2.0) - 무료 ⭐ 최우선
2. **로컬 템플릿** - 무료
3. **Cursor/Claude Console** - 무료 할당량
4. **API 호출** - 비용 발생 (최소화)

#### DeepSeek API 최적화
- **Context Caching 활용**: 최대 90% 비용 절감
- **Off-Peak 시간대**: UTC 16:30-00:30 (50-75% 할인)
- **대화 히스토리 제한**: 최대 10개 메시지
- **응답 크기 제한**: max_tokens=1500

#### 캐싱 전략
- 동일 포스트 7일 캐시
- API 응답 캐싱 (가능한 경우)
- 정적 리소스 CDN 캐싱

### 2. 인프라 비용

#### Vercel 프리티어 최적화
- 함수 타임아웃: 8초 (안전 마진)
- 메모리: 1024MB (최대 활용)
- 캐싱: 정적 리소스 1년, HTML 2-3시간
- Rate Limiting: DDoS 방지 및 비용 제어

#### Sentry 프리티어 최적화
- 로그 레벨: warn, error만
- 샘플링: 10% (Vercel Log Drains)
- 환경: 프로덕션만 수집
- 월 제한: 5,000 이벤트

### 3. 개발 비용

#### 자동화로 수동 작업 감소
- 포스트 개선: AI 기반 자동화 (80% 감소)
- 이미지 생성: 자동 생성 (90% 감소)
- 링크 검증: 자동 검증 및 수정
- SNS 공유: GitHub Actions 자동화

## UI/UX 개선 가이드라인

### 1. 접근성 (WCAG 2.1 AA 준수)

#### 필수 ARIA 속성
- 네비게이션: `role="navigation"`, `aria-label`
- 버튼: `aria-label`, `aria-expanded`, `aria-pressed`
- 다이얼로그: `role="dialog"`, `aria-modal="true"`
- 로그/동적 콘텐츠: `role="log"`, `aria-live="polite"`

#### 키보드 네비게이션
- 모든 인터랙티브 요소는 키보드로 접근 가능
- 포커스 순서 논리적
- `Tab`, `Enter`, `Space`, `Escape` 키 지원
- `:focus-visible` 스타일 명확히 표시

#### 색상 대비
- 텍스트 대비: 4.5:1 이상 (일반 텍스트), 3:1 이상 (큰 텍스트)
- 인터랙티브 요소: 3:1 이상
- 다크 모드 지원 필수

### 2. 성능 최적화

#### Core Web Vitals 목표
- **LCP (Largest Contentful Paint)**: < 2.5초
- **FID (First Input Delay)**: < 100ms
- **CLS (Cumulative Layout Shift)**: < 0.1

#### 최적화 기법
- 이미지 지연 로딩: `loading="lazy"`
- Critical CSS 인라인
- 리소스 힌트: `preconnect`, `dns-prefetch`
- Service Worker 캐싱
- 코드 스플리팅 (필요시)

### 3. 사용자 경험

#### 로딩 상태
- 스켈레톤 UI 제공
- 로딩 인디케이터 표시
- 진행률 표시 (가능한 경우)

#### 에러 처리
- 친화적인 에러 메시지
- 복구 방법 제시
- 자동 재시도 (적절한 경우)

#### 피드백
- 작업 완료 시 시각적 피드백
- 성공/실패 상태 명확히 표시
- 애니메이션으로 상태 변화 표현

### 4. 반응형 디자인

#### 브레이크포인트
- 모바일: ≤480px
- 태블릿: ≤768px
- 데스크톱: >768px

#### 모바일 최적화
- 터치 타겟 최소 44x44px
- 스와이프 제스처 지원
- 모바일 메뉴 제공
- 이미지 최적화 (WebP, 적절한 크기)

## 운영 효율성 가이드라인

### 1. 모니터링 및 알림

#### Sentry 설정
- Critical 에러 즉시 알림
- 에러 그룹핑 활성화
- 컨텍스트 정보 자동 추가
- Breadcrumbs 최대 100개

#### Vercel Analytics
- Core Web Vitals 추적
- 사용자 행동 분석
- 주간 리포트 자동 생성

### 2. 자동화

#### CI/CD 파이프라인
- 자동 빌드 및 배포
- 테스트 자동 실행
- 보안 스캔 자동화
- 의존성 업데이트 자동화

#### 스크립트 자동화
- 포스트 개선: `scripts/ai_improve_posts.py`
- 이미지 생성: `scripts/generate_post_images.py`
- 링크 검증: `scripts/fix_links_unified.py`
- 이미지 검증: `scripts/verify_images_unified.py`

### 3. 에러 복구

#### 자동 재시도
- 지수 백오프 전략
- 최대 3회 재시도
- 재시도 간격: 1초, 2초, 4초

#### 폴백 전략
- API 실패 시 캐시된 데이터 사용
- 네트워크 오류 시 오프라인 모드
- 에러 발생 시 기본 UI 표시

## 모바일 반응형 디자인

### 브레이크포인트
- **모바일**: ≤480px (1열 그리드)
- **태블릿**: ≤768px (2열 그리드)
- **데스크톱**: >768px (3열 그리드)

### 주요 반응형 컴포넌트
- `.posts-list`: 포스트 카드 그리드
- `.category-grid`: 카테고리 그리드
- `.stats-grid`: 통계 그리드
- `.related-grid`: 관련 포스트 그리드

## 성능 최적화 구현

### 캐싱 전략 (vercel.json)
| 리소스 | Cache-Control |
|--------|---------------|
| `/assets/*` | 1년 (immutable) |
| `/*.html` | 2시간 |
| `/posts/*` | 3시간 |
| `/feed.xml` | 1시간 |
| `/api/*` | no-cache |

### Service Worker (sw.js)
- 정적 리소스 캐싱
- 오프라인 지원
- Network-first, cache-fallback 전략