AI에게 repo 전체를 읽히기 전에, Context Pack으로 초기 조사 단계를 가볍게 만들었다

이 기사는 자신의 개인 개발에서 시도하고 있는 AI 초기 조사 도구의 측정 로그를 바탕으로 작성한 초안입니다. 숫자는 3개의 개인 개발 repo에서의 측정 결과이며, 일반적인 벤치마크가 아닙니다.

관련된 사고방식으로서, 이전에 Codex로 PR을 양산하기 전에 Issue·상태·판단 로그를 연결하는 「문맥 허브 (Context Hub)」를 만든다는 기사를 쓴 적이 있다. 이번에는 그중에서도 「AI에게 전달할 첫 번째 문맥을 어떻게 작게 만들 것인가」에 초점을 맞춘 측정 메모이다.

AI 코딩 에이전트 (AI Coding Agent)에게 repo 조사를 부탁할 때, 갑자기 repo 전체를 읽히는 것보다 먼저 「읽는 순서」를 만드는 편이 다루기 쉽다.

나는 이를 위해 repo 안에서 다음 후보들만을 작게 묶는 메커니즘을 만들어 테스트하고 있다.

• 가장 먼저 읽어야 할 파일
• test 후보
• contract 후보
• config나 source root 후보
• PR / Issue metadata에서 보이는 개발 영역의 편중
• 미확인 범위

이것을 여기서는 Context Pack이라고 부른다.

이번에 3개의 개인 개발 repo에서 측정한 결과, 추정 token 수는 합계 약 18.6만에서 약 4,800까지 떨어졌다. 절감률은 약 97%였다.

단, 이것은 「AI가 올바르게 구현할 수 있음」을 증명하는 것이 아니다. 어디까지나 초기 단계에서 읽을 문맥을 작게 만들고, 후보와 미확인 사항을 분리하기 위한 측정이다.

Codex와 같은 AI 코딩 에이전트는 repo를 넓게 읽을 수 있다.

하지만 넓게 읽을 수 있다는 것과, 처음부터 넓게 읽혀야 한다는 것은 별개의 문제였다.

나의 개인 개발에서는 AI에게 조사나 구현을 부탁하기 전에 매번 다음과 같은 고민이 있었다.

• 우선 어떤 파일을 읽혀야 하는가
• test는 어디에 있는가
• public contract나 schema에 가까운 파일은 무엇인가
• 변경 후보가 정말로 영향 범위인가, 아니면 단순히 이름만 일치하는 것인가
• PR이나 Issue 이력을 통해 지금 어느 영역이 혼란스러운가
• AI가 「전부 확인했습니다」라고 말해도, 어디를 보지 않았는가

이 상태에서 repo 전체를 읽히면 입력 token이 커질 뿐만 아니라, AI의 답변도 길어지기 쉽다.

그래서 처음에 repo를 기계적으로 얇게 스캔하여, AI에게 전달할 입구만을 만들도록 했다.

하는 방법은 간단하며, repo 내에 경량 스크립트를 넣어 다음과 같은 리포트를 생성한다.

docs/repo-audit/context_pack.md
docs/repo-audit/evidence.tsv
docs/repo-audit/metrics.tsv
...

Context Pack에는 코드 전문이나 diff 전문을 넣지 않는다.

대신 후보 경로, 이유, 건수, 미확인 사항을 넣는다.

예를 들어, AI에게 전달하는 첫 번째 문맥은 다음과 같은 형태가 된다.

- selected files: 129 / total tracked 129
- estimated baseline tokens: 92623
- test candidates: 10
...

중요한 것은 「이것은 후보일 뿐 결론이 아니다」라고 명시하는 것이다.

Context Pack은 영향 범위를 확정하는 것이 아니다. AI가 읽는 순서를 만들기 위한 입구이다.

3개의 개인 개발 repo에 대해 동일한 절차로 측정했다.

대략적인 흐름은 다음과 같다.

scripts/ai_audit_effect_measure.sh HEAD requirement.md

측정에서는 repo 내 대상 파일의 byte 수로부터 추정 token을 산출하고, 생성된 Context Pack의 추정 token과 비교했다.

추정 token은 엄격한 tokenizer가 아니라, bytes / 4의 근사치이다.

따라서 숫자는 「정확한 과금 token」이 아니라 「읽는 문맥량의 상대적 비교」로 보고 있다.

측정 결과는 다음과 같다.

repo	before	after	reduction	context budget	contract	scorecard	tests	contracts	evidence
Repo A	76,023	1,416	98%	PASS	PASS	PASS	2	5	10
...

합계로는 다음과 같이 되었다.

지표	값
before 추정 token	185,742
...

이 결과만 보면, 초기 조사(initial investigation)를 위한 입력 문맥(input context)을 상당히 작게 만들 수 있었다.

특히 AI에게 "먼저 이것을 읽어주세요"라고 전달하는 양이 1 repo당 약 1,100에서 2,200 추정 token 내로 수렴했다는 점은 다루기 쉽다.

가장 효과적이었던 것은 AI에게 전달하기 전에 읽는 순서(reading order)를 정할 수 있다는 점이었다.

예를 들어, repo에 들어가자마자 AI에게 다음과 같이 요청할 수 있다.

