Communitygithub.com

AdarGit008/baseline-skill

Claude Code용 /baseline 스킬 — 제로 의존성 프로젝트 준비 상태 검사기(69개 규칙). ~/.claude/skills/baseline에 설치하세요.

baseline-skill란 무엇인가요?

baseline-skill은 Claude Code와 같은 AI 에이전트가 프로젝트 저장소의 '준비 상태(readiness)'를 자동으로 평가하고 개선할 수 있도록 설계된 스킬입니다. 69개의 테스트 가능한 규칙 각각은 제로 의존성 Node.js 러너(`check.mjs`)가 저장소를 정적으로 분석하여 PASS, FAIL, WARN, SIGN-OFF, SKIP 상태를 반환합니다. CI 파이프라인에서 FAIL(블로커)이 발생하면 종료 코드 1로 실패하여 병합을 차단하며, 자동화된 검사로 판단할 수 없는 항목(예: 보안 위험 평가)은 서명 로그(sign-off ledger)를 통해 인간의 판단을 기록합니다. 점수(score), 초기화(init), 수정(fix), 설명(explain)의 네 가지 모드를 지원하며, 사용자의 말에서 의도를 파악하여 적절히 동작합니다. 핵심 철학은 '문서화된 약속을 신뢰하지 말고, 검증 가능한 것으로 확인하라'는 것입니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add AdarGit008/baseline-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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", "이 저장소 확인"

  1. 대상 저장소 선택: 요청에 명시된 경로가 있으면 해당 경로, 없으면 현재 작업 디렉터리. 저장소처럼 보이는지 확인(manifest 또는 .git이 있는지).
  2. 러너 실행(사람이 읽을 수 있는 형태):
    node "$SKILL_DIR/check.mjs" --repo <target>
    
    • 신뢰할 수 없는 저장소, 테스트를 실행할 시간이 없거나 명령어가 설정되지 않은 경우 등 저장소의 부트스트랩/테스트 명령어(BUILD-05)를 실행하지 말아야 한다면 --no-exec를 추가하세요. 안전할 때는 실행하는 것을 선호합니다. BUILD-05가 가장 중요한 검사이기 때문입니다.
    • 사용자가 전문가 규칙(SBOM, 코드 스캐닝, 변이 테스트, 심볼 무결성, 의존성 취약점 스캔, 커버리지 기준)을 원하면 --profile advanced를 추가하세요. project_type=service인 경우 service 프로필이 자동으로 활성화됩니다.
    • 결과를 점수표 대신 프로그래밍 방식으로 분석하려면 --json을 추가하세요.
  3. 결과를 사용자에게 제시하며, 블로커(CI를 실패시키는 항목)를 먼저 보여주고, 그 다음으로 수정할 가치가 있는 경고를 보여줍니다. 카테고리별로 그룹화합니다. 69개 행을 모두 덤프하지 말고 요약하세요: 준비율, 블로커 개수, 그리고 구체적인 FAIL/주목할 만한 WARN과 그 한 줄 설명. 수정 또는 스캐폴딩을 제안하세요.

모드: 초기화(init) — "여기에 baseline 설정", "표준 채택", "baseline 스캐폴드"

  1. 도구 키트를 저장소에 복사하거나(tools/baseline/ 제안), 제자리에서 참조합니다.
  2. 아티팩트를 스캐폴드합니다. 누락된 경우에만 수행하고, 묻지 않고 덮어쓰지 않습니다:
    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
    
  3. baseline.config.json을 저장소의 실제 상황에 맞게 편집합니다: project_type, bootstrap_command(BUILD-05를 위한 클린 체크아웃 설치+테스트 명령어), makes_external_claims(false이면 CLAIM-* 규칙을 건너뜁니다)를 설정합니다. 옵트인 *_globs 키(freshness/generated/grounding)는 저장소가 해당 규칙을 채택할 때까지 비워둡니다.
  4. README.md의 CI 연동 방법을 보여주고 baseline 작업을 필수 검사로 만듭니다(규칙 BUILD-06).
  5. 첫 번째 점수를 실행합니다.

모드: 수정(fix) — "baseline 실패 수정", "이것을 통과 상태로"

  1. 먼저 점수를 냅니다. 사용자가 해결하려는 각 블로커/경고에 대해, 규칙 자체의 fix 필드(rules.json에서 읽음)를 저장소에 구체적인 편집으로 적용합니다 — 라이선스 추가, 액션을 SHA로 고정, .gitignore에 .env 추가 및 시크릿 교체, 네거티브 테스트 추가 등.
  2. manual(서명) 규칙의 경우, 검사를 가장하지 말고 사용자가 판단(블래스트 반경, 사전 사례 검토, 웨지/모트)을 내릴 수 있도록 돕고 .project-baseline/signoff.json에 날짜를 기록한 항목을 추가합니다.
  3. 재점수하여 확인합니다.

모드: 설명(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에 있습니다 — 사용자가 깊이를 원하면 읽어보세요.

관련 스킬