Quick Flow

Graphify는 Codex 내장 기능이 아니라, 저장소를 지식 그래프로 추출하고 조회하는 별도 도구입니다. 그래프가 있으면 구조를 먼저 좁히고, 중요한 결론은 반드시 원본 파일로 되돌아가 확인합니다.

질문이 "이 저장소에서 X가 어디와 연결되는가"일 때
1. graphify-out/GRAPH_REPORT.md  -> 규모, 큰 허브, 커뮤니티 확인
2. graphify query "X의 흐름"    -> 넓은 관련 맥락
3. graphify path "A" "B"       -> 두 개념 사이의 연결 경로
4. graphify explain "X"         -> 그래프 노드의 짧은 해설
5. source_location과 원본 파일   -> 구현 사실 최종 확인

그래프를 읽는 순서

graphify-out/GRAPH_REPORT.md는 그래프의 입구입니다. 파일 수, 추출 상태, 큰 커뮤니티와 허브를 먼저 확인하면 질문에 관계없는 디렉터리를 통째로 읽지 않아도 됩니다. 그래프가 이미 있을 때는 다시 추출하기보다 query부터 실행하는 편이 빠릅니다.

graphify query "인증 실패가 응답으로 전달되는 경로"
graphify path "AuthModule" "Response"
graphify explain "AuthModule"

query는 넓게 후보를 모으는 명령이고, path는 두 노드가 그래프 안에서 어떻게 이어지는지 확인하는 명령입니다. 이름이 정확하지 않거나 그래프가 오래됐으면 결과가 비거나 엉뚱한 경로가 나올 수 있습니다. 이때는 결과의 source_location을 열어 현재 코드와 문서를 대조합니다.

Graphify 관계에는 직접 추출된 사실과 추론 관계가 섞일 수 있습니다. INFERRED나 AMBIGUOUS 표시는 원본을 읽기 위한 단서이지, 구현 계약이나 보안 판단의 근거가 아닙니다.

설치와 갱신 경계

현재 프로젝트에 Graphify가 없다면 도구 설치와 Codex용 Skill 배포는 별도 작업입니다. 설치 명령과 배포 방식은 Graphify 배포 버전에 따라 달라질 수 있으므로, 프로젝트의 설치 안내와 생성된 Skill을 함께 확인합니다.

# Python 환경에 CLI를 설치하는 한 가지 방식
python -m pip install graphifyy

# 현재 저장소의 기존 그래프를 갱신
graphify update .

graphify update .는 성공했다고 출력될 때만 graphify-out/을 최신 근거로 봅니다. 대형 저장소에서는 산출물 크기 제한, 의미 추출용 API 키, 제외 규칙, 실행 시간 때문에 갱신이 실패할 수 있습니다. 실패한 그래프에 새 변경이 반영됐다고 가정하면 이후 query 결과도 오래된 상태가 됩니다.

문서·이미지의 의미 추출은 설치 구성에 따라 외부 모델을 사용할 수 있습니다. 민감한 파일은 .graphifyignore 등 프로젝트의 제외 설정으로 먼저 범위를 정하고, 생성 산출물을 커밋할지 여부도 팀 규칙으로 결정합니다.

흔한 오해

• Graphify가 있다고 해서 원본 검색을 생략하지 않습니다. 그래프는 탐색 순서를 줄이는 도구입니다.
• graphify-out/graph.json이 있다고 해서 최신 그래프라는 뜻은 아닙니다. 보고서의 생성 시점과 마지막 변경을 비교합니다.
• query가 실패했다고 즉시 전체 재추출하지 않습니다. 먼저 CLI 설치 상태, 그래프 파일 존재, 노드 이름과 그래프 크기 제한을 확인합니다.
• Codex에 적용된 Graphify 지침은 프로젝트별 Skill 또는 AGENTS.md 규칙입니다. Codex 자체 명령이나 보안 정책으로 오해하면 설치·업데이트 실패 원인을 잘못 찾게 됩니다.

Codex의 지침·Skill 경계는 AGENTS.md 작성, 변경 후 검증 흐름은 검증과 리뷰 루프에서 이어서 확인할 수 있습니다.