FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

사용자가 마이그레이션된 소스 명령어 audit-whitepapers를 실행하도록 요청할 때 이 스킬을 사용하세요.

명령어 템플릿

백서 및 요약 카드 감사

모든 백서(FR + EN) 및 요약 카드(FR + EN)에 대한 포괄적인 신선도 및 품질 감사입니다. 각 문서를 현재 가이드 버전과 비교하여 점수를 매기고, FR/EN 일치 여부를 확인하며, 메타데이터 일관성을 검증합니다.

인수

• --fix - 업데이트 제안 및 프런트매터 패치 생성 (파일을 수정하지 않음)
• --verbose - 실패뿐만 아니라 통과 기준을 포함한 모든 기준 표시
• --cards-only - 요약 카드만 감사 (주요 백서 건너뜀)
• --wp-only - 주요 백서만 감사 (요약 카드 건너뜀)

사용법

/audit-whitepapers                  # 전체 감사, 실패만 표시
/audit-whitepapers --fix            # 감사 + 우선 순위 업데이트 제안
/audit-whitepapers --verbose        # 모든 기준에 대한 전체 세부 정보
/audit-whitepapers --cards-only     # 요약 카드만
/audit-whitepapers --wp-only        # 백서만

---

1단계: 검색

목적: 감사 가능한 모든 문서를 찾아서 목록화합니다.

단계

1. 현재 가이드 버전 읽기: 프로젝트 루트에 있는 VERSION 파일을 읽습니다. 이것이 모든 문서가 동기화되어야 하는 대상 버전입니다.

2. 디렉토리 스캔하여 .qmd 파일 찾기:

   whitepapers/fr/         (주요 백서 FR)
   whitepapers/en/         (주요 백서 EN)
   whitepapers/recap-cards/fr/    (요약 카드 FR)
   whitepapers/recap-cards/en/    (요약 카드 EN)
   

3. 각 파일 분류:

   • 주요 백서: whitepapers/fr/ 또는 whitepapers/en/ 디렉토리의 [0-9][0-9]-*.qmd 패턴 파일
   • 치트시트: *cheatsheet*.qmd 패턴 파일 (별도 추적, 점수 매기지 않음)
   • 사용자 정의 백서: 외부 파트너(strangebee, purchasely, devwithai)의 *-whitepaper.qmd 또는 *-cheatsheet.qmd 패턴 파일 -- 점수 매기기에서 제외, 별도로 나열
   • 요약 카드: recap-cards/fr/ 또는 recap-cards/en/ 디렉토리의 모든 .qmd 파일
   • 번들/포함: fiches-recap-serie.qmd, fiches/ 하위 디렉토리 파일 -- 제외 (구성된 문서임)

4. 각 포함 파일의 YAML 프런트매터 구문 분석 (첫 번째 ---와 두 번째 --- 사이 읽기). 추출:

   • title, subtitle, author, date
   • version (주요 백서 및 요약 카드에서 추적되는 가이드 버전)
   • wp-version (백서 자체 semver, 주요 백서만 해당)
   • guide-version (요약 카드에서 사용되는 명시적 가이드 버전 필드)
   • card-number, category, difficulty (요약 카드만 해당)
   • series (주요 백서만 해당)

5. 검색 요약 표시:

   가이드 버전: {VERSION}
   발견: {N}개의 주요 백서 ({FR}/{EN} FR/EN), {N}개의 요약 카드 ({FR}/{EN} FR/EN)
   제외: {N}개의 사용자 정의 파일 (strangebee, purchasely, devwithai), {N}개의 번들 파일
   

---

2단계: 버전 갭 분석 (파일당 40점)

목적: 각 문서가 가이드와 비교하여 얼마나 최신인지 점수를 매깁니다.

Semver 비교 로직

버전 문자열을 MAJOR.MINOR.PATCH로 구문 분석합니다. 부실 측정항목은 minor_gap = current_minor - file_minor입니다 (동일한 MAJOR 사용). MAJOR가 다르면 심각한 것으로 처리합니다.

주요 백서의 경우 가이드 버전 필드는 version입니다. 요약 카드의 경우 가이드 버전 필드는 guide-version입니다 (version이 없으면 version으로 대체).

점수표

