[Agent] git repo를 LLM-friendly context으로 변환하는 법

https://pypi.org/project/repo-context/

Client Challenge

git repo를 chatgpt 등 web based ai에게 context로 주입하고 싶을 때가 있다.

(codex를 쓰면 되지 않냐? 싶을 수 있는데, 실제 프로젝트 구축 및 코딩용이 아닌, 개념 이해 및 구상 목적으로는 chatgpt가 더 적합하다고 생각)

그럴 땐 다른 third-party app 쓸 필요 없이, 그냥 파이썬에서 바로 repo-context를 쓰면 해결이 가능하다.

git repo를 통째로 읽어서 LLM-friendly context로 변환해 줌.

설치

참고로 uv로만 배포한 듯 함

# uv가 없으면 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# repo-context용 별도 환경 생성
mkdir -p ~/tools/repo-context
cd ~/tools/repo-context

uv venv --python 3.12
source .venv/bin/activate

uv pip install repo-context

실행

# 이거 괄호 안에 님들꺼에 맞게 넣으셈
repo-context (context로 만들 git repo 경로) \
  --output (context를 넣을 directory 경로) \
  --ignore .git build devel logs install __pycache__ "*.bag" "*.pcd" "*.png" "*.jpg" "*.jpeg" "*.mp4" "*.zip"

# 예시
repo-context ~/AjouNice2026/third_party/FAST_LIO \
  --output ~/AjouNice2026/docs/other_contexts_for_ai \
  --ignore .git build devel logs install __pycache__ "*.bag" "*.pcd" "*.png" "*.jpg" "*.jpeg" "*.mp4" "*.zip"

결과

FAST_LIO repo 기준

용량: `375K`

줄 수: `11428`

이정도면 chatgpt한테 locally하게 먹여도 좋은 듯

git repo 통째로 vs md file 변환 context 효율성 비교

만약 codex 등 filesystem에 접근 가능한 coding tool을 사용할 때에도 md file 변환이 더 좋을 수 있을까? 에 대해 궁금해 chatgpt에게 질문해 봤음.

 

결론은 cross file relationship이 강하다는 점이나, 모든 file을 다 볼 필요가 없다는 점, directory 구조를 그대로 이해할 수 있다는 점 등을 통해

git repo를 그대로 context로 주는 것이 더 좋은 것 같다.

 

사실 당연히 그대로 주는 게 더 좋다고 생각했으나, 어떻게 근거를 들여 대답할지가 궁금해 물어봐 봤다.

ChatGPT 답변

결론부터 말하면, **대부분은 1번: repo를 clone해서 별도 폴더로 `@` 지정**을 추천합니다. 다만 “레포 전체를 깊게 탐색할 필요는 없고, API/설계/패턴만 참고시키고 싶다”면 **2번 md 단일 파일**이 더 안전하고 깔끔할 수 있습니다.

추천 기준

기준	1. repo clone 후 폴더 @	2. repo-context 등으로 md화 후 파일 @
코드 구조 이해	강함. 디렉터리, import, 테스트, config를 그대로 봄	약함. 구조가 평탄화되어 손실될 수 있음
에이전트의 탐색 능력	좋음. 필요한 파일만 열어볼 수 있음	보통. 긴 md 안에서 검색/스캔
토큰 효율	대체로 좋음. 필요한 파일만 읽게 유도 가능	나쁠 수 있음. md가 크면 통째로 오염됨
reference 전용 안전성	주의 필요. 수정 대상처럼 착각할 수 있음	좋음. 단일 읽기 자료처럼 인식됨
최신성 유지	좋음. git pull 가능	불편. md 재생성 필요
cross-file 관계	강함	약함~보통
특정 부분만 제공	다소 번거로움	강함. 필요한 subset만 md화 가능
에이전트가 실수로 수정할 위험	있음	낮음

1번을 추천하는 경우

레포의 실제 구조가 중요한 경우입니다.

예를 들어:

• 비슷한 아키텍처를 참고하고 싶다.
• 특정 라이브러리의 사용 패턴을 보고 싶다.
• 테스트, config, package 구조까지 참고해야 한다.
• 여러 파일 간 관계를 따라가야 한다.
• “이 repo에서는 이 기능을 어떻게 구현했는지 찾아봐” 같은 작업을 시키고 싶다.

이 경우 md로 합치면 오히려 정보가 손상됩니다. 코딩 에이전트는 보통 파일 트리와 개별 파일 단위 탐색에 강하므로, 원본 repo 형태가 더 좋습니다.

