plelevier/gcyphrq

Skill Guide

gcyphrq 스킬은 AI 코딩 에이전트가 자연어 프롬프트를 사용하여 JSON 그래프 파일에 대해 Cypher 쿼리를 실행할 수 있게 해줍니다. 한 번 설치한 후, "API Gateway에 의존하는 서비스는 무엇인가?" 와 같은 질문을 하면 구조화된 JSON 결과를 얻을 수 있습니다.

스킬이 하는 일

설치되면, 이 스킬은 AI 에이전트에게 다음을 가르칩니다:

• 자연어를 자동으로 Cypher 쿼리로 변환
• gcyphrq CLI를 사용하여 JSON 그래프 파일에 대해 쿼리 실행
• 결과를 해석하고 가독성 있는 형식으로 제시
• 복잡한 분석(블래스트 레이더, 경로 추적, 차수 분석 등)을 위해 여러 쿼리 연결

이 스킬에는 일반적인 인프라 질문(서비스 의존성, 복제 토폴로지, 모니터링 커버리지 등)을 위한 큐레이팅된 쿼리 패턴 라이브러리가 포함되어 있습니다.

설치

CLI 사용 (권장)

가장 쉬운 방법은 내장 설치 명령어를 사용하는 것입니다. 설치된 에이전트(pi, Claude Code, OpenCode)를 감지하고 자동으로 스킬을 설치합니다:

# 전역 설치 (에이전트 설정 디렉토리에 심볼릭 링크 생성)
gcyphrq --install-skill global

# 로컬 설치 (현재 디렉토리에 복사)
gcyphrq --install-skill local

--install-skill 명령어는:

• 시스템에 설치된 에이전트를 감지합니다
• 심볼릭 링크(전역) 또는 복사(로컬)를 통해 스킬 콘텐츠를 만듭니다
• Claude Code 및 OpenCode를 위한 CLAUDE.md / AGENTS.md 참조 파일을 생성합니다
• 멱등성을 가지므로 여러 번 실행해도 안전합니다

설치 후:

• Pi는 스킬을 자동으로 인식합니다. /skill:gcyphrq로 호출하거나 자연어로 원하는 작업을 설명하세요.
• Claude Code는 그래프 관련 질문을 하면 스킬을 자동으로 인식합니다.
• OpenCode는 프롬프트가 스킬 설명(그래프 쿼리, 인프라 토폴로지, 서비스 의존성 등)과 일치하면 스킬을 로드합니다.

수동 설치

설치 명령어가 환경에 맞지 않는 경우, 스킬 디렉토리를 수동으로 배치할 수 있습니다:

# pi
mkdir -p ~/.pi/agent/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.pi/agent/skills/gcyphrq/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.claude/skills/gcyphrq/SKILL.md

# OpenCode
mkdir -p ~/.opencode/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
  -o ~/.opencode/skills/gcyphrq/SKILL.md

references/ 디렉토리(queries.md 및 example-graph.json 포함)를 SKILL.md 옆에 references/ 하위 디렉토리로 다운로드하여 추가 쿼리 패턴과 자체 포함된 테스트 그래프를 얻을 수도 있습니다.

다른 에이전트

사용자 지정 명령어나 시스템 프롬프트를 지원하는 모든 AI 코딩 에이전트의 경우:

1. CLI 설치: npm install -g gcyphrq
2. SKILL.md 복사: https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md의 내용을 에이전트의 사용자 지정 명령어에 복사합니다.
3. 참조 파일 복사: https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/의 내용(queries.md 및 example-graph.json 포함)을 SKILL.md 옆에 references/ 하위 디렉토리로 복사합니다.
4. 그래프 파일을 가리키도록 설정: 스킬 예제에서 <graph.json>을 실제 그래프 파일 경로로 바꿉니다.

사전 요구 사항

• gcyphrq CLI가 설치되어 PATH에 있어야 합니다. 설치 방법은 시작하기를 참조하세요.
• 쿼리할 JSON 그래프 파일 (시작하려면 번들된 references/example-graph.json을 사용하세요).

예시 프롬프트

스킬이 설치되면 자연어 프롬프트를 사용할 수 있습니다. 다음은 스킬이 해결해야 할 예시입니다:

서비스 의존성

프롬프트: "API Gateway가 의존하는 서비스는 무엇인가?"

스킬은 이를 API Gateway 노드에서 나가는 연결을 추적하는 Cypher 쿼리로 변환합니다.

프롬프트: "PostgreSQL에 연결된 모든 서비스를 보여줘."

PostgreSQL Primary 데이터베이스에 TCP 연결이 있는 모든 서비스를 반환합니다.

블래스트 레이더 분석

프롬프트: "Kafka가 다운되면 무엇이 고장 나나요?"

Kafka 클러스터에서 2홉 이내에 도달 가능한 모든 노드를 추적하여 영향 범위를 보여줍니다.

프롬프트: "API Gateway가 실패하면 블래스트 레이더는 어떻게 되나요?"

