Skip to content

CLAUDE.md

Latest commit

 

History

History
206 lines (145 loc) · 14.8 KB

CLAUDE.md

File metadata and controls

206 lines (145 loc) · 14.8 KB
Raw

trustedoss

ISO/IEC 5230 (라이선스 컴플라이언스)과 ISO/IEC 18974 (보안 보증) 자체 인증을 위한 실전 키트. 챕터·Agent·산출물 전체 목록은 README.md 참조.

작업 범위

이 프로젝트는 콘텐츠가 중심이다. 아래 표는 기본 분류이며, 2026-06 스코프 완화로 "작업 금지(X)" 항목(website/src·설정·navbar/sidebar 등)도 고도화 목적이면 가드레일 하에 변경할 수 있다.

작업 대상 (O) 작업 금지 (X)
docs/ website/src/ (아래 예외 제외)
agents/ website/static/
templates/ website/src/**/*.ts (아래 예외 제외)
.claude/ website/src/**/*.tsx
CLAUDE.md *.js, *.css, *.scss (아래 예외 제외)
website/ai-coding/ (md만) 설정 파일 전체
website/devsecops/ (md만)

스코프 완화 (2026-06): 위 "작업 금지(X)" 항목도 고도화(쉬운·간결 콘텐츠, 실습·데모·메뉴·디자인 패리티) 목적이면 아래 가드레일 하에 변경 가능하다.

  1. 브랜드 — POSITIONING.md §5 준수. 제품(포털) 팔레트에 굴복 금지, 중립 공용 토큰 원칙. 브랜드 토큰(주색상·폰트·로고) 변경 시 POSITIONING 근거를 명시한다.
  2. 최소 변경 — 무분별한 재디자인 금지. 고도화 목표에 직접 기여하는 변경만 한다.
  3. 검증 — 변경 후 verify.sh 13/13, 디자인/코드 변경 시 cd website && npm run build 통과.
  4. 큰 변경은 확인 — 대규모 구조·디자인 변경은 방향을 사용자에게 먼저 확인한다.

website/src/css/customTheme.scss 의 sidebar 계층·테이블 가독성 CSS는 위 가드레일과 무관하게 계속 허용한다.

디렉토리 구조

경로 역할
docs/ 챕터별 가이드 문서
agents/ 산출물 자동 생성 agent
templates/ 문서 템플릿
samples/ 실습용 샘플 프로젝트
output/ 생성된 산출물 (gitignore)
.claude/skills/ 재사용 skill 정의
.claude/archive/ 역할이 끝난 일회성 문서 보관
website/ai-coding/ AI 코딩 가이드 페이지 (md)
website/devsecops/ DevSecOps 가이드 페이지 (md)

독자 상태 감지 — 다음 단계 안내

"어디서 시작해야 해?" 또는 "다음에 뭘 해야 해?" 질문 시 output/ 폴더를 스캔하고 아래 표로 안내한다.

output/ 상태 안내
비어있음 "시작하기 전에"(docs/00-overview/index.md) 및 "소프트웨어 공급망 보안: 왜 지금 중요한가"(docs/00-overview/supply-chain.md) 읽기 → 현재 Claude 세션 종료 후 cd agents/02-organization-designer && claude 실행
organization/ 있음, policy/ 없음 현재 Claude 세션 종료 후 cd agents/03-policy-generator && claude 실행
policy/ 있음, process/ 없음 현재 Claude 세션 종료 후 cd agents/04-process-designer && claude 실행
process/ 있음, sbom/ 없음 현재 Claude 세션 종료 후 cd agents/05-sbom-guide && claude 실행
sbom/ 있음, sbom-management-plan.md 없음 현재 Claude 세션 종료 후 cd agents/05-sbom-analyst && claude 실행 → 완료 후 cd agents/05-sbom-management && claude 실행
sbom-management-plan.md 있음, vulnerability/ 없음 현재 Claude 세션 종료 후 cd agents/05-vulnerability-analyst && claude 실행
vulnerability/ 있음, training/ 없음 현재 Claude 세션 종료 후 cd agents/06-training-manager && claude 실행
training/ 있음, conformance/ 없음 현재 Claude 세션 종료 후 cd agents/07-conformance-preparer && claude 실행
conformance/ 있음 완성 축하 → OpenChain 자체 인증 등록: https://openchainproject.org/get-started

