Skip to content

Commit 6ab0131

Browse files
helliceshellices
committed
feat(docs): 검색 가능한 GitHub Pages 문서 사이트 구축
사례, 가이드, 실습, 리서치 page bundle로 기존 콘텐츠를 이관한다. 메뉴와 서비스·태그 색인을 메타데이터에서 생성하고 Microsoft Learn 검증, 공개 안전성, Pages 배포 검사를 자동화한다.
1 parent e0f116e commit 6ab0131

461 files changed

Lines changed: 8308 additions & 1129 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/pull_request_template.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## 변경 내용
2+
3+
변경 목적과 독자가 얻는 결과를 간단히 적어 주세요.
4+
5+
## 공개 문서 체크리스트
6+
7+
- [ ] 사례·가이드·실습·리서치 중 올바른 문서 유형과 폴더를 선택했습니다.
8+
- [ ] 필수 front matter와 `docs-taxonomy.yml`의 분류 값을 사용했습니다.
9+
- [ ] Microsoft/Azure 기술 주장을 Microsoft Learn MCP와 `verify-with-microsoft-learn` skill로 원문까지 확인했습니다.
10+
- [ ] 실제 구독·테넌트 ID, 비밀, 내부 URL·IP·호스트명 등 공개 안전성 문제를 제거했습니다.
11+
- [ ] 필요한 경우 현재 가이드와 시점 고정 사례를 분리하고 서로 연결했습니다.
12+
- [ ] 아래 로컬 검증을 통과했습니다.
13+
14+
```powershell
15+
python -m pytest tests/docs -q
16+
python scripts/docs/validate_metadata.py
17+
python scripts/docs/validate_sources.py
18+
python scripts/docs/validate_links.py
19+
python scripts/docs/validate_public_safety.py
20+
mkdocs build --strict
21+
python scripts/docs/validate_search_index.py
22+
```

‎.github/skills/verify-with-microsoft-learn/SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: verify-with-microsoft-learn
3+
description: Use when creating, revising, or reviewing public technical documentation that contains Microsoft or Azure product claims.
4+
---
5+
6+
# Verify with Microsoft Learn
7+
8+
## Core rule
9+
10+
Verify product behavior, support status, limits, versions, configuration steps, and CLI or API usage against current official text. A source URL alone is not evidence of a completed review.
11+
12+
## Workflow
13+
14+
1. Extract every checkable claim from the changed document. Separate product claims from incident-specific observations.
15+
2. Confirm the `microsoft.docs.mcp` server is connected. Inspect its current tool descriptions through `tools/list`; tool names, parameters, and response shapes can change.
16+
3. Search Microsoft Learn for each claim using the official product name, feature, version, error, or command. Use the discovered documentation search tool rather than general web search.
17+
4. Fetch every selected article in full with the discovered article-fetch tool. Search snippets are only candidates.
18+
5. Compare each claim with the fetched article's scope, prerequisites, supported versions, limitations, and current terminology.
19+
6. Correct unsupported claims. For a historical case, preserve the observation but state its date and contrast it with current documented behavior.
20+
7. For Kubernetes or CNCF behavior that Microsoft Learn does not define, also check the relevant `kubernetes.io` or `cncf.io` source. Microsoft Learn remains mandatory for this repository's Azure context.
21+
8. Record the exact article title and canonical URL in `official_sources`, set `sources_checked_at` to the actual review date, and set `verification_status: verified` only after every material claim is covered.
22+
9. Run `python scripts/docs/validate_metadata.py`, `python scripts/docs/validate_sources.py`, and `python scripts/docs/validate_links.py`.
23+
24+
If the server is unavailable, no relevant full article can be fetched, or a material conflict remains, set `verification_status: needs-review` and report the unresolved claim. Never use `last_verified` to imply a check that did not occur.
25+
26+
## Evidence contract
27+
28+
```yaml
29+
verification_status: verified
30+
sources_checked_at: 2026-09-12
31+
official_sources:
32+
- title: Azure Kubernetes Service documentation
33+
url: https://learn.microsoft.com/azure/aks/
34+
```
35+
36+
Use at least one claim-relevant `https://learn.microsoft.com/` article. Add upstream official sources when they hold the authoritative implementation detail.
37+
38+
## Quick reference
39+
40+
| Claim | Verify |
41+
|---|---|
42+
| Supported feature or version | Availability, region, tier, preview/GA status |
43+
| Configuration procedure | Prerequisites, command syntax, defaults, permissions |
44+
| Limit or performance statement | Units, scope, exceptions, last-updated context |
45+
| Historical incident | Observation date separately from current product behavior |
46+
47+
## Common mistakes
48+
49+
- Treating a search snippet as the full source
50+
- Citing a product landing page that does not support the claim
51+
- Using blogs, Q&A, or copied examples when an official article exists
52+
- Marking a document verified while one material claim is unresolved