API Gateway를 사용할 수 없을 때 영향을 받는 모든 다운스트림 서비스와 인프라를 매핑합니다.

경로 추적

프롬프트: "CDN에서 데이터베이스까지의 경로를 보여줘."

CDN과 데이터베이스 노드 사이의 연결 경로를 찾아 중간 서비스를 보여줍니다.

프롬프트: "API Gateway에서 사용자 데이터베이스로 요청이 어떻게 흐르나요?"

인증, RPC 서비스 및 데이터베이스 연결을 통한 요청 경로를 추적합니다.

인프라 토폴로지

프롬프트: "메시지 큐는 어떻게 연결되어 있나요?"

모든 메시지 큐 인프라와 그들의 생산자/소비자 관계를 나열합니다.

프롬프트: "데이터베이스의 복제 설정은 무엇인가요?"

주-복제본 관계와 복제 에지 유형을 보여줍니다.

차수 분석

프롬프트: "가장 많은 나가는 연결을 가진 서비스는 무엇인가요?"

모든 서비스의 out-degree를 계산하고 가장 많이 연결된 서비스를 반환합니다.

프롬프트: "나가는 연결이 2개보다 많은 서비스를 찾아줘."

집계 및 WHERE를 사용하여 out-degree 임계값으로 서비스를 필터링합니다.

모니터링 커버리지

프롬프트: "모니터링되는 서비스는 무엇인가요?"

모니터링 인프라(Prometheus, Grafana 등)에 연결된 모든 서비스를 찾습니다.

프롬프트: "모니터링이 없는 서비스는 무엇인가요?"

OPTIONAL MATCH를 사용하여 모니터링 연결이 없는 서비스를 찾습니다.

외부 의존성

프롬프트: "외부 API를 호출하는 서비스는 무엇인가요?"

1-3홉 내의 RPC 서비스를 추적하여 외부 API 의존성을 찾습니다.

프롬프트: "모든 외부 통합을 나열해줘."

External 레이블이 있는 모든 노드와 이를 호출하는 상위 노드를 반환합니다.

고급 필터링

프롬프트: "모든 RPC 또는 Worker 서비스를 보여줘."

WHERE와 OR을 사용하여 여러 유형을 일치시킵니다.

프롬프트: "배치 작업이 아닌 서비스를 찾아줘."

WHERE와 NOT을 사용하여 유형을 제외합니다.

프롬프트: "us-east-1에 있고 이름에 'Service'가 포함된 서비스를 나열해줘."

WHERE와 AND를 사용하여 조건을 결합합니다.

페이지네이션

프롬프트: "서비스의 2페이지를 보여줘. 페이지당 10개, 알파벳 순으로 정렬."

ORDER BY, SKIP 및 LIMIT를 사용하여 서비스 결과를 페이지네이션합니다.

그래프 변형

프롬프트: "'Datadog'이라는 새 모니터링 서비스를 추가해줘."

CREATE를 사용하여 그래프에 새 노드를 추가합니다.

프롬프트: "API Gateway의 상태를 'deprecated'로 설정해줘."

SET을 사용하여 노드 속성을 업데이트합니다.

프롬프트: "Alice에서 'Person' 레이블을 제거해줘."

REMOVE를 사용하여 레이블을 제거하거나 노드에서 속성을 제거하면서 노드와 관계는 그대로 유지합니다.

스킬 참조

스킬 파일(SKILL.md)에는 다음이 포함됩니다:

• CLI 사용법 — 명령어 구문, 옵션, stdin 파이핑, 쿼리 체이닝
• 그래프 파일 형식 — 노드 및 에지 구조
• 지원되는 Cypher 기능 — 상태가 포함된 전체 기능 매트릭스
• 쿼리 패턴 — 번들된 references/example-graph.json을 사용한 사전 구축 쿼리
• 출력 형식 — 그래프 형식(기본값) 및 체이닝 예제가 포함된 행 형식
• 제한 사항 — 알려진 제약 조건(하위 쿼리 없음, APOC 없음 등)

문제 해결

문제	해결책
gcyphrq: command not found	npm install -g gcyphrq 실행
에이전트가 스킬을 감지하지 못함	SKILL.md가 플랫폼에 맞는 올바른 스킬 디렉토리에 있는지 확인
쿼리가 빈 결과 반환	노드 레이블과 속성 이름이 그래프 파일과 정확히 일치하는지 확인

다음 단계

• [시작하기]({{ '/getting-started/' | relative_url }}) — gcyphrq 설치 및 첫 번째 쿼리 실행
• [쿼리 가이드]({{ '/query-guide/' | relative_url }}) — 전체 Cypher 구문 참조
• [예제]({{ '/examples/' | relative_url }}) — 샘플 출력이 포함된 30개의 실행 가능한 쿼리
• [라이브러리 API]({{ '/library-api/' | relative_url }}) — Node.js / TypeScript에서 프로그래밍 방식으로 gcyphrq 사용