사용 경로

  • 셀프스터디: docs/ 챕터를 00부터 순서대로 진행

Skills — 언제 쓰는가

파일 트리거 조건
.claude/skills/create-doc.md docs/ 하위 문서를 새로 작성하거나 수정할 때. website/ai-coding/ 및 website/devsecops/ 하위 .md 작성 시에는 해당 폴더의 기존 파일 front matter 패턴을 따르고 create-doc.md 스킬은 적용하지 않음
.claude/skills/validate-checklist.md agents/07-conformance-preparer 또는 output/ 전체 완료 여부 점검 시
.claude/skills/generate-report.md SBOM 분석·취약점 분석·갭 분석 리포트를 생성할 때
.claude/skills/update-reference-samples.md output/ 또는 output-sample/ 갱신 후 website/reference/samples/ 페이지 재생성 시
.claude/skills/qa-loop/skill.md 파일 수정 후 품질 자동 검사·수정·검증 1회 실행 (/qa changed)
.claude/skills/diff-scope/skill.md qa-loop 내부 자동 호출 — git 변경 범위 계산 (직접 호출 불필요)
.claude/skills/kwg-check/skill.md KWG 원본과 싱크 확인 (/kwg-check) — 분기별 또는 KWG 업데이트 시

Agents — 언제 쓰는가 (QA 하네스)

/qa 슬래시 커맨드가 아래 에이전트를 자동으로 조율한다. 직접 호출은 특수 상황에서만.

파일 역할 직접 호출 시나리오
.claude/agents/qa-reviewer.md docs·agents·templates 품질 이슈 탐지 /qa 사용 권장
.claude/agents/doc-fixer.md qa-reviewer 이슈 자동 교정 /qa 사용 권장
.claude/agents/iso-verifier.md output/ ISO G항목 정합성 검증 /qa iso
.claude/agents/content-auditor.md docs/ 챕터 완성도 감사 /qa 03 (챕터 번호)
.claude/agents/kwg-drift-checker.md KWG 원본 의미론적 갭 분석 /kwg-check (자동 호출)

샘플 페이지 갱신 워크플로우

agents/ 실행으로 output/ 파일이 갱신된 후 샘플 페이지를 최신화하는 순서:

# 1. output/ → output-sample/ 동기화
bash .claude/scripts/sync-output-samples.sh

# 2. website/reference/samples/ 재생성 (Claude 스킬)
# /update-reference-samples

# 3. 검증
bash .claude/scripts/verify.sh

작업 완료 후 필수 규칙

1. 검증 실행

파일 생성·수정 후 반드시 실행하라.

bash .claude/scripts/verify.sh

검증 항목: Docusaurus 빌드 / 내부 링크 / front matter YAML / 필수 파일 / 로컬 경로 노출 / 18974 섹션 번호 형식 / agent 실행 admonition 누락 / ISO 커버리지 정합성 / output/ 산출물 완전성 / Agent 스펙 구조 / 골든 픽스처 회귀 / agent 체인 연결 / ko·en 문서 패리티 모든 항목 PASS 후에만 push 가능. push 전 5단계 절차는 CONTRIBUTING.md 참조.

verify.sh FAIL 처리 기준: FAIL 항목이 이번 변경 이전부터 존재하던 것인지 먼저 확인하라. git diff로 해당 파일을 건드리지 않았다면 기존 이슈로 간주하고 조사하지 않는다. 새로 발생한 FAIL만 수정한다.

