claude-grok-build-plugin: Instructions file for Claude Code

CLAUDE.md — claude-grok-build-plugin

이 파일은 Claude Code가 이 프로젝트에서 세션을 시작할 때 자동으로 읽는 컨텍스트 파일입니다. 사람이 읽는 개요는 README.md(영문 기본) 또는 README.ko.md(한글), 상세 설계는 docs/를 참조하세요. 여기에는 지금 알아야 할 것과 함정의 존재만 한 줄씩 둔다 — 옮긴 근거·절차·이력은 docs/11-maintainer-playbook.md (그 뒤에 더한 함정은 제 소스·테스트를 가리킨다).

⚠️ 이 CLAUDE.md는 이 저장소에서 개발할 때만 로드된다. 플러그인이 설치된 엔드유저에게는 플러그인 루트의 CLAUDE.md가 컨텍스트로 전달되지 않는다 (플러그인은 skill/agent/hook으로 컨텍스트를 제공). 따라서 절대 원칙(예: API 키 env 정제)이 엔드유저 런타임에 강제돼야 한다면 반드시 코드/hook에 구현해야 하며, 이 문서에만 적어두면 안 된다.

프로젝트 한 줄 요약

Claude Code 플러그인. Claude가 코딩 작업 중 일부를 xAI의 Grok Build CLI에 위임할 수 있게 하는 MCP 서버 래퍼. 과금은 API 종량제가 아니라 사용자의 xAI 구독(SuperGrok / X Premium+)을 쓰는 것이 최우선 제약이다. 목표는 다리만이 아니라 Claude(오케스트레이터) ↔ Grok(워커)의 멋진 협업 경험이다 — SSOT docs/00-product-vision.md.

세션 핸드오프 (필수)

의미 있는 작업 뒤에는 다음 세션이 즉시 이어받게 맞춘다. 같은 사실을 여러 곳에 복사하지 않는다 — 원천 하나를 고치고 나머지는 가리킨다. 이 파일 현재 상태(지금 사실·다음 할 일만, 이력 금지) · docs/06(Phase) · docs/09(범위·잔여· 릴리스 수락) · docs/10(열린 결함 큐 — 고치면 지운다) · docs/specs/·docs/plans/(결정 근거) · CHANGELOG.md(이력 색인).

현재 상태 (먼저 읽을 것)

최신 릴리스 v0.2.46. 무엇이 왜 나갔는지는 docs/releases/가 원천이고 CHANGELOG.md는 색인이다 — 여기 옮겨 적지 말 것.

