안내 · 에이전트

코딩 에이전트 통합

형태 검색 단위

일반 문자열 검색에서는 에이전트가 활용형을 직접 열거해야 합니다. 걷다를 찾을 때마다 걷고, 걸어, 걸었다를 추론하면 질의마다 회수 범위가 달라집니다. kfind는 표제어와 품사를 하나의 검색 계획으로 컴파일해 같은 입력에 같은 후보와 생성 근거를 반환합니다.

kfind는 문장의 의미를 판정하지 않습니다. 에이전트는 넓게 회수한 span 주변의 코드를 읽고 작업 목적에 맞는 후보를 선택합니다. 형태 생성과 문맥 판단의 책임을 분리하면 결과를 재현하면서도 에이전트가 문맥을 판단할 수 있습니다.

권장 사용 절차

1. 검색 대상과 품사

   파일 경로를 먼저 제한하고 각 atom에 n:, v: 같은 품사 태그를 지정합니다.

2. 회수 우선 경계

   --embedded --boundary any로 추가 리소스 초기화와 구조 판정을 생략하고 형태 후보를 수집합니다.

3. 구조화된 결과

   --json에서 UTF-8 span, 품사와 rule provenance를 읽어 후속 도구에 전달합니다.

4. 문맥 검토

   결과 줄과 인접 코드를 읽고 의미가 다른 동형이의어를 제외합니다.

kfind --embedded --boundary any --json 'n:사용자 v:검증하다' src
kfind --embedded --boundary any --pos verb --json 걷다 crates

통합 설치와 제거

kfind --init은 현재 프로젝트에 에이전트별 SKILL.md와 project hook을 설치합니다. 대화형 터미널에서는 대상을 선택합니다. 자동화에서는 --agent를 반복하거나 stdin으로 대상 이름을 전달합니다. kfind 관리 표식이 없는 기존 skill과 에이전트 설정은 보존합니다.

kfind --init
kfind --init --agent codex --agent claude-code
printf 'codex
gemini
' | kfind --init

--uninstall로 같은 대상의 통합을 제거합니다.

kfind --uninstall --agent codex --agent claude-code
printf 'codex
gemini
' | kfind --uninstall

제거 대상은 kfind 관리 skill과 kfind --agent-hook 핸들러뿐입니다. 다른 에이전트 설정과 hook은 보존하며, 이미 제거된 대상은 성공으로 처리합니다.

Homebrew 설치본의 skill은 버전별 Cellar 경로 대신 안정적인 opt 경로를 가리킵니다. brew upgrade 뒤에도 프로젝트 link를 다시 만들지 않고 새 릴리스의 지침을 사용합니다.

프로젝트 hook은 각 에이전트의 신뢰 절차를 통과한 뒤 동작합니다. Codex에서는 /hooks로 검토하고 신뢰합니다. SessionStart hook은 skill의 자동 선택 여부와 관계없이 한국어 표제어·활용형 검색에 kfind를 사용하라는 지침을 세션 context에 추가합니다. 실행 전 hook은 고정 문자열 모드 없이 한글 검색 패턴을 받은 rg·grep 계열과 git grep을 차단하고 kfind로 다시 검색하도록 안내합니다. 정확한 표기 검색의 -F, --fixed-strings와 fgrep은 허용합니다.

지원 에이전트

세 통합은 같은 검색 계약을 사용합니다. 에이전트는 저장소 안의 skill을 읽고, SessionStart hook은 그 사용 조건을 항상 주입하며, 실행 전 hook은 literal 셸 검색을 검사합니다.

자동화 패턴

금지 표현 검사는 --quiet의 종료 코드로 결과 존재 여부를 판정할 수 있습니다. 리팩터링 후보를 수집할 때는 JSON Lines를 유지하고 경로와 span을 기준으로 중복을 제거합니다. 여러 표제어의 순서가 중요하면 별도 명령을 합치지 말고 구 검색 질의와 --max-gap을 사용합니다.

kfind --pos verb --quiet 사용하다 docs && exit 1
kfind --embedded --boundary any --json 'n:권한 v:검증하다' src | jq -c 'select(.type == "match")'

결과가 너무 많으면 먼저 검색 경로와 glob을 줄입니다. 의미 판별을 기대해 경계 정책을 임의로 바꾸지 않으며, 구조 정밀도가 필요한 사람용 검색에서는 full POS와 smart를 별도 실행합니다.

통합 계약

검색 결과는 stdout에, 진단과 오류는 stderr에 기록합니다. 일치가 있으면 종료 코드 0, 일치가 없으면 1, 사용법·입력·리소스 오류가 발생하면 2를 반환합니다. JSON Lines의 각 match record는 경로, 행, 원문, UTF-8 byte span과 생성 근거를 포함합니다.

대규모 출력은 파일과 glob으로 먼저 제한합니다. TTY pager가 필요한 사람용 출력과 달리 --json, --count, --quiet는 비대화형 스트림을 유지합니다. 에이전트는 사람이 읽는 출력 문구를 파싱하지 않고 JSON 필드와 종료 코드만 사용합니다.