기준	점수	감지 방법
가이드 버전 최신 (0-1 마이너 뒤짐)	15	minor_gap <= 1
가이드 버전 최근 (2-3 마이너 뒤짐)	10	minor_gap 2-3 (부분 점수, 15점 대체)
가이드 버전 오래됨 (4-10 마이너 뒤짐)	5	minor_gap 4-10 (부분 점수)
wp-version 필드 존재 및 유효한 semver	5	필드 존재 AND \d+\.\d+\.\d+ 패턴 일치 (백서만 해당)
FR/EN 쌍과 wp-version 일치	10	대응 파일에서 동일한 wp-version 값 (백서만 해당)
FR/EN 쌍과 guide-version 일치	10	대응 파일에서 동일한 guide-version(또는 version) 값 (카드만 해당)

신선도 레이블:

• 0-1 마이너 뒤짐: 최신
• 2-3 마이너 뒤짐: 약간 부실
• 4-10 마이너 뒤짐: 매우 부실
• 11+ 마이너 뒤짐: 심각

참고: 가이드 버전에 대한 15, 10, 5점은 상호 배타적입니다 (가장 높은 적용 가능 등급만 부여).

---

3단계: 콘텐츠 부패 확인 (파일당 20점)

목적: 백서가 다루는 가이드 섹션이 마지막 업데이트 이후 변경되었는지 감지합니다.

백서-가이드 매핑 (내장)

WP#	FR 파일 이름 접두사	EN 파일 이름 접두사	가이드 섹션
00	00-introduction	00-series-introduction	guide/ultimate-guide.md Ch.1-2
01	01-prompts	01-effective-prompts	Ch.2 프롬프트 섹션
02	02-personnalisation	02-customization	Ch.3 메모리, Ch.4 에이전트, Ch.5 스킬
03	03-securite	03-security	Ch.7 훅, 보안 섹션
04	04-architecture	04-architecture	Ch.2 내부, 아키텍처 섹션
05	05-equipe	05-team	Ch.3 팀 설정, Ch.9 CI/CD
06	06-privacy	06-privacy	Ch.2 데이터/개인정보 보호 섹션
07	07-guide-reference	07-reference-guide	Ch.10 참조
08	08-agent-teams	08-agent-teams	Ch.9 에이전트 팀
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	비즈니스/ROI 콘텐츠

단계

1. 각 주요 백서에 대해 date 필드를 추출합니다. 날짜가 YYYY-MM-DD 형식이 아니면 구문 분석합니다 (예: "2026-02-12" 또는 "March 2026").
2. git log --since="{date}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/를 실행하여 백서 날짜 이후 가이드 콘텐츠를 건드린 커밋 수를 계산합니다.
3. 점수:

기준	점수	감지 방법
wp 날짜 이후 가이드 커밋 없음	10	git log가 0 커밋 반환
wp 날짜 이후 소수의 커밋 (1-5)	7	1-5 커밋 (부분)
중간 정도의 커밋 (6-15)	4	6-15 커밋 (부분)
많은 커밋 (>15)	0	15개 초과 커밋
이 WP에 대한 매핑 정의됨	5	WP 번호가 위의 매핑 테이블에 있음
Git 기록 접근 가능	5	git log 명령이 오류 없이 실행됨

요약 카드: 상세한 git 분석을 건너뜁니다. minor_gap을 기반으로 고정 부패 점수를 부여합니다:

• 0-1 뒤짐: 20점
• 2-3 뒤짐: 15점
• 4-10 뒤짐: 8점
• 11+ 뒤짐: 0점

---

4단계: FR/EN 일치 확인 (파일당 20점)

목적: 모든 문서가 다른 언어에 대해 완전하고 버전이 일관된 대응 파일을 가지고 있어야 합니다.

페어링 전략

주요 백서: 두 자리 숫자 접두사(예: 00, 03, 10)로 일치시킵니다. FR 및 EN 파일 이름은 다르지만 접두사는 일관됩니다.

요약 카드: 동일한 파일 이름으로 일치시킵니다 (두 언어 디렉토리가 동일한 파일 이름 사용).

점수표

기준	점수	감지 방법
다른 언어에 대응 파일 존재	10	일치하는 접두사(백서) 또는 동일한 이름(카드)의 파일 발견됨
쌍 간 wp-version 일치	5	동일한 wp-version 값 (백서만 해당)
쌍 간 가이드 버전 일치	5	동일한 version/guide-version 값