• 다음 할 일: docs/plans/2026-09-30-handoff-plan.md — docs/10 A(순서·재현·완료 조건은 계획에). 새 결함은 번호 재사용 없이 — 다음은 A76. 착수는 오너 승인 후(.claude/skills/repo-scope); 오너 판단은 docs/09 §4 F·H와 A 항목의 "오너 판단" 문장. B7·B9·B10은 오너의 실세션(컨테이너 로그인)이 있어야 잰다. 기각·반증된 항목을 다시 제기하기 전에 docs/09·docs/releases/의 근거부터 읽는다.
• ⚠️ docs/10의 B(측정 불가)는 대기열이 아니라 할 일 목록이다 — 환경을 만들 수 있으면(Docker, 컨테이너 전용 로그인) 지금 잰다. 절차는 docs/specs/grok-cli-contract.md §13.
• ⚠️ grok CLI는 스스로 업데이트된다 — 계약 스냅샷이 낡는 것을 전제로 설계한다. 실제 CLI를 보는 것은 npm run probe:contract뿐인데(쿼터 0; 유닛 테스트는 DI 목) probe-contract-drift.mjs 머리 주석이 나열한 것만 보고 plan 차단 같은 동작은 못 본다. ⚠️ grok 1.0.62에서 그 프로브가 STOP(sessionAccepted)을 냈다 — 원인을 알기 전엔 그것도, 같은 격리로 grok을 띄우는 측정도 돌리지 않는다(범위와 그 예외는 docs/10 A68). drifted(이 머신)와 snapshotBehindLatest(새 설치)는 다른 질문이고 뒤쪽은 --strict를 깨지 않는다; 조회 실패는 false가 아니라 null+사유다. 계약 SSOT docs/specs/grok-cli-contract.md는 절마다 유효 버전이 다르다.
• ⚠️ 측정·리뷰·개발 전에 grok과 Claude Code를 최신으로 맞춘다(오너 규칙) — grok --no-auto-update update --check --json·claude update, 뒤처진 grok은 grok_cli ["update"](timeout_ms 넉넉히 — commands/update.md)로 올리고 npm run probe:contract(⚠️ 위); 보고에 두 버전. 플러그인은 grok을 스스로 올리지 않는다(계약 머리). 옛 버전은 바이너리를 버릴 폴더에 복사해 버릴 홈에서만 돌린다 — 실제 설치를 grok update --version으로 내리지 않는다.
• ⚠️ 새 서브커맨드를 KNOWN_SUBCOMMANDS에 넣는 것이 기본값이 아니다 — 헤드리스로 못 돌거나, 호출보다 오래 살거나, 계정에 작용하면 NON_HEADLESS 행이다(두 집합은 반대 방향 — A29). 새 플래그는 grok-cli.ts 표로, 프롬프트를 싣는 것(-p 별칭)은 prompt-flags.ts에도 분류한다(A62) — probe는 이름만 봐 값 여부·숨은 플래그를 못 본다(A52 프롬프트 규칙이 표에 기댄다).
• ⚠️ plan 모드만으로는 쓰기를 못 막는다 — grok은 plan에서도 사용자 허용 규칙(grok 설정·~/.claude/settings.json)을 따른다. 그래서 plan은 PLAN_DENY_ARGS(셸·편집·쓰기·MCP 거부)를 넘기지만 지키는 것은 grok이고, 1.0.13·1.0.30의 예약 작업은 못 막는다 (계약 §6, A50·A60). 철자는 delegate.test.ts의 리터럴 비교가 지키고, planWroteFiles는 지우지 않으며, 사용자 문구에 "grok X.Y는 …한다"를 단정하지 않는다.
• ⚠️ 머지 직후 바로 태그를 끊는다(감시 release-tag-check) — 캐시는 버전 키라, 번들이 바뀌면 같은 번호로 재배포하지 말고 범프한다(이쪽은 자동 감시가 없다). 릴리스 노트는 GitHub 본문 한도(125,000자, CRLF 기준)에 들어가야 하고, 밖으로 옮긴 기록은 절대 주소로 링크한다(handoff-version.test.ts). 다음 버전 번호는 범프 전에 CLAUDE.md·CHANGELOG.md·docs/09에 쓰지 않는다(파일 이름도) — 그 테스트의 includes 검사가 미리 녹색이 된다.
• 의존성 PR의 dist 재빌드는 사람이 아니라 에이전트가 한다 — 패키지마다 다르다(grep -c "node_modules/<pkg>" dist/index.js가 0이면 재빌드 없이 머지). 근거 CONTRIBUTING.md.
• SCAManager 토큰 건은 2026-09-04에 실측으로 닫혔다 — 다시 열기 전에 CHANGELOG.md 그 날짜와 docs/09 §5. Dependabot 경보 건수는 여기 적지 않는다(원천 gh api …/dependabot/alerts?state=open과 npm audit).
• 릴리스 수락: 머지 내용(트리) 검증 → 즉시 태그·릴리스 → dist blob = 태그 blob → 클론 먼저 설치본 갱신 → 캐시 = 태그 blob → accept-release 레포·캐시. 마지막 칸(갱신 뒤 새 세션의 serverVersion과 그 세션 MCP 자식의 명령줄 버전 디렉터리)은 세션이 시작 시점의 MCP를 물고 있어 새 세션 몫이다. ⚠️ Claude Code 설치 기록(installed_plugins.json)의 gitCommitSha는 갱신 때 바뀌기도 하고 안 바뀌기도 한다 — 설치 신원의 증거로 쓰지 말 것(docs/09 §5 v0.2.37·v0.2.43). 버전 번호·실행 기록은 docs/09 §5에만.
• 새 클론·다른 PC: 클론이 먼저다 — 마켓플레이스 클론은 autoUpdate: false라 낡으면 claude plugin update가 새 버전을 못 본다. 절차 원천은 CONTRIBUTING.md와 docs/09 §5.
• 레포 밖/수동/보류(외부 오케스트레이터 실배선, GUI 클릭 수동 수락, ACP)와 오너가 연 새 기능 후보(§4 G)는 docs/09-scope-and-residuals.md가 분류한다.