anthropics/claude-code

이 문서는 본 저장소가 어떤 "하네스(harness)"로 구성되어 있는지를 5개 축으로 분해하고, 글로벌 CLAUDE.md 규칙(09-hooks-guide, 10-subagent-patterns)과의 갭을 정리한다.

분석 일자: 2026-04-07 대상: dev-reference/claude-code (Anthropic 공식 public reference repo) 관점: Harness Engineering — 실행 경계 / 정책 / 수명주기 / 검증 / 관찰성

이 문서는 본 저장소가 어떤 "하네스(harness)"로 구성되어 있는지를 5개 축으로 분해하고, 글로벌 CLAUDE.md 규칙(09-hooks-guide, 10-subagent-patterns)과의 갭을 정리한다.

신뢰도 레이블 — [검증됨] 코드 직접 확인 / [추론] 파일 분석 / [모름] 미확인

---

1. 하네스 5축 진단

1.1 실행 하네스 (Execution Harness) [검증됨]

GitHub 이벤트를 받아 anthropics/claude-code-action을 구동하는 워크플로우가 중심.

워크플로우	트리거	역할
.github/workflows/claude.yml	@claude 멘션 (issue/PR/review)	일반 대화형 Claude 호출
.github/workflows/claude-issue-triage.yml	issues.opened, issue_comment.created	이슈 자동 분류·라벨링
.github/workflows/claude-dedupe-issues.yml	신규 이슈	중복 이슈 탐지

핵심 패턴 — 모든 워크플로우가 anthropics/claude-code-action@v1을 단일 진입점으로 사용. 이벤트 → 조건 필터 → claude-code-action 호출 → 권한 제한된 도구만 사용 가능.

복사# .github/workflows/claude-issue-triage.yml:12-37
if: >-
  github.event_name == 'issues' ||
  (github.event_name == 'issue_comment' && !github.event.issue.pull_request && github.event.comment.user.type != 'Bot')
...
env:
  CLAUDE_CODE_SCRIPT_CAPS: '{"edit-issue-labels.sh":2}'
with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  allowed_non_write_users: "*"
  prompt: "/triage-issue REPO: ${{ github.repository }} ISSUE_NUMBER: ${{ github.event.issue.number }}"

1.2 정책 하네스 (Policy Harness) [검증됨]

명령 허용 범위를 3겹으로 강하게 제한.

1. allowed-tools — claude-code-action 자체의 도구 제한
2. CLAUDE_CODE_SCRIPT_CAPS — 특정 스크립트의 최대 호출 횟수 cap
   • 예: {"edit-issue-labels.sh":2} → 라벨 편집 스크립트는 1 워크플로우에서 최대 2회만
3. gh.sh 래퍼 — GitHub CLI 호출을 화이트리스트로 강제

복사# scripts/gh.sh:23-36
ALLOWED_FLAGS=(--comments --state --limit --label)
FLAGS_WITH_VALUES=(--state --limit --label)
...
case "$CMD" in
  "issue view"|"issue list"|"search issues"|"label list")
    ;;
  *)
    echo "Error: only 'issue view', 'issue list', 'search issues', 'label list' are allowed ..." >&2
    exit 1

추가 방어선 — scripts/gh.sh:79:

복사if [[ "$QUERY_LOWER" == *"repo:"* || "$QUERY_LOWER" == *"org:"* || "$QUERY_LOWER" == *"user:"* ]]; then
  # search query에 repo: / org: / user: qualifier 차단 → cross-repo 탐색 방지

→ 프롬프트 인젝션으로 다른 repo/org를 건드리지 못하게 막는 명시적 차단. 사용자 글로벌 03-security의 "가역성 R2 — 외부 시스템 상태 변경"을 코드 레벨에서 강제한 좋은 사례.

1.3 수명주기 하네스 (Lifecycle Harness) [검증됨]

이슈 라벨 → 타임아웃 → 자동 종료가 순환 처리됨.

