제도적 지식으로서의 스킬 · AI 네이티브 SDLC 플레이북

스킬은 조직이 제도적 지식을 운영 가능하게 만드는 방법입니다. 지침은 명시적이고, 버전 관리되며, 광범위하게 적용되고, 정책이 변경될 때 중앙에서 업데이트됩니다. 경험칙은 다음과 같습니다: 일관되게 적용되어야 하는 제도적 지식에 대해서는 스킬을 작성하고, CLAUDE.md나 프롬프트에 속하는 구성 요소에 대해서는 스킬을 작성하지 마세요.

시작하기

전제 조건: 필수 사항 없음. CLAUDE.md가 있으면 에이전트의 작업 지식을 저장소 안에 유지할 수 있어 도움이 되지만, 스킬이 이에 의존하지는 않습니다.
인프라: 지정된 소유자와 문서화된 신뢰할 수 있는 출처를 가진 하나의 정책.

실행 방법

오늘날 일관되지 않게 적용되고 있는 지식 한 가지를 선택하세요. 이는 보안 표준, API 설계 규칙, 또는 브랜드 규칙일 수 있습니다.
이를 스킬로 작성하세요. 스킬은 SKILL.md를 포함하는 폴더로, 프런트매터에는 언제 트리거되는지가, 본문에는 무엇을 해야 하는지가 적혀 있습니다. 엔지니어는 정책 소유자의 신뢰할 수 있는 출처를 바탕으로 Claude의 도움을 받아 이를 작성합니다.
스킬을 저장소의 .claude/skills/<name>/에 배치하여 코드와 함께 배포하거나, 플러그인을 통해 조직 전체에 배포하세요.
스킬이 트리거되는지 테스트하세요. Claude에게 관련 작업을 여러 방식으로 요청하고 매번 스킬이 로드되는지 확인하세요.
정책이 변경되면 스킬을 변경하고 정책 소유자가 변경 사항을 승인하도록 하세요.
엔지니어는 다음 세션에서 자동으로 새 버전을 받게 됩니다.

실제 모습

.claude/skills/secure-api-review/SKILL.md:

markdown

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review
When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.
Run scripts/check-endpoints.sh and include its output in your summary.

거버넌스 고려 사항

스킬은 통제 수단이지만, 권고적인 성격을 가집니다. 코드가 작성되는 동안 Claude가 정책을 적용할 가능성을 높이지만, 세션이 이를 반드시 준수하도록 강제하지는 않습니다. 항상 지켜져야 하는 정책에는 스킬 뒤에 결정론적인 무언가가 필요합니다. 예를 들어 해당 작업을 차단하는 훅이나 PR에서 정책을 다시 확인하는 리뷰 단계가 그것입니다. 스킬은 위반을 드물게 만들고, 훅은 위반을 거의 불가능하게 만듭니다. 훅은 편집 시점에 위반을 포착하고, 풀 리퀘스트에서의 동일한 검사는 다른 방식으로 브랜치에 도달한 모든 것을 포착합니다. 스킬 호출은 세션 추적 기록에 로그로 남으며, 정책 소유자는 코드를 검토하듯 스킬 변경 사항을 검토합니다.

측정 방법

선행 지표: 정책 소유자가 정책 변경을 승인한 시점부터 업데이트된 스킬이 병합되기까지의 시간으로, 스킬 폴더에 대한 PR에서 측정합니다.
후행 지표: 정책을 인용하는 PR 리뷰 지적 사항으로, 스킬이 코드 작성 중에 정책을 적용하게 되면 0에 가까워져야 합니다. 지적 사항이 0에 가까워지지 않는 경우, 스킬이 트리거되지 않고 있거나 스킬의 텍스트가 공식 정책에서 벗어난 것입니다.

빌드 타임 가드레일로서의 훅

스킬은 권고적인 통제 수단인 반면, 훅은 그 뒤에 있는 결정론적 계층입니다. Claude의 작업 대부분은 구현 중의 파일 편집과 셸 명령이므로, 빌드 단계는 훅이 가장 자주 실행될 수 있는 지점입니다.

빌드 단계 훅은 다음을 수행할 수 있습니다:

생성된 클래스나 고정된 패키지와 같은 보호된 경로에 대한 편집 차단
파일 편집 후 포매터와 린터를 실행하여 드리프트가 누적되지 않도록 함
자격 증명이 diff에 포함되지 않도록 유지
예외 없이 지켜져야 하는 정책을 가진 모든 스킬을 뒷받침

훅은 일치하는 각 작업마다 실행되므로, 빌드 단계 훅은 빠르고 변경된 파일로 범위가 한정되어야 합니다. 전체 테스트 스위트와 같은 더 무거운 검사는 커밋이나 PR 단계에 속합니다.

이것이 이 페이지 앞부분에서 보여드린 secure-api-review 스킬의 규칙 4 뒤에 있는 훅입니다. 이 저장소는 한 보험사의 것이며, 엔드포인트 파일은 claims-api/routes/에 있습니다. 이 파일들 중 하나가 편집될 때마다, 훅은 스킬이 이미 명시한 저장소 루트의 스크립트인 scripts/check-endpoints.sh를 실행합니다. 이 스크립트는 OpenAPI 스키마에서 pii로 태그된 필드가 로그 호출이나 발생된 오류에 도달할 때 실패합니다.

이 훅은 .claude/settings.json에 등록되어 있습니다. 빈 args 목록은 Claude Code가 셸을 거치지 않고 스크립트를 직접 실행하도록 만듭니다:

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/api-policy.sh",
            "args": [] }
        ]
      }
    ]
  }
}

훅 스크립트인 .claude/hooks/api-policy.sh:

bash

#!/bin/bash
# secure-api-review 스킬의 규칙 4를 스킬이 실행하는 것과 동일한 스크립트로 뒷받침합니다.
file=$(jq -r '.tool_input.file_path')
case "$file" in
  "$CLAUDE_PROJECT_DIR"/claims-api/routes/*.py) ;;
  *) exit 0 ;;                                   # not an endpoint
esac
cd "$CLAUDE_PROJECT_DIR" || exit 2
if ! found=$(scripts/check-endpoints.sh "${file#"$CLAUDE_PROJECT_DIR"/}"); then
  echo "secure-api-review rule 4: a pii field reaches a log or an error message." >&2
  echo "$found" >&2
  exit 2
fi

편집 후에 실행되는 훅은 그 편집을 되돌릴 수 없으므로, 종료 코드 2는 스크립트의 메시지를 Claude 앞에 표시하여 Claude가 해당 줄을 수정할 수 있게 합니다. 고객의 이름을 로그에 남기는 편집 후, Claude가 스크립트로부터 보게 되는 메시지는 다음과 같습니다:

text

secure-api-review rule 4: a pii field reaches a log or an error message.
claims-api/routes/status.py:10: policy_holder_name

셸 명령이 파일을 다시 작성할 때는 Edit|Write 훅이 실행되지 않습니다. 이러한 이유로, 동일한 스크립트는 모든 풀 리퀘스트에서 필수 검사로도 실행됩니다:

yaml

name: API policy
on: pull_request
jobs:
  check-endpoints:          # a required check in branch protection
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-endpoints.sh claims-api/routes/*.py

사람의 승인을 요청하는 훅은 5단계: 배포의 게이트에 속합니다. 빌드 중에 승인 프롬프트가 나타나면 병렬로 실행되는 모든 세션의 크리티컬 패스에 사람이 다시 개입하게 되기 때문입니다.

시작하기

실행 방법

실제 모습

거버넌스 고려 사항

측정 방법