REFERENCE · QUERY COMPILATION

쿼리와 옵션

확장 수준은 어떤 형태를 생성할지 결정하고, 품사는 적용할 형태 규칙을 결정하며, boundary는 생성된 후보를 원문에서 허용할 조건을 결정합니다. Unicode 정규화와 phrase 거리는 문자열 표현과 여러 atom의 결합 범위를 정합니다. 각 축은 독립적으로 선택되지만 하나의 query plan 안에서 함께 적용됩니다.

기본 query plan

별도 옵션이 없으면 kfind는 활용형을 확장하고, 사전에서 품사를 자동으로 분석하며, 품사별 smart boundary를 적용합니다. query는 NFC로 정규화하고, phrase atom 사이에는 최대 24개의 Unicode scalar를 허용합니다.

expand=inflection
pos=auto
boundary=smart
unicode-normalization=nfc
max-gap=24

이 기본값은 사람이 품사를 모르는 상태에서 직접 검색하는 경우를 대상으로 합니다. 자동화가 recall과 재현 가능한 초기화 비용을 우선하면 품사를 명시하고 --boundary any --embedded --json을 함께 사용합니다. 다음 절들은 각 선택이 query plan을 어떻게 바꾸는지 정의합니다.

확장 수준

--expand는 하나의 표제어 analysis에서 생성할 program의 범위를 정합니다. 세 값은 독립된 검색기를 선택하는 것이 아니라, 입력 표면형에서 활용과 파생을 차례로 추가하는 포함 관계를 이룹니다.

Literal

literal은 입력한 문자열을 포함하는 program 하나만 만듭니다. 활용형, 조사가 붙은 형태나 파생 표제어는 생성하지 않습니다. 다만 선택한 boundary와 Unicode 정규화는 그대로 적용하므로, literal은 byte 검색과 완전히 같은 의미가 아니라 형태 확장만 끈 상태입니다.

kfind --expand literal 걸어 .

찾음: 걸어
제외: 걷다 · 걸었다

Inflection

기본값인 inflection은 사전의 품사와 활용 분류를 바탕으로 조사 결합, 어미 결합, 불규칙 교체와 제한된 continuation을 생성합니다. 명사 검증에서는 검증을과 검증에서도를, 동사 걷다에서는 걸어, 걸었다, 걷는을 찾을 수 있습니다. 두 사전이 함께 지지하는 활용형도 포함하지만, 새로운 표제어를 만드는 파생형은 이 범위에 포함하지 않습니다.

kfind --expand inflection 걷다 .

찾음: 걸어 · 걸었다 · 걷는 · 걷기에서도
제외: 새 파생 표제어

Derivation

derivation은 inflection의 모든 program을 보존하고 data/rules에 정의된 생산적 파생 규칙을 추가합니다. 현재 규칙은 -적, -하다, -되다, -시키다, -스럽다, -답다, -롭다와 -화를 포함합니다. 파생 결과가 용언이면 그 표제어에 용언 활용을 다시 적용하므로 검증하다뿐 아니라 검증했다도 검색합니다. 이 범위는 program 수와 false positive 가능성을 함께 늘리므로 파생어가 필요한 query에만 사용합니다. 한국어기초사전에서 용언과 부사의 entry ID가 양방향으로 일치하는 파생형도 이 단계에서만 추가됩니다.

검증 / noun
  ├─ literal    → 검증
  ├─ inflection → 검증 · 검증을 · 검증에서도
  └─ derivation → 위 결과 + 검증하다 · 검증했다 · 검증되다

--literal은 --expand literal --pos literal을 동시에 지정하는 단축 옵션입니다. 따라서 --expand inflection|derivation 또는 literal이 아닌 --pos와 함께 사용할 수 없으며, 충돌하면 컴파일 오류를 반환합니다. Literal query는 품사 사전이 필요하지 않으므로 full POS lexicon을 읽지 않습니다.

Boundary 정책

확장 수준이 생성할 형태를 결정한다면 boundary는 원문에서 발견한 span이 어떤 문자 환경에 놓여야 하는지를 결정합니다. 같은 program이라도 boundary에 따라 허용되는 위치가 달라지므로, 형태 coverage와 부분 문자열 허용 범위를 별개의 문제로 다뤄야 합니다.

값	검증 조건	적합한 용도
`smart`	품사별 consumption이 조사·어미를 소비한 뒤 token 끝을 확인합니다. 명사·대명사·수사·관형사와 full-POS 일반 용언 component는 같은 fine POS의 형태 근거가 검증된 경우에만 복구합니다.	사람의 기본 검색, precision 우선
`token`	core 시작과 완성된 token 끝이 모두 Unicode token 경계에 맞아야 합니다.	독립 token만 필요한 검색
`any`	좌우 경계를 요구하지 않고 형태 program이 만든 부분 문자열 후보를 보존합니다.	자동화와 recall 우선 검색

예를 들어 n:요리를 중국요리에서 찾을 때 smart는 완전한 형태 경로에서 요리가 명사 component로 확인되면 후보를 허용합니다. 반면 국요는 중국과 요리의 component 경계를 가로지르므로 거부합니다. any는 이런 형태 경계를 요구하지 않으므로 같은 문자열을 부분 span으로 보존합니다.

품사와 자동 분석

