빠른 흐름
기본 사용
1. graphify 설치
2. 프로젝트 루트에서 graphify 실행
3. graphify-out/GRAPH_REPORT.md 로 구조 파악
4. graphify query/path/explain 으로 필요한 부분만 좁혀 질문
Codex 연결
- 설치: graphify install --platform codex
- 호출: $graphify .
- 상시 사용 설정: graphify codex install무엇을 만드는가
Graphify는 파일 묶음을 구조화된 지식 그래프로 바꾼다
Graphify는 코드베이스, 문서, PDF, 이미지 같은 입력을 읽고 개념과 관계를 그래프로 정리하는 도구입니다. 결과물은 단순 요약이 아니라 노드와 엣지, 커뮤니티, 경로, 근거 정보를 포함한 탐색 가능한 구조입니다. 큰 코드베이스에서 모든 파일을 다시 읽기보다, 먼저 그래프 보고서를 보고 중요한 허브와 연결을 좁혀 들어갈 때 효과가 큽니다.
대표 결과물
- graphify-out/graph.html: 인터랙티브 그래프
- graphify-out/GRAPH_REPORT.md: 주요 노드, 커뮤니티, 추천 질문
- graphify-out/graph.json: 쿼리 가능한 원시 그래프
- graphify-out/cache/: 변경 파일만 재처리하기 위한 캐시코드와 문서는 서로 다른 방식으로 추출된다
코드 파일은 tree-sitter 기반 AST 분석으로 클래스, 함수, import, 호출 관계 같은 구조를 로컬에서 추출합니다. 문서, 논문, 이미지 같은 비정형 자료는 AI 모델을 통해 개념과 관계를 추출합니다. 이 차이를 알고 있어야 보안 경계와 비용을 현실적으로 판단할 수 있습니다.
관계에는 EXTRACTED, INFERRED, AMBIGUOUS 같은 근거 상태가 붙습니다. 직접 추출된 관계와 추론된 관계를 구분할 수 있으므로, 아키텍처 결정을 검토할 때 추측을 사실처럼 받아들이는 위험을 줄일 수 있습니다.
Codex에서 쓰는 법
Codex에서는 슬래시 대신 달러 호출을 쓴다
Graphify README는 여러 AI 코딩 어시스턴트에서의 호출 방식을 함께 설명합니다. Codex에서는 슬래시 명령이 아니라 Skill 호출 규칙에 맞춰 $graphify . 형태로 실행하는 점이 중요합니다.
pip install graphifyy && graphify install --platform codexCodex에서 실행
$graphify .
$graphify ./docs
$graphify query "인증 흐름을 보여 줘"
$graphify path "DigestAuth" "Response"
$graphify explain "SwinTransformer"상시 사용 설정은 AGENTS.md와 훅을 건드릴 수 있다
graphify codex install은 Codex가 그래프 보고서를 먼저 참고하도록 프로젝트 지침과 훅을 설치하는 흐름입니다. 이 작업은 단순 패키지 설치와 달리 저장소 설정 파일을 수정할 수 있으므로, 팀 프로젝트에서는 변경 diff를 확인한 뒤 적용하는 편이 안전합니다.
적용 전 확인할 것
- AGENTS.md에 추가되는 규칙이 기존 프로젝트 규칙과 충돌하지 않는가
- .codex/hooks.json 같은 훅 파일이 새로 생기거나 바뀌는가
- graphify-out/ 산출물을 Git에 포함할지, .gitignore에 둘지 정했는가
- 문서나 이미지 분석 시 외부 모델 API로 내용이 전송될 수 있음을 팀이 알고 있는가언제 유용한가
| 상황 | Graphify를 쓰는 이유 |
|---|---|
| 큰 저장소의 구조를 처음 파악할 때 | 파일 검색 전에 주요 허브와 커뮤니티를 볼 수 있음 |
| 코드와 설계 문서의 연결을 찾을 때 | 코드 노드와 문서 개념을 같은 그래프에서 탐색할 수 있음 |
| 특정 흐름의 근거를 좁혀야 할 때 | query, path, explain으로 작은 서브그래프를 얻을 수 있음 |
| 긴 세션에서 컨텍스트 비용을 줄일 때 | 전체 파일 대신 GRAPH_REPORT.md와 쿼리 결과를 컨텍스트로 줄일 수 있음 |
| 변경된 파일만 다시 분석하고 싶을 때 | 캐시와 --update 흐름으로 재처리 범위를 줄일 수 있음 |
주의할 점
Graphify 결과는 원본을 대체하는 정답지가 아닙니다. INFERRED 관계는 추론이며,
중요한 판단에서는 원본 파일과 함께 확인해야 합니다. 특히 문서, PDF, 이미지 분석은
사용 중인 AI 플랫폼의 모델 API로 내용이 전송될 수 있으므로 민감한 자료에는 적용
범위를 먼저 정해야 합니다.
운영 기준
- 처음에는 작은 폴더에서 시험 실행한다
- graphify-out/GRAPH_REPORT.md 로 전체 구조를 먼저 본다
- 중요한 결론은 graph.json 쿼리 결과와 원본 파일을 함께 확인한다
- 자동 훅은 팀 규칙과 충돌하지 않는지 확인한 뒤 켠다
- 제외할 폴더는 .graphifyignore 에 명시한다참고 링크
2 sources