AI 에이전트가 조회할 수 있는 로컬 코드 그래프 도구 만들기

## AI 요약이 아닌 구문 트리로 로컬에서 코드 그래프 만들기 프로젝트 분석은 로컬에서 결정론적으로 수행하세요. 언어 모델의 요약이 아니라 구문 트리에서 기호, 관계, 파일을 도출하고, 프로젝트 범위의 상태를 로컬 색인 데이터베이스에 저장하며, 생성된 지식 그래프를 라이브러리, 명령줄 인터페이스 또는 에이전트 프로토콜로 제공하세요. 시스템을 계층형 처리 흐름으로 구성하세요. - 추출 계층은 소스 코드를 분석하여 표준 기호를 생성합니다. - 해석 계층은 가져오기, 이름, 프레임워크 및 기타 관계를 연결합니다. - 그래프 쿼리는 호출자, 피호출자, 경로 및 영향에 관한 질문에 답합니다. - 컨텍스트 형식화 계층은 소비 시스템을 위해 간결한 Markdown 또는 JSON을 준비합니다. 부하가 큰 분석은 주 실행 스레드 밖에서 수행하세요. 모든 계층을 하나의 공개 진입점으로 연결하고 그 진입점만 지원되는 라이브러리 인터페이스로 삼으세요. 하나의 실행 파일이 의도적으로 설치 프로그램, 색인 프로그램 및 프로토콜 서버 역할을 모두 한다면 같은 아티팩트로 모든 역할을 테스트하세요. 에이전트용 도구 지침에는 하나의 기준 정보원만 유지하고, 가급적 프로토콜 초기화 응답을 사용하세요. 같은 지침을 각 클라이언트의 저장소 파일에 중복해서 넣지 마세요. 복사본은 서로 달라져 업그레이드나 제거를 불완전하게 만들기 때문입니다. ## 런타임 버전을 고정하고 코드가 아닌 파일도 빌드에 포함하기 저장소에 문서화된 빌드, 개발, 정리, 테스트, 평가 및 로컬 CLI 명령을 찾아 사용하세요. 고정된 실행 환경 버전 범위를 준수하고 그 범위를 벗어나면 명확히 실패하게 하세요. 주 버전이 더 최신이라고 해서 자동으로 호환되는 것은 아니며, 소스에서 실행할 때는 묶음 배포판보다 더 엄격한 최소 버전이 필요할 수 있습니다. 실행 시 필요한 리소스를 빌드 계약의 일부로 취급하세요. 데이터베이스 스키마, 구문 분석기 문법, WebAssembly 모듈 및 코드가 아닌 기타 파일을 배포판에 복사하세요. 새 리소스를 추가할 때마다 복사 단계를 갱신하지 않으면 그 리소스는 배포되지 않습니다. 특정 테스트 파일이나 이름 패턴으로 검증을 시작한 다음 직접 영향을 받는 테스트 모음을 실행하세요. 일반 단위 테스트를 수행하는 대신 테스트 픽스처를 만들거나 동작을 평가하는 평가 모음은 별도로 유지하세요. 저장소 의미가 중요할 때는 실제 저장 동작을 사용하세요. 서로 격리된 임시 디렉터리를 만들고 각 테스트 후에 정리하며, 모의 객체로 가리지 말고 실제 데이터베이스 모드를 확인하세요. ## 노드와 엣지 종류를 통일하고 공개 API를 작게 유지하기 표준 노드 유형과 에지 유형을 하나의 스키마에 정의하세요. 추출기와 해석기는 정확히 그 문자열을 생성해야 합니다. 쿼리, 순회 또는 직렬화된 데이터를 몰래 분할하는 거의 같은 변형을 도입하지 마세요. 공개 API의 범위를 좁게 유지하세요. 지원되는 유형을 공개 진입점에서 다시 내보내고, 명령줄 및 프로토콜 어댑터가 우회하지 않고 동일한 핵심 서비스를 사용하도록 하세요. 저장 방식에 관한 주장은 명시적이고 검증 가능하게 만드세요. 제품에 선행 기록 방식과 전문 검색을 지원하는 데이터베이스 백엔드가 하나뿐이라면 실제로 동작 중인 그 백엔드를 보고하고, 호환성 어댑터는 간결하게 유지하며, 구현되지 않은 네이티브 또는 WebAssembly 대체 수단이 있는 것처럼 암시하지 마세요. 언어, 프레임워크, 쿼리 또는 스키마 필드를 추가할 때는 담당 추출기나 해석기, 공개 계약, 직렬화, 테스트 및 사용자용 지침을 함께 갱신하세요. ## 여러 AI 클라이언트에 설정을 망가뜨리지 않고 설치하고 깔끔하게 제거하기 지원되는 각 클라이언트를 고유한 구성 위치, 형식 및 프로토콜 인수를 가진 대상으로 모델링하세요. 설치 프로그램 전체에 조건문을 흩뿌리지 말고, 하나의 대상 구현과 하나의 레지스트리 항목으로 새 클라이언트를 추가하세요. 구성을 정밀하게 편집하세요. 관련 없는 TOML 표와 배열을 보존하고, 주석 포함 JSON의 형식과 주석을 유지하며, 이미 존재하는 지원 파일 변형을 우선 사용하고, 새로 설치할 때만 문서화된 기본값을 생성하세요. 설치는 멱등성을 가져야 하고, 재설치는 부분적인 상태를 스스로 복구해야 하며, 제거는 설치 프로그램이 소유한 변경만 되돌려야 합니다. 안정적인 마커를 사용해 오래된 지침 블록을 제거하되, 현재 에이전트 지침은 다른 복사본을 작성하지 말고 실행 중 사용되는 단일 정보원에 유지하세요. 인접 설정 보존, 바이트 단위로 동일한 재실행, 되돌릴 수 있는 제거 및 부분 상태 복구에 대해 매개변수화된 계약 테스트로 모든 대상을 다루세요. 클라이언트가 잘못된 디렉터리에서 프로토콜 하위 프로세스를 시작할 때 명시적인 프로젝트 경로를 삽입하는 것처럼 클라이언트별 작업 디렉터리 수정 사항을 유지하세요. ## 에이전트가 이미 쓰는 검색 도구를 강화하기 검색 기능을 만들기 전에, 에이전트가 이미 호출하는 도구가 에이전트가 이미 제공하는 입력으로 더 많은 일을 할 수 있게 하는지 물어보세요. 에이전트가 새 도구를 배우거나, 다른 쿼리 방식을 채택하거나, 눈에 잘 띄지 않는 예시와 초기화 설명을 알아차릴 것이라고 기대하지 마세요. 정확한 답을 얻으려면 정확한 입력을 사용하세요. 기본 탐색 도구는 한정 이름을 포함한 간결한 기호 이름 집합을 받아 그 사이의 흐름을 연결해야 합니다. 보조 노드 도구는 전체 소스 코드와 호출자 및 피호출자 컨텍스트를 반환해야 하며, 이름이 모호하면 가능한 모든 오버로드를 하나의 응답으로 반환해야 합니다. 끝점을 구분하지 못하는 모호한 자연어 도구에 정밀한 흐름 응답을 합치지 마세요. 정적 추출과 증거 기반 동적 관계를 포함하여 에이전트가 이미 선택하는 도구 내부에서 범위를 개선하세요. 토큰 사용량뿐 아니라 실제 경과 시간 지연과 도구 호출 횟수도 최적화하세요. 절감 효과는 더 작게 누적된 컨텍스트에서 더 적은 대화 차례를 거칠 때 생기므로 마지막 응답만이 아니라 모든 대화 차례의 총사용량을 측정하세요. ## 에이전트가 파일을 직접 읽으러 돌아가지 않도록 답하기 예상되는 상태는 성공 형태로 반환하세요. 색인되지 않은 프로젝트, 누락된 기호 또는 색인 밖의 파일은 오류 표시 없이 실행 가능한 지침을 반환해야 합니다. 실제 오류는 보안상 거부와 진짜 오작동에만 사용하고, 재시도가 적절한 경우에만 제한된 재시도 지침을 추가하세요. 현재 루트가 색인되지 않았더라도 도구 인터페이스를 제공하세요. 색인된 프로젝트를 선택하는 방법은 설명하되 색인 생성은 사용자가 결정하게 하세요. 시작할 때 도구를 숨기면 모노레포와 색인 생성 전에 시작된 세션이 제대로 작동하지 않을 수 있습니다. 저장소 크기에 따라 탐색 호출 예산과 출력 예산을 모두 단조롭게 늘리세요. - 파일 500개 미만: 호출 1회, 약 18,000자, 파일당 3,800자 - 파일 500–4,999개: 호출 2회, 약 28,000자, 파일당 6,500자 - 파일 5,000–14,999개: 호출 3회, 약 35,000자, 파일당 7,000자 - 파일 15,000–24,999개: 호출 4회, 약 38,000자, 파일당 7,000자 - 파일 25,000개 이상: 최대 호출 5회, 약 38,000자, 파일당 7,000자 더 큰 구간에는 더 작은 구간보다 적은 파일당 예산을 절대로 배정해서는 안 됩니다. 에이전트에게 원시 파일 직접 읽기로 돌아가라고 절대로 지시하지 마세요. 다른 그래프 호출로 안내하고 반환된 소스 코드는 이미 읽은 것으로 취급해야 한다고 명시하세요. ## 콜백과 이벤트 흐름을 처음부터 끝까지 연결하기 정적 분석은 콜백, 옵저버, 이벤트 이미터, 반응형 렌더링, 디스크립터 및 기타 간접 디스패치를 놓칩니다. 제한된 범위의 합성기나 프레임워크 해석기는 방어 가능한 증거로 표준 흐름을 연결할 수 있을 때만 추가하세요. 합성된 모든 에지를 휴리스틱으로 표시하고, 어떤 메커니즘이 생성했는지 기록하며, 등록 또는 연결 위치를 포함하세요. 이 출처 정보를 흐름과 함께 표시하여 소비 시스템이 분석된 사실과 추론된 관계를 구분할 수 있게 하세요. 한 번의 간접 전환을 보여주면서 다음 경계를 끊긴 상태로 두는 부분적 범위는 아무것도 없는 것보다 나쁩니다. 흐름을 시작 동작부터 눈에 보이는 결과까지 연결하고, 에이전트를 다시 측정하며, 여전히 수동 재구성을 강요하는 반쯤 연결된 경로를 배포하지 마세요. 안전하게 추론할 수 없는 실행 환경 경계에서는 잘못된 에지보다 침묵을 선택하세요. 재색인이 노드 수를 부풀리지 않는지 확인하고, 해석기의 범위를 넓히기 전에 합성된 에지의 정확도를 표본 점검하세요. ## 실제 저장소와 Windows·Linux에서 에이전트 동작 확인하기 모든 언어와 프레임워크에 대해 서로 다른 흐름 질문을 최소 3개 사용하여 실제 소형, 중형, 대형 저장소를 테스트하세요. 다루기 어려운 디스패치 경계를 피하는 고립된 기호 대신 각 프레임워크의 표준 종단 간 흐름을 선택하세요. 빌드된 아티팩트를 대상으로 결정론적 검사를 실행하세요. 탐색이 예산 내에서 예상 끝점을 연결하고, 재색인 후에도 노드 수가 안정적으로 유지되며, 휴리스틱 에지에 정확한 출처 정보가 포함되는지 확인하세요. 의도적으로 선택한 동일한 최저 성능 모델과 동일한 추론 노력을 사용하여 실험군별로 에이전트 A/B 테스트를 최소 2회 실행하세요. 소요 시간, 총 도구 호출 수, 원시 파일 읽기 및 텍스트 검색을 기록하고, 유리한 단일 실행 대신 범위를 보고하세요. 시작 지연 때문에 도구가 가려질 수 있다면 지속형 프로토콜 프로세스를 미리 예열하고, 초기화 시점의 스냅샷이 아니라 실제 호출을 기준으로 연결 여부를 판단하세요. 저장소의 탐색 예산 안에서 원시 파일 읽기와 검색이 거의 없고, 대조군보다 더 빨리 완료되며, 대조 저장소에서 성능 저하가 없도록 요구하세요. 플랫폼별 동작은 실제 플랫폼에서 검증하세요. Windows 전용 주장과 Windows 외 플랫폼용 주장을 명시적으로 구분하세요. Linux에서는 일회용 컨테이너에 플랫폼 네이티브 종속성을 새로 설치하여 빌드하고 init 프로세스를 사용해 종료된 하위 프로세스를 회수하세요. Windows에서는 로컬 파일 시스템과 실제 가상 머신에 새로 설치한 종속성을 사용하고, 원인을 지목하기 전에 의심스러운 실패를 기본 브랜치와 비교하세요. ## 릴리스 노트를 쓰고 게시는 자동 릴리스 워크플로에 맡기기 예정된 변경 사항은 Unreleased 섹션 아래에 작성하세요. 릴리스 작업 흐름이 Unreleased 내용을 자동으로 승격한다면 다음 버전 블록을 미리 만들지 마세요. 사용자에게 유용한 릴리스 노트를 작성하세요. - 기능, 수정, 보안 또는 호환되지 않는 변경 사항에 해당할 때만 사용자 중심 제목 아래에 내용을 분류하세요. - 각 항목에는 기능이나 해결된 증상을 설명하는 쉬운 문장 하나를 작성하세요. - 내부 경로, 구현 기호, 성능 측정 세부 정보 및 빈 섹션은 제외하세요. - 유용한 이슈 참조, 지원되는 플랫폼 이름 및 사용자가 실제로 입력하는 명령은 유지하세요. 자동 릴리스 작업 흐름이 잠금 파일 버전을 동기화하고, 변경 기록을 승격하고, 플랫폼 번들을 빌드하고, 체크섬을 생성하고, 릴리스와 패키지를 게시하도록 두세요. 명시적으로 요청받지 않았다면 버전을 올리지 말고, 해당 단계가 작업 흐름에 속한다면 패키지를 수동으로 게시하거나 릴리스 커밋을 푸시하거나 태그를 만들지 마세요. 이슈, 검토 의견 또는 외부 보고서에 대응하기 전에 날짜를 기준으로 삼고, 릴리스된 상태, 병합되었지만 아직 릴리스되지 않은 상태 및 현재 브랜치를 비교하세요. 진행 중인 수정 사항을 보고자가 이전에 볼 수 있었던 상태의 것으로 돌리지 마세요. 제품 요구 사항은 코드 그래프에서 추론되는 사실이 아니라 사용자의 결정으로 취급하세요. 모든 문서 이미지 URL에 버전을 지정하고 리소스가 변경될 때마다 쿼리 태그를 증가시켜 캐시가 오래된 바이트를 계속 제공하지 못하게 하세요.