--pos auto는 core lexicon, enriched 용언 metadata, user lexicon, 생산적 접미 패턴과 full POS lexicon에서 가능한 analysis를 정해진 우선순위로 모읍니다. 같은 표제어에 여러 analysis가 있으면 하나를 임의로 선택하지 않고 합집합을 보존합니다. 전역 --pos 또는 atom 태그를 지정하면 이 집합을 해당 coarse POS로 제한합니다.

CLI 값	Atom 태그	주요 확장
`noun`	`n:`	복수·조사 연쇄, derivation
`pronoun`	`pro:`	대명사 override와 조사
`numeral`	`num:`	체언 consumption
`verb`	`v:`	동작 용언 어미와 불규칙 활용
`adjective`	`adj:`	상태 용언 어미와 불규칙 활용
`determiner`	`det:`	literal surface와 경계
`adverb`	`adv:`	literal, derivation에서 제한 보조사
`particle`	`j:`	받침 조건을 반영한 조사 이형태
`interjection`	`intj:`	literal surface와 token 경계
`literal`	`lit:`	형태 분석 없음

입력이 다로 끝난다는 사실만으로는 동사인지, 형용사인지, 체언인지 결정할 수 없습니다. kfind는 사전에 없는 다 종결 입력을 용언으로 추정하지 않고 literal 후보로 남깁니다. 새 용언을 활용형까지 검색하려면 v:커스텀하다처럼 품사를 명시하거나 user lexicon에 분석을 추가해야 합니다.

Unicode 정규화와 phrase 거리

정규화 옵션은 같은 글자가 서로 다른 Unicode byte열로 표현될 때 만들 query program을 정합니다. 원문 전체를 복사해 정규화하지 않으므로, 선택한 모드에 따라 anchor 수와 검증 비용이 달라집니다. Phrase의 max-gap은 정규화와 별개로, 앞 atom의 token 끝과 다음 atom의 token 시작 사이에 허용할 거리를 제한합니다.

옵션	동작	비용과 제약
`--unicode-normalization nfc`	NFC로 정규화한 query program을 사용합니다.	기본값이며 corpus 전체를 정규화하지 않습니다.
`canonical`	NFC와 NFD anchor를 모두 만듭니다.	program과 matcher 크기가 늘 수 있습니다.
`none`	입력 byte 형태를 그대로 찾습니다.	정규화가 다른 문자열은 같은 글자로 보여도 일치하지 않습니다.
`--max-gap 24`	인접 atom의 token span 사이 Unicode scalar 수를 제한합니다.	atom 순서를 유지하고 줄을 넘지 않습니다.

kfind 'n:권한 v:검증하다' src --max-gap 24

파일 검색과 출력 옵션

Query compile 옵션과 별도로 검색 범위, 입력 인코딩, 출력 문맥과 결과 형식을 제어할 수 있습니다. 다음 표는 역할별 옵션 묶음이며, 값과 충돌 규칙을 포함한 전체 CLI 계약은 한국어 README에서 확인할 수 있습니다.

역할	옵션 또는 값
검색 범위	`--glob · --type · --hidden · --no-ignore`
인코딩	`auto · utf-8 · utf-16le · utf-16be · euc-kr`
문맥과 위치	`-A · -B · -C · -n · --column`
결과 요약	`--count · --files-with-matches · --quiet`
구조화와 설명	`--json · --explain-query · --explain-match`
Terminal 출력	`--color · --no-pager`
실행 제어	`--threads · --sort path · --data-dir`

일반 text 결과를 TTY stdin/stdout에서 쓰면 검색 시작과 함께 내장 TUI를 열고 완성된 행을 점진적으로 반영합니다. 긴 match 줄은 검증된 match마다 별도 행으로 펼치고 target 앞뒤를 원문 비율에 맞춰 생략합니다. 검색 결과의 마지막 행이 content 영역 아래에 닿으면 더 스크롤하지 않습니다. 키 반복 이동은 입력된 이동량을 유지하면서 content viewport 크기에 맞는 frame으로 합칩니다. 검색 중에도 terminal resize와 이동을 처리하며,↑/↓ 또는 k/j로 이동하고 q나Esc로 종료합니다. Redirect, pipe, JSON Lines와 count·파일명 요약·quiet 출력은 기존 stdout stream을 유지합니다. 대화형 text 출력에서도 TUI가 필요하지 않으면 --no-pager로 끌 수 있습니다.

Agent skill 초기화 옵션

Skill 초기화는 프로젝트 파일을 변경하는 동작이고, 검색은 corpus를 읽는 동작입니다. 두 책임을 섞지 않기 위해 --init mode에는 query, path와 검색 옵션을 전달할 수 없습니다.

옵션	입력	계약
`--init`	query와 path 없음	현재 디렉터리에 agent skill을 초기화합니다.
`--agent <AGENT>`	`claude-code` · `codex` · `gemini` · `custom`	`--init`에서만 사용하며 반복할 수 있습니다. 같은 대상은 한 번만 처리합니다.
대상 옵션 생략	TTY 선택 또는 비TTY stdin	TTY에서는 checkbox를 표시하고, 비대화형 입력에서는 공백이나 줄바꿈으로 구분한 agent 이름을 받습니다.

대화형 선택을 취소하거나 대상을 고르지 않으면 파일을 변경하지 않습니다. 설치 대상 중 하나라도 실패하면 전체 작업을 성공으로 보고하지 않으며, kfind 관리 표식이 없는 기존 파일은 보존합니다. 이 계약은 반복 실행으로 관리 중인 skill을 갱신하면서도 사용자가 만든 파일을 덮어쓰지 않게 합니다.