OpenAI Codex 쪽도 read-only/sandbox 개념이 있어서, Codex가 파일을 inspect하되 수정하지 못하게 하는 모드가 있습니다. Codex CLI 문서에는 read-only가 “consultative mode”로, 파일을 볼 수 있지만 변경은 하지 않는 방식이라고 설명되어 있습니다. (OpenAI 개발자) 또한 보안 문서에서도 변경 없이 채팅/계획만 하고 싶으면 /permissions로 read-only mode를 쓰라고 안내합니다. (OpenAI 개발자)

추천 셋업은 이런 식입니다.

workspace/
  target-repo/          # 실제 수정 대상
  references/
    external-lib/       # 읽기 전용 참고 repo

그리고 프롬프트에 명시합니다.

@target-repo 는 수정 대상입니다.
@references/external-lib 는 참고용 read-only context입니다.
references 아래 파일은 절대 수정하지 말고, 필요한 구현 패턴이나 API 사용법만 참고하세요.

가능하면 reference repo 폴더 자체를 OS 권한으로 read-only 처리하거나, Codex/agent의 sandbox를 read-only로 두는 게 좋습니다. Codex 문서상 read-only sandbox에서는 파일 검사는 가능하지만 편집이나 명령 실행은 승인 없이는 못 하도록 설계되어 있습니다. (OpenAI 개발자)

2번을 추천하는 경우

reference를 “검색 가능한 문서”처럼 주고 싶을 때 좋습니다.

예를 들어:

• 레포 전체가 아니라 README, docs, public API, 주요 예제만 필요하다.
• 에이전트가 reference repo를 수정 대상으로 오해하는 걸 최대한 막고 싶다.
• 의존성, 빌드 파일, generated code, lockfile, test fixture 등은 빼고 싶다.
• 컨텍스트를 의도적으로 압축하고 싶다.
• “이 문서를 참고해서 우리 코드 스타일을 맞춰라” 정도의 용도다.

이 경우 하나의 md가 더 명확합니다. 특히 다음처럼 md 상단에 경계를 박아두면 좋습니다.

# Reference only: external-lib

This file is read-only context generated from external-lib.
Do not modify, patch, or create diffs for this reference.
Use it only to understand APIs, architecture, and implementation patterns.

다만 단점은 큽니다. repo-context류 도구가 파일을 합치는 과정에서 파일 경로, import 관계, 테스트와 소스의 대응, 설정 파일의 의미가 약해질 수 있습니다. 또 md가 너무 커지면 에이전트가 필요 없는 부분까지 컨텍스트로 삼아 산만해질 수 있습니다.

제 추천

기본값은 1번입니다.
즉, repo를 clone해서 원본 구조 그대로 주되, 다음 3가지를 같이 하세요.

1. reference repo를 references/ 같은 명확한 폴더 아래 둔다.
2. 프롬프트나 AGENTS.md에 “수정 금지, 읽기 전용”을 명시한다.
3. 가능하면 권한/sandbox/read-only mode로 물리적으로도 막는다.

Codex는 AGENTS.md를 작업 전에 읽는다고 공식 문서에 나와 있으므로, reference 경계와 수정 금지 규칙을 AGENTS.md에 넣는 방식이 잘 맞습니다. (OpenAI 개발자)

실전에서는 hybrid가 제일 좋습니다

가장 안정적인 방식은 1번 + 작은 요약 md입니다.

workspace/
  target-repo/
  references/
    external-lib/              # 원본 repo, read-only
    external-lib-CONTEXT.md    # 사람이 만든/도구가 만든 요약

그리고 에이전트에게 이렇게 줍니다.

@target-repo 를 수정하세요.

@references/external-lib-CONTEXT.md 를 먼저 읽고,
필요할 때만 @references/external-lib 안의 원본 파일을 확인하세요.

@references 아래는 reference-only입니다. 절대 수정하지 마세요.

이 방식이 좋은 이유는, 에이전트가 먼저 요약으로 방향을 잡고, 불확실할 때만 원본 repo를 깊게 들어가기 때문입니다.

한 줄 추천

정확한 구현 참고, 구조 탐색, cross-file 이해가 필요하면 1번.
수정 위험을 줄이고 정제된 참고자료만 주고 싶으면 2번.
가장 추천은 1번 repo clone + reference-only AGENTS.md/프롬프트 + 작은 context md 요약입니다.