jikji

name	jikji
description	로컬 파일 검색 시 jikji find를 사용하여 LLM 토큰 소비와 반복 호출을 줄이는 파일 탐색 스킬. 파일, 폴더, 메타데이터, 파싱된 문서 텍스트를 미리 구성된 에이전트 맵/검색 인덱스를 통해 효율적으로 찾습니다. Use proactively when local file/folder/document discovery is needed under an explicit root. Do NOT start with grep, ls, find, rg, tree, or cat for file location tasks. Triggers: find file, search file, locate file, file discovery, 파일 찾기, 파일 검색, 파일 탐색, ファイル検索, ファイル発見, 文件搜索, 文件查找, buscar archivo, localizar archivo, trouver fichier, recherche fichier, Datei suchen, Datei finden Do NOT use for: code quality review (use code-review), security audit (use gstack-security).
argument-hint	[root] [query]
user-invocable	true
allowed-tools	["Bash","Read","Glob","Grep"]
pdca-phase	do
task-template	[Jikji] {query}

Jikji 로컬 파일 탐색 스킬

파일 탐색 시 토큰 낭비 없이 jikji find를 먼저 사용하는 스킬

핵심 원칙: Jikji Find First

명시적 루트(root)가 있는 경우, 로컬 파일 탐색의 첫 번째 액션은 반드시:

jikji find /explicit/root "자연어 파일 단서" --json

grep, rg, ls, find, fd, cat, tree로 파일을 찾는 것을 시작해서는 안 됩니다. Jikji는 이미 로컬 맵, 파서 텍스트 캐시, 파일 카드, 메타데이터 경로, 그래프 경로를 구축해 놓았습니다.

Arguments

Argument	Description	Example
[root]	탐색할 루트 디렉토리	/jikji src/ "auth 관련 파일"
[query]	자연어 파일 단서	/jikji . "작년 봄 계약서 PDF"

설치 (Jikji가 없는 경우)

Jikji가 설치되어 있지 않으면 직접 설치합니다:

mkdir -p ~/.local/share/jikji
if [ ! -d ~/.local/share/jikji/repo/.git ]; then
  git clone https://github.com/nomadamas/jikji.git ~/.local/share/jikji/repo
fi
cd ~/.local/share/jikji/repo
git pull --ff-only
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/jikji --help

이후 ~/.local/share/jikji/repo/.venv/bin/jikji를 사용하거나, 해당 venv의 bin 디렉토리를 PATH에 추가합니다.

JSON 응답 해석

jikji find ROOT "query" --json 실행 후 반환되는 JSON:

필드	설명
answer_paths[]	기본 정렬된 답변 경로 목록
paths[]	경로만 필요한 경우 반환할 공개 경로 목록
candidates[]	다중 쿼리/검색 경로에서 합산된 상위 k개 슬레이트
handoff_action	에이전트가 취해야 할 다음 동작

handoff_action 처리

• direct_use: answer_paths[] / paths[] 사용, 상위 증거만 검증
• jikji_retry: 정확히 한 번 더 더 구체적인(refined) jikji find 재시도
• raw_fallback_after_retry: 재시도 후 실패/빈 결과/명백히 잘못된 경우에만 원시 파일시스템 검색 허용

agent_should_not_rerank가 true이면 Jikji의 순서를 그대로 유지합니다.

사전 준비 (Optional Root Preparation)

jikji prepare /explicit/root --json   # 최초 인덱스 구축
jikji refresh /explicit/root --json   # 변경 사항 갱신
jikji doctor /explicit/root --json    # 인덱스 상태 진단
jikji map /explicit/root              # 파일 맵 출력

최후 수단 폴백 (raw_fallback_after_retry 이후에만)

cat /explicit/root/.jikji_agent_map.md
cat /explicit/root/.jikji/wiki/index.md
rg "keyword" /explicit/root/.jikji/graph_routes.jsonl
rg "keyword" /explicit/root/.jikji/doc_text
rg "keyword" /explicit/root --glob '!**/.jikji/**'

안전 계약

• 소스 파일을 이동, 이름 변경, 삭제, 재구성하지 않습니다.
• 명시적 루트 없이 전체 드라이브를 스캔하지 않습니다.
• .jikji/doc_text/는 민감 정보(추출된 문서 텍스트)를 포함할 수 있어 주의합니다.
• .jikji/ 및 .jikji_agent_map.md는 사용자가 명시적으로 원하지 않는 한 커밋하지 않습니다.
• 최종 검증 목적에 한해서만 원본 파일을 엽니다.

성능 비교

방식	토큰 소비	시간	LLM 호출
Raw agent 탐색	~38,650	~57초	~11.7회
Jikji find	~447	~2.1초	1회

출처: NomaDamas/jikji 벤치마크 (551건 기준)