먼저 docs/repo-audit/context_pack.md 를 읽어주세요.
그곳에 있는 candidate / unknown / verification 을 구분해서 다뤄주세요.
필요해진 파일만 추가로 읽어주세요.

이것만으로도 첫 번째 응답이 달라진다.

repo 전체를 대략적으로 요약하는 것이 아니라, 후보(candidate), 미확인(unknown), 다음에 읽어야 할 파일에 대한 이야기로 흐르기 쉽다.

또 하나 효과적이었던 것은 PR / Issue metadata를 가로축(horizontal axis)으로 사용할 수 있다는 점이었다.

repo 내의 스캔(scan)은 source, test, contract와 같은 세로축(vertical axis)을 만든다.

반면, PR이나 Issue의 metadata를 보면 "최근 어느 영역의 수정이 반복되고 있는가"를 볼 수 있다.

예를 들어, 다음과 같은 클러스터(cluster)로 나눈다.

ci-workflow
planning-orchestration
mvp-scaffolding
...

물론 이것은 metadata만의 분류이므로, 정확한 영향 범위(impact scope)는 아니다.

다만, 처음에 어느 영역을 의심할지에 대한 우선순위 후보는 될 수 있다.

약점도 있다.

우선, PR 수가 적은 repo에서는 PR 클러스터가 별로 신뢰할 만하지 않다.

실제로 1개의 repo에서는 PR 샘플이 적어, 클러스터 평가를 insufficient_pr_sample로 처리했다.

이는 실패가 아니라, "가로축의 근거로서는 약하다"라고 명시하기 위한 상태이다.

또한, test 후보가 0건인 repo도 있었다.

이 경우, Context Pack이나 scorecard가 PASS라 하더라도, 구현 검증(implementation verification)의 강도는 별개의 문제가 된다.

PASS는 어디까지나 "리포트 형식, 상한선, 후보 수집의 최소 조건을 충족했다"라는 의미일 뿐이다.

이 메커니즘에서 가장 주의하고 있는 점은 PASS를 너무 강력하게 보여주지 않는 것이다.

PASS는 다음을 보장하지 않는다.

• QA 완료
• 보안 안전성 (Security safety)
• 사양 적합성 (Specification compliance)
• 완전한 영향 범위
• AI가 올바르게 이해했는지 여부

오히려 Context Pack에는 미확인 사항을 반드시 남겨둔다.

예를 들어, 다음과 같은 주의 사항을 넣는다.

- active scope나 file size 상한으로 인해 확인하지 못한 범위가 있음
- candidate는 영향이 확정된 것이 아님
- PR title에 의한 분류는 metadata-only이므로 오분류될 수 있음
...

AI에게 전달하는 문맥을 작게 만들수록, 보지 못한 범위도 생긴다.

그렇기 때문에 내용을 덜어내는 것과, 덜어냈다는 사실을 명시하는 것을 세트로 구성하고 있다.

이번 측정에서는 AI 초기 조사의 전처리(preprocessing)로서 효과가 있었다.

특히 효과가 있었던 용도는 다음과 같다.

• repo 전체를 읽기 전의 Context Pack 작성
• test / contract / evidence 후보 추출
• PR / Issue metadata로부터의 가로축 클러스터 파악
• token을 절감하면서 읽는 순서를 만드는 것
• 미확인 사항을 처음부터 분리하는 것

한편, 이것은 자동 리뷰나 품질 보증(QA)을 위한 도구가 아니다.

"AI에게 처음에 무엇을 읽게 할 것인가"를 결정하는 보조 도구로 사용하는 것이 적절하다.

다음에는 측정 대상을 늘리고 싶다.

특히 보고 싶은 것은 다음 3가지 유형이다.

• 소규모 Web app
• monorepo
• GitLab repo

GitLab의 경우, Merge Request metadata를 TSV로 전달하면 동일하게 가로축 클러스터로 사용할 수 있다.

다만, GitLab 실제 repo에서의 측정은 아직 앞으로의 과제이다.

또한, 향후에는 "token을 줄였는가"뿐만 아니라, "AI가 정말로 읽어야 할 파일을 놓치지 않았는가"도 측정할 필요가 있다.

최종적으로는, 도입 대상 repo마다 기대 후보를 fixture화하여, 누락된 후보를 다음 개선에 반영하는 형태로 만들고 싶다.

AI에게 repo 조사를 맡길 때, 처음부터 repo 전체를 읽게 하는 것보다 먼저 읽는 순서를 만드는 편이 더 안정적인 경우가 있다.

이번 3개 repo 측정에서는 추정 토큰(token)이 약 18.6만에서 약 4,800까지 감소했으며, Context Pack은 1개 repo당 약 1,100에서 2,200 추정 토큰 수준으로 수렴했다.

단, 이것이 품질을 보장하는 것은 아니다.

내 생각에 Context Pack은 "AI에게 전달하는 첫 번째 지도"이며, 지도에 표시되지 않은 곳이 있을 수도 있다는 점을 동시에 전달하는 것이라고 생각한다.

AI 개발에서는 많은 양을 읽히는 것보다, 무엇을 읽혔고 무엇을 읽히지 않았는지를 구분하는 것이 더 효과적인 상황이 있다.