2. 경로 규칙

구분 패턴 예시
금지 사용자명 포함 절대경로 ~username/..., C:\Users\사용자명\...
허용 상대 경로 ./docs/...
허용 홈 디렉토리 약칭 ~/
허용 일반화 예시 경로 /path/to/trustedoss

명령어 예시·스크립트·에러 인용·README 설치 가이드 모두 동일 규칙 적용.

docs/ → reference/ 크로스 인스턴스 링크

docs/ 문서에서 website/reference/ 페이지를 참조할 때는 Docusaurus 절대 경로를 사용한다.

구분 형식 예시
올바름 /reference/samples/{name} /reference/samples/sbom
금지 상대 경로로 reference/ 접근 ../../website/reference/...

verify.sh 링크 체크는 /로 시작하는 절대 경로를 자동으로 건너뛴다 (Docusaurus 라우팅 경로로 처리).

3. 스펙 섹션 번호 표기 규칙

ISO/IEC 5230과 18974는 섹션 번호 체계가 다르다. 혼용하면 verify.sh [6/6] 항목이 FAIL을 낸다.

표준 섹션 번호 체계 올바른 예 잘못된 예
ISO/IEC 5230 3.x.x 3.1.1, 3.3.2, 3.6.1 —
ISO/IEC 18974 4.x.x 4.1.1, 4.3.2, 4.4.1 3.1.1, 3.3.2

스펙 전문은 .claude/reference/iso-5230.md 및 .claude/reference/iso-18974.md 참조.

4. 상태·심각도 기호 규칙

산출물 표 형식과 짝을 이루는 상태·심각도 기호(충족 ✅/🔶/❌, CVSS 🔴/🟠/🟡/🟢/⚪)는 STYLEGUIDE.md §7 예외로 유지한다. ko-style 린트가 이모지로 지적해도 제거하지 않는다. 그 외 불릿 장식·감정 이모지는 금지.

5. settings 파일 규칙

파일 용도 로컬 경로 커밋
settings.json 프로젝트 공통 절대 금지 가능
settings.local.json 로컬 전용 사용 가능 금지

로컬에서만 필요한 설정은 반드시 settings.local.json 에 작성하라.

파일 탐색 원칙

파일에서 특정 패턴(헤더, 키워드, 줄)을 찾을 때는 Read 전에 Grep을 먼저 사용하라.

  • 파일 전체가 필요한 경우에만 Read를 쓴다.
  • 사용자가 지목한 파일만 스코프에 포함한다. 관련이 있어 보여도 명시되지 않은 파일은 읽지 않는다.

막혔을 때

해당 docs/ 챕터 폴더로 이동하면 그 폴더의 CLAUDE.md 가 맥락을 제공한다.

하네스 운영 방법(슬래시 커맨드, 에이전트, 스크립트 상세 사용법)은 .claude/harness-guide.md 참조.

진행 상황

.claude/progress.md 참조

CLAUDE.md 업데이트 규칙

아래 상황 발생 시 CLAUDE.md를 즉시 업데이트하라.

상황 업데이트 항목
새 챕터/Agent 추가 독자 상태 감지 테이블
새 스킬 파일 추가 스킬 트리거 테이블
디렉토리 구조 변경 핵심 경로 섹션
새 규칙/제약 발견 해당 규칙 섹션
하네스 구조 변경 .claude/harness-guide.md

업데이트 후 변경 내용을 커밋 메시지에 명시하라. 예: "docs: update CLAUDE.md - add devsecops agent trigger"

세션 종료 전 체크리스트

매 작업 세션 종료 전 아래를 순서대로 실행하라.

  • bash .claude/scripts/verify.sh 실행 후 13/13 모두 PASS 확인
  • .claude/progress.md 업데이트 (완료 항목 체크, 다음 작업 갱신)
  • 이번 세션에서 구조 변경이 있었으면 CLAUDE.md도 업데이트
  • git commit