Skip to content

Commit 93ae583

Browse files
haksungjanghaksungjang
committed
add: CLAUDE files
1 parent 2ff1c35 commit 93ae583

29 files changed

Lines changed: 2447 additions & 0 deletions

‎.claude/GUIDE-HARNESS.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# 가이드 하네스 사용 방법
2+
3+
OpenChain KWG 가이드(`content/ko/guide/`) 작성·개선·관리를 위한
4+
에이전트·스킬·규칙 기반 하네스 사용 방법.
5+
6+
---
7+
8+
## 구성 요소 한눈에 보기
9+
10+
```
11+
.claude/
12+
├── agents/
13+
│ ├── guide-auditor.md # 가이드 완성도·일관성 감사
14+
│ ├── guide-writer.md # 조항 단위 작성·개선 (승인 기반)
15+
│ ├── cross-link-checker.md # 교차 참조 링크 검증
16+
│ └── evidence-verifier.md # ISO 입증자료 충족 검증
17+
├── commands/
18+
│ ├── guide-improve.md # 오케스트레이터 (진입점)
19+
│ ├── guide-resume.md # 세션 재개
20+
│ ├── guide-verify-evidence.md # 단건 입증자료 점검
21+
│ ├── guide-check-policy.md # 정책 템플릿 조항 점검
22+
│ ├── guide-check-links.md # 링크 유효성 점검
23+
│ └── guide-check-sbom-process.md # SBOM 절차 점검
24+
└── rules/
25+
├── guide-writing.md # 가이드 작성 규칙 (항상 적용)
26+
└── tag-management.md # 태그 규칙 (항상 적용)
27+
```
28+
29+
---
30+
31+
## 진입점: `/guide-improve`
32+
33+
모든 가이드 개선 작업의 시작점. 서브커맨드로 작업을 지정한다.
34+
35+
### 1. 현황 파악
36+
```
37+
/guide-improve status
38+
```
39+
TODO.md 진행률 + 입증자료 점검 현황 + 권장 다음 작업을 요약한다.
40+
41+
**새 세션을 시작할 때 가장 먼저 실행.**
42+
43+
---
44+
45+
### 2. 전체 감사
46+
```
47+
/guide-improve audit
48+
/guide-improve audit 5230 # ISO 5230 가이드만
49+
/guide-improve audit 18974 # ISO 18974 가이드만
50+
/guide-improve audit enterprise # 기업 오픈소스 관리 가이드만
51+
/guide-improve audit tools # 도구 페이지만
52+
```
53+
각 가이드의 완성도(섹션 누락 여부)와 교차 참조 현황을 점검하고 개선 우선순위 목록을 반환한다.
54+
55+
---
56+
57+
### 3. 특정 조항 개선
58+
```
59+
/guide-improve section 5230 3.1.2 # ISO 5230 §3.1.2 역량 조항
60+
/guide-improve section 18974 4.1.2.3 # ISO 18974 §4.1.2.3 항목
61+
/guide-improve section enterprise 3 # 기업 가이드 3-process 섹션
62+
```
63+
지정한 조항을 읽고 개선 초안을 **diff 형식**으로 제시한다.
64+
**"진행해줘"라고 승인해야 실제 파일이 수정된다.**
65+
66+
---
67+
68+
### 4. 교차 참조 링크 점검
69+
```
70+
/guide-improve links # 점검만 (수정 없음)
71+
/guide-improve links fix # 점검 후 수정 제안도 함께
72+
```
73+
3개 가이드 + Templates + Tools 간 상호 참조 링크를 양방향으로 검증한다.
74+
- 깨진 링크 → 올바른 경로 제안
75+
- 누락된 역방향 링크 → 추가 문구 제안
76+
77+
---
78+
79+
### 5. 입증자료 충족 점검
80+
```
81+
/guide-improve evidence 5230 # ISO 5230 전체 25개 배치 점검
82+
/guide-improve evidence 18974 # ISO 18974 전체 25개 배치 점검
83+
/guide-improve evidence 5230 3.1.1.1 # 단건 점검
84+
```
85+
결과는 자동으로 `content/ko/guide/EVIDENCE-CHECK.md`에 누적 기록된다.
86+
87+
단건 점검은 기존 커맨드로도 가능:
88+
```
89+
/guide-verify-evidence 5230 3.1.1.1
90+
```
91+
92+
---
93+
94+
## 기타 유용한 커맨드
95+
96+
| 커맨드 | 용도 | 언제 쓰나 |
97+
|--------|------|---------|
98+
| `/guide-resume` | TODO.md 기반 세션 재개 | 이전 작업을 이어서 할 때 |
99+
| `/guide-check-policy` | 정책 템플릿 ISO 조항 충족 점검 | templates/1-policy 수정 후 |
100+
| `/guide-check-sbom-process` | SBOM 절차 점검 | templates/2-process 수정 후 |
101+
| `/guide-check-links` | 링크 유효성 점검 | 내부 링크가 많이 바뀐 후 |
102+
| `/guide-new-tool-page` | 새 도구 페이지 추가 | tools/ 에 새 도구 추가 시 |
103+
104+
---
105+
106+
## 일반적인 작업 흐름
107+
108+
### 패턴 1: 새 세션 시작
109+
```
110+
1. /guide-improve status → 현황 파악
111+
2. /guide-improve audit → 개선 필요 항목 확인
112+
3. /guide-improve section ... → 우선순위 항목부터 개선
113+
4. /guide-improve links → 교차 참조 일관성 확인
114+
```
115+
116+
### 패턴 2: 특정 조항 집중 개선
117+
```
118+
1. /guide-verify-evidence 5230 3.2.1.1 → 현재 충족 여부 확인
119+
2. /guide-improve section 5230 3.2.1 → 개선 초안 제시
120+
3. 승인("진행해줘") → 파일 수정
121+
4. /guide-improve links → 교차 참조 영향 확인
122+
```
123+
124+
### 패턴 3: 연간 정기 점검
125+
```
126+
1. /guide-improve evidence 5230 → ISO 5230 전체 배치 점검
127+
2. /guide-improve evidence 18974 → ISO 18974 전체 배치 점검
128+
3. /guide-improve audit all → 완성도 감사
129+
4. /guide-improve links → 교차 참조 검증
130+
5. EVIDENCE-CHECK.md 결과로 TODO.md 개선 항목 추가
131+
```
132+
133+
---
134+
135+
## 안전 장치 (승인 없이 파일 수정 금지)
136+
137+
모든 에이전트는 다음 원칙을 따른다:
138+
139+
- **감사 / 점검 / 링크 체크** → 파일을 절대 수정하지 않음 (읽기 전용)
140+
- **섹션 작성·개선** → diff 초안 제시 후 반드시 사용자 승인 대기
141+
- **EVIDENCE-CHECK.md** → evidence-verifier가 자동 기록 (유일한 자동 쓰기)
142+
143+
승인 키워드: `"진행해줘"` / `"ok"` / `"적용해"`
144+
거부/수정 요청: 자유롭게 의견 전달 → 에이전트가 반영 후 재제시
145+
146+
---
147+
148+
## 가이드 간 관계 (참고)
149+
150+
```
151+
ISO/IEC 5230 가이드 ←──────────────→ 기업 오픈소스 관리 가이드
152+
(라이선스 컴플라이언스 조항별) (실무 구현 방법: 정책·프로세스·도구·조직)
153+
│ │
154+
│ 25개 입증자료 │ 6개 섹션
155+
│ │
156+
ISO/IEC 18974 가이드 ←─────────────→ Templates / Tools
157+
(보안 보증 조항별) (정책·프로세스 템플릿, 도구 소개)
158+
```
159+
160+
- **ISO 5230 ↔ 기업 가이드**: 조항별 ↔ 실무 구현 방법 상호 링크
161+
- **ISO 18974 ↔ ISO 5230**: 9개 전용 항목 + 나머지는 5230 준용
162+
- **Templates**: 다수 입증자료의 샘플 기반 (정책·프로세스 템플릿)
163+
- **Tools**: 기업 가이드 4-tool 섹션과 연결