‎.github/skills/verify-with-microsoft-learn/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Verify with Microsoft Learn"
3+
short_description: "Verify technical docs against Microsoft Learn"
4+
default_prompt: "Use $verify-with-microsoft-learn to verify this technical documentation against current official sources."

‎.github/workflows/docs-ci.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Documentation CI
2+
3+
on:
4+
pull_request:
5+
workflow_dispatch:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
validate:
12+
runs-on: ubuntu-latest
13+
timeout-minutes: 15
14+
steps:
15+
- name: Check out repository
16+
uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.13"
22+
cache: pip
23+
cache-dependency-path: requirements-docs.txt
24+
25+
- name: Install documentation dependencies
26+
run: python -m pip install -r requirements-docs.txt
27+
28+
- name: Run documentation tests
29+
run: python -m pytest tests/docs -q
30+
31+
- name: Validate public documentation
32+
run: |
33+
python scripts/docs/validate_metadata.py
34+
python scripts/docs/validate_sources.py
35+
python scripts/docs/validate_links.py
36+
python scripts/docs/validate_public_safety.py
37+
38+
- name: Build site strictly
39+
run: mkdocs build --strict
40+
41+
- name: Validate search index
42+
run: python scripts/docs/validate_search_index.py

‎.github/workflows/pages.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Deploy documentation to Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
concurrency:
13+
group: pages
14+
cancel-in-progress: false
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
timeout-minutes: 15
20+
steps:
21+
- name: Check out repository
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.13"
28+
cache: pip
29+
cache-dependency-path: requirements-docs.txt
30+
31+
- name: Install documentation dependencies
32+
run: python -m pip install -r requirements-docs.txt
33+
34+
- name: Validate public documentation
35+
run: |
36+
python scripts/docs/validate_metadata.py
37+
python scripts/docs/validate_sources.py
38+
python scripts/docs/validate_links.py
39+
python scripts/docs/validate_public_safety.py
40+
41+
- name: Build site strictly
42+
run: mkdocs build --strict
43+
44+
- name: Validate search index
45+
run: python scripts/docs/validate_search_index.py
46+
47+
- name: Configure Pages
48+
uses: actions/configure-pages@v5
49+
50+
- name: Upload Pages artifact
51+
uses: actions/upload-pages-artifact@v4
52+
with:
53+
path: site
54+
55+
deploy:
56+
permissions:
57+
contents: read
58+
pages: write
59+
id-token: write
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
runs-on: ubuntu-latest
64+
needs: build
65+
steps:
66+
- name: Deploy to Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
node_modules/
22
.env
3-
.github/skills/
3+
.github/skills/*
4+
!.github/skills/verify-with-microsoft-learn/
5+
!.github/skills/verify-with-microsoft-learn/**
46
.venv
57
sim-env.json.vscode/
68
.mirrord/
79
__pycache__/
810
*.py[cod]
11+
.pytest_cache/
12+
site/
913
.worktrees/
1014
.superpowers/
1115
monitor/sre-agent-event-lab/evidence/

‎.vscode/mcp.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"servers": {
3+
"microsoft.docs.mcp": {
4+
"type": "http",
5+
"url": "https://learn.microsoft.com/api/mcp"
6+
}
7+
}
8+
}

‎AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Repository instructions
2+
3+
## Public documentation contract
4+
5+
- 상세 기준은 `docs/contributing/index.md`를 단일 설명 문서로 사용한다.
6+
- 공개 기술 문서는 `docs/<collection>/<service>/<topic>/index.md` page bundle로 작성한다.
7+
- `<collection>`은 `cases`, `guides`, `labs`, `research` 중 하나이며 front matter의 `document_type`과 일치해야 한다.
8+
- 새 서비스, 기술 또는 태그가 필요할 때만 `docs-taxonomy.yml`을 함께 수정한다.
9+
- 개별 문서를 추가하기 위해 `mkdocs.yml`, `docs/.nav.yml`, README 또는 수동 문서 목록을 수정하지 않는다. 빌드가 폴더와 메타데이터에서 메뉴·색인을 생성한다.
10+
11+
## Content lifecycle
12+
13+
- 발생 시점의 환경, 관측값, 조사와 해결 이력은 `cases`에 보존한다.
14+
- 현재 권장 절차, 지원 상태와 버전별 차이는 `guides`에서 계속 갱신한다.
15+
- 한 문서에 두 성격이 섞이면 사례와 가이드로 분리하고 `related_cases`·`related_guides`로 연결한다.
16+
- 실행 가능한 프로젝트, 배포 매니페스트와 대용량 결과물은 `samples/`에 두고 문서에서는 GitHub 소스 링크를 사용한다.
17+
- 페이지에서 렌더링할 이미지만 같은 bundle의 `images/`에 두며 의미 있는 대체 텍스트를 작성한다.
18+
19+
## Official-source verification
20+
21+
- Microsoft 또는 Azure의 동작, 지원 여부, 제한, 버전, 구성 단계, CLI/API 사용법을 추가하거나 바꿀 때 `.github/skills/verify-with-microsoft-learn/SKILL.md`의 `verify-with-microsoft-learn` skill을 반드시 사용한다.
22+
- Microsoft Learn MCP 검색 뒤 선택한 원문 전체를 조회하고, 주장과 적용 범위를 비교한다.
23+
- `official_sources`, `sources_checked_at`, `verification_status`는 실제 검증 결과와 일치시킨다. URL만 추가한 것은 검증이 아니다.
24+
- Microsoft Learn이 최종 권위가 아닌 Kubernetes·CNCF 세부 동작은 upstream 공식 문서도 함께 확인한다.
25+
- 의미 검증을 완료하지 못하면 `verification_status: needs-review`로 남기고 완료했다고 표현하지 않는다.
26+
27+
## Public safety
28+
29+
- 고객·조직·사용자 실명, 구독·테넌트 ID, 비밀, 연결 문자열, 내부 URL·IP·호스트명, 개인정보가 담긴 로그와 승인되지 않은 화면을 공개 문서에 넣지 않는다.
30+
- 실제 식별자는 문서 전체에서 일관된 가상 값으로 치환한다.
31+
32+
## Required validation
33+
34+
문서 또는 사이트 구성을 변경한 뒤 저장소 루트에서 실행한다.
35+
36+
```powershell
37+
python scripts/docs/validate_metadata.py
38+
python scripts/docs/validate_sources.py
39+
python scripts/docs/validate_links.py
40+
python scripts/docs/validate_public_safety.py
41+
mkdocs build --strict
42+
python scripts/docs/validate_search_index.py
43+
```
44+
45+
테스트나 검증 실패를 무시하거나 생성된 `site/` 및 검색 인덱스를 커밋하지 않는다.

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# 기여하기
2+
3+
새 공개 문서는 `docs/<collection>/<service>/<topic>/index.md`에 추가합니다. 올바른 폴더와 front matter를 사용하면 메뉴와 색인은 빌드 시 자동 생성됩니다.
4+
5+
문서 유형 선택, 메타데이터, 본문 구조, 태그, 이미지와 공개 안전성의 기준 문서는 [상세 기여 지침](docs/contributing/index.md)입니다.
6+
7+
Microsoft 또는 Azure 기술 내용을 새로 쓰거나 바꿀 때는 repository skill `verify-with-microsoft-learn`을 사용해 Microsoft Learn 원문과 대조하고 출처 메타데이터를 갱신해야 합니다.
8+
9+
제출 전 다음을 실행하세요.
10+
11+
```powershell
12+
python scripts/docs/validate_metadata.py
13+
python scripts/docs/validate_sources.py
14+
python scripts/docs/validate_links.py
15+
python scripts/docs/validate_public_safety.py
16+
mkdocs build --strict
17+
python scripts/docs/validate_search_index.py
18+
```

‎README.md‎

Lines changed: 18 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,30 @@
11
# DevGuideSample
22

3-
> Microsoft CSA(Customer Success Architect) 팀을 위한 Azure 기술 가이드 및 이슈 해결 사례 저장소
3+
실제 Azure 문제 해결 이력과 지속적으로 갱신하는 기술 가이드를 외부에 공개하는 문서 저장소입니다.
44

5-
## 📌 저장소 소개
5+
## 문서 사이트
66

7-
이 저장소는 한국 지역에서 발생하는 다양한 Azure 관련 기술 이슈와 솔루션을 체계적으로 정리하고 공유하기 위한 목적으로 만들어졌습니다. Microsoft CSA 팀이 고객 지원 과정에서 경험한 실제 사례와 베스트 프랙티스를 문서화하여, 팀원들 간의 지식 공유와 빠른 문제 해결을 돕습니다.
7+
**[DevGuideSample GitHub Pages에서 검색하기](https://hellices.github.io/devguidesample/)**
88

9-
## 🎯 활용 플랜
9+
사이트에서는 한국어·영어 전체 텍스트, 제품명, 오류 메시지와 태그로 모든 공개 문서를 검색할 수 있습니다.
1010

11-
### 1. 지식 베이스로 활용
12-
- 과거에 해결했던 이슈를 빠르게 검색하고 참고
13-
- 유사한 문제 발생 시 검증된 솔루션 적용
14-
- 신규 팀원 온보딩 시 학습 자료로 활용
11+
| 모음 | 용도 |
12+
|---|---|
13+
| 문제 해결 사례 | 특정 시점의 증상, 조사, 근본 원인과 해결 결과를 보존합니다. |
14+
| 일반 가이드 | 현재 재사용할 수 있는 절차를 제품 변화에 따라 계속 검증하고 갱신합니다. |
15+
| 실습 | 배포, 실행, 검증과 정리를 재현할 수 있는 시나리오입니다. |
16+
| 리서치 | 비교, 벤치마크와 아키텍처 조사를 기준 시점과 함께 기록합니다. |
1517

16-
### 2. 베스트 프랙티스 공유
17-
- 실제 프로덕션 환경에서 검증된 구성 및 설정 공유
18-
- Azure 서비스별 최적화 전략 문서화
19-
- 성능 튜닝 사례 및 트러블슈팅 가이드 제공
18+
전체 문서 목록은 파일로 중복 관리하지 않습니다. 올바른 폴더와 front matter를 사용하면 Pages 메뉴, 서비스 색인과 태그 색인에 자동으로 포함됩니다.
2019

21-
### 3. 협업 및 확장
22-
- 팀원들이 새로운 이슈 해결 사례를 지속적으로 추가
23-
- 코드 예제와 함께 상세한 설명 제공
24-
- 한국 고객 환경에 특화된 가이드 작성
20+
## 로컬 미리보기
2521

26-
## 🧪 실습 랩
27-
28-
문서만 읽는 가이드와 달리, 실제 Azure 리소스를 배포해 직접 돌려 보는 실습입니다. 각 랩은 자체 `azure.yaml`을 가지고 있어 `azd up` 한 번으로 환경이 만들어집니다.
29-
30-
| 랩 | 무엇을 확인하나 | 소요 시간 | 과금 |
31-
|---|---|---|---|
32-
| [Azure SRE Agent 이벤트 기반 장애 분석](monitor/sre-agent-event-lab/README.md) | 장애를 세 번 주입하고 Azure Monitor 경고를 받은 SRE Agent가 원인을 짚어내는지 | 배포 5분 + 시나리오당 30~40분 | 있음 (Container Apps, Log Analytics, Storage 등) |
33-
34-
각 랩의 README가 사전 조건, 배포, 정리 절차를 안내합니다. **실습을 마치면 반드시 각 랩의 정리 절차를 따라 리소스를 삭제하세요.**
35-
36-
새 랩을 추가할 때는 `azure.yaml`과 README를 갖춘 디렉터리를 만들고 위 표에 행을 추가합니다.
37-
38-
## 📝 기여 방법
39-
40-
### 새로운 가이드 추가하기
41-
42-
1. 적절한 카테고리 폴더 선택 (aks, automation, cosmosdb, mysql, develop, architect)
43-
2. 필요시 하위 폴더 생성 (예: `nodejs/`, `python/` 등)
44-
3. Markdown 파일 작성 시 다음 항목 포함 권장:
45-
- 문제 상황 설명
46-
- 원인 분석
47-
- 해결 방법 (코드 예제 포함)
48-
- 참고 링크
49-
50-
### 가이드 작성 예시 구조
51-
52-
```markdown
53-
# [제목]: 문제 및 해결 방법 간략 설명
54-
55-
## 문제 상황
56-
실제 발생한 이슈에 대한 설명
57-
58-
## 원인 분석
59-
문제의 근본 원인 파악
60-
61-
## 해결 방법
62-
상세한 해결 단계 및 코드 예제
63-
64-
## 참고 링크
65-
- 관련 Microsoft Learn 문서
66-
- Kubernetes/Azure 공식 문서
22+
```powershell
23+
python -m venv .venv
24+
.\.venv\Scripts\python -m pip install -r requirements-docs.txt
25+
.\.venv\Scripts\mkdocs serve
6726
```
6827

69-
## 🎓 대상 독자
70-
71-
- Microsoft Customer Success Architect (CSA)
72-
- Azure 기술 지원 엔지니어
73-
- Azure 클라우드 아키텍트
74-
- Azure 서비스를 사용하는 개발자
75-
76-
## 🔗 관련 리소스
77-
78-
- [Microsoft Learn](https://learn.microsoft.com/ko-kr/)
79-
- [Azure Documentation](https://docs.microsoft.com/ko-kr/azure/)
80-
- [Azure Architecture Center](https://learn.microsoft.com/ko-kr/azure/architecture/)
81-
이 저장소의 내용은 Microsoft CSA 팀 내부 지식 공유를 목적으로 합니다.
82-
83-
---
28+
자세한 작성·검증 규칙은 [CONTRIBUTING.md](CONTRIBUTING.md)를 확인하세요.
8429

85-
**Last Updated**: 2025-11-17
30+
> 이 저장소와 Pages는 공개되어 있습니다. 고객·사용자 식별자, 구독·테넌트 ID, 비밀, 내부 URL 또는 승인되지 않은 화면 캡처를 커밋하지 마세요.

0 commit comments

Comments
 (0)