Skip to main content

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

CLI 또는 SDK를 유지 관리하고 공식 Anthropic 마켓플레이스에 플러그인이 있다면, 도구가 Claude Code 사용자에게 해당 플러그인을 설치하도록 권유할 수 있습니다. CLI는 Claude Code 내부에서 실행 중임을 감지할 때 stderr에 한 줄 마커를 작성합니다. Claude Code는 마커를 읽고 출력에서 제거한 후 사용자에게 일회성 설치 프롬프트를 표시합니다. Claude Code는 힌트 줄을 명령 출력에서 제거한 후 모델로 전송하므로 마커는 대화에 나타나지 않으며 토큰 사용량에 계산되지 않습니다. 이 프로토콜은 추가 명령이 필요하지 않으며 Claude Code 외부에서 CLI를 실행하는 사용자에게 출력되는 내용을 변경하지 않습니다. 이 페이지는 CLI 및 SDK 유지 관리자를 위한 것입니다. 플러그인 설치를 찾고 있다면 플러그인 발견 및 설치를 참조하세요.

​
작동 방식

Claude Code는 Bash 및 PowerShell 도구를 통해 실행하는 모든 명령에 대해 CLAUDECODE 환경 변수를 1로 설정합니다. CLI가 해당 변수를 감지하면 자체 종료 <claude-code-hint /> 태그를 stderr에 작성합니다. Claude Code가 명령 출력을 받으면 다음을 수행합니다:
  1. 힌트 줄을 스캔하고 출력이 모델에 도달하기 전에 제거합니다
  2. 힌트가 공식 Anthropic 마켓플레이스의 플러그인을 대상으로 하는지 확인합니다
  3. 플러그인이 이미 설치되지 않았으며 이전에 프롬프트되지 않았는지 확인합니다
  4. 힌트를 내보낸 명령의 이름을 지정하는 설치 프롬프트를 사용자에게 표시합니다
Claude Code는 플러그인을 자동으로 설치하지 않습니다. 사용자가 항상 확인합니다.

​
힌트 내보내기

CLAUDECODE 환경 변수에서 내보내기를 제어하여 마커가 일반 사용자의 터미널에 나타나지 않도록 합니다. 그런 다음 태그를 stderr에 자체 줄로 작성합니다. 다음 예제는 공식 마켓플레이스에서 example-cli라는 플러그인에 대한 힌트를 내보냅니다: 
if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}
공식 마켓플레이스에서 플러그인의 이름으로 example-cli를 바꿉니다.

​
내보낼 위치 선택

힌트를 내보낼 코드 경로를 제어합니다. Claude Code는 플러그인별로 중복 제거하므로 모든 호출에서 내보내는 것은 단점이 없습니다. 잘 작동하는 접점은 다음과 같습니다:
배치작동하는 이유
--help 출력Claude는 종종 익숙하지 않은 CLI를 탐색할 때 도움말을 실행합니다
알 수 없는 하위 명령 오류Claude가 인터페이스에 대해 혼동하는 순간에 도달합니다
로그인 또는 인증 성공사용자가 이미 설정 마음가짐에 있습니다
첫 실행 환영 메시지자연스러운 온보딩 순간입니다

​
사용자가 보는 것

힌트가 모든 검사를 통과하면 Claude Code는 다음과 같은 프롬프트를 표시합니다: 
─────────────────────────────────────────────────────────────
  플러그인 추천

    example-cli 명령이 플러그인 설치를 제안합니다.

    플러그인: example-cli
    마켓플레이스: claude-plugins-official
    example-cli 배포를 위한 공식 통합

    설치하시겠습니까?
    ❯ 1. 예, example-cli 설치
      2. 아니오
      3. 아니오, 플러그인 설치 힌트를 다시 표시하지 않기

─────────────────────────────────────────────────────────────
프롬프트는 힌트를 생성한 명령의 이름을 지정하므로 사용자가 도구와 권장하는 플러그인 간의 불일치를 발견할 수 있습니다. 사용자가 30초 이내에 응답하지 않으면 프롬프트는 아니오로 해제됩니다. 프롬프트 빈도는 제한됩니다:
  • 플러그인당 한 번: 프롬프트가 표시된 후 Claude Code는 플러그인을 기록하고 사용자의 답변에 관계없이 다시 프롬프트하지 않습니다.
  • 세션당 한 번: 머신의 모든 CLI에서 Claude Code 세션당 최대 하나의 힌트 프롬프트가 나타납니다.
예를 선택하면 플러그인이 사용자 범위로 설치됩니다. 아니오, 플러그인 설치 힌트를 다시 표시하지 않기를 선택하면 사용자에 대한 모든 향후 힌트 프롬프트가 비활성화됩니다.

​
힌트 형식

힌트는 세 개의 필수 속성이 있는 자체 종료 태그입니다. 
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
속성필수설명
v예프로토콜 버전. 1은 유일하게 지원되는 값입니다
type예힌트 종류. plugin은 유일하게 지원되는 값입니다
value예name@marketplace 형식의 플러그인 식별자
속성 값은 큰따옴표로 인용하거나 인용하지 않을 수 있습니다. 인용하지 않은 값은 공백을 포함할 수 없습니다. 이스케이프 시퀀스는 지원되지 않습니다.

​
요구 사항

Claude Code는 힌트에 대해 조치를 취하기 전에 두 가지 조건을 적용합니다. 두 검사 중 하나라도 실패한 힌트는 삭제됩니다:
  • 자체 줄: 태그는 자체 줄을 차지해야 합니다. 예를 들어 로그 문 내부에 줄 중간에 포함된 태그는 무시됩니다. 줄의 선행 및 후행 공백은 허용됩니다.
  • 공식 마켓플레이스: value는 claude-plugins-official과 같은 Anthropic 제어 마켓플레이스의 플러그인을 참조해야 합니다. 다른 마켓플레이스를 가리키는 힌트는 자동으로 삭제됩니다.
힌트 줄은 버전 또는 유형이 인식되지 않을 때도 항상 모델에 도달하기 전에 출력에서 제거되므로 마커는 토큰 사용량에 계산되지 않습니다. 나머지 지침은 권장되지만 적용되지 않습니다. Claude Code는 CLI가 이를 따르는지 관찰할 수 없습니다:
  • stderr에 작성: stderr는 example-cli deploy | jq와 같은 셸 파이프라인에서 태그를 제외합니다. Claude Code는 두 스트림을 모두 스캔하므로 stdout도 작동합니다.
  • CLAUDECODE에서 제어: CLAUDECODE 환경 변수가 설정된 경우에만 내보냅니다. 이렇게 하면 마커가 CLI를 직접 실행하는 사용자에게 나타나지 않습니다.

​
공식 마켓플레이스에 플러그인 추가

힌트 프로토콜은 공식 Anthropic 마켓플레이스에 나열된 플러그인에 대해서만 적용됩니다. 플러그인을 제출하려면 앱 내 제출 양식 중 하나를 사용하세요: Anthropic 파트너 담당자와 함께 작업 중인 경우 그들에게 연락하여 목록을 조정하세요.

​
참고 항목