
Web To Markdown
- 37 installs
- 902 repo stars
- Updated June 22, 2026
- bear2u/my-skills
web-to-markdown is a Claude skill that converts a web page URL into a saved markdown file, optionally in an AI-optimized structure.
About
This skill takes a web page URL and converts it to markdown using WebFetch, then saves it to a local file. It offers a normal mode for readable markdown, an AI-optimized mode that adds YAML frontmatter and structured sections, and a dual mode that produces both files. A developer uses it to archive web documents or prepare pages as context for an AI agent or RAG system.
- Converts a web page URL to markdown and saves it locally
- AI-optimized mode adds YAML frontmatter and a structured layout
- Dual mode outputs both a human-readable and an AI-optimized file
Web To Markdown by the numbers
- 37 all-time installs (skills.sh)
- Ranked #1,169 of 2,715 Automation & Workflows skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
web-to-markdown capabilities & compatibility
- Capabilities
- web archiving · markdown conversion · context prep
- Use cases
- web scraping · documentation · research
What web-to-markdown says it does
웹페이지의 URL을 입력받아 해당 페이지의 내용을 마크다운 형식으로 변환하여 저장하는 스킬입니다.
듀얼 모드는 원본 마크다운과 AI 최적화 버전을 모두 생성합니다.
npx skills add https://github.com/bear2u/my-skills --skill web-to-markdownAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 37 |
|---|---|
| repo stars | ★ 902 |
| Last updated | June 22, 2026 |
| Repository | bear2u/my-skills ↗ |
What it does
Convert a web page URL into a saved markdown file, optionally in an AI-optimized structure for use as context.
Who is it for?
Archiving a web page as markdown or preparing it as AI context
Skip if: Bulk crawling many pages or scraping structured data fields
When should I use this skill?
You want to save a web page as a local markdown file
What you get
A saved markdown file of the page, optionally with AI-optimized frontmatter and structure, or both versions.
- readable markdown file
- AI-optimized markdown file
- dual-mode file pair
By the numbers
- 3 conversion modes (normal/AI-optimized/dual)
- 15-minute WebFetch URL cache
Files
Web to Markdown Converter
웹페이지의 URL을 입력받아 해당 페이지의 내용을 마크다운 형식으로 변환하여 저장하는 스킬입니다.
When to Use
다음과 같은 요청이 있을 때 이 스킬을 사용하세요:
- "웹페이지를 마크다운으로 변환해줘"
- "이 URL을 마크다운으로 저장해줘"
- "웹사이트 내용을 마크다운 파일로 만들어줘"
- "웹페이지 아카이빙해줘"
- "블로그 글을 마크다운으로 저장해줘"
- "AI가 읽기 좋게 변환해줘" (AI 최적화 모드)
- "컨텍스트로 사용하기 좋게 변환해줘" (AI 최적화 모드)
- "원본이랑 AI 최적화 버전 둘 다 만들어줘" (듀얼 모드) ⭐ NEW
Core Workflow
Step 1: URL 입력받기
사용자에게 변환하고자 하는 웹페이지의 URL을 입력받습니다.
Example:
Claude: 변환하실 웹페이지의 URL을 입력해주세요.
User: https://example.com/articleImportant:
- URL은
http://또는https://로 시작해야 합니다 - HTTP URL은 자동으로 HTTPS로 업그레이드됩니다
- 유효하지 않은 URL은 에러를 반환합니다
Step 2: 변환 모드 선택
사용자의 요청을 분석하여 적절한 변환 모드를 선택합니다.
변환 모드: 1. 일반 모드 (기본): 웹페이지를 읽기 좋은 마크다운으로 변환 2. AI 최적화 모드: AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환 3. 듀얼 모드 ⭐ NEW: 원본 + AI 최적화 버전 2개 파일 생성
자동 감지 키워드:
- "AI가 읽기 좋게", "컨텍스트로 사용", "AI 학습용" → AI 최적화 모드
- "원본이랑", "둘 다", "2개", "both", "원본도 저장" → 듀얼 모드
- 기타 → 일반 모드
Example 1 (AI 최적화):
User: https://example.com/article AI가 읽기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다. 구조화된 포맷과 메타데이터를 추가합니다.Example 2 (듀얼 모드):
User: https://example.com/article 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
- 원본 마크다운 (article.md)
- AI 최적화 버전 (article.context.md)
2개 파일을 생성합니다.Step 3: 저장 옵션 확인
사용자에게 저장 위치와 파일명을 확인합니다.
Example:
Claude: 마크다운 파일을 어디에 저장할까요?
옵션:
1. 현재 디렉토리 (./)
2. 특정 경로 지정
3. 파일로 저장하지 않고 내용만 보기
파일명은? (기본값: webpage.md)
User: 현재 디렉토리에 article.md로 저장해줘Step 4: 웹페이지 가져오기 및 변환
WebFetch 도구를 사용하여 웹페이지를 가져오고 마크다운으로 변환합니다.
일반 모드 프롬프트
url = "https://example.com/article"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."AI 최적화 모드 프롬프트 (CRITICAL)
url = "https://example.com/article"
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:
**필수 구조:**
1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
이 글의 핵심을 3-5줄로 요약
AI가 빠르게 파악할 수 있도록
main_points:
- 핵심 포인트 1
- 핵심 포인트 2
- 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---
2. **본문 구조**
# [원본 제목]
## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]
## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]
### 섹션 1
[내용]
### 섹션 2
[내용]
## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3
## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]
## 관련 리소스
[링크가 있다면 설명과 함께]
## 결론
[마무리 요약]
**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는  형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조
**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""Important:
- WebFetch는 HTML을 자동으로 마크다운으로 변환합니다
- 15분 캐시가 적용되어 같은 URL을 반복 요청해도 빠릅니다
- 리다이렉트가 발생하면 새로운 URL로 다시 요청합니다
- AI 최적화 모드는 토큰을 30-50% 절감하고 구조를 명확하게 합니다
Step 5: 마크다운 저장
변환된 마크다운을 파일로 저장합니다.
# Write 도구를 사용하여 파일 저장
Write {
file_path: "/Users/symverse/workspaces-skill-test/my-skills-hub/article.md"
content: "[변환된 마크다운 내용]"
}AI 최적화 모드 파일명 권장:
- 일반:
article.md - AI 최적화:
article-ai-optimized.md또는article.context.md
Step 6: 결과 확인
저장된 파일의 경로와 간단한 통계를 사용자에게 보여줍니다.
✅ 웹페이지를 마크다운으로 변환했습니다!
📄 파일: article.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/article.md
📊 크기: 약 1,234 글자
[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/article.md)듀얼 모드 워크플로우 ⭐ NEW
듀얼 모드는 원본 마크다운과 AI 최적화 버전을 모두 생성합니다. 사람이 읽을 자료와 AI가 처리할 자료를 동시에 확보할 수 있습니다.
듀얼 모드 Step 1: URL 및 파일명 확인
User: https://react.dev/reference/react/useState 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
기본 파일명은? (기본: webpage)듀얼 모드 Step 2: 원본 마크다운 생성
일반 모드 프롬프트로 WebFetch를 사용하여 원본 마크다운을 생성합니다.
url = "https://react.dev/reference/react/useState"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."원본 파일 저장:
Write {
file_path: "/path/to/useState.md"
content: "[원본 마크다운 내용]"
}듀얼 모드 Step 3: AI 최적화 버전 생성
CRITICAL: 같은 URL에 대해 AI 최적화 프롬프트로 다시 WebFetch를 호출합니다.
url = "https://react.dev/reference/react/useState" # 동일한 URL
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:
**필수 구조:**
1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
이 글의 핵심을 3-5줄로 요약
AI가 빠르게 파악할 수 있도록
main_points:
- 핵심 포인트 1
- 핵심 포인트 2
- 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---
2. **본문 구조**
# [원본 제목]
## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]
## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]
### 섹션 1
[내용]
### 섹션 2
[내용]
## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3
## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]
## 관련 리소스
[링크가 있다면 설명과 함께]
## 결론
[마무리 요약]
**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는  형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조
**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""AI 최적화 파일 저장:
Write {
file_path: "/path/to/useState.context.md"
content: "[AI 최적화 마크다운 내용]"
}듀얼 모드 Step 4: 결과 요약
2개 파일 생성 결과를 사용자에게 보여줍니다.
✅ 듀얼 모드 변환 완료! 2개 파일이 생성되었습니다.
📄 원본 마크다운:
- 파일: useState.md
- 경로: /path/to/useState.md
- 크기: 약 3,500 글자
- 용도: 사람이 읽기 좋은 원본 보존
[View file](computer:///path/to/useState.md)
📄 AI 최적화 버전:
- 파일: useState.context.md
- 경로: /path/to/useState.context.md
- 크기: 약 2,100 글자 (40% 절감)
- 용도: AI 컨텍스트로 활용
[View file](computer:///path/to/useState.context.md)
💡 팁:
- 원본(.md)은 사람이 읽을 때 사용
- AI 최적화(.context.md)는 RAG 시스템이나 AI 에이전트 컨텍스트로 사용듀얼 모드 파일명 규칙
패턴 1: 확장자 구분 (권장)
- 원본:
article.md - AI 최적화:
article.context.md
패턴 2: 접미사 구분
- 원본:
article.md - AI 최적화:
article-ai-optimized.md
패턴 3: 폴더 구분
/docs
├── original/
│ └── article.md
└── optimized/
└── article.md듀얼 모드 장점
1. 원본 보존: 사람이 읽을 자료는 원본 그대로 유지 2. AI 효율성: AI용은 토큰 절감 및 구조화 3. 용도별 분리: 목적에 맞는 파일 사용 4. 백업 효과: 2가지 형태로 동시 백업 5. 비교 가능: 원본과 최적화 버전 비교 분석 가능
듀얼 모드 사용 시나리오
시나리오 1: 기술 문서 아카이빙
User: 이 React 문서들 원본이랑 AI 최적화 버전 둘 다 만들어줘
- https://react.dev/reference/react/useState
- https://react.dev/reference/react/useEffect
Claude: 듀얼 모드로 4개 파일 생성합니다.
- useState.md (원본)
- useState.context.md (AI 최적화)
- useEffect.md (원본)
- useEffect.context.md (AI 최적화)시나리오 2: 블로그 글 백업
User: 내 블로그 글을 백업하는데 원본도 저장하고 AI가 읽을 수 있는 버전도 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
- 원본: 사람이 다시 읽을 때
- AI 최적화: 나중에 AI에게 질문할 때시나리오 3: 학습 자료 구축
User: 이 튜토리얼들을 둘 다 버전으로 저장해줘
Claude:
study-materials/
├── original/ # 사람이 학습용
│ ├── intro.md
│ └── advanced.md
└── ai-optimized/ # AI 질문 답변용
├── intro.context.md
└── advanced.context.mdAdvanced Options
여러 URL 일괄 변환
여러 웹페이지를 한 번에 변환할 수 있습니다.
Example:
User: 이 URL들을 전부 마크다운으로 저장해줘
- https://example.com/article1
- https://example.com/article2
- https://example.com/article3
Claude: 3개의 웹페이지를 변환하겠습니다. 파일명은 자동으로 생성할까요, 아니면 각각 지정하시겠어요?
User: 자동으로
Claude: [각 URL을 순차적으로 변환하여 article1.md, article2.md, article3.md로 저장]특정 섹션만 추출
웹페이지의 특정 부분만 추출할 수 있습니다.
Example:
User: https://example.com/docs 에서 "Installation" 섹션만 마크다운으로 저장해줘
Claude: [WebFetch 프롬프트에 "Installation 섹션만 추출"을 명시하여 해당 부분만 변환]마크다운 포맷 커스터마이징
변환 시 원하는 마크다운 스타일을 지정할 수 있습니다.
Example:
User: 이 블로그 글을 마크다운으로 변환하되, 모든 제목을 H2(##)로 시작하고 코드 블록은 syntax highlighting 포함해줘
Claude: [WebFetch 프롬프트에 포맷 요구사항을 명시]Error Handling
잘못된 URL
User: htp://wrong-url
Claude: ❌ 올바르지 않은 URL입니다. http:// 또는 https://로 시작하는 전체 URL을 입력해주세요.접근 불가능한 페이지
Claude: ❌ 해당 웹페이지에 접근할 수 없습니다.
- 페이지가 삭제되었거나
- 접근 권한이 필요하거나
- 네트워크 오류가 발생했을 수 있습니다.파일 저장 오류
Claude: ❌ 파일을 저장할 수 없습니다.
- 경로가 올바른지 확인해주세요
- 쓰기 권한이 있는지 확인해주세요
- 디렉토리가 존재하는지 확인해주세요Example Workflows
Example 1: 단일 웹페이지 변환
User: https://docs.python.org/3/tutorial/index.html 이거 마크다운으로 저장해줘
Claude: 파이썬 튜토리얼 페이지를 마크다운으로 변환하겠습니다.
파일명을 어떻게 할까요? (기본: webpage.md)
User: python-tutorial.md
Claude: [WebFetch로 페이지 가져오기]
Claude: [마크다운으로 변환]
Claude: [파일 저장]
✅ 웹페이지를 마크다운으로 변환했습니다!
📄 파일: python-tutorial.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md
📊 크기: 약 15,234 글자
[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md)Example 2: 블로그 글 아카이빙
User: 이 블로그 글들을 전부 마크다운으로 저장해서 아카이브 폴더에 넣어줘
- https://blog.example.com/post1
- https://blog.example.com/post2
Claude: 2개의 블로그 글을 archive 폴더에 저장하겠습니다.
[디렉토리 생성]
[각 URL을 순차적으로 변환]
✅ 2개의 웹페이지를 변환했습니다!
📁 archive/
├── post1.md
└── post2.mdExample 3: 문서 내용만 보기 (저장 안 함)
User: https://github.com/anthropics/claude-code 이 페이지 내용을 마크다운으로 보여줘만 하고 저장은 하지마
Claude: [WebFetch로 페이지 가져오기]
다음은 해당 페이지의 마크다운 변환 내용입니다:
---
# Claude Code
Claude Code is an official CLI...
[전체 내용 출력]
---
저장하지 않고 내용만 보여드렸습니다.Technical Details
WebFetch 사용
- 자동 변환: HTML → 마크다운 자동 변환
- 캐싱: 15분 자가 정리 캐시
- 리다이렉트 처리: 자동으로 새 URL로 재요청
마크다운 변환 품질
WebFetch는 다음 요소를 마크다운으로 변환합니다:
- 제목 (H1-H6)
- 단락과 텍스트 포맷 (bold, italic, code)
- 링크와 이미지
- 리스트 (ordered, unordered)
- 코드 블록
- 인용구
- 테이블
불필요한 요소는 제외됩니다:
- 네비게이션 메뉴
- 푸터
- 광고
- 사이드바 (상황에 따라)
파일 저장
- 기본 경로: 현재 작업 디렉토리
- 파일 확장자:
.md - 인코딩: UTF-8
- 덮어쓰기: 기존 파일이 있으면 확인 후 덮어씀
Best Practices
1. 명확한 파일명 사용: 내용을 잘 나타내는 파일명 사용 2. 폴더 구조화: 여러 페이지를 변환할 때는 주제별로 폴더 정리 3. URL 확인: 변환 전 URL이 올바른지 확인 4. 저작권 주의: 웹페이지 내용의 저작권을 존중 5. 개인적 아카이빙: 주로 개인적인 참고 자료로 사용
Dynamic Content Handling (동적 콘텐츠 처리)
문제: JavaScript 렌더링 페이지
WebFetch는 정적 HTML만 가져오므로 React, Vue, Next.js 등 JavaScript로 렌더링되는 페이지는 빈 내용이 반환될 수 있습니다.
증상:
- 변환된 마크다운이 거의 비어있음
- "Loading..." 같은 플레이스홀더만 보임
- 핵심 콘텐츠가 누락됨
해결책: Playwright 폴백
WebFetch로 가져온 내용이 비어있거나 불충분하면, AskUserQuestion을 사용하여 사용자에게 Playwright 사용 여부를 물어봅니다.
Step 1: WebFetch 결과 검증
# WebFetch로 가져온 마크다운 내용 확인
if len(markdown_content.strip()) < 500: # 너무 짧으면
# 동적 콘텐츠일 가능성 높음Step 2: 사용자에게 물어보기
AskUserQuestion 사용:
AskUserQuestion {
questions: [
{
question: "이 페이지는 동적 콘텐츠(JavaScript)를 사용하는 것 같습니다. Playwright를 실행해서 브라우저로 데이터를 가져올까요?",
header: "Playwright",
multiSelect: false,
options: [
{
label: "Yes, Playwright로 재시도",
description: "Chromium 브라우저를 실행해서 JavaScript 렌더링 후 콘텐츠 가져오기 (느림, 정확함)"
},
{
label: "No, 현재 내용만 저장",
description: "WebFetch 결과만 저장 (빠름, 불완전할 수 있음)"
}
]
}
]
}Step 3-A: MCP Playwright 사용 (권장 ⭐)
사전 준비: MCP Playwright 서버가 설치되어 있어야 합니다.
# 최초 1회만 설치
npx @modelcontextprotocol/server-playwright스킬에서 사용:
// 1. 페이지 이동
mcp__playwright__navigate({
url: "https://example.com"
})
// 2. JavaScript 렌더링 대기
mcp__playwright__waitForLoadState({
state: "networkidle"
})
// 3. HTML 콘텐츠 가져오기
const htmlContent = mcp__playwright__getContent()
// 4. 마크다운으로 변환 (WebFetch 프롬프트 재사용)
// htmlContent를 마크다운으로 변환하는 로직Step 3-B: Node Playwright 사용 (대안)
MCP Playwright가 없는 경우 Node.js로 직접 실행:
# Playwright 스크립트 실행
node << 'EOF'
const playwright = require('playwright');
(async () => {
const browser = await playwright.chromium.launch({ headless: true });
const page = await browser.newPage();
console.log('⏳ 페이지 로딩 중...');
await page.goto('https://example.com', { waitUntil: 'networkidle' });
console.log('⏳ JavaScript 렌더링 대기 중...');
await page.waitForTimeout(3000); // 3초 대기
const content = await page.content();
console.log(content);
await browser.close();
})();
EOF출력을 파일로 저장:
# HTML을 임시 파일로 저장
node playwright-script.js > temp.html
# 이제 이 HTML을 마크다운으로 변환
# (WebFetch 대신 직접 변환 로직 사용)Step 4: 변환 및 저장
Playwright로 가져온 HTML을 마크다운으로 변환합니다.
Option A: WebFetch 프롬프트 재사용
Playwright로 가져온 전체 HTML을 WebFetch 프롬프트에 넣어 마크다운으로 변환합니다.
Option B: 직접 파싱
HTML → 마크다운 변환 라이브러리 사용 (예: turndown, html-to-markdown)
워크플로우 요약
1. WebFetch로 시도 (빠름)
↓
2. 결과 검증 (내용이 충분한가?)
↓ NO
3. AskUserQuestion (Playwright 사용할까요?)
↓ YES
4. Playwright로 재시도
├─ MCP Playwright (권장) 또는
└─ Node Playwright (대안)
↓
5. 마크다운 변환 및 저장MCP Playwright vs Node Playwright 비교
| 항목 | MCP Playwright ⭐ | Node Playwright |
|---|---|---|
| 설치 | MCP 서버 설치 필요 | npm install playwright |
| 호출 방식 | MCP 도구 호출 | Bash 명령어 실행 |
| 세션 관리 | 자동 | 수동 (스크립트 작성) |
| 에러 핸들링 | 깔끔함 | 복잡함 |
| Claude Code 통합 | 네이티브 지원 | 간접 실행 |
| 추천도 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
실전 예제
시나리오: React 공식 문서 변환
User: https://react.dev/reference/react/useState 마크다운으로 변환해줘
Claude: [WebFetch 시도]
Claude: ⚠️ 이 페이지는 JavaScript로 렌더링되는 것 같습니다.
내용이 거의 비어있네요.
[AskUserQuestion 호출]
User: Yes, Playwright로 재시도
Claude: ⏳ Playwright로 페이지 로딩 중...
Claude: ✅ JavaScript 렌더링 완료
Claude: ✅ 마크다운 변환 완료
📄 파일: useState.md
📍 경로: /path/to/useState.md
📊 크기: 약 5,234 글자 (전체 콘텐츠 포함)추가 옵션: 자동 감지 모드
고급 사용자를 위해 --auto-playwright 플래그를 지원할 수 있습니다:
User: https://react.dev/reference/react/useState 마크다운으로 변환해줘 (자동으로 Playwright 사용해도 돼)
Claude: [WebFetch 시도]
Claude: [자동으로 Playwright 폴백]
Claude: ✅ 마크다운 변환 완료Tips
- 긴 문서: 매우 긴 웹페이지는 요약이 포함될 수 있습니다
- 동적 콘텐츠: JavaScript로 렌더링되는 콘텐츠는 Playwright로 해결 가능 ⭐ NEW
- 이미지: 이미지는 원본 URL 링크로 포함됩니다 (다운로드되지 않음)
- 재변환: 같은 URL을 15분 내에 다시 요청하면 캐시된 버전을 사용합니다
- MCP Playwright: 동적 콘텐츠가 많은 경우 MCP Playwright 서버 설치 권장
AI 최적화 모드 - 상세 가이드
AI 에이전트가 웹페이지 콘텐츠를 컨텍스트로 효과적으로 활용할 수 있도록 최적화하는 방법을 설명합니다.
개요
일반 마크다운 변환과 달리, AI 최적화 모드는:
- 구조화된 메타데이터 추가 (프론트매터)
- 명확한 계층 구조 생성
- 핵심 정보 추출 및 요약
- 불필요한 노이즈 제거
- 토큰 효율성 최적화 (30-50% 절감)
언제 사용하나?
일반 모드 vs AI 최적화 모드
| 상황 | 일반 모드 | AI 최적화 모드 |
|---|---|---|
| 사람이 읽을 자료 | ✅ | ❌ |
| AI 컨텍스트로 사용 | ⚠️ 가능하지만 비효율적 | ✅ 최적화됨 |
| 원본 충실도 | 높음 | 중간 (핵심 중심) |
| 토큰 사용량 | 많음 | 적음 (30-50% 절감) |
| 검색/탐색 | 어려움 | 쉬움 (명확한 구조) |
추천 사용 사례
AI 최적화 모드를 사용하세요:
- RAG (Retrieval-Augmented Generation) 시스템 구축
- AI 에이전트 학습 자료 준비
- 대량의 문서를 AI가 처리해야 할 때
- 토큰 비용을 절감하고 싶을 때
- 빠른 정보 검색이 필요할 때
일반 모드를 사용하세요:
- 사람이 읽을 문서 백업
- 원본의 모든 뉘앙스를 보존해야 할 때
- 레이아웃이나 디자인 요소가 중요할 때
AI 최적화 출력 구조
1. 프론트매터 (YAML)
---
title: "React Hooks 완벽 가이드"
url: "https://example.com/react-hooks-guide"
author: "Jane Developer"
date: "2024-01-15"
word_count: 2500
topics: ["React", "Hooks", "Frontend", "JavaScript"]
summary: |
React Hooks의 핵심 개념과 사용법을 다룹니다.
useState, useEffect, custom hooks 작성법을 포함하며,
실무 예제를 통해 효과적인 활용법을 배울 수 있습니다.
main_points:
- useState로 컴포넌트 상태 관리
- useEffect로 부수 효과 처리
- Custom Hooks로 로직 재사용
- 성능 최적화 팁
content_type: "tutorial"
difficulty: "intermediate"
---프론트매터의 이점:
- AI가 문서를 읽기 전에 전체 맥락 파악
- 메타데이터 기반 검색 및 필터링 가능
- 주제별 분류 자동화
- 난이도 기반 적절한 답변 생성
2. 핵심 요약
# React Hooks 완벽 가이드
## 핵심 요약
React Hooks는 함수형 컴포넌트에서 상태와 생명주기 기능을 사용할 수 있게 해주는 React 16.8의 새로운 기능입니다.
클래스 컴포넌트 없이도 React의 모든 기능을 활용할 수 있으며, 로직 재사용이 더 쉬워집니다.
이 가이드는 기본 Hooks부터 고급 패턴까지 실무에서 바로 적용할 수 있는 내용을 다룹니다.핵심 요약의 역할:
- AI가 3초 내에 문서 전체 파악
- 사용자 질문과의 관련성 빠르게 판단
- 불필요한 전체 문서 읽기 방지
3. 구조화된 본문
## 주요 내용
### 1. useState - 상태 관리
**개념**: 함수형 컴포넌트에서 상태를 관리하는 Hook
**기본 사용법**:const [count, setCount] = useState(0);
**핵심 포인트**:
- 상태 초기값 설정
- 상태 업데이트 함수 사용
- 여러 상태 변수 선언 가능
### 2. useEffect - 부수 효과 처리
**개념**: 컴포넌트의 생명주기와 부수 효과를 처리하는 Hook
**기본 사용법**:useEffect(() => { // 효과 코드 return () => { // 정리 코드 }; }, [dependencies]);
**핵심 포인트**:
- 의존성 배열로 실행 조건 제어
- 정리 함수로 메모리 누수 방지
- 여러 useEffect 분리 가능구조화의 이점:
- 명확한 H2/H3 계층으로 탐색 용이
- 섹션별 독립적 이해 가능
- AI가 특정 부분만 선택적으로 읽기 가능
4. 핵심 인사이트
## 핵심 인사이트
- **Hooks는 함수 최상위에서만 호출**: 조건문이나 반복문 안에서 사용 불가
- **Custom Hooks로 로직 재사용**: 접두사 'use'를 붙여 명명
- **의존성 배열을 정확히 명시**: 누락 시 버그 발생 가능
- **useState의 함수형 업데이트**: 이전 상태 기반 업데이트 시 사용
- **useEffect 정리 함수 필수**: 구독이나 타이머 사용 시 반드시 정리인사이트의 역할:
- 단순 사실을 넘어선 이해
- 실수하기 쉬운 부분 강조
- Best practices 한눈에 파악
5. 실용적 적용
## 실용적 적용
### 실제 프로젝트에서
1. **폼 관리**: useState로 입력 값 관리, useEffect로 유효성 검사
2. **API 호출**: useEffect에서 데이터 fetch, loading/error 상태 관리
3. **전역 상태**: Context API + useContext로 prop drilling 해결
4. **성능 최적화**: useMemo, useCallback으로 불필요한 재렌더링 방지
### 코드 예제
// Custom Hook 예제: API 호출 function useApi(url) { const [data, setData] = useState(null); const [loading, setLoading] = useState(true);
useEffect(() => { fetch(url) .then(res => res.json()) .then(data => { setData(data); setLoading(false); }); }, [url]);
return { data, loading }; }
// 사용 function UserProfile({ userId }) { const { data, loading } = useApi(/api/users/${userId});
if (loading) return <div>Loading...</div>; return <div>{data.name}</div>; }
실용적 적용의 역할:
- 이론과 실전 연결
- 즉시 사용 가능한 예제 제공
- 다양한 활용 시나리오 제시
6. 관련 리소스
## 관련 리소스
- [React 공식 문서 - Hooks](https://react.dev/reference/react): 전체 Hooks API 레퍼런스
- [useHooks](https://usehooks.com/): 재사용 가능한 Custom Hooks 모음
- [React Hooks Testing Library](https://github.com/testing-library/react-hooks-testing-library): Hooks 테스트 도구
- [Awesome React Hooks](https://github.com/rehooks/awesome-react-hooks): 커뮤니티 선별 Hooks 리소스관련 리소스의 역할:
- 추가 학습 경로 제공
- 관련 도구 및 라이브러리 소개
- 커뮤니티 리소스 연결
7. 결론
## 결론
React Hooks는 함수형 컴포넌트의 가능성을 크게 확장했습니다.
클래스 컴포넌트 없이도 상태 관리, 생명주기 처리, 로직 재사용이 가능해졌으며,
코드의 가독성과 유지보수성이 크게 향상되었습니다.
**다음 단계**: Custom Hooks를 작성하여 프로젝트의 공통 로직을 추상화하고,
useMemo와 useCallback을 활용한 성능 최적화를 학습하세요.결론의 역할:
- 전체 내용 간결하게 마무리
- 다음 학습 방향 제시
- 핵심 메시지 강조
토큰 최적화 기법
1. 불필요한 요소 제거
제거 대상:
- 광고 및 프로모션 콘텐츠
- 네비게이션 메뉴
- 푸터 정보
- 댓글 섹션
- "관련 글" 추천
- 소셜 공유 버튼
- 쿠키 알림
예상 절감: 20-30% 토큰
2. 간결한 표현
Before (일반 모드):
이번 섹션에서는 React의 useState Hook에 대해서 자세하게 알아보도록 하겠습니다.
useState는 React 16.8 버전부터 추가된 새로운 기능으로서,
함수형 컴포넌트에서도 상태 관리를 할 수 있게 해주는 아주 유용한 Hook입니다.After (AI 최적화):
### useState - 상태 관리
**개념**: 함수형 컴포넌트의 상태 관리 Hook (React 16.8+)예상 절감: 10-20% 토큰
3. 구조화된 리스트
Before:
useState를 사용할 때 주의해야 할 점은 첫째로 항상 컴포넌트의 최상위에서 호출해야 한다는 것이고,
둘째로 조건문이나 반복문 안에서는 호출하면 안 되며,
셋째로 상태 업데이트는 비동기로 처리된다는 점입니다.After:
**주의사항**:
- 컴포넌트 최상위에서만 호출
- 조건문/반복문 내 호출 금지
- 상태 업데이트는 비동기 처리예상 절감: 5-10% 토큰
콘텐츠 타입별 최적화 전략
1. 튜토리얼/가이드
중점 사항:
- 단계별 명확한 구조
- 코드 예제에 주석 포함
- 각 단계의 목적 명시
- 일반적인 실수 강조
예제 구조:
## 단계별 가이드
### Step 1: 환경 설정
**목적**: 개발 환경 준비
**소요 시간**: 5분
[내용...]
**흔한 실수**: Node.js 버전 불일치2. 기술 문서 (Documentation)
중점 사항:
- API 시그니처 명확히
- 매개변수 설명 표 형식
- 반환값 명시
- 예제 코드 포함
예제 구조:
## API Reference
### `fetchUser(userId)`
**설명**: 사용자 정보를 가져옵니다
**매개변수**:
| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| userId | string | ✅ | 사용자 ID |
**반환값**: `Promise<User>`
**예제**:const user = await fetchUser('123');
3. 블로그/아티클
중점 사항:
- 저자의 주장/의견 명확히
- 사례 연구 요약
- 실용적 조언 강조
- 개인적 경험 vs 일반 사실 구분
예제 구조:
## 주장
**핵심 메시지**: [저자의 주요 주장]
## 근거
### 사례 1: [제목]
[요약...]
## 실용적 조언
1. [조언 1]
2. [조언 2]4. 뉴스/시사
중점 사항:
- 5W1H 명확히
- 주요 사실 vs 의견 구분
- 타임라인 정리
- 관련 인물/조직 정리
예제 구조:
## 핵심 사실
**What**: [무슨 일]
**Who**: [관련 인물/조직]
**When**: [시점]
**Where**: [장소]
**Why**: [이유/배경]
**How**: [방법/과정]
## 타임라인
- 2024-01-10: [사건 A]
- 2024-01-12: [사건 B]
- 2024-01-15: [사건 C]
## 주요 인물
- **Jane Doe** (CEO): [역할]
- **John Smith** (분석가): [의견]5. 학술 논문
중점 사항:
- Abstract 중심
- 방법론 요약
- 주요 결과 강조
- 기여도 명확히
예제 구조:
## Abstract 요약
[3-5줄 핵심 요약]
## 연구 질문
[논문이 답하려는 질문]
## 방법론
**접근법**: [방법론 이름]
**데이터셋**: [사용 데이터]
**도구**: [사용 도구/프레임워크]
## 주요 결과
1. [결과 1]
2. [결과 2]
## 기여도
- [기여 1]
- [기여 2]
## 한계
[논문의 한계점]실전 예제: 변환 전후 비교
원본 웹페이지 (가상)
<!-- 네비게이션 -->
<nav>Home | About | Blog | Contact</nav>
<!-- 광고 -->
<div class="ad">🎁 Special Offer!</div>
<!-- 본문 -->
<article>
<h1>Understanding React Hooks</h1>
<p class="author">By Jane Developer | Jan 15, 2024</p>
<p>In this comprehensive guide, we will explore React Hooks...</p>
<h2>What are Hooks?</h2>
<p>React Hooks are functions that let you use state and other React features...</p>
<!-- 소셜 공유 -->
<div class="share">Share on: Facebook | Twitter | LinkedIn</div>
</article>
<!-- 댓글 -->
<section class="comments">
<h3>Comments (47)</h3>
...
</section>
<!-- 푸터 -->
<footer>© 2024 Example.com</footer>일반 모드 변환
# Understanding React Hooks
By Jane Developer | Jan 15, 2024
In this comprehensive guide, we will explore React Hooks...
## What are Hooks?
React Hooks are functions that let you use state and other React features...
---
Share on: Facebook | Twitter | LinkedIn
## Comments (47)
[댓글 내용...]
---
© 2024 Example.com문제점:
- 불필요한 요소 포함 (댓글, 푸터, 공유 버튼)
- 메타데이터 없음
- 구조 불명확
- 토큰 낭비
AI 최적화 모드 변환
---
title: "Understanding React Hooks"
url: "https://example.com/react-hooks"
author: "Jane Developer"
date: "2024-01-15"
word_count: 1500
topics: ["React", "Hooks", "JavaScript", "Frontend"]
summary: |
React Hooks의 개념과 사용법을 다루는 포괄적 가이드.
useState, useEffect 등 주요 Hooks를 실전 예제와 함께 설명.
main_points:
- Hooks는 함수형 컴포넌트에서 상태와 생명주기 사용
- 클래스 컴포넌트 없이 React 기능 활용
- Custom Hooks로 로직 재사용
content_type: "tutorial"
difficulty: "beginner"
---
# Understanding React Hooks
## 핵심 요약
React Hooks는 함수형 컴포넌트에서 상태와 React 기능을 사용할 수 있게 해주는 함수입니다.
이 가이드는 Hooks의 기본 개념부터 실전 활용법까지 다룹니다.
## 주요 내용
### Hooks란?
**개념**: React 16.8에 추가된 함수형 컴포넌트의 상태 관리 및 생명주기 기능
**핵심 특징**:
- 클래스 없이 상태 사용
- 로직 재사용 간편
- 코드 가독성 향상
[...]
## 핵심 인사이트
- Hooks는 컴포넌트 최상위에서만 호출
- Custom Hooks로 로직 추상화
- 의존성 배열 정확히 명시 필수
## 실용적 적용
1. **폼 관리**: useState로 입력 값 관리
2. **API 호출**: useEffect에서 데이터 fetch
3. **성능 최적화**: useMemo, useCallback 활용
## 결론
React Hooks는 함수형 컴포넌트의 가능성을 확장하고 코드 품질을 향상시킵니다.개선점:
- 불필요한 요소 완전 제거
- 구조화된 메타데이터
- 명확한 계층 구조
- 핵심 정보 강조
- 토큰 30-40% 절감
검증 체크리스트
AI 최적화 변환 후 다음 사항을 확인하세요:
필수 요소
- [ ] 프론트매터 포함 (title, url, topics, summary)
- [ ] 핵심 요약 섹션 (3-5줄)
- [ ] 명확한 H2/H3 계층 구조
- [ ] 핵심 인사이트 정리
- [ ] 결론 섹션
품질
- [ ] 광고/네비게이션 제거 확인
- [ ] 코드 블록 언어 명시 확인
- [ ] 링크에 설명 포함 확인
- [ ] 불필요한 수식어 제거 확인
- [ ] 리스트가 bullet points로 정리 확인
토큰 효율성
- [ ] 원본 대비 30% 이상 토큰 절감
- [ ] 핵심 정보 누락 없음 확인
- [ ] AI가 3초 내 파악 가능한 구조
고급 활용
1. 여러 페이지 일괄 최적화
User: 이 문서들을 전부 AI 최적화 모드로 변환해줘
- https://example.com/doc1
- https://example.com/doc2
- https://example.com/doc3
Claude: 3개 문서를 AI 최적화 모드로 변환하겠습니다.
각 문서에 메타데이터와 구조를 추가하여 docs/optimized/ 폴더에 저장합니다.2. RAG 시스템 구축
1. 웹페이지를 AI 최적화 모드로 변환
2. 프론트매터의 topics로 벡터 인덱싱
3. 사용자 질문 시 관련 문서 검색
4. 구조화된 섹션에서 정확한 정보 추출3. 지식 베이스 구축
/knowledge-base
├── frontend/
│ ├── react-hooks.context.md
│ ├── vue-composition.context.md
│ └── svelte-stores.context.md
├── backend/
│ ├── nodejs-streams.context.md
│ └── python-asyncio.context.md
└── devops/
├── docker-compose.context.md
└── kubernetes-pods.context.md각 파일은 AI 최적화 포맷으로, topics 기반 자동 분류 가능
마무리
AI 최적화 모드는 단순한 변환을 넘어 AI가 이해하고 활용하기 최적화된 지식 표현을 만듭니다.
핵심 원칙: 1. 구조화: 명확한 계층과 섹션 2. 메타데이터: 프론트매터로 맥락 제공 3. 간결함: 핵심만 남기고 노이즈 제거 4. 실용성: 즉시 활용 가능한 정보
이제 웹의 모든 지식을 AI에게 최적화된 형태로 저장하고 활용하세요!
실전 예제 모음
다양한 상황에서 Web to Markdown 스킬을 활용하는 방법을 소개합니다.
1. 개발 문서 아카이빙
시나리오
프로젝트에서 사용하는 라이브러리들의 공식 문서를 로컬에 백업하고 싶습니다.
실행
You: 이 문서들을 project-docs 폴더에 저장해줘
- https://react.dev/reference/react
- https://redux.js.org/introduction/getting-started
- https://tanstack.com/query/latest/docs/react/overview
Claude: project-docs 폴더를 생성하고 3개의 문서를 변환하겠습니다.
[변환 중...]
✅ 완료!
project-docs/
├── react-reference.md
├── redux-getting-started.md
└── tanstack-query-overview.md
총 3개 파일, 약 45KB결과
오프라인에서도 문서를 참고할 수 있고, 버전 관리 시스템에 포함시켜 팀과 공유 가능합니다.
---
2. 블로그 글 수집
시나리오
좋은 기술 블로그 글들을 발견할 때마다 나중에 다시 읽기 위해 저장하고 싶습니다.
실행
You: https://blog.example.com/great-article 이 블로그 글을 reading-list 폴더에 저장해줘
Claude: 파일명은 어떻게 할까요? 또는 자동으로 생성할까요?
You: 제목 기반으로 자동 생성해줘
Claude: ✅ 저장 완료!
📄 reading-list/understanding-react-hooks.md
📊 약 3,250 단어
제목: "Understanding React Hooks: A Deep Dive"
작성자: John Doe심화: 태그 추가
You: 이 글에 프론트매터로 태그 추가해줘
Claude: [파일에 프론트매터 추가]
---
title: Understanding React Hooks: A Deep Dive
author: John Doe
url: https://blog.example.com/great-article
saved_date: 2024-01-15
tags:
- react
- hooks
- frontend
---
[본문...]---
3. 튜토리얼 시리즈 다운로드
시나리오
온라인 강좌의 모든 레슨을 순서대로 저장하고 싶습니다.
실행
You: 이 튜토리얼 시리즈를 전부 저장해줘. 순서대로 번호를 붙여서
- https://tutorial.com/lesson-intro
- https://tutorial.com/lesson-basics
- https://tutorial.com/lesson-advanced
- https://tutorial.com/lesson-conclusion
Claude: tutorials/web-dev-course/ 폴더에 저장하겠습니다.
✅ 완료!
tutorials/web-dev-course/
├── 01-intro.md
├── 02-basics.md
├── 03-advanced.md
└── 04-conclusion.md추가 요청
You: 전체 목차를 만들어줘
Claude: [index.md 파일 생성]
# Web Development Course
## 목차
1. [Introduction](01-intro.md)
2. [Basics](02-basics.md)
3. [Advanced Topics](03-advanced.md)
4. [Conclusion](04-conclusion.md)
---
전체 약 15,000 단어
예상 학습 시간: 2-3시간---
4. 뉴스 아티클 아카이브
시나리오
중요한 뉴스 기사를 날짜별로 아카이빙하고 싶습니다.
실행
You: 오늘자 중요한 기사들을 archive/2024/01/ 폴더에 저장해줘
- https://news.com/tech-breakthrough
- https://news.com/market-update
- https://news.com/policy-change
Claude: ✅ 저장 완료!
archive/2024/01/
├── 2024-01-15-tech-breakthrough.md
├── 2024-01-15-market-update.md
└── 2024-01-15-policy-change.md
날짜가 파일명에 자동으로 포함되었습니다.---
5. API 문서 로컬 복사
시나리오
자주 참고하는 API 문서를 로컬에 두고 빠르게 검색하고 싶습니다.
실행
You: Stripe API 문서의 주요 섹션들을 api-docs/stripe/ 폴더에 저장해줘
- https://stripe.com/docs/api/authentication
- https://stripe.com/docs/api/charges
- https://stripe.com/docs/api/customers
- https://stripe.com/docs/api/subscriptions
Claude: ✅ 완료!
api-docs/stripe/
├── authentication.md
├── charges.md
├── customers.md
└── subscriptions.md검색 활용
You: customers.md 파일에서 "create customer" 예제 찾아줘
Claude: [파일 검색 및 관련 섹션 표시]
## Create a Customer
const customer = await stripe.customers.create({ email: 'customer@example.com', source: 'tok_visa', });
---
6. GitHub README 수집
시나리오
유용한 오픈소스 프로젝트들의 README를 모아서 영감을 얻고 싶습니다.
실행
You: 이 프로젝트들의 README를 awesome-readmes 폴더에 저장해줘
- https://github.com/facebook/react
- https://github.com/vercel/next.js
- https://github.com/tailwindlabs/tailwindcss
Claude: ✅ 완료!
awesome-readmes/
├── react-README.md
├── nextjs-README.md
└── tailwindcss-README.md---
7. 레시피 웹사이트 저장
시나리오
좋아하는 요리 레시피를 마크다운으로 저장하여 개인 레시피북을 만들고 싶습니다.
실행
You: 이 레시피를 recipes/italian/ 폴더에 저장해줘
https://cooking.com/classic-carbonara
Claude: ✅ 저장 완료!
📄 recipes/italian/classic-carbonara.md
# Classic Carbonara
## 재료
- 스파게티 400g
- 판체타 200g
- 달걀 4개
- 파마산 치즈 100g
[...]
## 조리법
1. 물을 끓이고...
[...]---
8. 학술 논문 요약본
시나리오
arXiv 논문의 요약본을 저장하고 싶습니다.
실행
You: https://arxiv.org/abs/2301.12345 이 논문의 요약과 주요 내용만 추출해서 저장해줘
Claude: 논문의 abstract와 주요 섹션을 추출하겠습니다.
✅ 저장 완료!
papers/transformers-survey.md
제목: "A Survey of Transformer Architectures"
저자: Smith et al.
발행일: 2023-01-15
주요 내용:
- Abstract
- Introduction
- Key Contributions
- Conclusion---
9. 제품 문서 번역 준비
시나리오
영문 제품 문서를 번역하기 위해 먼저 마크다운으로 변환하고 싶습니다.
실행
You: https://product.com/docs/user-guide 이걸 마크다운으로 저장하고, 한국어로 번역 준비해줘
Claude: 먼저 마크다운으로 변환하겠습니다.
✅ user-guide.md 저장 완료!
번역 작업을 시작할까요?
You: 네, user-guide-ko.md로 번역해줘
Claude: [번역 진행...]
✅ user-guide-ko.md 생성 완료!---
10. 웹 포트폴리오 아카이빙
시나리오
영감을 주는 포트폴리오 사이트들의 "About" 페이지를 모으고 싶습니다.
실행
You: 이 디자이너들의 About 페이지를 inspiration/portfolios/ 폴더에 저장해줘
- https://designer1.com/about
- https://designer2.com/about
- https://designer3.com/about
Claude: ✅ 완료!
inspiration/portfolios/
├── designer1-about.md
├── designer2-about.md
└── designer3-about.md
각 파일에는 자기소개, 경력, 작업 철학이 포함되어 있습니다.---
11. AI 최적화 모드 - 기술 문서
시나리오
기술 문서를 AI 에이전트가 컨텍스트로 활용할 수 있도록 최적화하여 저장하고 싶습니다.
실행
You: https://react.dev/reference/react/useState 를 AI가 읽기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다.
구조화된 프론트매터와 명확한 섹션을 추가합니다.
✅ 저장 완료!
📄 docs/react-useState.context.md
📊 원본 3,500 토큰 → 최적화 2,100 토큰 (40% 절감)결과 미리보기
---
title: "useState - React Reference"
url: "https://react.dev/reference/react/useState"
author: "React Team"
date: "2024-01-15"
word_count: 1800
topics: ["React", "Hooks", "State Management", "Frontend"]
summary: |
useState는 컴포넌트에 상태 변수를 추가할 수 있는 React Hook입니다.
초기 상태를 인자로 받아 현재 상태와 setter 함수를 반환합니다.
main_points:
- 상태 변수와 setter 함수를 배열로 반환
- 초기 상태는 함수로도 전달 가능
- 상태 업데이트는 다음 렌더링에 반영
- 객체/배열 상태는 불변성 유지 필요
content_type: "documentation"
difficulty: "beginner"
---
# useState - React Reference
## 핵심 요약
useState는 함수형 컴포넌트에 상태를 추가하는 Hook입니다.
초기값을 받아 [상태, setter] 배열을 반환하며, setter 호출 시 리렌더링을 트리거합니다.
## 주요 내용
### 기본 사용법
**Syntax**:const [state, setState] = useState(initialState);
**Parameters**:
- `initialState`: 초기 상태값 (any type)
**Returns**: `[state, setState]`
- `state`: 현재 상태
- `setState`: 상태 업데이트 함수
### 상태 업데이트
**직접 업데이트**:setState(newValue);
**함수형 업데이트**:setState(prev => prev + 1);
## 핵심 인사이트
- **초기화는 한 번만**: 초기 상태는 첫 렌더링에서만 사용
- **비동기 업데이트**: setState는 즉시 반영되지 않음
- **불변성 유지**: 객체/배열은 새로운 참조로 업데이트
- **함수형 업데이트**: 이전 상태 기반 업데이트 시 필수
## 실용적 적용
**카운터 예제**:function Counter() { const [count, setCount] = useState(0); return <button onClick={() => setCount(count + 1)}>{count}</button>; }
**입력 폼**:function Form() { const [text, setText] = useState(''); return <input value={text} onChange={e => setText(e.target.value)} />; }
## 결론
useState는 React의 가장 기본적이면서 중요한 Hook입니다.
상태 관리의 기초를 이해하면 더 복잡한 Hooks도 쉽게 활용할 수 있습니다.---
12. AI 최적화 모드 - 블로그 아티클
시나리오
기술 블로그 글을 AI가 학습하기 좋은 형태로 변환하고 싶습니다.
실행
You: https://blog.example.com/microservices-best-practices 를 컨텍스트로 사용하기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다.
✅ 저장 완료!
📄 knowledge-base/microservices-best-practices.context.md
📊 원본 4,200 토큰 → 최적화 2,500 토큰 (40% 절감)
프론트매터에 주제, 핵심 포인트, 난이도가 포함되어 있어
AI가 빠르게 문서의 맥락을 파악할 수 있습니다.결과 특징
- 프론트매터: 주제, 저자, 핵심 요약 포함
- 구조화: 명확한 섹션 구분 (H2/H3)
- 인사이트 추출: 저자의 주요 주장과 근거 정리
- 실용적 조언: 즉시 적용 가능한 팁 강조
- 노이즈 제거: 광고, 댓글, 네비게이션 완전 제거
---
13. AI 최적화 모드 - 여러 문서 일괄 처리
시나리오
여러 기술 문서를 AI 최적화 모드로 일괄 변환하여 지식 베이스를 구축하고 싶습니다.
실행
You: 이 문서들을 AI 학습용으로 변환해서 knowledge-base/react/ 폴더에 저장해줘
- https://react.dev/reference/react/useState
- https://react.dev/reference/react/useEffect
- https://react.dev/reference/react/useContext
- https://react.dev/reference/react/useReducer
- https://react.dev/reference/react/useMemo
Claude: 5개 문서를 AI 최적화 모드로 변환하겠습니다.
[변환 중...]
✅ 완료!
knowledge-base/react/
├── useState.context.md
├── useEffect.context.md
├── useContext.context.md
├── useReducer.context.md
└── useMemo.context.md
총 5개 파일
원본: 약 18,000 토큰
최적화: 약 10,500 토큰 (42% 절감)
각 파일에는:
- 구조화된 프론트매터
- 핵심 요약 (3-5줄)
- 명확한 API 레퍼런스
- 실전 예제
- 주요 인사이트활용 방법
User: useState와 useReducer의 차이점을 알려줘
AI Agent:
[knowledge-base/react/useState.context.md 읽기]
[knowledge-base/react/useReducer.context.md 읽기]
프론트매터를 통해 빠르게 각 Hook의 용도를 파악했습니다:
- useState: 단순 상태 관리
- useReducer: 복잡한 상태 로직
주요 차이점:
1. [구조화된 문서에서 추출한 정확한 정보]
2. [...]---
14. AI 최적화 모드 - RAG 시스템 구축
시나리오
AI 에이전트가 참고할 수 있는 RAG (Retrieval-Augmented Generation) 시스템을 구축하고 싶습니다.
실행
You: 우리 프로젝트 관련 문서들을 AI 최적화 모드로 변환해줘
- 내부 API 문서 20개
- 기술 블로그 15개
- 공식 라이브러리 문서 10개
Claude: 총 45개 문서를 AI 최적화 모드로 변환하겠습니다.
[변환 진행...]
✅ 완료!
rag-knowledge-base/
├── api-docs/ (20 files)
├── blog-posts/ (15 files)
└── library-docs/ (10 files)
모든 파일은 .context.md 확장자로 저장되었으며,
프론트매터의 topics 필드로 자동 분류 가능합니다.시스템 구조
1. 문서 변환 (AI 최적화 모드)
↓
2. 프론트매터에서 topics 추출
↓
3. 벡터 데이터베이스에 인덱싱
↓
4. 사용자 질문 시 관련 문서 검색
↓
5. 구조화된 섹션에서 정확한 정보 추출
↓
6. AI 에이전트가 답변 생성장점
- 빠른 검색: 프론트매터의 topics로 즉시 필터링
- 정확한 추출: 명확한 H2/H3 구조로 특정 정보 찾기 쉬움
- 토큰 절감: 필요한 섹션만 컨텍스트에 포함
- 일관성: 모든 문서가 동일한 구조로 통일
---
15. AI 최적화 모드 - 비교 분석
시나리오
두 가지 기술이나 접근법을 비교 분석하기 위해 문서를 최적화하여 저장합니다.
실행
You: React와 Vue의 상태 관리를 비교하고 싶어. 관련 문서들을 AI 최적화 모드로 변환해줘
- https://react.dev/learn/managing-state
- https://vuejs.org/guide/essentials/reactivity-fundamentals.html
Claude: 2개 문서를 AI 최적화 모드로 변환하겠습니다.
✅ 완료!
comparisons/state-management/
├── react-state.context.md
└── vue-reactivity.context.md
이제 AI가 두 문서의 프론트매터와 핵심 요약을 읽고
빠르게 차이점을 분석할 수 있습니다.AI 분석 예시
AI Agent가 두 .context.md 파일을 읽고:
1. 프론트매터에서 주제 확인:
- React: ["state", "hooks", "immutability"]
- Vue: ["reactivity", "ref", "reactive"]
2. 핵심 요약 비교:
- React: 불변성 기반, 명시적 상태 업데이트
- Vue: 반응성 시스템, 자동 추적
3. 핵심 인사이트 추출:
- React: "상태는 불변 객체로 관리"
- Vue: "ref/reactive로 반응성 자동 생성"
4. 비교 결과 생성:
[상세한 비교 분석...]---
16. 듀얼 모드 - 원본 + AI 최적화 동시 생성 ⭐⭐
시나리오
웹페이지를 사람이 읽을 원본과 AI가 활용할 최적화 버전 모두 필요합니다.
실행
You: https://react.dev/reference/react/useState 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
[1단계: 원본 마크다운 변환 중...]
✅ useState.md 생성 완료
[2단계: AI 최적화 버전 변환 중...]
✅ useState.context.md 생성 완료
✅ 듀얼 모드 변환 완료! 2개 파일이 생성되었습니다.
📄 원본 마크다운:
- 파일: useState.md
- 크기: 약 3,500 글자
- 용도: 사람이 읽기 좋은 원본 보존
- 특징: 모든 내용 포함, 원본 구조 유지
[View file](computer:///path/to/useState.md)
📄 AI 최적화 버전:
- 파일: useState.context.md
- 크기: 약 2,100 글자 (40% 절감)
- 용도: AI 컨텍스트로 활용
- 특징: 구조화된 프론트매터, 핵심 요약, 명확한 섹션
[View file](computer:///path/to/useState.context.md)
💡 팁:
- 원본(.md)은 사람이 읽을 때 사용
- AI 최적화(.context.md)는 RAG 시스템이나 AI 에이전트 컨텍스트로 사용파일 비교
useState.md (원본)
# useState
useState is a React Hook that lets you add a state variable to your component.
const [state, setState] = useState(initialState)
## Reference
### useState(initialState)
Call useState at the top level of your component to declare a state variable.
[... 전체 내용, 모든 섹션 포함 ...]useState.context.md (AI 최적화)
---
title: "useState - React Reference"
url: "https://react.dev/reference/react/useState"
topics: ["React", "Hooks", "State Management"]
summary: |
useState는 컴포넌트에 상태를 추가하는 React Hook.
초기값을 받아 [상태, setter] 배열을 반환.
main_points:
- 상태와 setter 함수를 배열로 반환
- 초기 상태는 첫 렌더링에서만 사용
- 상태 업데이트는 비동기 처리
content_type: "documentation"
difficulty: "beginner"
---
# useState - React Reference
## 핵심 요약
useState는 함수형 컴포넌트에 상태를 추가하는 Hook입니다.
초기값을 받아 [상태, setter] 배열을 반환하며, setter 호출 시 리렌더링을 트리거합니다.
## 주요 내용
### 기본 사용법
[핵심만 간결하게...]
## 핵심 인사이트
[...]---
17. 듀얼 모드 - 여러 문서 일괄 처리
시나리오
여러 기술 문서를 원본과 AI 최적화 버전 모두 생성하고 싶습니다.
실행
You: 이 React Hooks 문서들 전부 원본이랑 AI 최적화 버전 둘 다 만들어줘
- https://react.dev/reference/react/useState
- https://react.dev/reference/react/useEffect
- https://react.dev/reference/react/useContext
Claude: 듀얼 모드로 3개 문서를 변환하겠습니다.
총 6개 파일이 생성됩니다.
[변환 중...]
✅ 완료!
docs/react-hooks/
├── useState.md (3,500 글자)
├── useState.context.md (2,100 글자)
├── useEffect.md (4,200 글자)
├── useEffect.context.md (2,500 글자)
├── useContext.md (3,800 글자)
└── useContext.context.md (2,300 글자)
통계:
- 원본 파일: 11,500 글자
- AI 최적화: 6,900 글자 (40% 절감)
- 총 6개 파일활용 방법
# 사람이 학습할 때
You: useState에 대해 자세히 알려줘
Claude: [useState.md 파일을 읽음]
useState에 대한 전체 설명입니다...
[원본의 모든 내용 제공]
# AI에게 질문할 때
You: useState와 useReducer의 차이점을 비교해줘
Claude: [useState.context.md와 useReducer.context.md 읽음]
프론트매터를 통해 빠르게 각 Hook의 핵심을 파악했습니다:
- useState: 단순 상태 관리, 초기값 직접 설정
- useReducer: 복잡한 상태 로직, reducer 함수로 관리
주요 차이점:
1. [구조화된 문서에서 추출한 정확한 정보]
2. [...]
원본 파일보다 60% 빠르게 답변 생성 (토큰 절감 효과)---
18. 듀얼 모드 - 폴더 구조 분리
시나리오
원본과 AI 최적화 버전을 폴더로 명확히 구분하고 싶습니다.
실행
You: 이 문서들을 원본은 docs/original/ 폴더에, AI 최적화는 docs/optimized/ 폴더에 저장해줘
- https://example.com/guide1
- https://example.com/guide2
- https://example.com/guide3
Claude: 듀얼 모드로 폴더 구조를 분리하여 저장하겠습니다.
✅ 완료!
docs/
├── original/
│ ├── guide1.md
│ ├── guide2.md
│ └── guide3.md
└── optimized/
├── guide1.md
├── guide2.md
└── guide3.md
이제 용도에 따라 폴더를 선택하여 사용하세요:
- original/: 사람이 읽을 때
- optimized/: AI가 처리할 때장점
- 명확한 구분
- 파일명 충돌 없음
- 관리 용이
---
19. 듀얼 모드 - 블로그 글 아카이빙
시나리오
자신의 블로그 글을 백업하면서 나중에 AI에게 질문할 수 있도록 준비합니다.
실행
You: 내 블로그 글 전체를 백업하는데, 나중에 내가 다시 읽을 용도랑 AI에게 물어볼 용도로 둘 다 만들어줘
- https://myblog.com/post1
- https://myblog.com/post2
- https://myblog.com/post3
[... 총 50개 글]
Claude: 듀얼 모드로 50개 블로그 글을 변환하겠습니다.
[변환 중... 1/50]
[변환 중... 2/50]
...
[변환 중... 50/50]
✅ 완료!
blog-archive/
├── for-reading/ # 사람이 읽을 원본
│ ├── 2024-01-15-post1.md
│ ├── 2024-01-20-post2.md
│ └── ... (50개)
└── for-ai/ # AI 질문 답변용
├── 2024-01-15-post1.context.md
├── 2024-01-20-post2.context.md
└── ... (50개)
총 100개 파일
- 원본: 약 250,000 글자
- AI 최적화: 약 150,000 글자 (40% 절감)활용 예시
3개월 후...
You: 내가 예전에 React Hooks에 대해 뭐라고 썼더라?
AI: [blog-archive/for-ai/ 폴더의 .context.md 파일들 검색]
프론트매터의 topics 필드에서 "React Hooks"를 찾았습니다.
2024-03-10-understanding-react-hooks.context.md
핵심 내용:
- useState의 기본 개념
- useEffect 활용 사례
- Custom Hooks 작성법
전체 글을 읽으시려면:
[View original](blog-archive/for-reading/2024-03-10-understanding-react-hooks.md)---
20. 듀얼 모드 - RAG 시스템 + 사람 문서 동시 구축
시나리오
회사 내부 지식 베이스를 구축하는데, 직원들이 읽을 문서와 AI 시스템용 문서를 동시에 준비합니다.
실행
You: 회사 문서들을 직원용과 AI 시스템용으로 둘 다 만들어줘
- 내부 API 문서 (20개)
- 프로세스 가이드 (15개)
- 기술 스택 문서 (10개)
Claude: 듀얼 모드로 45개 문서를 변환하겠습니다.
[변환 진행...]
✅ 완료!
company-knowledge-base/
├── employee-docs/ # 직원들이 읽을 문서
│ ├── api/
│ │ ├── user-api.md
│ │ └── ... (20개)
│ ├── process/
│ │ └── ... (15개)
│ └── tech-stack/
│ └── ... (10개)
└── ai-system/ # RAG 시스템용
├── api/
│ ├── user-api.context.md
│ └── ... (20개)
├── process/
│ └── ... (15개)
└── tech-stack/
└── ... (10개)시스템 통합
[직원이 사용할 때]
내부 포털 → employee-docs/ 폴더 → 사람이 읽기 편한 원본
[AI 챗봇이 답변할 때]
직원 질문 → RAG 시스템 → ai-system/ 폴더의 .context.md 파일들 검색
→ 프론트매터로 빠른 필터링 → 관련 섹션만 추출 → 답변 생성
효과:
- 토큰 비용 40% 절감
- 답변 속도 2배 향상
- 정확도 30% 개선 (구조화된 데이터)---
고급 활용 팁
1. 배치 처리 스크립트
You: urls.txt 파일에 있는 모든 URL을 마크다운으로 변환해줘
Claude: [파일 읽기 → 각 URL 변환 → 저장]
✅ 25개 URL 변환 완료!2. 정기 백업
You: 매주 월요일마다 이 URL들을 weekly-backups 폴더에 날짜별로 저장해줘
[자동화 설정]3. 컨텐츠 비교
You: 이 두 버전의 문서를 비교해줘
- https://docs.com/v1/guide (현재 v1-guide.md)
- https://docs.com/v2/guide
Claude: [v2 변환 → diff 비교 → 변경사항 요약]---
팁 모음
1. 폴더 구조화: 주제별로 폴더를 만들어 체계적으로 관리 2. 일관된 파일명: 규칙적인 네이밍 컨벤션 사용 3. 메타데이터 추가: 프론트매터에 URL, 날짜, 태그 포함 4. 정기 업데이트: 중요한 문서는 주기적으로 재변환 5. 백업: 변환한 파일들을 git으로 버전 관리
---
이 예제들을 참고하여 자신만의 활용법을 찾아보세요!
Quick Start Guide - Web to Markdown
웹페이지를 마크다운으로 변환하는 가장 빠른 방법을 알려드립니다.
5초 만에 시작하기
1. 단일 페이지 변환
You: https://example.com/article 이거 마크다운으로 저장해줘
Claude: 파일명을 어떻게 할까요? (기본: webpage.md)
You: article.md
Claude: ✅ 완료!
📄 article.md 파일이 생성되었습니다.2. 빠른 변환 (파일명 생략)
You: https://docs.python.org/tutorial 를 python-tutorial.md로 저장해줘
Claude: [바로 변환 및 저장]
✅ python-tutorial.md 파일이 생성되었습니다.3. 내용만 보기
You: https://blog.example.com/post 내용을 마크다운으로 보여줘만
Claude: [마크다운 내용을 화면에 출력, 파일로 저장 안 함]자주 사용하는 패턴
여러 페이지 한 번에
You: 이 URL들을 docs 폴더에 마크다운으로 저장해줘
- https://example.com/guide1
- https://example.com/guide2
- https://example.com/guide3
Claude: [docs 폴더 생성 및 각 페이지를 guide1.md, guide2.md, guide3.md로 저장]특정 섹션만 추출
You: https://example.com/docs 에서 "설치 가이드" 부분만 마크다운으로 저장해줘
Claude: [해당 섹션만 추출하여 저장]자동 파일명
You: https://example.com/blog/awesome-article 이거 적당한 파일명으로 저장해줘
Claude: [페이지 제목을 기반으로 자동 파일명 생성]
✅ awesome-article.md 파일이 생성되었습니다.실전 예제
예제 1: 기술 문서 아카이브
You: 이 기술 문서들을 tech-docs 폴더에 저장해줘
- https://react.dev/learn
- https://nextjs.org/docs
- https://tailwindcss.com/docs
Claude: [tech-docs 폴더 생성]
Claude: [3개 파일 변환 및 저장]
✅ 3개의 문서가 tech-docs 폴더에 저장되었습니다:
- react-learn.md
- nextjs-docs.md
- tailwindcss-docs.md예제 2: 블로그 포스트 백업
You: 내 블로그 글 https://myblog.com/posts/2024/my-post 를 백업해줘
Claude: 어디에 저장할까요?
You: backup/blog/ 폴더에 날짜 포함해서
Claude: ✅ 저장 완료!
📄 backup/blog/2024-01-15-my-post.md예제 3: 튜토리얼 컬렉션
You: 파이썬 튜토리얼 시리즈를 전부 마크다운으로 저장해줘
- https://tutorial.com/python/basics
- https://tutorial.com/python/intermediate
- https://tutorial.com/python/advanced
Claude: tutorials/python/ 폴더에 저장하겠습니다.
✅ 저장 완료!
tutorials/python/
├── basics.md
├── intermediate.md
└── advanced.mdPro Tips
1. URL만 붙여넣기: URL만 입력해도 Claude가 알아서 처리합니다
You: https://example.com/article2. 파일명에 경로 포함: 원하는 폴더를 파일명에 포함시키세요
You: docs/guide.md로 저장해줘3. 여러 URL 한 번에: 줄바꿈으로 구분하여 여러 URL 입력
You: 이것들 전부 마크다운으로
https://url1.com
https://url2.com
https://url3.com4. 빠른 미리보기: 저장 여부를 나중에 결정
You: https://example.com 먼저 보여줘
[내용 확인 후]
You: 이거 article.md로 저장해줘트러블슈팅
문제: URL이 열리지 않음
해결: URL 전체를 복사했는지 확인 (https:// 포함)
문제: 이상한 내용이 저장됨
해결: "주요 내용만 추출해서 다시 저장해줘" 요청
문제: 파일이 너무 큼
해결: "요약해서 저장해줘" 또는 "특정 섹션만 저장해줘" 요청
다음 단계
더 자세한 내용은 다음 문서를 참고하세요:
SKILL.md: 전체 워크플로우 및 고급 기능README.md: 개요 및 활용 예시EXAMPLES.md: 다양한 실전 예제
---
준비 완료! 이제 웹페이지 URL을 입력하고 마크다운으로 변환해보세요.
Web to Markdown Converter
웹페이지를 마크다운 형식으로 변환하여 저장하는 Claude 스킬입니다.
개요
이 스킬은 웹페이지 URL을 입력받아 해당 페이지의 HTML 콘텐츠를 깔끔한 마크다운 형식으로 변환합니다. 블로그 글, 기술 문서, 튜토리얼 등을 로컬에 아카이빙하고 싶을 때 유용합니다.
주요 기능
- 간단한 변환: URL만 입력하면 자동으로 마크다운 변환
- 스마트 정리: 불필요한 네비게이션, 광고 등 자동 제거
- 캐싱: 같은 URL을 반복 요청해도 빠른 응답
- 일괄 처리: 여러 URL을 한 번에 변환 가능
- 커스터마이징: 특정 섹션만 추출하거나 포맷 지정 가능
- AI 최적화 모드 ⭐: AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환
- 듀얼 모드 ⭐⭐ NEW: 원본 + AI 최적화 버전 2개 파일 동시 생성
사용 방법
기본 사용
User: https://example.com/article 이거 마크다운으로 저장해줘
Claude: 파일명을 어떻게 할까요? (기본: webpage.md)
User: article.md
Claude: ✅ 웹페이지를 마크다운으로 변환했습니다!여러 페이지 일괄 변환
User: 이 URL들을 전부 마크다운으로 저장해줘
- https://example.com/doc1
- https://example.com/doc2
- https://example.com/doc3내용만 보기 (저장 안 함)
User: https://example.com 내용을 마크다운으로 보여줘만 하고 저장은 하지마AI 최적화 모드 ⭐ NEW
AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환합니다.
User: https://react.dev/reference/react/useState 를 AI가 읽기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다.
구조화된 프론트매터, 핵심 요약, 명확한 섹션을 추가합니다.
✅ 저장 완료!
📄 react-useState.context.md
📊 원본 3,500 토큰 → 최적화 2,100 토큰 (40% 절감)AI 최적화 모드의 특징:
- 📋 구조화된 메타데이터: YAML 프론트매터 (제목, 주제, 요약, 난이도)
- 🎯 핵심 요약: 3-5줄로 빠른 이해 가능
- 📚 명확한 계층: H2/H3 섹션으로 탐색 용이
- 💡 인사이트 추출: 핵심 포인트 bullet points로 정리
- 🚀 토큰 절감: 불필요한 요소 제거로 30-50% 절감
- 🔍 검색 최적화: topics 기반 분류 가능
활용 사례:
- RAG (Retrieval-Augmented Generation) 시스템 구축
- AI 에이전트 학습 자료 준비
- 지식 베이스 구축
- 문서 비교 분석
자세한 내용: AI_OPTIMIZATION.md 참고
듀얼 모드 ⭐⭐ NEW
원본 마크다운과 AI 최적화 버전을 동시에 생성합니다.
User: https://react.dev/reference/react/useState 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
[원본 변환 중...]
[AI 최적화 변환 중...]
✅ 듀얼 모드 변환 완료! 2개 파일이 생성되었습니다.
📄 원본 마크다운:
- 파일: useState.md
- 크기: 약 3,500 글자
- 용도: 사람이 읽기 좋은 원본 보존
📄 AI 최적화 버전:
- 파일: useState.context.md
- 크기: 약 2,100 글자 (40% 절감)
- 용도: AI 컨텍스트로 활용
💡 팁:
- 원본(.md)은 사람이 읽을 때
- AI 최적화(.context.md)는 RAG 시스템이나 AI 컨텍스트로듀얼 모드의 장점:
- 🎯 용도별 최적화: 사람용 vs AI용 동시 확보
- 💾 원본 보존: 원본 그대로 백업
- 🚀 토큰 절감: AI용은 40% 토큰 절감
- 🔄 비교 가능: 두 버전 비교 분석 가능
- ⚡ 한 번에 처리: 2번 요청할 필요 없음
활용 시나리오:
- 기술 문서를 사람도 읽고 AI도 활용할 때
- 백업과 AI 학습을 동시에 하고 싶을 때
- 원본 충실도와 AI 효율성을 모두 원할 때
활성화 키워드
다음과 같은 요청에 자동으로 활성화됩니다:
일반 모드:
- "웹페이지를 마크다운으로 변환해줘"
- "이 URL을 마크다운으로 저장해줘"
- "웹사이트 내용을 마크다운 파일로 만들어줘"
- "웹페이지 아카이빙해줘"
- "블로그 글을 마크다운으로 저장해줘"
AI 최적화 모드:
- "AI가 읽기 좋게 변환해줘"
- "컨텍스트로 사용하기 좋게 변환해줘"
- "AI 학습용으로 변환해줘"
- "RAG 시스템용으로 변환해줘"
듀얼 모드:
- "원본이랑 AI 최적화 버전 둘 다 만들어줘"
- "원본도 저장하고 AI용도 만들어줘"
- "2개 버전으로 저장해줘"
- "사람용이랑 AI용 둘 다"
변환되는 요소
포함되는 요소
- 제목 (H1-H6)
- 본문 텍스트
- 링크
- 이미지 (URL 링크로)
- 리스트
- 코드 블록
- 인용구
- 테이블
제외되는 요소
- 네비게이션 메뉴
- 푸터
- 광고
- 사이드바 (대부분의 경우)
제한사항
- JavaScript로 동적 렌더링되는 콘텐츠는 포함되지 않을 수 있습니다
- 이미지는 다운로드되지 않고 원본 URL 링크로 저장됩니다
- 매우 긴 문서는 요약될 수 있습니다
- 접근 권한이 필요한 페이지는 변환할 수 없습니다
활용 예시
일반 모드
1. 기술 문서 아카이빙
프로젝트에 필요한 공식 문서들을 로컬에 저장하여 오프라인에서도 참고2. 블로그 글 백업
중요한 블로그 글을 마크다운으로 저장하여 개인 아카이브 구축3. 학습 자료 정리
온라인 튜토리얼이나 가이드를 마크다운으로 변환하여 학습 노트에 통합4. 콘텐츠 마이그레이션
다른 플랫폼의 콘텐츠를 마크다운으로 변환하여 새 시스템에 이전AI 최적화 모드 ⭐
5. RAG 시스템 구축
AI 에이전트가 참고할 수 있는 지식 베이스를 구조화된 형태로 구축
- 45개 문서를 AI 최적화 모드로 변환
- 프론트매터의 topics로 자동 분류
- 토큰 40% 절감으로 비용 효율적6. AI 에이전트 학습 자료
기술 문서를 AI가 빠르게 이해할 수 있는 형태로 변환
- 핵심 요약으로 3초 내 파악
- 명확한 섹션 구조로 특정 정보 쉽게 추출
- 인사이트 정리로 best practices 학습7. 지식 베이스 관리
topics 기반으로 문서를 자동 분류하고 검색 최적화
- 프론트매터 메타데이터로 필터링
- content_type과 difficulty로 적절한 문서 선택
- 일관된 구조로 유지보수 용이8. 문서 비교 분석
여러 기술이나 접근법을 AI가 체계적으로 비교
- 구조화된 포맷으로 공정한 비교
- 핵심 인사이트로 차이점 명확히
- 실용적 적용 섹션으로 선택 기준 제시기술 스택
- WebFetch: Claude의 웹 페이지 가져오기 도구 (HTML → 마크다운 자동 변환)
- Write: 파일 저장 도구
- 캐싱: 15분 자가 정리 캐시
팁
1. 명확한 파일명: 나중에 찾기 쉽도록 의미 있는 파일명 사용 2. 폴더 정리: 주제별로 폴더를 만들어 체계적으로 관리 3. 저작권 주의: 변환한 콘텐츠는 개인적인 용도로만 사용 4. 정기 백업: 중요한 온라인 리소스는 주기적으로 백업
문제 해결
URL 오류
- URL이
http://또는https://로 시작하는지 확인 - 전체 URL을 복사했는지 확인
접근 불가
- 페이지가 여전히 존재하는지 확인
- 로그인이 필요한 페이지는 변환할 수 없음
- VPN이나 방화벽이 차단하고 있지 않은지 확인
저장 실패
- 파일 경로에 쓰기 권한이 있는지 확인
- 디렉토리가 존재하는지 확인
- 파일명에 특수문자가 있는지 확인
라이선스
이 스킬은 Claude Code의 일부로, 개인적 및 교육적 용도로 자유롭게 사용할 수 있습니다.
피드백
문제나 개선 아이디어가 있으시면 언제든지 공유해주세요!
Claude Code Best Practices: Comprehensive Guide
Core Summary
This guide distills best practices from 12 expert sources on using Claude Code for production-quality development. Success hinges on three pillars: obsessive context management, mandatory planning before implementation, and architectural simplicity. The guide provides actionable recommendations organized by priority level, complete with workflows, anti-patterns to avoid, and metrics for measuring success.
The Three Critical Takeaways
1. Context Management is Paramount
The most successful Claude Code workflows obsessively manage context through:
- CLAUDE.md files (100-200 lines maximum) documenting project-specific rules and command references
- Aggressive clearing at 60k tokens or 30% context threshold
- Documentation systems using plan.md, context.md, and tasks.md structure
- Token-efficient tool design keeping baseline context under 20k tokens
"Context degradation is the primary failure mode" across production deployments.
2. Planning Before Implementation is Non-Negotiable
Eight sources emphasize upfront planning for production code:
- Use Planning Mode to research codebase and propose approaches
- Create written development docs before implementation
- Challenge assumptions and request alternative approaches
- Document decisions in version-controlled planning files
- "Vibe coding" works only for throwaway MVPs, not production systems
3. Simplicity Beats Complexity
"Simple control loops outperform multi-agent systems. Low-level tools plus selective abstractions beat heavy RAG or complex frameworks."
The Claude Code architecture itself uses:
- One main thread (flat message list)
- Maximum one branching point (subagent results)
- LLM search via ripgrep/jq rather than RAG
- Minimal, purposeful tool abstraction
Essential Practices (Implement First)
Create CLAUDE.md (100-200 lines max)
Structure the file as:
- Root CLAUDE.md: Critical universal rules, command reference, testing instructions, repository etiquette
- Subdirectory CLAUDE.md: Project-specific context (50-100 lines each)
Anti-patterns to avoid:
- Don't embed entire files with @-mentions; instead reference documentation paths
- Don't write negative prescriptions ("Never use X flag"); suggest positive alternatives
- Don't create comprehensive manuals; document what Claude gets wrong
Token efficiency: One team reports 20k baseline tokens (10% of 200k context) with strategic CLAUDE.md structure.
Aggressive Context Clearing
Clear context at:
- 60k tokens, or
- 30% of available context
Use the /clear + /catchup pattern for simple restarts. For complex tasks, implement "Document & Clear": 1. Have Claude write progress to .md file 2. Execute /clear 3. Start fresh session reading the progress file 4. Continue work
"Don't use /compact; it's opaque, error-prone, and not well-optimized" for preserving important details.
Test-Driven Development Pattern
The consensus workflow: 1. Write tests BEFORE implementation 2. Confirm tests fail (avoid mock implementations) 3. Commit tests separately 4. Implement until tests pass 5. Do NOT modify tests during implementation
"AI-generated code often works superficially but contains subtle bugs. Tests provide the only reliable validation mechanism."
Planning Workflow (Explore → Plan → Code → Commit)
Step 1: Explore - Tell Claude NOT to code yet; read relevant files, existing patterns, images, URLs Step 2: Plan - Use Planning Mode, research details, verify architecture, create written plan Step 3: Code - Implement with explicit verification steps, commit in stages Step 4: Commit - Update documentation, create PR with clear commit messages
"Steps 1-2 are crucial—without them, Claude tends to jump straight to coding."
Be Specific in Instructions
Bad: "Add a user settings page"
Good: "Create user settings page at /settings with profile section (name, email, avatar), notification preferences (checkboxes), using UserProfile component pattern, MUI v7 grid layout, and form validation tests"
High-Impact Practices to Implement Soon
Dev Docs System
Use the three-file pattern for each feature:
~/dev/active/[task-name]/
├── [task-name]-plan.md # Accepted plan
├── [task-name]-context.md # Key files, decisions
└── [task-name]-tasks.md # Work checklistUpdate the plan document during implementation to reveal changed requirements and enable fresh conversations to resume exactly where you left off.
Skills with Auto-Activation Hooks
Manual skills are ignored ~90% of the time. The solution: hook-based auto-activation via:
UserPromptSubmit Hook (before Claude sees message):
- Analyze prompt for keywords/intent
- Inject skill activation reminders
- Claude sees recommendation before processing
Stop Event Hook (after response):
- Analyze edited files for risky patterns
- Display gentle self-check reminders
- Non-blocking awareness cues
Skill structure best practices:
- Main SKILL.md: Under 500 lines
- Use progressive disclosure with resource files
- Token efficiency improved 40-60% after restructuring
Quality Gate Hooks
Implement non-blocking hooks for:
- Build checker (TypeScript/linter errors)
- Test runner (ensure passing tests)
- Error handling reminder
- Skills auto-activation
Strategy: "Don't block at write time—let the agent finish its plan, then check the final result."
Continuous Quality Gates
Enforce quality automatically with:
- TypeScript/linter checks after every edit
- Build validation before commits
- Test execution on file changes
- Manual formatting between sessions (avoid auto-formatting hooks; they consume 160k tokens in 3 rounds)
Code Review (Self + Human)
Multi-layer review process: 1. Claude self-review: Ask Claude to review its own code using subagents or fresh context 2. Human review: Manually verify behavior and test coverage 3. Multiple Claude instances: One writes, another reviews with fresh context
Look for: spaghetti code, substantial API changes, unnecessary imports, missing error handling, security issues.
Advanced Patterns
Git Worktrees for Parallel Work
Run multiple Claude instances on independent tasks:
git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude
# In new terminal:
git worktree add ../project-feature-b feature-b
cd ../project-feature-b && claudeBest practices: consistent naming, one terminal per worktree, notifications for attention needed, separate IDE windows, clean up afterward.
Multi-Claude Verification Pipeline
Separate contexts for writing and reviewing: 1. Claude A writes code 2. /clear or start Claude B in new terminal 3. Claude B reviews Claude A's work 4. /clear or start Claude C 5. Claude C reads code and review, edits based on feedback
Advanced: o3 + Sonnet pipeline for critical code:
- o3: Generate plan
- Sonnet 4: Verify plan, create task list
- Sonnet 3.7/4: Execute plan
- Sonnet 4: Verify against plan
- o3: Verify against original ask
- Feed issues back into plan template
Subagent Delegation Strategy
Two competing approaches:
Custom Specialized Subagents:
- code-architecture-reviewer
- build-error-resolver
- strategic-plan-architect
Master-Clone Architecture (preferred):
- Put all context in CLAUDE.md
- Let main agent use Task(...) to spawn clones
- Agent manages orchestration dynamically
- Preserves context better, more flexible
Resolution: Start with clone pattern for most tasks. Use specialized subagents only for highly specific, narrow tasks.
Common Tools & Optimization
Recommended Slash Commands
Planning/Docs:
/dev-docs- Create strategic plan/catchup- Read changed files in branch/create-dev-docs- Convert plan to dev doc files
Quality:
/code-review- Architectural review/build-and-fix- Run builds and fix errors
Testing:
/test-route- Test authenticated routes/route-research-for-testing- Find affected routes
Git Integration:
/pr- Clean up code, prepare PR with commit message
Philosophy: "If you have a long list of complex custom commands, you've created an anti-pattern. The entire point is to type almost whatever you want and get useful results."
MCP Strategy: "Scripting Model"
Heavy MCP usage is an anti-pattern. If using >20k tokens of MCPs, "you're crippling Claude, giving you only 20k tokens left of actual work before context is cooked."
Better approach:
- Few powerful gateway tools (download_raw_data, take_sensitive_action, execute_code)
- MCP handles auth/security, agent scripts against data
- Most stateless tools → Simple CLIs documented in Skills
- MCPs only for stateful environments (e.g., Playwright)
Error Handling Standards
try {
await prismaOperation()
} catch (error) {
Sentry.captureException(error) // Must capture
throw new CustomError('Descriptive message', { context }) // Include context
}Philosophy: "Fail fast with descriptive messages. Never silently swallow exceptions."
Key Contradictions & Trade-Offs
Skills Volume vs Context Efficiency
More skills approach: Multiple specialized skills (frontend, backend, workflow, notification guidelines)
Minimal skills approach: Keep skills under 100 lines total
Resolution: Progressive disclosure (main <500 lines + resource files). Token budget determines skill count. Measure baseline context usage and adjust accordingly.
Auto-Formatting Hooks
Original recommendation: Auto-format after edits for consistency
Updated consensus: Don't auto-format in hooks—they consume excessive tokens (160k reported in 3 rounds)
Better practice: Run Prettier manually between sessions
Planning Mode vs Manual Plans
Built-in Planning Mode: Better codebase research, structured output
Custom planning with slash commands: More control, can see agent output while planning
Resolution: Use Planning Mode for research phase, then exit and create manual dev docs from results. Use custom slash commands for plan refinement. This combines benefits of both approaches.
Architecture & Design Principles
Simple Control Loops > Multi-Agent Systems
"Debuggability >> complicated hand-tuned multi-agent lang-chain-graph-node mishmash"
Claude Code architecture:
- One main thread (flat message list)
- Maximum one branch (subagent results)
- No complex multi-agent orchestration
- Simple iterative tool calling
Reasoning: Every abstraction layer makes debugging exponentially harder. LLMs are fragile; added complexity breaks unpredictably.
LLM Search > RAG for Code
Claude Code uses complex ripgrep, jq, find commands rather than RAG.
RAG introduces hidden failure modes:
- What similarity function?
- What reranker?
- How to chunk code?
- How to handle large JSON/logs?
LLM search:
- Examines 10 lines to understand structure
- Requests 10 more if needed (like humans)
- Reinforcement-learnable
- Model does heavy lifting, fewer moving parts
Tool Abstraction Strategy
Strategic mix:
- Low-level (Bash, Read, Write): Flexibility
- Medium-level (Edit, Grep, Glob): Frequently used patterns
- High-level (Task, WebFetch): Deterministic workflows
Decision framework: High-frequency tasks → Dedicated tools. Low-frequency → Use Bash. Highly deterministic → High-level tools.
Production Code Quality Standards
Testing Checklist
1. Parameterize inputs (no magic numbers/strings) 2. Add test only if it can fail for real defect 3. Ensure description matches assertion 4. Compare to independent expectations, not function output 5. Follow same lint/type-safety as production code 6. Express invariants/axioms (use fast-check for property tests) 7. Group unit tests under describe(functionName) 8. Use expect.any(...) for variable parameters 9. Use strong assertions (toEqual vs toBeGreaterThanOrEqual) 10. Test edge cases, realistic input, boundaries 11. Don't test conditions caught by type checker
Test types:
- Unit tests: Colocated *.spec.ts
- Integration tests: Separate from unit tests (don't mock DB)
- Property-based tests: Use fast-check for invariants
Type Safety Practices
// Prefer branded types for IDs
type UserId = Brand<string, 'UserId'> // ✅
type UserId = string // ❌
// Use import type for type-only imports
import type { User } from './types' // ✅
// Override incorrect generated types in db-types.override.ts
export interface CustomOverride {
bigIntField: string; // Override BigInt → string
}Visual References for UI Work
Methods:
- Paste screenshots (macOS: cmd+ctrl+shift+4 → ctrl+v)
- Drag and drop images
- Provide image file paths
- Use design mocks as reference
Iteration pattern: 1. Give Claude visual mock 2. Implement in code 3. Take screenshot of result 4. Compare and iterate 5. Usually 2-3 iterations for good match
Quick-Start Workflow (4-Week Ramp-Up)
Week 1: Foundations
- Create CLAUDE.md with commands and testing instructions
- Practice Planning Mode → review → implement → commit
- Start clearing context at 60k tokens
- Manually review all AI-generated code
Week 2: Quality Systems
- Set up TDD workflow
- Create 2-3 custom slash commands
- Implement basic build checker hook
- Add visual references to UI work
Week 3: Advanced Context
- Implement dev docs system
- Create 1-2 Skills for common patterns
- Add skill auto-activation hook
- Practice subagent code review
Week 4: Optimization
- Audit context usage with
/context - Optimize CLAUDE.md
- Add quality gate hooks
- Experiment with git worktrees
Success Metrics
Context Efficiency
- Baseline context cost: <20k tokens (10% of 200k)
- CLAUDE.md size: <2000 tokens
- MCP tools total: <20k tokens
- Context clearing: Every 60k tokens or less
Code Quality
- Test coverage: >80% for new code
- TypeScript errors: Zero before commits
- Code review findings: Track patterns, update CLAUDE.md
- Production bugs from AI code: Decreases over time
Productivity
- Time from plan to PR: Track and optimize
- Plan iterations: Should stabilize at 1-3
- Context compactions: Decrease with better practices
- Parallel tasks: Can scale to 3-4 with worktrees
Practices to Avoid
❌ Auto-formatting hooks (excessive token consumption) ❌ Heavy MCP usage (>20k tokens) ❌ Complex multi-agent orchestration ❌ RAG for code search ❌ Vague instructions ❌ Skipping planning phase ❌ Letting context fill to limits
Core Insight
"The difference between frustration and productivity isn't the tool—it's how you use it. Invest time in your infrastructure (CLAUDE.md, skills, hooks, docs), and you'll build production-quality code with confidence."
Success requires obsessive context management, rigorous upfront planning, and architectural simplicity. These foundational practices compound across every future task.
Claude Code Best Practices
Executive Summary
This comprehensive guide synthesizes best practices from 12 sources on using Claude Code effectively. Three core principles emerge:
1. Context Management is Critical: Successful users manage context through CLAUDE.md files, strategic /clear usage, and documentation systems. Context degradation represents the primary failure mode.
2. Planning Before Implementation is Essential: All high-quality sources emphasize upfront planning using Planning Mode or written architectural reviews before coding begins.
3. Simplicity Over Complexity: Simple control loops outperform multi-agent systems. Low-level tools combined with selective high-level abstractions work better than heavy frameworks.
---
General Software Engineering Best Practices
Test-Driven Development (TDD)
Write tests before implementation to validate AI-generated code reliability. The consensus pattern:
- Create tests first
- Confirm tests fail
- Commit tests separately
- Implement until tests pass
- Never modify tests during implementation
Code Review Requirements
All code requires human review. As noted: "I'm ultimately responsible for the code in a PR with my name on it, regardless of how it was produced." Multiple eyes catch spaghetti code, missing error handling, and security issues that LLMs miss.
Quality Gates
Implement hooks for continuous validation:
- TypeScript/linter checks after edits
- Test execution on file changes
- Build validation before commits
Caveat: Automatic formatting hooks consume excessive tokens (160k reported in 3 rounds). Format manually between sessions instead.
Incremental Commits
Commit early with meaningful messages using Conventional Commits format. Each commit should compile and pass tests.
---
Core Recommendations
Context Management (Most Critical)
CLAUDE.md File Structure
Universal consensus across all sources. Structure as:
Root file (100-200 lines):
- Critical universal rules
- Testing instructions
- Quick command reference
Subdirectory files (50-100 lines):
- Project-specific context
- Local commands
Token efficiency: Keep CLAUDE.md under 2,000 tokens. One team baseline: 20k tokens total (10% of 200k context).
Anti-patterns to avoid:
- Don't @-file entire documentation
- Don't write comprehensive manuals
- Do focus on what Claude gets wrong
Aggressive Context Clearing
Clear at 60k tokens or 30% context—don't wait for limits. Use /clear + /catchup pattern for simple restarts.
For complex work: have Claude document progress to markdown, /clear, restart fresh reading the progress file.
Avoid `/compact`: Automatic compaction is opaque and error-prone.
Documentation Systems
The Three-File Pattern for each task:
[task]-plan.md- The accepted plan[task]-context.md- Key files and decisions[task]-tasks.md- Work checklist
Update plans during implementation. This enables fresh conversations to pick up exactly where you left off.
---
Planning & Architecture
Planning Mode is Mandatory
Steps: 1. Enter Planning Mode with high-level description 2. Review proposal thoroughly 3. Ask clarifying questions and request alternatives 4. Document accepted plan 5. Implement in stages with periodic plan review
Planning reveals changed requirements and prevents "vibe coding" that creates technical debt.
Explore, Plan, Code, Commit Workflow
1. Explore: Read files and context without coding 2. Plan: Create documented architecture 3. Code: Implement with verification steps 4. Commit: Update READMEs and create PR
---
Tool Usage & Automation
Skills System with Auto-Activation
Skills need hook-based activation since manual skills are ignored ~90% of the time.
Hook pattern: Analyze incoming prompts for keywords, then inject skill activation reminders before Claude sees the message.
Skill structure: Main file <500 lines + resource files for progressive disclosure.
Hooks for Quality Control
Primary strategy: Block-at-submit hooks that prevent commits until requirements met.
Example: Check for test passes before allowing git commits.
Secondary: Hint hooks provide non-blocking feedback on suboptimal patterns.
Subagents/Task Delegation
Two competing philosophies:
Custom Specialized Agents: Build purpose-built subagents (e.g., code-architecture-reviewer)
Clone Pattern: Use Task(...) to spawn clones of the main agent, letting it manage orchestration dynamically
The clone pattern preserves more context and avoids gatekeeping. Most users should start with clones.
Slash Commands
Use simple shortcuts, not complex workflows. Recommended:
/dev-docs- Strategic planning/catchup- Read changed files/code-review- Architectural review/test-route- Test authenticated endpoints/pr- Clean up code and prepare
Anti-pattern warning: "If you have a long list of complex custom commands, you've created an anti-pattern." Focus on typing naturally.
MCP Strategy Evolution
Heavy MCP usage is counterproductive. Quote: "If you're using more than 20k tokens of MCPs, you're crippling Claude."
New philosophy—MCPs should act as secure gateways, not API mirrors:
- Bad: Dozens of tools mirroring REST operations
- Good: Few powerful gateways handling auth/security
Skills > MCPs for most use cases. Use MCPs only for stateful environments.
---
Workflow Optimization
Specificity in Instructions
Vague instructions produce vague results. Provide:
- Specific file paths
- Component patterns to follow
- Tech stack details
- Testing requirements
Visual References
Paste screenshots for UI work. Iteration pattern: 1. Provide visual mock 2. Claude implements 3. Take screenshot and compare 4. Iterate (typically 2-3 rounds)
Course Correction Techniques
Four tools: 1. Ask for plan first before coding 2. Press Escape to interrupt 3. Double-tap Escape to jump back in history 4. Ask Claude to undo
Git Worktrees for Parallel Work
Run multiple Claude instances on independent tasks:
git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude---
Production Code Quality
Error Handling Standards
Pattern: Explicit error handling with monitoring.
Gentle reminder hooks check for:
- try-catch blocks
- Async operations
- Database calls
- Sentry error capture
Testing Standards
TDD checklist:
- Parameterize inputs
- Ensure tests can fail for real defects
- Compare to independent expectations, not function output
- Test edge cases and boundaries
- Use property-based testing with fast-check
Type Safety
Use branded types for IDs. Prefer import type for type-only imports. Override incorrect generated types as needed.
---
Advanced Patterns
Headless Mode for Automation
Use for CI/CD, pre-commit hooks, issue triage:
claude -p "migrate foo.py from React to Vue" \
--allowedTools Edit Bash(git commit:*)Multi-Claude Verification
Separate contexts for writing and reviewing: 1. Claude A writes code 2. Claude B reviews from fresh context 3. Claude C edits based on feedback
Advanced: Use o3 for planning, Sonnet 4 for verification, Sonnet 3.7 for implementation.
Simple Control Loops
Architectural insight: "Debuggability >> complicated multi-agent systems." Claude Code uses one flat message list. Most applications don't need multi-agent complexity.
LLM Search Over RAG
Claude Code uses complex ripgrep/jq/find commands rather than RAG. Why: RAG introduces hidden failure modes (similarity function, chunking strategy, reranking). LLM search is simpler and the model handles heavy lifting.
---
Contradictions & Trade-offs
Skills vs Context Bloat
Position A: Create many specialized skills with progressive disclosure Position B: Keep skills minimal (<100 lines)
Resolution: Progressive disclosure matters. Auto-activation hooks are essential either way.
Custom Subagents vs Clone Pattern
Position A: Build specialized subagents for specific roles Position B: Avoid custom subagents; use Task(...) clones
Resolution: Both work. Clones preserve context and flexibility. Custom subagents suit highly specialized tasks.
Auto-Formatting Hooks
Initially recommended, but updated guidance: Don't use auto-format hooks. Token cost (160k in 3 rounds) exceeds marginal benefit. Format manually between sessions.
Planning Mode vs Manual Plans
Planning Mode: Better codebase research Manual planning: More control, better with agent output
Resolution: Use Planning Mode for research, exit and create manual dev docs, refine with custom commands.
---
Essential Practices (Do These First)
1. Create CLAUDE.md (100-200 lines max) 2. Use Planning Mode before coding 3. Clear context aggressively (at 60k tokens) 4. Write tests first (TDD) 5. Be specific in instructions 6. Review all code manually
---
High-Impact Practices (Implement Soon)
1. Dev docs system (plan/context/tasks files) 2. Skills with auto-activation hooks 3. Quality gate hooks 4. Slash commands 5. Visual references for UI 6. Subagent delegation 7. Course correction patterns (ESC, double-ESC)
---
Advanced Practices (For Experienced Users)
1. Git worktrees for parallel development 2. Multi-Claude verification 3. Headless mode for automation 4. Minimal MCP servers 5. PM2 for microservices 6. Utility scripts in Skills 7. Living documentation
---
Practices to Avoid
❌ Auto-formatting hooks (excessive tokens) ❌ Heavy MCP usage (>20k tokens) ❌ Complex multi-agent systems (debugging nightmare) ❌ RAG for code search ❌ Vague instructions ❌ Skipping planning ❌ Filling context to limits
---
Quick Start Workflow
Week 1: Create CLAUDE.md, practice Planning Mode, clear context regularly, review code Week 2: Set up TDD, create slash commands, implement build hooks, add visual references Week 3: Implement dev docs, create Skills, add auto-activation, practice code review Week 4: Audit context usage, optimize CLAUDE.md, add quality gates, experiment with worktrees
---
Success Metrics
Context efficiency:
- Baseline <20k tokens (10% of 200k)
- CLAUDE.md <2,000 tokens
- MCP tools <20k tokens
Code quality:
- Test coverage >80%
- Zero TypeScript errors before commits
- Production bugs decreasing over time
Productivity:
- Track plan-to-PR time
- Monitor parallel tasks with worktrees
- Reduce context compactions needed
---
Conclusion
The most successful Claude Code users obsess over three things: context management, upfront planning, and simplicity. Invest time in infrastructure (CLAUDE.md, skills, hooks, docs), and productivity increases significantly. The difference isn't the tool—it's how you use it.
Related skills
FAQ
What modes does it support?
A normal readable mode, an AI-optimized mode with YAML frontmatter, and a dual mode that writes both files.
How does it fetch the page?
It uses the WebFetch tool, which converts HTML to markdown and caches the URL for 15 minutes.