AI 코딩 하네스 프레임워크
2026-04-01 — present
Claude Code·Codex·Amazon Q 등 AI 코딩 에이전트의 컨텍스트, 규칙, RAG, 비용, 브라우저 런타임을 Git 기반 운영 인프라로 통합한 개인 개발 프레임워크 — 로컬 BGE-M3 벡터 RAG, MCP, 훅 기반 거버넌스, 런타임 서피스 컴파일러, 비용 분석기 구축
시스템 아키텍처
문제 해결 과정
AI 에이전트별 컨텍스트와 규칙이 문서·설정·로컬 홈에 흩어져 런타임마다 드리프트 발생
하네스 소스를 canonical source로 두고 Claude/Codex 런타임 서피스를 자동 생성, XML runtime contract와 cross-harness diff 검증 추가
kh/gp/gd 3개 하네스의 생성 CLAUDE.md 및 런타임 컨트랙트 정합성 확보
마크다운 지식 베이스가 커져 에이전트가 관련 컨텍스트를 매번 수동 탐색
sqlite-vec + FTS5 하이브리드 RAG, BGE-M3 로컬 임베딩, RRF fusion, MCP 검색 서버, 마크다운 변경 후 자동 재색인 구현
548 파일·3,347 청크·20.7 MB 인덱스, warm 쿼리 0.7초, 골드 쿼리 5건 top-2/3 적중
RAG가 opt-in 참고 도구라 실제 조사·검토 프롬프트에서 누락
UserPromptSubmit 기본 트리거로 전환하고 프롬프트 12자 이상이면 search_harness가 자동 호출되도록 gp/gd까지 포팅
3개 하네스에서 15/15 default-on 테스트 통과, 실 프롬프트 smoke test 적중
이력서·포트폴리오 JSON이 RAG 검색 범위 밖이라 JD 커스터마이징 시 근거 검색 누락
portfolio/resume JSON chunker와 target=resume 색인 경로, path-based auto-reindex, federation 검색을 구현
resume corpus 109 청크 색인, 32개 테스트 통과, 4개 DB 통합 검색 동작 확인
프로젝트 설명
AI 코딩 에이전트를 단발성 도구가 아니라 반복 가능한 개발 인프라로 운영하기 위해 만든 개인 하네스다. Claude/Codex 런타임 서피스를 소스 설정에서 자동 생성하고, 마크다운 지식 베이스를 로컬 임베딩 기반 RAG로 색인해 세션 시작·프롬프트 제출·편집·커밋 시점에 자동 주입한다. 문서만으로는 지켜지지 않는 규칙은 Git 훅과 테스트로 강제하고, 비용 분석기는 세션 트랜스크립트를 8개 범주로 분해해 숨은 토큰 비용을 추적한다. 이후 portfolio/resume JSON 코퍼스까지 RAG 대상으로 확장해 이력서 커스터마이징과 포트폴리오 검색에도 같은 증거 검색 경로를 적용했다.
주요 내용
- Claude/Codex 런타임 서피스 자동 생성 + XML runtime contract로 3개 하네스 정합성 확보
- 로컬 BGE-M3 RAG로 548 파일·3,347 청크 색인, warm 쿼리 0.7초 달성
- RAG default-on 전환으로 프롬프트 12자 이상 search_harness 자동 호출, 3개 하네스 15/15 테스트 통과
- resume/portfolio JSON을 RAG 코퍼스로 통합, 109 청크 색인 + 32개 테스트 통과
- Codex Browser + node_repl IAB 신뢰 경계와 fallback 순서 문서화, 3개 하네스 런타임 설정 반영
성과 지표
| 성과 지표 | 이전 | 이후 |
|---|---|---|
| RAG MVP 인덱스 | manual context search | 548 files / 3,347 chunks / 20.7 MB (0.7s warm query) |
| RAG default-on 검증 | opt-in trigger | 15/15 tests across 3 harnesses (prompt >=12 chars auto-search) |
| Resume RAG 코퍼스 | 0 indexed chunks | 109 chunks (32 tests passed) |
기술 선택 근거
- ▶ 클라우드 벡터 DB 대신 로컬 BGE-M3 + sqlite-vec 선택: 마크다운 변경 직후 자동 재색인과 비용 통제를 우선
- ▶ 문서 규칙 대신 hook-first 강제 선택: 에이전트가 필요 시점에 문서를 읽지 않는 문제를 런타임 차단으로 보완
- ▶ Claude/Codex별 수동 설정 대신 runtime surface compiler 선택: 생성물 드리프트를 줄이고 3개 하네스 정합성 검증을 자동화
- ▶ 검색 opt-in 대신 default-on 선택: 조사·리뷰·편집 같은 실제 프롬프트에서 근거 검색 누락을 줄이기 위해 UserPromptSubmit에 연결
깨달은 점
- • AI 개발 생산성은 프롬프트 품질만으로 유지되지 않고, 런타임 컨텍스트·규칙 강제·증거 검색·비용 관측성을 같은 운영 경로로 묶어야 재현 가능하다는 점을 체득
- • 문서 규칙은 필요 시점에 읽히지 않으면 정책이 아니라 참고 자료에 머물기 때문에, 중요한 규칙은 훅·테스트·컴파일러 출력으로 강제해야 한다는 기준 정립
- • RAG는 검색 품질뿐 아니라 자동 호출 위치, 색인 최신성, 사용 로그, fallback 경로까지 포함해야 실제 에이전트 워크플로우에 편입된다는 점 확인
- • Claude/Codex처럼 런타임별 기능과 신뢰 경계가 다른 도구는 canonical source와 생성기 기반으로 관리해야 장기 운영에서 드리프트를 줄일 수 있다는 점 학습