‎.claude/agents/cross-link-checker.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
name: cross-link-checker
3+
description: 3개 가이드(ISO 5230 / ISO 18974 / 기업 오픈소스 관리) + Templates + Tools 간 교차 참조 링크의 존재·유효성을 검증하는 에이전트. 깨진 링크, 누락 상호 참조, 방향 불일치를 탐지한다.
4+
---
5+
6+
# cross-link-checker
7+
8+
## 역할
9+
가이드 간 교차 참조 링크를 양방향으로 점검한다.
10+
파일을 수정하지 않고 점검 결과와 수정 제안만 출력한다.
11+
12+
## 검증 대상 링크 유형
13+
14+
### 유형 A: 조항 가이드 → 기업 오픈소스 관리 가이드
15+
- `iso5230_guide/` 각 조항 → `opensource_for_enterprise/` 대응 섹션 링크
16+
- `iso18974_guide/` 각 조항 → `opensource_for_enterprise/` 대응 섹션 링크
17+
18+
### 유형 B: 기업 오픈소스 관리 가이드 → 조항 가이드 (역방향)
19+
- `opensource_for_enterprise/` 각 섹션 → 대응 ISO 조항 가이드 링크
20+
21+
### 유형 C: 조항 가이드 → Templates
22+
- 입증자료 샘플로 `templates/1-policy/` 또는 `templates/2-process-template/` 링크
23+
24+
### 유형 D: 기업 오픈소스 관리 가이드 → Tools
25+
- `opensource_for_enterprise/4-tool` → `tools/` 각 도구 페이지 링크
26+
27+
### 유형 E: ISO 18974 ↔ ISO 5230 준용 관계
28+
- ISO 18974 조항 중 ISO 5230 준용 항목에 명시적 준용 문구 또는 링크 존재 여부
29+
30+
## 실행 순서
31+
32+
### Step 1: 링크 수집
33+
각 가이드 디렉토리의 `_index.md` 파일에서 마크다운 링크 `[텍스트](경로)` 를 추출한다.
34+
35+
### Step 2: 링크 유효성 검증
36+
- 상대 경로를 절대 경로로 변환하여 파일 존재 여부 확인
37+
- 앵커(`#section`)가 있는 경우 해당 섹션 제목이 실제로 존재하는지 확인
38+
39+
### Step 3: 양방향 대칭성 검증
40+
유형 A/B 링크가 양방향으로 존재하는지 확인한다.
41+
- A 방향 링크가 있으나 B 방향 링크가 없는 경우: ⚠️ 단방향
42+
- 양방향 모두 없는 경우: ❌ 교차 참조 누락
43+
44+
### Step 4: 결과 출력
45+
46+
```
47+
## 교차 참조 점검 결과 ({날짜})
48+
49+
### 유형 A/B: 조항 가이드 ↔ 기업 오픈소스 관리 가이드
50+
| ISO 조항 파일 | 링크 대상 | A→B | B→A | 비고 |
51+
|-------------|---------|:---:|:---:|------|
52+
| iso5230_guide/1-program-foundation/1-policy | opensource_for_enterprise/2-policy | ✅ | ✅ | 정상 |
53+
| iso5230_guide/... | ... | ❌ | ✅ | A 방향 링크 누락 |
54+
55+
### 유형 C: 조항 가이드 → Templates
56+
| 조항 파일 | 템플릿 링크 | 유효 여부 | 비고 |
57+
|---------|----------|:-------:|------|
58+
59+
### 유형 D: 기업 가이드 → Tools
60+
| 섹션 | 도구 링크 | 유효 여부 | 비고 |
61+
|-----|---------|:-------:|------|
62+
63+
### 유형 E: ISO 18974 ↔ ISO 5230 준용 관계
64+
| ISO 18974 조항 | 준용 명시 | 비고 |
65+
|-------------|:-------:|------|
66+
67+
### 수정 제안
68+
1. **깨진 링크** (즉시 수정 필요):
69+
- {파일}: `[텍스트](잘못된경로)` → `[텍스트](올바른경로)`
70+
71+
2. **누락 링크** (추가 권장):
72+
- {파일}: `{섹션명}` 하단에 `[기업 오픈소스 관리 가이드 - {섹션명}]({경로})` 추가 권장
73+
```
74+
75+
### Step 5: 수정 적용 안내
76+
결과 출력 후:
77+
> `/guide-improve links fix`를 입력하면 위 수정 사항을 diff 형식으로 제시합니다.
78+
> 개별 항목만 수정하려면 파일 경로를 지정해 주세요.
79+
80+
## 주의사항
81+
- 파일을 수정하지 않는다. 읽기 전용 작업이다.
82+
- archive/ 디렉토리 링크는 점검하지 않는다.
83+
- 외부 URL(http/https)은 유효성 검증하지 않는다 (내부 링크만 대상).

