기술 문서용 코드 예제 패턴 라이브러리. doc-writer 에이전트가 코드 예제, 튜토리얼을 작성할 때 참조. '코드 예제 패턴', '튜토리얼 코드 작성' 요청 시 사용. 단, 실제 코드 컴파일이나 테스트 실행은 범위 밖.
doc-writer 에이전트가 기술 문서에 포함할 코드 예제의 품질을 높이는 패턴.
1. 목표 선언 — "이 코드는 X를 수행합니다"
2. 사전 조건 — 라이브러리, 환경 변수, 설정
3. 핵심 코드 — 최소 작동 예제
4. 실행 결과 — 예상 출력
5. 확장 포인트 — "다음 단계로 Y를 할 수 있습니다"
나쁜 예제 (컨텍스트 없음):
result = client.process(data)
좋은 예제 (자기완결적):
# pip install example-sdk
from example_sdk import Client
client = Client(api_key="your-api-key")
data = {"name": "테스트", "value": 42}
result = client.process(data)
print(result.status) # "success"
Step 1: 최소 동작 코드
Step 2: 입력 처리 추가
Step 3: 에러 처리 추가
Step 4: 설정 외부화
Step 5: 프로덕션 코드
각 단계에서 변경 부분만 강조, 기존 코드는 ...으로 축약.
#### 문제: [구체적 문제 설명]
#### 해결: [코드와 함께 해결 방법]
| 방식 | 장점 | 단점 | 코드 |
|---|---|---|---|
| 동기 | 단순 | 블로킹 | result = fetch() |
| 비동기 | 성능 | 복잡 | result = await fetch() |
| 규칙 | 설명 |
|---|---|
| WHY 주석 | "왜" 이렇게 작성했는지 |
| WHAT 금지 | "무엇"은 코드 자체로 |
| 한글 주석 | 한국어 문서에서 한글 |
| TODO 금지 | 예제에 미완성 금지 |
| 하드코딩 설명 | "실제 환경에서는..." 주석 |
# 올바름: 환경변수
api_key = os.environ["API_KEY"]
# 문서용 플레이스홀더
api_key = "your-api-key-here" # 실제 키로 교체
| 항목 | 기준 |
|---|---|
| 자기완결성 | import~실행까지 복사-붙여넣기 동작 |
| 에러 처리 | try/catch 포함 |
| 타입 정보 | 변수/파라미터/반환값 타입 명시 |
| 실행 결과 | 예상 출력 포함 |
| 민감 정보 | 하드코딩 시크릿 없음 |
| 버전 명시 | 언어/라이브러리 버전 |