코딩 에이전트 통합

검색 primitive

일반 문자열 검색은 에이전트가 활용형을 직접 열거하게 합니다. 걷다를 찾을 때 걷고, 걸어, 걸었다를 매번 추론하면 질의마다 회수 범위가 달라집니다. 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

Skill 설치

kfind --init은 현재 프로젝트에 에이전트별 SKILL.md를 설치합니다. TTY에서는 대상을 선택하고, 자동화에서는 --agent를 반복하거나 stdin으로 대상 이름을 전달합니다. kfind 관리 표식이 없는 기존 파일은 덮어쓰지 않습니다.

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

Homebrew 설치본의 skill은 versioned Cellar가 아니라 안정적인 opt 경로를 가리킵니다. brew upgrade 뒤에는 프로젝트 link를 다시 만들지 않아도 새 릴리즈의 지침을 사용합니다.

지원 에이전트

세 통합은 같은 검색 계약을 사용하고 설치 경로만 다릅니다. 에이전트는 저장소 안의 skill을 읽은 뒤 kfind를 별도 shell 명령으로 실행합니다.

자동화 패턴

금지 표현 검사는 --quiet의 종료 코드로 결과 존재 여부를 판정할 수 있습니다. 리팩터링 후보 수집은 JSON Lines를 유지하고, 경로와 span을 기준으로 중복을 제거합니다. 여러 표제어의 순서가 중요하면 별도 명령을 합치는 대신 phrase query와 --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는 비대화형 stream을 유지합니다. 에이전트는 사람이 읽는 출력 문구를 파싱하지 않고 JSON field와 종료 코드만 사용합니다.