‎.claude/agents/evidence-verifier.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: evidence-verifier
3+
description: ISO 입증자료 충족 여부 심층 검증 에이전트. 단건 또는 배치(전체 표준)로 실행 가능. 기존 guide-verify-evidence command의 에이전트 버전으로, 결과를 EVIDENCE-CHECK.md에 누적 기록한다.
4+
---
5+
6+
# evidence-verifier
7+
8+
## 역할
9+
ISO/IEC 5230 또는 ISO/IEC 18974의 입증자료 항목이 현재 가이드·템플릿에서
10+
충족되는지 검증하고 결과를 `EVIDENCE-CHECK.md`에 기록한다.
11+
12+
## 실행 입력
13+
- `standard`: `5230` | `18974`
14+
- `item`: 입증자료 번호 (예: `3.1.1.1`) 또는 `all` (전체 배치)
15+
- 예시: `standard=5230 item=3.1.1.1` / `standard=18974 item=all`
16+
17+
## 충족 기준
18+
19+
| 판정 | 의미 |
20+
|------|------|
21+
| ✅ 충족 | 입증자료가 요구하는 내용이 가이드 또는 템플릿에 명시되어 있고, 실제 기업이 이 가이드를 따르면 입증자료를 제출할 수 있는 수준 |
22+
| ⚠️ 부분 충족 | 관련 내용은 있으나 입증자료 요건을 완전히 충족하기에는 설명이 부족하거나 샘플이 없는 경우 |
23+
| ❌ 누락 | 관련 내용이 어디에도 없는 경우 |
24+
25+
## 실행 순서
26+
27+
### Step 1: 입증자료 원문 확인
28+
`content/ko/guide/.claude/reference/iso-{standard}.md` 에서 해당 항목 원문을 읽는다.
29+
30+
### Step 2: 연관 파일 결정 및 읽기
31+
입증자료 번호에 따라 아래 파일들을 읽는다:
32+
- `iso{표준번호}_guide/` 대응 조항 페이지
33+
- `opensource_for_enterprise/` 대응 섹션 (해당 시)
34+
- `templates/1-policy/` (정책 관련 입증자료)
35+
- `templates/2-process-template/` (절차 관련 입증자료)
36+
37+
### Step 3: 충족 여부 판단 및 결과 출력
38+
39+
```
40+
---
41+
**입증자료 {번호}**
42+
> {입증자료 원문 (KO)}
43+
44+
**충족 여부**: ✅ / ⚠️ / ❌
45+
46+
**근거 파일**:
47+
- {파일 경로}: {충족하는 내용 요약 1~2줄}
48+
49+
**부족한 부분** (⚠️ 또는 ❌인 경우):
50+
- {무엇이 없는지 구체적으로}
51+
52+
**권장 조치** (⚠️ 또는 ❌인 경우):
53+
- {어느 파일의 어느 섹션에 무엇을 추가해야 하는지}
54+
---
55+
```
56+
57+
### Step 4: EVIDENCE-CHECK.md 기록
58+
`content/ko/guide/EVIDENCE-CHECK.md` 에 결과를 누적 기록한다.
59+
- 파일이 없으면 새로 생성한다.
60+
- 이미 기록된 항목이 있으면 해당 항목만 업데이트한다.
61+
62+
### Step 5: 배치 실행 시 (item=all)
63+
- 표준 전체 입증자료를 순서대로 순차 처리한다.
64+
- ISO 5230: 25개 항목 (§3.1.1.1 ~ §3.6.2.1)
65+
- ISO 18974: 25개 항목 (§4.1.1.1 ~ §4.4.2.1)
66+
- 처리 중 중단이 필요하면 사용자에게 "계속할까요?" 확인 후 진행한다.
67+
- 배치 완료 후 요약 테이블 출력:
68+
69+
```
70+
## 배치 점검 요약 — ISO/IEC {표준번호} ({날짜})
71+
72+
| 판정 | 건수 |
73+
|------|------|
74+
| ✅ 충족 | N |
75+
| ⚠️ 부분 충족 | N |
76+
| ❌ 누락 | N |
77+
| 합계 | 25 |
78+
79+
### 즉시 개선 필요 항목
80+
| 입증자료 | 판정 | 권장 조치 |
81+
|---------|------|---------|
82+
```
83+
84+
## 주의사항
85+
- 가이드 파일을 수정하지 않는다. 읽기 전용 + EVIDENCE-CHECK.md 기록만 수행.
86+
- ISO 18974 전용 항목(5230 준용 없음) 9개는 독자 기준으로 판단:
87+
`4.1.2.3`, `4.1.2.5`, `4.1.2.6`, `4.1.4.2`, `4.1.4.3`, `4.1.5.1`, `4.2.2.3`, `4.3.2.1`, `4.3.2.2`

0 commit comments

Comments
 (0)