Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
gograph는 Go 언어의 심볼 및 구조를 분석하는 고급 쿼리 도구입니다. 모호한 이름 처리와 파일 경로 기반 셀렉터를 지원하며, 정밀 빌드 및 뮤테이션 쿼리를 통해 코드의 상태 변화를 추적합니다. 또한, 테스트 기여도 및 커밋되지 않은 변경 사항까지 상세하게 검토할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기심볼 쿼리는 이름이 모호할 때 path/to/file.go:Name, 또는 path/to/file.go:Receiver.Method를 포함하는 path/to/file.go: 형식의 경로, 혹은 임포트-한정된 파일 경로를 허용합니다. source는 모호한 일치 항목에 대한 정확한 셀렉터를 출력합니다. 지원되는 선언 도구 및 명명된 예외 사항은 셀렉터 계약 (the selector contract)에 나열되어 있습니다.
쿼리는 구조체 필드를 포함합니다. query --no-tests는 테스트 파일 행을 제외합니다. 정밀한 뮤테이션 쿼리(mutation queries)는 반환된 값에 할당된 필드의 타입을 복구합니다. 라우트(Routes)는 상수 및 해결되지 않은 경로 등록을 유지하며, 정밀 빌드(precise builds)는 net/http 메서드 패턴을 포함하여 패키지 전반의 상수를 해결합니다.
tests --transitive --files-only는 MCP 전이 보고서(MCP transitive report)에 있는 파일과 일치하는 고유한 파일 경로를 출력합니다.
그래프 상태 출력 및 기능은 freshness_context를 노출합니다: CLI 신선도 검사(CLI freshness checks)는 GOFLAGS를 포함하여 쿼리 프로세스의 Go context를 사용하며, MCP는 자체 시작 컨텍스트와 명시적 태그를 사용합니다. 컨텍스트 불일치(context mismatch)가 발생하면 소스 바이트가 변경되지 않았더라도 오래된 상태로 유지됩니다. 환경 변수 값은 출력되지 않습니다.
정밀 인덱스(Precise indexes)에는 비교(comparisons), 스위치 케이스(switch cases), 복합 값(composite values), 함수 인수(function arguments)를 포함하여 usages 및 query의 패키지 수준 상수 참조가 포함됩니다. 타입이 지정된 열거형 같은 상수(Typed enum-like constants)는 선언 정체성(declaration identity)을 유지하며, 로컬 섀도우(local shadows)는 제외됩니다.
query는 이러한 참조 지점들을 usage 행으로 레이블링합니다. AST 전용 그래프(AST-only graphs)는 타입이 해결된 상수 사용을 주장하지 않습니다.
review는 context와 동일한 테스트 기여도(test attribution)를 사용합니다. 업그레이드 후 다시 빌드하십시오.
review --uncommitted는 changes --git HEAD에서 삭제된 선언을 포함하며, 역사적 호출자(historical callers), 테스트 및 위험은 명시적으로 평가되지 않은 상태로 남겨둡니다. 다른 현재 그래프 순회 명령어(current-graph traversal commands)들은 삭제 거부(deletion refusal)를 유지합니다. 빌드는 감싸는 Git 저장소(enclosing Git repository)가 요청된 디렉토리를 무시하는 경우에 대해 설명합니다.
커밋되지 않은 계획(plan)/검토(review)는 심볼 순회 중 var _ I = (*T)(nil)와 같은 빈 식별자 선언을 건너뜁니다. 검토 기능은 해당 선언 증거를 유지하고 한계를 명명하며, changes --git HEAD에서도 여전히 이를 나열합니다.
세션 감사(Session audits)는 호출 오류(invocation errors)를 운영 실패(operational failures)와 별도로 목록화하고, 이를 규정 준수 점수(compliance scoring) 계산에서 제외합니다. 조합성(Composability)은 구성된 쿼리 명령어와 원시 쿼리 명령어의 혼합을 측정하며, 답변 정확도나 토큰 절약량은 측정하지 않습니다.
Go Report Card
License: MIT
Go Version
Homebrew
Docs
Go 코딩 에이전트에게 더 안전한 리팩토링을 위한 컴파일러 인식 맵 제공.
gograph는 선택적 타입 검사 CHA/SSA 강화가 적용된 로컬 구조 그래프를 Go 리포지토리에 구축합니다. 이의 CLI 및 MCP 워크플로우는 코딩 에이전트가 임베딩이나 호스팅 코드 인덱스 없이도 호출자(callers)와 인터페이스 구현을 추적하고, 변경 영향도를 계획하며, 아키텍처를 강제할 수 있도록 돕습니다.
대화형 설치 없는 데모 살펴보기 · 재현 가능한 벤치마크 검토
경계가 지정된 결과 페이지, 스냅샷 기반 커서(snapshot-bound cursors), 정확한/가능한 영향도, 변경 평가 상태에 대한 내용은 CLI/MCP 쿼리 계약을 참조하십시오.
보조 프로젝트: Scrinium은 코딩 에이전트를 위해 리포지토리 소유의 증거 기반 지식(evidence-backed knowledge)을 제공하며, Rulefloor는 이를 구체적인 테스트에 바인딩하고 드리프트(drift)를 감지함으로써 리포지토리 로컬 불변성(repository-local invariants)을 보호합니다. 이들은 독립적이고 선택적인 도구입니다: Scrinium은 Gograph의 구조적 관찰 결과를, Rulefloor의 검증 결과와 별도의 증거로 유지할 수 있으며, 어느 쪽도 관련 없는 동작이나 전역 프로젝트의 정확성에 대한 증거로 취급하지 않습니다.
Gograph Demo
정적 분석; 타겟 코드 실행 없음. 기본 인덱싱은 Go 소스를 로컬에서 파싱하며 애플리케이션 서비스를 호출하지 않습니다. go/build가 인식하는 링크된 디렉토리 및 링크/특수 파일은 제외되며, 비(非)Go 확장자를 가진 관련 없는 일반 파일이나 느슨한 링크는 Go 툴 입력이 아니므로 정밀 분석을 방해하지 않습니다. 그래프 지향 소스 읽기는 분석된 리포지토리 아래의 일반 파일로 제한되며, 링크되거나 비(非)일반적인 Go 툴 메타데이터(go.mod, go.sum, go.work, go.work.sum, 및 vendor/modules.txt)는 툴체인 호출 전에 거부됩니다. 명시적으로 심볼릭 링크된 리포지토리 루트는 계속 지원됩니다. 적용 가능한 go.work use 멤버는 가장 가까운 실제 Git 체크아웃 아래의 형제 모듈일 수 있으며, 해당 경계가 없으면 워크스페이스 디렉토리 아래에 제한됩니다. 각 멤버 디렉토리, go.mod, 그리고 선택적 go.sum은 cmd/go가 시작되기 전에 유효성 검사를 거칩니다. Gograph는 또한 .gitignore, graph/config JSON, 및 Git 상태와 같은 프로젝트 메타데이터를 읽습니다. 인덱싱은 설치된 Go 툴체인에 효과적인 빌드/모듈 컨텍스트를 요청하며, 정밀 모드는 추가로 패키지 유형 로딩을 수행하고, doc은 go doc을 실행합니다. 이러한 작업은 구성된 모듈/캐시/네트워크 정책을 따릅니다. 리포지토리 패키지 로드 또는 go doc 이전에, 적용 가능한 로컬 모듈/워크스페이스 소스 트리는 cmd/go가 검사할 수 있는 링크를 위해 사전 점검(preflight)됩니다. .git 및 .gograph 서브트리는 제외됩니다. 세션 원격 측정 데이터는 .gograph/sessions/ 아래 로컬에 저장되며, gograph 서비스로 아무것도 전송되지 않습니다.
# 설치
brew install --cask ozgurcd/tap/gograph
# 또는: go install github.com/ozgurcd/gograph/cmd/gograph@latest
...
Homebrew와 go install은 일반적인 gograph CLI를 설치합니다. MCP Bundles를 지원하는 MCP 클라이언트는 대신 공식 MCP 레지스트리에서 로컬 stdio 서버를 io.github.ozgurcd/gograph로 발견할 수 있습니다. 레지스트리/MCPB 설치는 별도의 배포 경로입니다. 이는 Homebrew 캐스크를 설치하거나 Claude Code 마켓플레이스 플러그인을 구성하지 않습니다. 레지스트리는 현재 프리뷰 상태입니다. 클라이언트 지원, 타겟 선택 및 현재 제한 사항에 대해서는 공식 MCP 레지스트리 및 MCPB 설치를 참조하십시오.
summary, hotspot, 또는 gograph complexity가 보여주는 실제 함수나 메서드를 선택한 후, 아래에 이름을 대체하십시오:
gograph explore "YourSymbol" --compact # low-token discovery, identity/role, and complete evidence counts
gograph explore "YourSymbol" # standard source + callers/callees + tests + exact identity impact
gograph explore "YourSymbol" --deep # standard response + depth-3 exact evidence, package context, explanation
...
빌드 아티팩트는 대상 디렉터리인 .gograph/ 아래에 작성됩니다. gograph는 사용 가능한 경우 포함하는 Git 리포지토리 루트의 .gitignore에 .gograph/를 추가하고, Git 외부에서는 빌드 대상 .gitignore로 폴백하며, Go 파일이 발견되지 않거나 소스 파일 파싱에 성공하지 못하면 아티팩트를 교체하지 않고 종료됩니다. 업데이트는 누락되었거나 일반적인 .gitignore만 허용하며, 리포지토리에서 제공하는 링크는 거부되고 해당 대상은 수정되지 않습니다.
Go 빌드 제약 조건, 명시적인 쉼표로 구분된 --tags (또는 플래그가 없을 때 상속되는 GOFLAGS), cmd/go 패키지 디렉터리 규칙, 생성된 소스, 모듈 모드 무시 지시어, 그리고 Git 무시는 빌드, 신선도 확인(freshness checks), 및 변경 감지에 동일한 스캐너 정책을 사용합니다. 연결된 .go 파일, 연결된 디렉터리, 및 기타 비정규화(non-regular)로 인식되는 Go 입력은 보고되고 제외됩니다. 관련 없는 일반 파일 및 비(非)Go 확장자를 가진 끊어진 링크(dangling links)(예: YAML 설정 또는 TSV 고정 데이터)는 Go 툴 프리플라이트(preflight)에 의해 무시됩니다.
연결되거나 비정규화된 go.mod, go.sum, go.work, go.work.sum, 및 vendor/modules.txt 항목은 gograph 또는 Go 툴체인(toolchain)이 읽기 전에 거부됩니다. 적용 가능한 go.work use 멤버는 가장 가까운 실제 Git 체크아웃 아래의 형제 모듈일 수 있습니다. 비(非)Git 레이아웃은 워크스페이스 디렉터리 제한을 유지하며, 중첩된 Git 경계를 넘지 않으며, cmd/go가 시작되기 전에 모든 멤버 디렉터리, go.mod, 그리고 선택적 go.sum이 검증됩니다.
.gograph 자체는 실제 디렉터리여야 하며, graph.json은 일반적인 리포지토리 제한 파일이어야 합니다. 누락되었거나 지원되지 않는 제한 정책 마커를 가진 그래프는 그래프 기반 명령이 사용하기 전에 현재 바이너리로 재구축되어야 합니다. 이전 버전의 바이너리는 이 경계를 강제하지 않으므로 신뢰할 수 없는 리포지토리를 분석하는 데 사용되어서는 안 됩니다.
각 인덱싱된 소스 파일은 SHA-256 콘텐츠 다이제스트를 저장합니다. 재구축(Rebuilds) 시 변경된 패키지의 모든 선택된 파일을 한 번에 다시 구문 분석하고(reparse), 변경되지 않은 패키지의 파서 기록을 재사용하며; stats는 reused_files와 rebuilt_packages를 보고합니다.
정밀 빌드(Precise builds)는 해당 AST 작업을 재사용하지만, 크로스 패키지 디스패치(cross-package dispatch)가 올바르게 유지되도록 리포지토리 전체의 타입/CHA/SSA 풍부화(enrichment)를 여전히 다시 계산합니다.
저메모리 모드(Low-memory mode)는 더 공격적인 가비지 컬렉션(garbage collection)을 사용하면서 해당 그래프 의미론(graph semantics)을 보존하며, 프로덕션 분석과 테스트 분석 사이에 메모리를 회수하고 AST 그래프의 전체 JSON 복사본 생성을 방지합니다. --max-memory는 1GB 또는 1GiB와 같은 정수 바이트 크기를 허용하며, --memory-mode=low를 요구합니다. 이는 하드 RSS 제한이 아닌 소프트한 Go 런타임 메모리 목표치입니다. 따라서 메모리 매핑 파일, 실행 파일, 그리고 Go 툴체인 서브프로세스가 프로세스 메모리를 요청된 값을 초과하게 만들 수 있습니다. 공격적인 GC는 CPU 시간을 증가시킬 수 있으며, 너무 낮은 목표치는 빌드를 훨씬 느리게 하거나 실패하게 할 수 있습니다. Gograph는 이를 충족시키기 위해 절대 정밀도를 조용히 낮추지 않습니다.
정밀 폴백(Precise fallback)은 호환성을 위해 기본적으로 0을 반환하며 그래프 메타데이터에 기록됩니다. 폴백이 CI에서 실패해야 하는 경우 --precise와 함께 --strict를 추가하십시오. Gograph는 여전히 비영(non-zero)을 반환하기 전에 진단 아티팩트(diagnostic artifact)를 게시하거나 보존합니다.
관련 없는 디렉터리에 의해 차단되는 정밀 빌드에 대해서는 디렉터리 제외(directory exclusions)를 참조하십시오. gograph mcp 시작 시 동일한 --exclude-dirs 선택을 사용하십시오. 가져온 의존성은 여전히 타입 검사를 통과해야 합니다.
심볼릭 링크된 스킬(symlinked skills)의 경우, v1.7.2는 --exclude-dirs=.claude/skills를 지원합니다: 이 실제 디렉터리 아래에 있는 디렉터리 링크들은 타겟을 따라가지 않고 Go 로딩에서 숨겨집니다. 연결된 Go 입력 및 메타데이터는 보호됩니다. 등록 및 검증은 Codex MCP 설정 가이드를 참조하십시오.
외부 소비자들은 사람이 사용하는 CLI 출력을 구문 분석할 필요 없이 하나의 닫힌 구조적 술어(closed structural predicate)를 검증할 수 있습니다:
gograph version --json
gograph validate --repo /work/project --binding-json '{"schema_version":"gograph.binding.v1","predicate":"symbol_exists","subject":{"language":"go","kind":"symbol","id":"example.com/project/internal/auth::Authorize"},"required_precision":"ast"}' --json
버전 및 결과 스키마는 gograph.version.v1과 gograph.validation.v1이며, 바인딩은 gograph.binding.v1을 사용합니다. V1은 오직 symbol_exists, package_imports, call_edge_exists, 그리고 type_implements만 지원합니다. 검증(Validation)은 읽기 전용(read-only)이며 그래프를 구축하거나 새로 고치지 않습니다.
종료 코드 0은 '성공(pass)'을 의미하고, 종료 코드 1은 명확하게 평가된 '실패(fail)'를 의미하며, 종료 코드 2는 '평가 불가(cannot_evaluate)' 또는 잘못된 요청을 의미합니다.
부정적인 결과는 술어(predicate)별 완전성(completeness)을 요구합니다. 심볼 및 직접 임포트 부재에는 현재의 완전한 AST 그래프가 필요하며, 구현 부재에는 현재의 정밀-완전(precise-complete) 그래프가 필요하고, 호출 부재에는 추가적으로 주체(subject)와 관련된 모든 호출 엣지(call edges)에 대한 완벽한 해결이 요구됩니다. 누락되거나(missing), 오래되었거나(stale), 부분적이거나(partial), 모호하거나(ambiguous), 해결되지 않은 증거는 '평가 불가'로 저하됩니다. precise_fallback 그래프는 AST 존재 여부는 지원할 수 있지만, 평가된 부재(evaluated absence)는 절대 지원하지 않습니다.
결과는 정확한 그래프 바이트, 선택된 소스/빌드 컨텍스트 매니페스트(source/build-context manifest), 그리고 SHA-256 지문이 찍힌 표준화된 바인딩을 결합합니다.
Gograph는 선택된 빌드 컨텍스트의 Go 구조를 검증합니다. 이는 런타임 동작이나 비즈니스적 정확성을 증명하지 않습니다. CHA(Call Hand-off/Call Edge) 엣지는 가능한 정적 대상일 뿐, 런타임 디스패치 확실성(runtime dispatch certainty)을 의미하지 않습니다. V1은 도달 가능성(reachability), 불안정한 또는 외부 심볼 식별자, 이름 없는 타입(unnamed types), 그리고 Go 언어가 아닌 언어를 제외합니다. 정확한 내용은 machine-validation contract를 참조하십시오.
적용 가능한 로컬 모듈/워크스페이스 소스 루트는 명시적인 --repo 루트 아래에 남아 있어야 하며, V1은 권한을 확장하는 대신 '평가 불가'를 반환합니다.