쌍의 FR 및 EN 파일 모두 일치 점수를 동일하게 부여합니다 (쌍이 완전하면 둘 다 20점, 하나가 누락되면 기존 파일은 일치 점수 0점).

---

5단계: 메타데이터 품질 (파일당 20점)

목적: 프런트매터 완전성, 필드 형식 및 동일한 유형의 파일 간 일관성을 검증합니다.

주요 백서 (최대 20점)

기준	점수	감지 방법
필수 필드 존재	6	title, subtitle, author, date, version, wp-version, series 모두 있음
version이 semver 패턴 따름	3	\d+\.\d+\.\d+ 패턴 일치
wp-version이 semver 패턴 따름	3	\d+\.\d+\.\d+ 패턴 일치
date를 구문 분석할 수 있고 미래 날짜가 아님	3	유효한 날짜, 오늘 이후가 아님
series 값이 일관됨	2	"Codex Ultimate Guide"와 같음
wp-version 누락 없음 (비어 있거나 없으면 안 됨)	3	필드에 비어 있지 않은 값 있음

요약 카드 (최대 20점)

기준	점수	감지 방법
필수 필드 존재	5	title, subtitle, card-number, category, difficulty, guide-version, author, version, date 모두 있음
card-number가 파일 이름 접두사와 일치	4	예: card-number의 C01이 파일 이름의 c01-와 일치
category가 언어에 대해 유효함	4	FR: "Technique", "Methodologie", "Conception" 중 하나; EN: "Technical", "Methodology", "Design" 중 하나 (EN에서 "Conceptual"을 불일치로 표시)
difficulty가 유효한 값임	3	"beginner", "intermediate", "advanced" 중 하나
guide-version과 version 필드가 서로 일치	4	두 필드가 모두 존재하고 동일한 파일 내에서 동일한 값을 가짐

자동으로 감지해야 하는 알려진 문제: EN C-시리즈 카드는 두 가지 다른 카테고리 값("Conceptual"은 c01-c05, "Design"은 c06+)을 사용합니다. 보고서의 메타데이터 문제 섹션에서 이 불일치를 명시적으로 표시하세요.

---

6단계: 점수 계산 및 등급

점수 공식 (파일당)

총점 = 버전 갭 (40) + 콘텐츠 부패 (20) + FR/EN 일치 (20) + 메타데이터 품질 (20)
점수 = (총점 / 100) * 100  [백분율]

등급 척도

등급	점수	상태
A	90-100	최신, 완전 동기화
B	80-89	양호 (프로덕션 임계값)
C	70-79	곧 업데이트 필요
D	60-69	부실, 우선 순위 지정 필요
F	<60	심각: 콘텐츠가 오래된 것으로 추정

전체 건강 점수

가중 건강 = (WP 점수 합 * 2 + 카드 점수 합 * 1) / (WP 개수 * 2 + 카드 개수 * 1)

백서는 각각 20-80페이지인 반면 요약 카드는 2페이지이므로 가중치를 2배로 부여합니다. 부실한 백서는 더 큰 위험을 수반합니다.

---

7단계: 보고서

다음 Markdown 보고서를 출력합니다. 최상위 수준을 스캔 가능하게 유지하기 위해 개별 파일 분석에는 <details> 블록을 사용하세요.

# 백서 및 요약 카드 감사

**날짜**: {today}
**가이드 버전**: {VERSION}
**전체 건강**: {score}% ({grade})
**감사된 파일**: {total} ({wp_count}개 백서, {card_count}개 요약 카드)

---

## 버전 상태 대시보드

| 상태 | 백서 | 요약 카드 | 합계 |
|--------|-------------|-------------|-------|
| 최신 (0-1 마이너 뒤짐)   | N | N | N |
| 약간 부실 (2-3 마이너 뒤짐)   | N | N | N |
| 매우 부실 (4-10 뒤짐)   | N | N | N |
| 심각 (11+ 뒤짐)      | N | N | N |

**현재 사용 중인 버전**:
- 주요 WP 00-09: {version} ({gap} 마이너 버전 뒤짐)
- 주요 WP 10: {version} ({gap} 마이너 버전 뒤짐)
- 요약 카드: {guide-version} ({gap} 마이너 버전 뒤짐)

