project-baseline
테스트 가능한 준비 기준: 69개의 규칙, 각 규칙은 제로 의존성 Node 러너가 저장소를 정적으로 분석하여 실행하는 검사로 뒷받침됩니다. 블로커는 CI를 실패시키고(exit 1); 스크립트가 판단할 수 없는 사안은 날짜가 기록된 서명 원장(sign-off ledger)을 통해 해결합니다. 핵심 요점: 문서화된 약속을 신뢰하지 말고 — 검증 가능한 것으로 확인하세요.
도구 키트는 이 파일과 같은 디렉터리에 있습니다: check.mjs(러너), rules.json(69개 규칙), config.example.json, templates/, README.md(빠른 시작 가이드), REFERENCE.md(전체 참조: 규칙 표, 카테고리, 아키텍처 다이어그램, CI 연동), GLOSSARY.md(DevOps/공급망 용어에 대한 쉬운 설명).
먼저 스킬 디렉터리를 확인하세요. 아래 $SKILL_DIR은 이 SKILL.md가 포함된 디렉터리의 절대 경로를 의미합니다 — 명령어를 실행하기 전에 반드시 구체적인 경로로 확인하세요(리터럴 문자열 $SKILL_DIR을 쉘에 전달하지 마십시오). 일반적으로 ~/.claude/skills/baseline입니다. check.mjs는 자신의 디렉터리에서 rules.json을 로드하므로 두 파일은 같은 위치에 있어야 합니다; 항상 절대 경로로 러너를 호출하고(node "<abs>/check.mjs" …) 다른 곳으로 복사하지 마십시오. 러너는 Node ≥ 18과 git만 필요합니다; node가 없으면 추측하지 말고 사용자에게 알려주세요.
호출 시
사용자의 말에서 의도를 파악하고 모드를 선택합니다. 명시되지 않은 경우 기본값은 **점수(score)**입니다.
모드: 점수(score, 기본값) — "baseline 실행", "/baseline", "이 저장소 확인"
- 대상 저장소 선택: 요청에 명시된 경로가 있으면 해당 경로, 없으면 현재 작업 디렉터리. 저장소처럼 보이는지 확인(manifest 또는
.git이 있는지). - 러너 실행(사람이 읽을 수 있는 형태):
node "$SKILL_DIR/check.mjs" --repo <target>- 신뢰할 수 없는 저장소, 테스트를 실행할 시간이 없거나 명령어가 설정되지 않은 경우 등 저장소의 부트스트랩/테스트 명령어(BUILD-05)를 실행하지 말아야 한다면
--no-exec를 추가하세요. 안전할 때는 실행하는 것을 선호합니다. BUILD-05가 가장 중요한 검사이기 때문입니다. - 사용자가 전문가 규칙(SBOM, 코드 스캐닝, 변이 테스트, 심볼 무결성, 의존성 취약점 스캔, 커버리지 기준)을 원하면
--profile advanced를 추가하세요.project_type=service인 경우service프로필이 자동으로 활성화됩니다. - 결과를 점수표 대신 프로그래밍 방식으로 분석하려면
--json을 추가하세요.
- 신뢰할 수 없는 저장소, 테스트를 실행할 시간이 없거나 명령어가 설정되지 않은 경우 등 저장소의 부트스트랩/테스트 명령어(BUILD-05)를 실행하지 말아야 한다면
- 결과를 사용자에게 제시하며, 블로커(CI를 실패시키는 항목)를 먼저 보여주고, 그 다음으로 수정할 가치가 있는 경고를 보여줍니다. 카테고리별로 그룹화합니다. 69개 행을 모두 덤프하지 말고 요약하세요: 준비율, 블로커 개수, 그리고 구체적인 FAIL/주목할 만한 WARN과 그 한 줄 설명. 수정 또는 스캐폴딩을 제안하세요.
모드: 초기화(init) — "여기에 baseline 설정", "표준 채택", "baseline 스캐폴드"
- 도구 키트를 저장소에 복사하거나(
tools/baseline/제안), 제자리에서 참조합니다. - 아티팩트를 스캐폴드합니다. 누락된 경우에만 수행하고, 묻지 않고 덮어쓰지 않습니다:
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # 저장소가 외부 주장을 하는 경우에만 cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # 상태 문서가 없는 경우 mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json baseline.config.json을 저장소의 실제 상황에 맞게 편집합니다:project_type,bootstrap_command(BUILD-05를 위한 클린 체크아웃 설치+테스트 명령어),makes_external_claims(false이면 CLAIM-* 규칙을 건너뜁니다)를 설정합니다. 옵트인*_globs키(freshness/generated/grounding)는 저장소가 해당 규칙을 채택할 때까지 비워둡니다.README.md의 CI 연동 방법을 보여주고baseline작업을 필수 검사로 만듭니다(규칙 BUILD-06).- 첫 번째 점수를 실행합니다.
모드: 수정(fix) — "baseline 실패 수정", "이것을 통과 상태로"
- 먼저 점수를 냅니다. 사용자가 해결하려는 각 블로커/경고에 대해, 규칙 자체의
fix필드(rules.json에서 읽음)를 저장소에 구체적인 편집으로 적용합니다 — 라이선스 추가, 액션을 SHA로 고정,.gitignore에.env추가 및 시크릿 교체, 네거티브 테스트 추가 등. manual(서명) 규칙의 경우, 검사를 가장하지 말고 사용자가 판단(블래스트 반경, 사전 사례 검토, 웨지/모트)을 내릴 수 있도록 돕고.project-baseline/signoff.json에 날짜를 기록한 항목을 추가합니다.- 재점수하여 확인합니다.
모드: 설명(explain) — "SEC-03이 무엇을 검사하나요?", "CTX-05가 왜 실패했나요?"
rules.json에서 규칙(각각 title, rationale, fix, source, check 포함)을 읽고 평이하게 설명하며, 러너가 실제로 무엇을 찾았는지도 설명합니다. 익숙하지 않은 전문 용어(SBOM, SLSA, 출처, 서명 원장, …)에 대해서는 이 디렉터리의 GLOSSARY.md에 쉬운 설명이 있습니다.
러너가 결정하는 방법(상세 행을 해석할 수 있도록)
- 규칙당 PASS / FAIL / WARN / SIGN-OFF / SKIP.
blocker인 FAIL만 종료 코드 1을 설정합니다. - SKIP은 규칙이 적용되지 않음을 의미합니다: 잘못된
project_type(<type>에 해당 없음), 프로필이 꺼져 있음(profile 'advanced' off), 채택되지 않은 옵트인 기능, 또는 확인할 항목이 없음. SKIP은 준비율에 영향을 주지 않습니다. - 프로필:
core는 항상 실행됩니다;service는project_type=service일 때 자동 실행됩니다;advanced는--profile advanced또는 설정의profiles:["advanced"]로만 실행됩니다. - 주장(claims)은 옵트인: CLAIM-*은 클레임 레지스터가 존재하거나
makes_external_claims:true가 명시적으로 설정된 경우에만 실행됩니다. 클레임 레지스터가 없는 저장소는 불이익을 받지 않습니다. - 설정은 합리적으로 자동 감지합니다; 저장소 루트의
baseline.config.json이 이를 재정의합니다. 키는config.example.json에 문서화되어 있습니다. - 러너는 제로 의존성(Node ≥ 18 + git)이며 충돌에 강합니다: 평가할 수 없는 규칙의 검사는 SKIP으로 전환되어 실행 자체를 중단시키지 않습니다.
참고 사항
- 경고를 블로커로 또는 그 반대로 제시하지 마십시오 — 심각도는
rules.json과 러너의 출력에 있습니다. - 저장소를 신뢰할 수 있고 부트스트랩 명령어가 설정된 경우 BUILD-05를 실제로 실행하는 것을 선호하세요(
--no-exec생략) — 녹색의 가장 중요한 검사는 가장 강력한 단일 신호입니다. - 전체 근거, 규칙 표, 카테고리 설명, 아키텍처 다이어그램 및 CI 스니펫은 이 디렉터리의
REFERENCE.md에 있습니다 — 사용자가 깊이를 원하면 읽어보세요.