컴포넌트	역할
scripts/issue-lifecycle.ts	라벨 정의 + 일수 임계값
scripts/sweep.ts	정기 sweep — stale → autoclose 라벨 부착
.github/workflows/sweep.yml	sweep 스케줄링
.github/workflows/auto-close-duplicates.yml	dedupe 결과로 자동 종료
.github/workflows/issue-lifecycle-comment.yml	stale 라벨 부착 시 안내 코멘트
.github/workflows/lock-closed-issues.yml	종료된 이슈 잠금
.github/workflows/remove-autoclose-label.yml	사용자 활동 시 라벨 회수

핵심 로직 — 페이지네이션 + 정렬 기반 컷오프:

복사// scripts/sweep.ts:45-67
async function markStale(owner: string, repo: string) {
  const staleDays = lifecycle.find((l) => l.label === "stale")!.days;
  const cutoff = new Date();
  cutoff.setDate(cutoff.getDate() - staleDays);
  ...
  for (let page = 1; page <= 10; page++) {
    const issues = await githubRequest<any[]>(
      `/repos/${owner}/${repo}/issues?state=open&sort=updated&direction=asc&per_page=100&page=${page}`
    );
    ...
    if (updatedAt > cutoff) return labeled;  // updated_at 정렬이라 컷오프 넘으면 즉시 종료

sort=updated&direction=asc + if (updatedAt > cutoff) return 조합은 불필요한 API 호출을 조기 차단하는 정석적 sweep 패턴. 10페이지 cap도 안전장치.

1.4 로컬 검증 하네스 (Local Validation Harness) [검증됨]

plugins/plugin-dev 안에 plugin 개발자용 검증 스크립트가 존재.

스크립트	위치
validate-agent.sh	plugins/plugin-dev/skills/agent-development/scripts/validate-agent.sh
hook-linter.sh	plugins/plugin-dev/skills/hook-development/scripts/hook-linter.sh
test-hook.sh	plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh

→ "규칙 기반 품질 체크" 의 공식 레퍼런스. plugin 작성 시 frontmatter / hook 형식 / agent 정의가 표준에 맞는지 자동 검증. 사용자 글로벌 09-hooks-guide의 hook 작성 원칙을 도구화한 사례.

1.5 관찰성 (Observability) [검증됨 / 일부 추론]

• 운영 스크립트 (scripts/sweep.ts, scripts/issue-lifecycle.ts)에 단계별 로그 출력 — console.log("\n=== marking stale (${staleDays}d inactive) ===") 등
• .github/workflows/log-issue-events.yml — 이벤트 자체를 별도 워크플로우로 로깅
• .github/workflows/non-write-users-check.yml — write 권한 없는 사용자 액션 모니터링
• 일부 워크플로우에서 Statsig 이벤트 전송 가능성 [추론] — 실제 Statsig 호출 코드는 본 분석에서 직접 확인하지 않음

---

2. 강점

안전한 실행 경계

도구·명령·플래그 허용 범위를 3겹(allowed-tools / CLAUDE_CODE_SCRIPT_CAPS / gh.sh 래퍼)으로 명시적으로 좁혀 프롬프트 오남용 리스크를 구조적으로 차단.

자동화된 운영 루프

triage → dedupe → stale → autoclose → lock 까지 이슈 운영 전체가 워크플로우 단위로 책임 분리되어 체계화됨. 각 단계가 독립 워크플로우라 한 단계가 실패해도 다른 단계는 계속 작동.

재사용 가능한 개발 하네스

plugin-dev 안에 검증 스크립트가 표준화되어 있어 새 plugin 작성 시 "규칙 기반 품질 체크"가 즉시 적용 가능. 사용자가 작성한 advisory 규칙을 deterministic 검증으로 끌어올리는 모범 사례.

이벤트 기반 확장성

워크플로우 단위 책임 분리 → 새 이벤트 추가 시 새 워크플로우 1개만 추가하면 끝. 기존 워크플로우 수정 없이 기능 확장 가능.

---

3. 취약점 / 갭

전통적 테스트 스위트 부재 [검증됨]

루트 기준 *.test.*, *.spec.*, __tests__ 디렉토리가 사실상 없음. 회귀 검증은 운영 스크립트와 수동 검증 의존도가 큼 → 코드 로직 변경 시 안전망이 약함.

하네스 편중

"GitHub 이슈 운영 하네스"는 매우 강하지만, "코드 로직 품질 하네스(단위/통합 테스트)"는 약함. 운영 자동화에 비해 코드 자동화가 뒤처짐. 본 저장소가 reference·plugin 모음이라 의도된 비대칭일 수 있음 [추론].

워크플로우 보안 설정의 민감도

allowed_non_write_users: "*" (claude-issue-triage.yml:35)는 편의성은 높지만 권한 범위 점검을 지속적으로 강제해야 함. .github/workflows/non-write-users-check.yml이 이 위험을 일부 상쇄하지만, 정책 변경 시 사람 리뷰가 필수.

표준 실행 엔트리 불명확

루트에 package.json 통합 테스트 엔트리가 없음 → 신규 기여자의 검증 진입점이 약함. "내가 만든 plugin이 동작하는지 어디서 어떻게 확인하나"가 README에 명시되어 있지 않음.

---

4. 글로벌 CLAUDE.md 규칙과의 매핑

글로벌 규칙	본 저장소의 대응	갭
09-hooks-guide MUST-HOOK 4종	examples/hooks/bash_command_validator_example.py — exit 2 차단 패턴	사용자 09-hooks-guide는 "exit 1"로 적힘 → 정정 필요
10-subagent-patterns 권한 제한	plugins/pr-review-toolkit/ — 6개 전문 reviewer agent	사용자 규칙은 5종 — 더 세분화 가능
03-security 가역성 R2 (외부 상태 변경)	scripts/gh.sh:79 — search qualifier 차단	사용자 규칙은 텍스트 advisory만 — 래퍼 패턴으로 강화 가능
04-workflow idle 모드	plugins/ralph-wiggum/ — Stop hook 패턴	사용자 규칙은 advisory만 — Stop hook으로 deterministic 보강 가능
08-local-env sandbox	examples/settings/settings-bash-sandbox.json	사용자 규칙에 sandbox 채널 자체가 없음 ← 가장 큰 갭

---

5. 권장 후속 작업

본 저장소 자체에 적용 가능

1. [중간] 루트에 CONTRIBUTING.md 또는 docs/PLUGIN_DEVELOPMENT.md 추가 — plugin-dev 검증 스크립트 사용법 안내로 "검증 진입점" 갭 해소
2. [중간] 핵심 운영 스크립트(sweep.ts, issue-lifecycle.ts)에 단위 테스트 추가 — 라벨 컷오프 로직 회귀 방어
3. [낮음] allowed_non_write_users: "*" 사용 워크플로우에 정책 리뷰 주기 명시 (주석 또는 별도 문서)

사용자 글로벌 하네스에 흡수 가능

1. [높음] 09-hooks-guide.md의 exit code 정정 — 차단은 exit 2 (Claude에 stderr 전달)
2. [높음] sandbox 채널 신설 — examples/settings/settings-bash-sandbox.json을 baseline으로 글로벌 규칙에 11-sandbox.md 추가
3. [중간] gh.sh 같은 CLI 래퍼 패턴을 03-security 가역성 R2 방어선으로 표준화 — 외부 상태 변경 도구는 화이트리스트 래퍼 경유 강제
4. [중간] ralph-wiggum의 Stop hook 패턴을 04-workflow idle 모드 deterministic 구현으로 흡수

---

6. 결정 로그

• why: 사용자 글로벌 하네스(09/10 규칙 중심)가 공식 레퍼런스에서 어떤 부분이 검증되어 있고 어떤 부분이 누락됐는지 파악해야 진화 방향이 정해짐
• alternatives: README 수정 / 글로벌 CLAUDE.md 직접 업데이트 / 본 분석 문서 단독 작성 — 후자 선택 (사용자가 명시 요청)
• rule_applied: 09-hooks-guide (Advisory↔Deterministic), 10-subagent-patterns (권한 제한), 05-responses (신뢰도 레이블)
• reversibility: R0 — 신규 분석 문서 1개, 코드 변경 없음