---

## 백서 점수

| WP# | 제목 | version | 갭 | wp-version | 일치 | 점수 | 등급 |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | 일치/갭 | N%    | X     |
...

<details>
<summary>개별 기준 분석 (WP 00)</summary>

| 단계 | 기준 | 결과 | 점수 |
|-------|-----------|--------|------|
| 버전 갭 | 가이드 버전 최신 | 심각 (-11) | 0/15 |
| 버전 갭 | wp-version 유효한 semver | 통과 | 5/5 |
| ... | ... | ... | ... |
| **총점** | | | **N/100** |
</details>

---

## 요약 카드 점수

| 시리즈 | 카드 수 | 평균 guide-version | 평균 갭 | 평균 점수 | 등급 |
|--------|-------|-------------------|---------|-----------|-------|
| T (Technical)    | 22 | ... | -N | N% | X |
| M (Methodology)  | 22 | ... | -N | N% | X |
| C (Conceptual)   | 13 | ... | -N | N% | X |

<details>
<summary>개별 카드 점수</summary>

| 카드 | 카테고리 | guide-version | 갭 | 일치 | 메타데이터 | 점수 | 등급 |
|------|----------|---------------|-----|--------|----------|-------|-------|
...
</details>

---

## FR/EN 일치 보고서

### 백서
| WP# | FR | EN | wp-version 일치 | version 일치 |
|-----|----|----|------------------|---------------|
...

### 요약 카드
- **FR 개수**: {N} | **EN 개수**: {N}
- **누락된 FR**: [목록 또는 "없음"]
- **누락된 EN**: [목록 또는 "없음"]
- **버전 불일치**: [목록 또는 "없음"]

---

## 메타데이터 문제

### 알려진: EN 요약 카드 카테고리 불일치
EN C-시리즈 카드는 "Conceptual/Design" 카테고리에 대해 서로 다른 두 값을 사용합니다:
- "Conceptual": c01, c02, c03, c04, c05
- "Design": c06, c07, c08, ...
권장 사항: 가이드 용어와 일치하도록 "Design"으로 표준화합니다.
영향을 받는 파일: whitepapers/recap-cards/en/c01-*.qmd 부터 c05-*.qmd ("Conceptual"을 "Design"으로 변경)

### 기타 문제
[누락된 필드, 잘못된 형식, 날짜 문제 등을 나열...]

---

## 우선 순위 작업 항목

### 심각 (등급 F, 11+ 버전 뒤짐)
[파일 경로가 포함된 특정 백서를 나열]

### 높음 (등급 D-F, 2+ 버전 뒤짐)
[특정 파일을 나열]

### 중간 (메타데이터 품질, 카테고리 수정)
[특정 문제를 나열]

### 낮음 (정리, 날짜 정렬)
[특정 문제를 나열]

---

## 다음 단계

1. `/update-whitepapers --since {oldest_version}` 실행하여 모든 부실 WP 업데이트
2. EN 카테고리 불일치 수정 (5개 파일: c01 부터 c05, "Conceptual"을 "Design"으로 변경)
3. 업데이트 후 `/audit-whitepapers` 재실행하여 진행 상황 추적
4. 목표: 모든 파일에서 80%+ 건강 (등급 B)

---

수정 모드 (--fix)

--fix가 전달되면 보고서 뒤에 수정 제안 섹션을 추가합니다. 이 섹션은 구체적인 패치를 제공하지만 파일을 수정하지는 않습니다.

프런트매터 버전 패치

가이드 버전이 부실한 각 파일에 대해 다음을 출력합니다:

# 파일: whitepapers/fr/00-introduction-serie.qmd
# 변경:
version: "3.27.6"  ->  version: "{current_VERSION}"
date: 2026-02-12   ->  date: {today}

카테고리 수정 패치 (EN 요약 카드)

업데이트할 파일 (카테고리: "Conceptual" -> "Design"):
- whitepapers/recap-cards/en/c01-trust-calibration.qmd
- whitepapers/recap-cards/en/c02-*.qmd
- whitepapers/recap-cards/en/c03-*.qmd
- whitepapers/recap-cards/en/c04-*.qmd
- whitepapers/recap-cards/en/c05-*.qmd